Take this section out. We're already caching the possibility of a prepend equal method with "prepend_eq". Added caching on that just gets complicated.
Method/function & prefix: extend the rule and decide on doc sweep
**Decided.** Methods can now be defined without the `&` prefix on the name. `method foo(...)` is valid; `method &foo(...)` is no longer required. **Open:** 1. Should the same change apply to regular `function` definitions? Today `function &name(...)` is still the documented form.…
Why is $left lazy? It's always called. I think this function should look more like this: class method &evaluate($left, $right: {lazy: true}) do if $left return $left else return $right.call end end end
File: documentation/requirements/caspian/lucy/index.md § on_call: dispatch identity as a function property (#on-call-property)
Dead-link report — 2026-06-23 04:58 Crawled 554 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4078. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **360 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-22 — 360 broken
Dead-link report — 2026-06-22 04:58 Crawled 554 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4077. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **360 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-21 — 360 broken
Dead-link report — 2026-06-21 04:58 Crawled 554 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4076. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **360 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-20 — 360 broken
Dead-link report — 2026-06-20 04:58 Crawled 554 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4075. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **360 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-19 — 360 broken
Dead-link report — 2026-06-19 04:58 Crawled 554 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4074. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **360 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-18 — 359 broken
Dead-link report — 2026-06-18 04:58 Crawled 553 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4081. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **359 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-17 — 359 broken
Dead-link report — 2026-06-17 04:58 Crawled 553 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4084. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **359 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-16 — 359 broken
Dead-link report — 2026-06-16 04:58 Crawled 553 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 4083. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **359 broken internal link(s) across 85 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-15 — 353 broken
Dead-link report — 2026-06-15 04:58 Crawled 535 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3981. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **353 broken internal link(s) across 83 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-14 — 353 broken
Dead-link report — 2026-06-14 04:58 Crawled 534 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3934. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **353 broken internal link(s) across 83 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-13 — 353 broken
Dead-link report — 2026-06-13 04:58 Crawled 534 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3933. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **353 broken internal link(s) across 83 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-12 — 353 broken
Dead-link report — 2026-06-12 04:58 Crawled 534 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3932. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **353 broken internal link(s) across 83 page(s):** ### `/documentation/ideas/age…
Daily link check — 2026-06-11 — 358 broken
Dead-link report — 2026-06-11 04:58 Crawled 536 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3940. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **358 broken internal link(s) across 84 page(s):** ### `/documentation/` - `/doc…
Daily link check — 2026-06-10 — 358 broken
Dead-link report — 2026-06-10 04:58 Crawled 536 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3939. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **358 broken internal link(s) across 84 page(s):** ### `/documentation/` - `/doc…
documentation/ideas/mcp-and-caspian.md § Where MCP intersects with Caspian — the agent-calling spec
File: documentation/ideas/mcp-and-caspian.md Section: Where MCP intersects with Caspian — the agent-calling spec Anchor: #where-mcp-intersects-with-caspian-the-agent-calling-spec **The statement, _"ACP (Agent Communication Protocol) is Caspian's own protocol for agent-related m…
Daily link check — 2026-06-09 — 358 broken
Dead-link report — 2026-06-09 04:58 Crawled 536 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3937. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **358 broken internal link(s) across 84 page(s):** ### `/documentation/` - `/doc…
File: documentation/requirements/puck/class-definition.md § Open points (#open-points)
Regarding this: Versioning across calls. A client cached the v1.0.0 definition; the server has shipped v1.1.0 since. Does the proxy re-resolve, raise on mismatch, or silently use the older shape? TBD. Review versioning in Puck. Versioning is only loosely supported.
File: documentation/requirements/puck/class-definition.md § Example: rendered page for https://puck.uno/geo (#example-rendered-page-for-https-puck-uno-geo)
Scan all the docs for instances where a class is given a UNS. We don't do that anymore: Wrong: class 'puck.uno/geo' Right class-
Post-V1: Argument parser library (resolved via %puck, not built-in)
## Concept A Caspian library that parses `$args` into named flags, positional arguments, subcommands, etc. — like Python's `argparse`, Ruby's `optparse`, or Go's `flag` package. **Available online, not built into the engine.** Resolved through the standard puck-lookup chain (e.…
Sidequest: `.global = true` flag on capabilities (e.g., `%stdout.global = true`)
## Concept Certain capabilities — `%stdout`, `%stderr`, possibly others — can be marked **globally available** to any role by setting a flag: ```caspian %stdout.global = true ``` After this, any role (libraries, agents, nested code) can write to stdout without explicit capabi…
Sidequest: `dofunc` block keyword — like `do` but passes a function (no closure)
## Concept Caspian's `do ... end` block in a method-call position passes a **closure** — captures the caller's lexical scope. Sometimes the caller wants to pass a **function** instead — no outer scope captured, just the block's own code. Working idea: a sibling keyword `dofun…
Daily link check — 2026-06-08 — 340 broken
Dead-link report — 2026-06-08 04:58 Crawled 507 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3838. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **340 broken internal link(s) across 77 page(s):** ### `/documentation/` - `/doc…
Clarify temp directory mechanism: %utils.tmp_dir.new is the actual API; existing %tmp references need reconciliation
**Issue:** temp directories in Caspian are obtained via `%utils.tmp_dir.new` — but this isn't documented anywhere, and existing docs scatter references to a `%tmp` engine-granted directory that may not actually be how the mechanism works. ## What we need to clarify - **The actu…
File: documentation/ideas/object-hive.md § Systems that already do something like this (#systems-that-already-do-something-like-this)
Bryton: bare minimum. --- Placeholder issue. Filed for later — not designing now.
Engine should be able to restrict which network protocols are allowed
The engine should be able to restrict which network protocols it allows. So let's say it only allows HTTP. --- Placeholder issue. Filed for later — not designing now.
Sweep: declare class methods with `method &name` instead of `function &name`
**Convention change:** Methods of a class are now declared with the `method` keyword instead of `function`. The form: ```caspian $myclass = class method &foo($port) @port = $port @clients = [] end end ``` Same `&name(...)` sigil for the method-as-property declaration; only the ke…
**Convention:** Caspian classes don't name themselves. Per the canonical spec in [classes/index.md § Class identity](https://puck.uno/documentation/requirements/caspian/classes#class-identity), the DSL form is just `class ... end` — the class is anonymous in source. A class on…
File: documentation/ideas/caspian/events/index.md § The chat client (#the-chat-client)
Take out the stuff about sugar. Just show how to create the jail the normal way with %net.http.client.jail
Network: SMTP-direct vs provider-API as V1.0 primary email-send surface
**Context:** [network.md § SMTP](https://puck.uno/documentation/requirements/caspian/network#smtp) sketches `puck.uno/smtp/client` as the primary email-send class. The sketch uses SMTP-direct (script opens a socket to an SMTP server with credentials). Modern scripts often use pr…
**Context:** Per the network restructure ([network.md](https://puck.uno/documentation/requirements/caspian/network)), V1.0 covers raw sockets, HTTP, SMTP, DNS, and basic TCP listening. Other common network protocols are post-V1.0. This issue tracks them as a single rollup so they…
Network: listen-grant flag syntax (--allow-listen=PORT, =HOST:PORT, ranges?)
**Context:** Per the network restructure ([network.md](https://puck.uno/documentation/requirements/caspian/network)), listening sockets need a separate permission grant from outbound network access. Listening exposes the script to the network; outbound just lets it reach out. Dif…
Network: Lua/LuaSocket integration plan — what we wrap, where, what gaps
**Context:** Per the network restructure ([network.md](https://puck.uno/documentation/requirements/caspian/network)), Caspian's network surface is general-purpose — raw sockets (TCP/UDP/SSL) plus per-protocol clients (HTTP/SMTP/etc.) built on top. Miko's direction: hook into Li…
Network: cookie handling — none, per-client jar, per-script, or optional?
**Context:** [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network) doesn't address cookies. Real HTTP usage (login flows, session persistence, anti-CSRF tokens) needs them. ## The question How does the client handle cookies? - **No cookie handling.** S…
Network: redirect handling default — follow, hop limit, HSTS, cross-origin
**Context:** Per [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network), `puck.uno/http/client` accepts `follow_redirects` as an opts field. What's the default behavior? ## The question When a server returns 301/302/303/307/308: - **Follow automatically…
Network: default User-Agent string when caller doesn't override
**Context:** [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network) shows `User-Agent` as an overridable header. What does Caspian send if the caller doesn't override? ## The question - **Caspian-branded default** — `caspian/0.x.y` or `caspian/<versio…
Network: default timeout — sensible default, no default, or infinite?
**Context:** [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network) accepts `timeout:` as a per-request option. What happens if the caller doesn't set one? ## The question - **Sensible default** (e.g., 30s, 60s, 120s). - **No default, must be set.** Cal…
Network: per-host allowlist check timing — URL-parse vs TCP-connect
**Context:** Per [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network), per-host allowlist enforcement is engine-side. If a script has `--allow-net=api.example.com` and code tries `%net.fetch('other.com/...')`, the engine raises `puck.uno/error/network…
Network: streaming bodies — whole-thing only, or stream chunks?
**Context:** [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network) treats request and response bodies as "the whole thing" — fetched once, available as `.body` or `.json`. Real use cases need more: - **Chunked transfer.** Large responses streamed in …
Network: server-side class location — network.md, Sammy spec, or both?
**Context:** [caspian/network.md](https://puck.uno/documentation/requirements/caspian/network) covers client-side HTTP. Server-side HTTP (listening for inbound requests) overlaps with the Sammy slice. ## The question Where does the server-side class live? - **Network spec.** `puc…
**Context:** [%engine.config](https://puck.uno/documentation/requirements/caspian/engine/config) accepts multiple blocks at the top of a script/library. Several open design points remain about how those blocks combine and what happens to misplaced blocks. ## Open points (from con…
require version resolution model: per-scope (multi-version) vs per-program (single-version)
**Context:** [require.md § Version constraints](https://puck.uno/documentation/requirements/caspian/engine/require#version-constraints) was designed this session with the inheritance model: user constraints flow down the full dep tree; nested-library constraints scope to their o…
Permission flag spec landing: --standard, default-deny, Frank amendment
**Context:** Permission flags were settled in the 2026-06-07 design conversation. Default-deny posture; `--standard` is the convenience bundle (replaces the older `--allow-all` / `-A`); granular per-resource flags are the Frank-spec `--allow-*` family. This issue tracks the spec …
Post-V1: %engine.config strict enforcement mode
**Context:** [%engine.config](https://puck.uno/documentation/requirements/caspian/engine/config) declares the resources a script (or library) needs to run. Current spec treats declarations as **transparency only** — the script declares what it intends to use; actual per-operati…
Post-V1: blockchain support for discovering test suites for libraries
**Context:** Idea proposed by Miko on 2026-06-07. The blockchain should support marking libraries as tests for OTHER libraries; that lets third parties publish their own test suites for existing packages, and adopters can discover those test suites via the blockchain. **Status:**…
Post-V1: track every line of code that uses a particular resource
**Context:** Per the resource-usage tracking direction (resources self-register in `state.used_resources` on first use, manifest reports usage). The basic feature is binary: was the resource used or not? A richer extension tracks WHERE in the code each resource was accessed. **St…
Network access surface in Caspian — how is network permission accessed?
**Context:** Per the permission-flag direction (default-deny + `--standard` bundle includes network), Caspian scripts can be granted network access. The CLI flag is settled; the runtime surface is not. Miko's note on 2026-06-07: *"--standard includes a network connection. I'm not…
Post-V1: blockchain support for discovering test suites for other libraries
**Context:** Idea proposed by Miko on 2026-06-07. The blockchain should support marking libraries as tests for OTHER libraries; that lets third parties publish their own test suites for existing packages, and adopters can discover those test suites via the blockchain. **Status:**…
Post-V1: track every line of code that uses a particular resource
**Context:** Per the resource-usage tracking direction (resources self-register in `state.used_resources` on first use, manifest reports usage). The basic feature is binary: was the resource used or not? A richer extension tracks WHERE in the code each resource was accessed. **St…
Network access surface in Caspian — how is it passed in and accessed?
**Context:** Per the permission-flag direction (default-deny + `--standard` bundle includes network), Caspian scripts can be granted network access. The CLI flag is settled; the runtime surface is not. Miko's note on 2026-06-07: *"--standard includes a network connection. I'm not…
overview.md uses UNS framing throughout — sweep to URL-as-address
**Context:** [documentation/overview.md](https://puck.uno/documentation/overview) is the top-level Puck overview doc. Per the URL-as-address direction (2026-06-06), UNS is no longer the primary class addressing model — URLs are. The overview currently frames UNS as a major Puck…
Caspian docs use wire-form `stack` (plural-platter); worldlet wire form is `class` singular
**Context:** Worldlet wire form is \`{class, bucket}\` with \`class\` singular. The plural-platter \`stack\` shape is the runtime class stack only — never on the wire. Per memory: *"\`class\` (singular, wire) is not the same thing as \`classes\` (plural, runtime)."* Two caspian…
drinian/examples/mid-execution.md still has `pending_exceptions: []` (removed from spec)
**Context:** Earlier this session, the drinian spec was updated to drop the \`pending_exceptions\` top-level field — exceptions now live as call_stack elements with \`action: "exception"\`. The drinian/index.md was updated to reflect this. However, [drinian/examples/mid-executi…
Review ecoverse/uns.md under URL-as-address model — retire or reframe
**Context:** Per Miko's URL-as-address direction, UNS is no longer the primary class addressing model — URLs are. The doc [ecoverse/uns.md](https://puck.uno/documentation/requirements/ecoverse/uns) is a 267-line spec that frames UNS as the primary identifier scheme. Worth a top…
ecoverse/standard-fields.md lists `bucket` as a pass-through field; bucket is structural
**Context:** [ecoverse/standard-fields.md](https://puck.uno/documentation/requirements/ecoverse/standard-fields) lists six reserved pass-through fields including `bucket`. Per the worldlet spec and the cross-reference in memory ([feedback notes]), the pass-through fields are: `vi…
caspian/classes/index.md: reframe UNS-as-storage-address language as URL-based
**Context:** Per Miko's URL-as-address direction, UNS is being retired as the primary terminology. [classes/index.md](https://puck.uno/documentation/requirements/caspian/classes/index) uses "UNS" extensively throughout — the framing is conceptually correct (UNS = the address wh…
**Context:** Per Miko's URL-as-address direction (2026-06-06), UNS is being retired as the primary class addressing model. URLs are the address layer; bare form `foo.com/bar` is shorthand for `https://foo.com/bar`. This issue bundles all the remaining UNS-as-primary-class-address…
Mikobase index.md 'What is not yet designed' list is stale
**Context**: The mikobase doc's worldlet section ends with a "What is not yet designed" list. Several entries are now stale — the listed items are either in active design or already designed. ## Specific occurrence ### [mikobase/index.md:805-811](https://puck.uno/documentation/…
Mikobase migration.md uses stale meta-class name `puck.uno/record/class`
**Context**: Per memory `project_meta_class_renamed_puck_class.md`: the meta-class for class definitions was renamed from `puck.uno/record/class` to `puck.uno/class`. The current name is `puck.uno/class`. ## Specific occurrence ### [mikobase/migration.md:60-61](https://puck.uno/d…
Mikobase 'Capabilities Manifest' for worldlets contradicts %engine.config design
**Context**: Designed this session at [engine/config.md](https://puck.uno/documentation/requirements/caspian/engine/config): script-level resource declarations use `%engine.config <<EOF('json') ... EOF` — a JSON heredoc inside the Caspian source. The mikobase doc has its own pr…
Mikobase records use platter `stack` on the wire; worldlet spec wire form is `class` singular
**Context**: Per Miko: *"worldlets are little mikobases. If something in the mikobase docs contradicts our definition of worldlets then the mikobase docs are in error."* The current worldlet spec at [ecoverse/worldlets/index.md](https://puck.uno/documentation/requirements/ecovers…
Mikobase docs: reframe UNS as URL throughout
**Context**: Per Miko's recent direction (URL-as-address model), Caspian no longer uses UNS as the primary class addressing form. URLs are the address layer; the bare form (`foo.com/bar`) is shorthand for `https://foo.com/bar`. The mikobase docs were written under the UNS framing…
Post-V1: dependency tree in %engine.manifest
**Status:** Post-V1 feature. The cheap implementation depends on engine infrastructure that's still settling (per-library role identity). Filed per Miko's request to record the design space without committing to V1.0. **Current state of `%engine.manifest`:** `caspian.libs` is a f…
Daily link check — 2026-06-06 — 338 broken
Dead-link report — 2026-06-06 04:57 Crawled 490 pages from http://127.0.0.1:8181 starting at /documentation/. External links not fetched: 3603. Skipped (mailto/etc): 0. GitHub line-refs ignored: 0. **338 broken internal link(s) across 76 page(s):** ### `/documentation/` - `/doc…
Hash_element bucket: by symmetry should it be empty?
Recent change: \`puck.uno/variable\`'s bucket was emptied because the name lives as the key in the frame's \`locals\` and the frame is implicit (the variable exists because some frame's locals references it). Variables now have \`bucket: {}\` everywhere. By the same symmetry argu…
Platter IDs: live sequence vs serialized UUIDs distinction in spec
The [references.md spec § Object IDs](https://puck.uno/documentation/requirements/caspian/skeletor/references#object-ids) currently states: > Platter IDs are different: they're UUIDs (see base-class-use.md § Proposed shape), not from this counter. The reason: platter IDs appear…
Skeletor representation cleanup sweep
Mid-execution.md and references.md (example) have been brought to the current Skeletor representation in recent sessions. Several other files lag behind and need the same treatment to keep the doc set consistent. **Changes that need propagating:** - **Shadow platters carry explic…
blockchain-implementation/index.md: 'UNS-addressed objects' should be URL-addressed
File: documentation/requirements/caspian/downloads/blockchain/blockchain-implementation/index.md:6 Vibecode \`role\` field mentions 'UNS-addressed objects' — contradicts URL-as-address model. Also worth checking the rest of the file (this is the chain implementation doc; multip…
engine/require.md: 'identified by its UNS' should be 'identified by URL'
File: documentation/requirements/caspian/engine/require.md:13 States libraries are 'identified by its [UNS]' — contradicts URL-as-address model. Suggested fix: 'identified by URL' (with the UNS form being a URL with the protocol elided).
puck/index.md: 'resolve the class by UNS' should be URL framing
File: documentation/requirements/puck/index.md:41 Workflow described as 'resolve the class by UNS' — contradicts the URL-as-address model. Classes are located by URL; UNS is a naming convention layered on top. Suggested reframe: 'resolve the class by URL (or by UNS shorthand, w…
objects/structure.md: drop UNS-registry framing for class resolution
File: documentation/requirements/ecoverse/objects/structure.md:68 Describes class deserialization as 'the named class identified by that UNS' and 'deserializer looks the class up from wherever it lives (a Mikobase record, the engine's built-in registry, etc.)' — implies UNS res…
Drop UNS from class declarations across all docs
The canonical reference at documentation/requirements/caspian/classes/index.md has been rewritten so that classes are declared as just \`class ... end\` (no UNS in the declaration; identity = storage location). Many other docs still show the older \`class 'foo.com/X' do ... end\`…
Puckai: issue should carry on-completion instructions
PuckAI needs to include instructions on what to do when the process is complete. That information lives in the issue.
Spec out the blockchain interface
Let's spec out the blockchain interface. There's already a doc for it somewhere (likely under documentation/requirements/caspian/downloads/service/blockchain/).
Skeletor serialization should include meta info (class versions; manifest dump option)
Outputting skeletor should include meta information like the current version of classes. It doesn't have to actually live in skeletor but it should output that information when it's serialized. Some of that information is the same as in a manifest. So maybe there could be an opti…
Manifest: include Linux version and libraries used; manifest report → config file
Manifest file can show Linux version. Can show Linux libraries that were used. The manifest report can be used to generate a config file.
File: documentation/requirements/caspian/roles.md — clarify fetcher-role vs faucet-role ownership
[roles.md](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/roles.md) currently says external objects pulled through faucets are "owned by the **faucet's** role." The fetcher concept (the layer that *contains* faucets) isn't mentioned as a role-ow…
File: documentation/requirements/caspian/downloads/caching/ — pin the on-disk paths for user, system, and engine-shared caches
The [downloads/index.md § Typical search path](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/downloads/index.md#typical-search-path) section describes a layered hierarchy of caches that real deployments will use: - **User-owned cache** — lik…
File: documentation/requirements/caspian/downloads/index.md § The search path — first-hit vs consult-all resolution semantics
The new search-path framing in [downloads/index.md](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/downloads/index.md#the-search-path) describes `%puck` walking its fetcher array and stopping at the first one that returns a match ("tries each on…
When eval'd code runs, it runs in a jail (no ambient access)
Design note to land in the eventual eval-spec doc: When the engine permits eval, the **eval'd code itself runs in a jail**, like an untrusted function — it has no access to anything ambient. The caller must hand it permissions explicitly if it needs any. This is the same role-b…
File: documentation/requirements/ecoverse/AI2AI/single-agent/index.md § Before — the worldlet sent to the agent (#before)
AI2AI: support multiple candidate decisions per session
Future idea: allow a session to carry **more than one** `puck.uno/ai/decision` record. Each would be a candidate answer with its own `body` and its own `confidence`. The client picks the candidate with the highest confidence above the configured `confidence_floor`. **Use case:** …
object.md § uses: provisional accessor name
The read accessor for the recorded use-sites in [object tracking](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/built-in-classes/object.md#uses) is currently named `uses`. The name is provisional. Candidates: `uses`, `history`, `sites`, `tracks…
object.md § track: identity vs name semantics for 'a use'
[`$foo.object.track = true`](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/built-in-classes/object.md#track) records every site where the object is used. The doc currently says tracking follows **object identity, not variable names** — so `$b…
Idea raised: a syntax like `%engine.cover 'foo.bar/gup'` to specify libraries for coverage. The established rule is that 'all loaded libraries are included in coverage,' so specifying libraries must mean something other than 'opt in to library tracking.' Possible interpretations:…
manifest.md: Block-form coverage interaction with property-form
When both forms of [%engine.coverage](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/index.md) are used — `%engine.coverage = true` (process-wide) AND `%engine.coverage do ... end` (block-scoped) — what happens? Current doc treats the…
manifest.md: Name for coverage full-detail option
An option on [%engine.manifest](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/manifest.md#coverage) should be able to override the retention setting and produce every executable line with hit count, regardless of what `%engine.coverage` …
manifest.md: `range` field shape in constraints mode
When [%engine.manifest](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/manifest.md) JSON is authored by hand as a constraints file (rather than emitted by the engine), fields can carry a sibling `range` field expressing acceptable variati…
engine/index.md: %engine.dir semantic — cwd, script-dir, or FS jail?
The [%engine.dir](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/index.md) row says 'the directory the program is running in.' Three reasonable interpretations: - Current working directory (cwd) - The directory containing the running scri…
engine/index.md: Is %stderr also a top-level slot, or only %engine.stderr?
[%engine.stderr](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/index.md) is in the standard slots table. `%engine.stdout` is documented as having a parallel top-level `%stdout` (broadly grantable to non-user roles, same underlying channe…
manifest.md: `runtime` field format unsettled
The `process.runtime` field in [%engine.manifest](https://github.com/mikosullivan/puck/blob/main/documentation/requirements/caspian/engine/manifest.md) reports how long the process has been running. The format is TBD: - ISO 8601 duration (`PT5M23S`) - Seconds as a number (`323.45…
|Both files reference base-class-use.md (stale) for platter mechanics. references.md ties platter IDs to the UUID generator (see related uuid-generation.md issue). Update citations to point at the new objects spec; reconcile the platter-ID question with whatever the resolution is…
|Discusses "platter IDs" as one of the use cases for libsodium UUIDs, with the justification that platter IDs appear as keys inside user buckets where a sequencer integer-string could collide. The current objects spec uses arbitrary string keys on platters (the convention is shor…
|Query API uses `"classes": "foo.com/character"` (and array form) as a filter parameter on `select` actions. Under the new model where each record has one primary class identity, the parameter should probably be `class:` singular. Resolve: rename to `class`, or document why the p…
|Historical log of an earlier single-class → multi-platter migration. The "after" shape it documents is no longer current (the current shape is `{bucket, stack}` for instances + whole-hash for class defs). Either extend the log with the subsequent evolution, or rewrite as a cur…
File: documentation/requirements/caspian/classes/index.md § The worldlet envelope (#the-worldlet-envelope)
Clarification. In a worldlet the keys can be any string. This example just appears to be a sequencer. They could be UUIDs, sequences, or short random strings. The worldlet format does not decide how you generate record keys.
V1.x: Boot from image — preloaded VM state as starting point
**Filed for V1.x exploration, not for V1.0 implementation.** ## The concept Skeletor specs a virtual-machine state model. Once snapshot/revive lands (post-V1.0), the state hash can be serialized and reloaded — the existing skeletor.md design. **Boot-from-image** is the natural …
Helpers storage: platter-bucket vs top-level bucket
## Current state The `helper foo` BWC in a class body desugars to: ```caspian function &foo() return @foo ||= $helper_class.new(self) end ``` `@foo ||= ...` is access to the **parent's top-level bucket**. The helper instance is memoized there. ## Problem With per-platter buckets …
Helpers documentation cleanup in lucy.md
Small cleanup items found in [lucy.md § Helpers](https://github.com/mikosullivan/puck/blob/main/documentation/caspian/lucy/lucy.md#helpers): ## 1. Example bug The example shows: ``` $myclass = class helper foo function &bar() return self.reference.gup end end end $myclass.foo.ba…
V1.1+: %utils.sequence.compact for long-running processes
## Background In long-running Caspian processes (data center workloads, multi-month server runs), the global object-ID counter ratchets up indefinitely. IDs grow from 1-2 characters to 12-15+ over the program's lifetime, costing storage in the \`references\` hash, the \`objects\`…
Restricted-addition classes: complement to sticky for security markers
Sticky classes (#338 or similar) prevent removal once a class is in an object's stack. But stickiness is half a security mechanism — it protects against removal but not against unauthorized addition. For markers like \`puck.uno/class/validated\` or \`puck.uno/class/audit_logged…
Filesystem: lock/unlock/with_lock API on file objects
filesystem.md and frank.md now have file-lock as a separate permission (--allow-fs-lock=PATH). The permission gating is in place; the actual lock API surface isn't designed yet. Open API questions: - Method names on file objects: \`\$file.lock()\` + \`\$file.unlock()\`? Or a bloc…
Snapshot redaction via sticky puck.uno/class/redact marker class
**Settled design** (replacing the on_snapshot/on_revive hook approach from #334): Snapshot-time redaction works via a sticky marker class — \`puck.uno/class/redact\` or similar. Apply it to any value or field. It does nothing during normal execution. At snapshot time, the engin…
V1.1+: Compact serialization form for primitive objects
Every value in Skeletor wraps even simple types in the CaspianJ expression vocabulary: - An integer 5 stores as \`{"value": 5, "src": [...]}\` - A boolean stores as \`{"value": true, "src": [...]}\` A program with hundreds of integer locals or counters multiplies that wrapping. W…
V1.1+: .object.src API with role-based access
In the remote-library example (skeletor.md and examples/05-remote-library.md), a value created in user code carries its caller's \`src\` — \`["a", 3]\` for a user-file line — even after it passes into a loaded library across the role boundary. Concretely: the library's frame …
File: documentation/development/v1/frank.md § Open question: where does the granted permission set live? (#skeletor-impact-open-permissions)
Let's talk about the names of those permissions. We might need to standardize the terms for those permissions. Like 'http', 'dir' or something. I'd like to implement a system in which libraries can provide a list of what permissions are required or are optional. What do you think…
File: documentation/development/v1/frank.md § Open question: where does the granted permission set live? (#skeletor-impact-open-permissions)
What do you think of this format? class 'puck.uno/geo' field :lat field :long field :alt function(remote:true) &address end function(remote:true) &distance_to($other) end function(remote:true) &city end end
Introduce `%['...']` early on and use that format thereafter.
Cache clear: invalidate loaded classes and force reload (deferred)
**Filed for later exploration; not actively pursued.** Came up during the 2026-05-23 metaprogramming discussion. Miko's note: > I don't think it would be too hard to do a sort of "cache clear" so that all classes have to be reloaded. ## The idea Caspian's class cache (which store…
Engine-pluggable process state hash
**Filed for later exploration; not actively pursued.** Updated 2026-05-23 with the sharper framing from continued design discussion. ## The architectural commitment Caspian's runtime is organized around a single **process state hash**. The interpreter never touches runtime state …
Memory pipe: engine-pluggable memory backend for Caspian (deferred)
**Filed for later exploration; not actively pursued.** Came up during the 2026-05-23 design conversation about Caspian's runtime state organization. The idea: > Caspian itself doesn't know anything about its memory backend. The engine passes in a "memory pipe." By default, it pas…
I would like to have an easy way to add two helpers to any object. Those helpers are called "misc" and "corporate". Those methods stored in "%bucket['misc']" and "%bucket['corporate']". What would be an easy API to add those two helpers?
Have we implemented the DSL system to allow for this kind of statement? accessor @foo, :get, :set
Markie: failure modes for user-endpoint outages and timeouts
**Doc:** [markie.md](../blob/main/documentation/ideas/markie/markie.md) When a user-registered endpoint is down, slow, or returns an error, Markie has to decide what to splice in its place. Options (probably all configurable per-component): - **Fallback HTML**: registration inclu…
Markie: auth between Markie and user-registered endpoint
**Doc:** [markie.md](../blob/main/documentation/ideas/markie/markie.md) When Markie fetches a user-registered endpoint (e.g. on a `<my-widget>` expansion), the user's server can't tell whether the request really came from Markie or from a random attacker spoofing Markie's user-ag…
File: documentation/site/frameworks/jqmin/jqmin.md § Which existing pieces survive into the Puck version? (#which-existing-pieces-survive-into-the-puck-version)
No existing features will be ported by default. We'll pick and choose them as we like. We won't proceed with jqmin until we have an actual need for it. I'm not convinced we'll ever have that need.
Design: argument inspection mechanism for DSL receivers (prereq for parser refactor #66)
**Context:** [dsl.md](../blob/main/documentation/charlie/dsl.md) makes the class-body DSL the canonical example of pure-DSL design. The class-body DSL has commands like: \`\`\` accessor @nickname field :name, class: :string, required: true \`\`\` In the pure-DSL model, \`accessor…
Decide: $dispatcher.dsl shape (DSL object, hash view, or both)
**Context:** [dsl.md](../blob/main/documentation/charlie/dsl.md) describes setting a DSL on a dispatcher inside a function before yielding. [lucy.md § DSL Receivers](../blob/main/documentation/charlie/lucy/lucy.md#dsl-receivers) describes \`\$dispatcher.dsl\` as a hash you assig…
Spec: puck.uno/dsl and puck.uno/dsl/entry class definitions
**Context:** [dsl.md](../blob/main/documentation/charlie/dsl.md) commits to using DSLs broadly across the language. We need a canonical Mikobase-style class definition for the DSL itself so DSLs can be created, stored, reused, and documented. **Proposed schema:** \`\`\`json { "cl…
Parser refactor: class-body keywords should be DSL bwcs, not parser keywords
**Spec:** [dsl.md](../blob/main/documentation/charlie/dsl.md) (the canonical "pure-DSL where practical" architecture) and [lucy.md § Defining a class](../blob/main/documentation/charlie/lucy/lucy.md#defining-a-class) ("Class definition syntax is a DSL — it uses the same dispat…
I like this example: $myfunc = function() $dispatcher = %call.dispatcher $dispatcher.dsl['foo'] = $bar $dispatcher.yield end &myfunc do foo # calls $bar.foo gup # calls $bar.gup end Clarify where $bar comes from. Maybe just invent a class for it.
Take this out: Identity comparison (===) compares instances and so distinguishes any two distinct nulls regardless of flavor.
CJS must preserve comments and %vibecode heredocs as first-class nodes
Prerequisite for the formatter, the Differ ([#55](https://github.com/mikosullivan/puck/issues/55)), and any future linters or refactor tools. ## The principle Every tool that reads Charlie source should go through the canonical Charlie→CJS transpiler, never parse Charlie text d…
Differ: Charlie-aware diff service (brainstorm)
Brainstorm doc: [documentation/ideas/differ.md](../blob/main/documentation/ideas/differ.md) Online service that takes two Charlie scripts (pasted, or pulled from a file's GitHub history), reformats both sides through the viewer's personal `style.json`, and shows a clean diff. Str…
Explore line-spacing preferences for the Charlie formatter
**Source:** discussion 2026-05-22 while designing the Charlie formatter spec. ## What's already settled `blank_line_around_blocks` is documented in [vscode/formatter.md § blank_line_around_blocks](https://www.puck.uno/documentation/charlie/vscode/formatter#blank-line-around-bloc…
Containers tag explicit nulls with :explicit flavor
**Source:** discussion 2026-05-22 while designing `ideas/matrix.md`. ## The rule When a container (hash, array, matrix, or any future container type) is queried for a value, and the value at that key/index/coordinate **was explicitly set to null**, the returned null carries the `…
parameters.md: document that closures implicitly accept *args and **opts
**Source:** discussion 2026-05-22 while designing `ideas/matrix.md`. ## The rule to document Closures, unlike functions, **default to accepting any number of positional and named arguments.** There is an implicit `*args` and `**opts` in every closure's parameter definition. This …
numbers.md § Rounding: example value 12.25 is not actually a midpoint
**File:** [documentation/charlie/built-in-classes/numbers.md § Rounding](https://www.puck.uno/documentation/charlie/built-in-classes/numbers#rounding) (line 158) The example block says: ``` $foo = 12.25 $foo.round(multiple: 0.2) -> 12.2 or 12.4 (midpoint rule applies) ``` But `1…
File: documentation/mikobase/mikobase.md § Field declarations (#field-declarations)
I do not understand any of this. Please exaplain. "participants": {"class": "array", "items": "puck.uno/ai/agent"} "tags": {"class": "array", "items": "string"} "by_name": {"class": "hash", "items": "foo.com/person"} A consumer reading these can validate participants element-by-e…
File: documentation/mikobase/mikobase.md § Field declarations (#field-declarations)
Add a feature. If a string field is required, you can set the requirement like this: `"required":"content"`. That means that the string must have at least one non-space character in it. Also, string field definitions may include `"collapse":true` which means to collapse whitespac…
Clarify that Orlando is a temporary solution and that we'll switch to Sammy before V 1.0.
scope.operators namespace referenced but not specified [LOW]
**Audit issue #41 from documentation/issues.md (2026-05-17 four-agent audit).** Severity: LOW. Deferred — entangled with #20 (operator-namespace question). ## Problem The operator specs reference a `scope.operators` namespace but don't define what `scope` is in that context. Is…
Operator namespace inconsistent: charlie.uno/ vs puck.uno/ [HIGH]
**Audit issue #14 from documentation/issues.md (2026-05-17 four-agent audit).** Severity: HIGH. Entangled with #20 (see below). ## Problem The operator-related specs reference `charlie.uno/` as if it were a separate namespace, but `charlie.uno/` is never defined anywhere — the …
File: documentation/charlie/packages/trivet/trivet.md § Status (#status)
I feel like most entire page is unnecessary. The design principles and justification for Lua are worth keeping. The rest feels like it's already covered elsewhere.