Skip to content

ByteTerrace/Puck / .claude/skills/puck-world

puck-world

Verified

Maps Puck.World: .puck worlds, rules, grants, console verbs, extensions, the live MCP World. Use to run or verify a World change (stdin script, stale binary, headless run) or debug a refusal.

FileKindSize
SKILL.mdskill md72.0 KB
evals/w01-seat-mouse-look-sensitivity/graders/behavior-preserving-default.mdmarkdown191 B
evals/w01-seat-mouse-look-sensitivity/graders/names-the-existing-record.mdmarkdown71 B
evals/w01-seat-mouse-look-sensitivity/graders/no-flag-or-constant.mdmarkdown89 B
evals/w01-seat-mouse-look-sensitivity/graders/one-seat-through-identity.mdmarkdown186 B
evals/w01-seat-mouse-look-sensitivity/graders/pointer-sensitivity-members.mdmarkdown88 B
evals/w01-seat-mouse-look-sensitivity/graders/read-back-verb.mdmarkdown76 B
evals/w01-seat-mouse-look-sensitivity/graders/reuses-existing-vocabulary.mdmarkdown155 B
evals/w01-seat-mouse-look-sensitivity/graders/skill-fired.mdmarkdown36 B
evals/w01-seat-mouse-look-sensitivity/graders/value-in-the-document-model.mdmarkdown125 B
evals/w01-seat-mouse-look-sensitivity/prompt.mdmarkdown268 B
evals/w02-row-set-refusal/graders/actor-differs-from-target.mdmarkdown158 B
evals/w02-row-set-refusal/graders/captures-both-streams.mdmarkdown122 B
evals/w02-row-set-refusal/graders/grant-versus-subject.mdmarkdown283 B
evals/w02-row-set-refusal/graders/skill-fired.mdmarkdown36 B
evals/w02-row-set-refusal/graders/stamped-principal.mdmarkdown252 B
evals/w02-row-set-refusal/graders/success-control.mdmarkdown70 B
evals/w02-row-set-refusal/prompt.mdmarkdown251 B
evals/w03-hermetic-hud-script/graders/announcement-on-stderr.mdmarkdown84 B
evals/w03-hermetic-hud-script/graders/bom-less-utf8.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/captures-both-streams.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/drain-barrier-or-wait.mdmarkdown96 B
evals/w03-hermetic-hud-script/graders/frame-after-pending.mdmarkdown204 B
evals/w03-hermetic-hud-script/graders/isolated-state-directory.mdmarkdown76 B
evals/w03-hermetic-hud-script/graders/pixel-versus-replay-proof.mdmarkdown108 B
evals/w03-hermetic-hud-script/graders/skill-fired.mdmarkdown36 B
evals/w03-hermetic-hud-script/prompt.mdmarkdown224 B
evals/w04-cooldown-rule/graders/authored-as-puck.mdmarkdown138 B
evals/w04-cooldown-rule/graders/boots-the-source.mdmarkdown76 B
evals/w04-cooldown-rule/graders/compiled-in-memory.mdmarkdown143 B
evals/w04-cooldown-rule/graders/folds-through-the-rule-frame.mdmarkdown170 B
evals/w04-cooldown-rule/graders/gate-on-tick.mdmarkdown68 B
evals/w04-cooldown-rule/graders/names-the-mutation-kinds.mdmarkdown140 B
evals/w04-cooldown-rule/graders/no-decrementing-remainder.mdmarkdown97 B
evals/w04-cooldown-rule/graders/remove-sugar.mdmarkdown71 B
evals/w04-cooldown-rule/graders/row-set-is-not-authoring.mdmarkdown109 B
evals/w04-cooldown-rule/graders/schedule-sugar.mdmarkdown73 B
evals/w04-cooldown-rule/graders/skill-fired.mdmarkdown36 B
evals/w04-cooldown-rule/graders/targets-the-debug-world.mdmarkdown215 B
evals/w04-cooldown-rule/prompt.mdmarkdown239 B
evals/w05-gcp-storage-provider/graders/assembly-attribute.mdmarkdown82 B
evals/w05-gcp-storage-provider/graders/catalog-in-a-running-host.mdmarkdown83 B
evals/w05-gcp-storage-provider/graders/duplicates-refused-by-name.mdmarkdown149 B
evals/w05-gcp-storage-provider/graders/extension-model-laws.mdmarkdown79 B
evals/w05-gcp-storage-provider/graders/installed-not-referenced.mdmarkdown171 B
evals/w05-gcp-storage-provider/graders/mcp-services-provider.mdmarkdown188 B
evals/w05-gcp-storage-provider/graders/no-own-directory-scan.mdmarkdown84 B
evals/w05-gcp-storage-provider/graders/no-per-kind-interface.mdmarkdown87 B
evals/w05-gcp-storage-provider/graders/no-static-registry.mdmarkdown74 B
evals/w05-gcp-storage-provider/graders/one-extension-project.mdmarkdown105 B
evals/w05-gcp-storage-provider/graders/one-hosted-control.mdmarkdown85 B
evals/w05-gcp-storage-provider/graders/registers-through-add-storage.mdmarkdown141 B
evals/w05-gcp-storage-provider/graders/skill-fired.mdmarkdown36 B
evals/w05-gcp-storage-provider/prompt.mdmarkdown246 B
evals/w06-agent-harness-on-azure/graders/agent-harness-participant.mdmarkdown71 B
evals/w06-agent-harness-on-azure/graders/body-five.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/default-azure-credential.mdmarkdown79 B
evals/w06-agent-harness-on-azure/graders/deliberate-approval.mdmarkdown89 B
evals/w06-agent-harness-on-azure/graders/extensions-document.mdmarkdown84 B
evals/w06-agent-harness-on-azure/graders/grants-in-the-world.mdmarkdown162 B
evals/w06-agent-harness-on-azure/graders/installs-beside-each-host.mdmarkdown156 B
evals/w06-agent-harness-on-azure/graders/local-config-flag.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/no-key.mdmarkdown60 B
evals/w06-agent-harness-on-azure/graders/participant-laws.mdmarkdown86 B
evals/w06-agent-harness-on-azure/graders/participant-settings.mdmarkdown175 B
evals/w06-agent-harness-on-azure/graders/principal-not-console.mdmarkdown114 B
evals/w06-agent-harness-on-azure/graders/silo-extension-laws.mdmarkdown83 B
evals/w06-agent-harness-on-azure/graders/silo-row-extensions-member.mdmarkdown125 B
evals/w06-agent-harness-on-azure/graders/skill-fired.mdmarkdown36 B
evals/w06-agent-harness-on-azure/graders/status-line.mdmarkdown103 B
evals/w06-agent-harness-on-azure/prompt.mdmarkdown202 B
evals/w07-failed-build-stale-binary/graders/build-exits-zero.mdmarkdown104 B
evals/w07-failed-build-stale-binary/graders/documented-recipe.mdmarkdown114 B
evals/w07-failed-build-stale-binary/graders/hermetic-state-dir.mdmarkdown68 B
evals/w07-failed-build-stale-binary/graders/old-binaries-ran.mdmarkdown170 B
evals/w07-failed-build-stale-binary/graders/reports-the-run.mdmarkdown76 B
evals/w07-failed-build-stale-binary/graders/same-script.mdmarkdown72 B
evals/w07-failed-build-stale-binary/graders/says-no.mdmarkdown91 B
evals/w07-failed-build-stale-binary/graders/skill-fired.mdmarkdown36 B
evals/w07-failed-build-stale-binary/prompt.mdmarkdown261 B
evals/w08-gpu-grant-held-by-parity/graders/build-exit-zero-first.mdmarkdown129 B
evals/w08-gpu-grant-held-by-parity/graders/build-runs-beside-the-leg.mdmarkdown153 B
evals/w08-gpu-grant-held-by-parity/graders/effective-presentation-modes.mdmarkdown118 B
evals/w08-gpu-grant-held-by-parity/graders/headless-runs-now.mdmarkdown171 B
evals/w08-gpu-grant-held-by-parity/graders/headless-world-is-not-gpu-work.mdmarkdown142 B
evals/w08-gpu-grant-held-by-parity/graders/self-excluding-search.mdmarkdown166 B
evals/w08-gpu-grant-held-by-parity/graders/skill-fired.mdmarkdown36 B
evals/w08-gpu-grant-held-by-parity/graders/windowed-waits-for-a-grant.mdmarkdown121 B
evals/w08-gpu-grant-held-by-parity/prompt.mdmarkdown279 B
evals/w09-live-world-mcp/graders/camera-read-back.mdmarkdown76 B
evals/w09-live-world-mcp/graders/lists-the-worlds.mdmarkdown68 B
evals/w09-live-world-mcp/graders/names-the-world.mdmarkdown178 B
evals/w09-live-world-mcp/graders/own-world-for-worktree-edits.mdmarkdown222 B
evals/w09-live-world-mcp/graders/restores-the-mutation.mdmarkdown174 B
evals/w09-live-world-mcp/graders/skill-fired.mdmarkdown36 B
evals/w09-live-world-mcp/prompt.mdmarkdown360 B
evals/w10-bounded-diagnostic-report/graders/bounds-and-running.mdmarkdown542 B
evals/w10-bounded-diagnostic-report/graders/snapshot-and-hold.mdmarkdown453 B
evals/w10-bounded-diagnostic-report/prompt.mdmarkdown547 B
evals/w11-reload-delta/graders/delta-and-drain.mdmarkdown1.1 KB
evals/w11-reload-delta/prompt.mdmarkdown735 B
references/addons.mdmarkdown32.7 KB
references/adjacency-and-federation.mdmarkdown55.7 KB
references/authority.mdmarkdown40.0 KB
references/console.mdmarkdown58.5 KB
references/documents-composition.mdmarkdown34.4 KB
references/documents-identity.mdmarkdown19.4 KB
references/documents-motion.mdmarkdown37.2 KB
references/documents-render.mdmarkdown40.5 KB
references/documents-rules.mdmarkdown27.4 KB
references/documents-state.mdmarkdown59.2 KB
references/documents.mdmarkdown21.1 KB
references/engagement.mdmarkdown50.6 KB
references/hosting-and-release.mdmarkdown31.1 KB
references/hud.mdmarkdown33.4 KB
references/mutations.mdmarkdown36.4 KB
references/ordered-domain.mdmarkdown14.6 KB
references/replay.mdmarkdown69.7 KB
references/schedules-and-tests.mdmarkdown26.4 KB
references/session-lifecycle.mdmarkdown15.0 KB
references/views.mdmarkdown54.8 KB

references/addons.md

View on GitHub
# Addons — the WebAssembly guest runtime

A `WorldAddonRow` in the world document's `addons` section mounts a
deterministic WebAssembly guest. World-side runtime:
`src/Puck.World.Addons/WorldAddonRuntime.cs` + `WorldAddonWire.cs`, behind the
`IWorldAddonHost` seam `src/Puck.World.Server/IWorldAddonHost.cs` declares.
The ABI itself (cell layouts, exports, mount steps, determinism posture) is
owned by `docs/reference/scripting.md` (`src/Puck.Scripting/README.md` links it) — read it before touching the guest
boundary; this file carries the World-relevant surface.

The addon system exists for player-built mods (the owner's ruling). The debug
world's addons (watchdog, guide, fuzzer, traversal, scope, machine debugger)
are stress tests of that platform, chosen to exercise it, so judge a change by
what a mod author and an untrusted mod need: authoring, safety, budgets,
determinism and cost. The addon system is improved as it is used (the owner's ruling). A lane that
finds a meaningful gap or refinement while writing or running a guest (a
missing event, query or mutation kind, an awkward authoring path, a diagnostic
it lacked) fixes it in the same change or records it in
`docs/plans/open-items.md`. It never works around the gap inside the guest.

For nondeterministic providers and external side effects — extension hosting,
Azure's ARM provider, storage confinement, and configured collection reads —
read `src/Puck.World.Server/Extensions.md`, `src/Puck.World.Server/ExtensionHosting.md`,
`src/Puck.World.Server/ExtensionConfiguration.md`, and `src/Puck.World.Azure/README.md`;
those documents are the owning home for that surface, not this file. The one
addon-relevant fact those documents don't carry: `IWorldAddonHost` extends
`IWorldExtensionRuntime` with `Recomputed` policy, and `WorldRecordedExtension`
uses recorded mutation ingress and the same `WorldCapabilityRequest` matcher an
addon's own grants go through — so an addon and a configured extension share
one capability-disclosure vocabulary even though they mount through different
doors.

## Contents

- The row, mounting, and the prepare/commit transaction
- The three pump points
- Channels and the wire
- Requests, queries, verdicts
- Fuel
- Receipts and replay
- Verbs
- World events
- The shipped examples
- Puck.Scripting in one paragraph

## The row, mounting, and the prepare/commit transaction

`WorldAddonRow(Name, ModulePath, Hash, Fuel, Enabled, Requests?,
MemoryWatches?, Revision)`. `Hash` is REQUIRED (`sha256/<64 lowercase hex>`): an
unpinned guest makes state depend on a file on disk — a determinism hole
before a security one. The hash is verified BEFORE descriptor decode, so
the pin covers the channel table too; a mismatch is a load fault. Source-size and pin checks
precede WAT conversion and compilation. Both the authored integrity pin and compile cache use
the full SHA-256 identity. One 16 MiB memory and one bounded table are admitted;
hidden extra resources cannot multiply that budget. The
[scripting resource contract](../../../../docs/reference/scripting.md#loading-ticking-faulting)
owns the exact limits and native-compiler limitations. `WorldAddonLimits` bounds the
document's addon count, individual and total fuel, total manifest requests and total
memory watches, including disabled rows. A zero fuel declaration is charged at the
ABI default. `WasmModuleLoader` admits only `AddonModuleLimits.ConcurrentCompilations`
source loads/conversions/compilations process-wide; capacity refusal can be retried
after another load finishes, and every failure releases its slot. `Revision`
(`ulong`, default 0) is the instance-revision token: any change from what a
currently-mounted guest was prepared under means fresh guest instantiation,
even when every other field is unchanged — the document-authored equivalent
of a reload. It is NOT promised monotonic (undo and a whole-document load
legitimately move it backward — configuration undo, not time travel: the
pre-undo guest's memory is not part of the document and is never restored);
an author driving it forward is expected to increment with checked overflow.

**A guest may be WebAssembly text.** A `.wat` module is source: commit it and
no compiled `.wasm` beside it (the debug world's guests are
`worlds/debug/addons/*.wat`). `hash: "auto"` pins the module's source bytes at
compile time, the bytes the loader checks before converting them, so editing
the text moves the pin; the compile-time contract check reads binaries only,
and a text guest's exports and imports are checked when it mounts. A guest's
grants are authored rows like any other: each imported module may author its
own, since grant rows compose by their `(grantee, capability, subject)` triple.

The guide's exhibit copy is authored in `worlds/debug/guide.puck`, not in its
WAT: `guideCopy` lowers to `guideExhibits`, whose `<ordinal>-title` and
`<ordinal>-note` cells follow the manifest's region order. `ReadStateText`
completions carry `Applied` (10), unlike an Ask's allowed-hold verdict (1–3).
Assemble chunks before decoding or JSON-escaping: a multi-byte UTF-8 scalar
can cross a 16-byte chunk boundary. A scratch source edit and a headless
`world.state guide` read show changes without editing or rebuilding the guest.

The addon finish phase suppresses successful mount/disclosure confirmations
while `WorldExtensions.IsReplaying`; it still retires superseded instances.
An offline verification reports refusal or drift instead of narrating a
second boot. Do not suppress stderr globally: preparation faults and replay
diagnostics must remain visible.

**The doors are `world.row.set addons <row-json>` / `world.row.remove addons
<name>`** — the ordinary document-mutation pipeline (`WorldMutation.UpsertAddon`/
`RemoveAddon`), nothing else. There is no separate runtime-facing lifecycle
surface: mounting, unmounting, reloading, enabling, and disabling an addon are
all expressed through the SAME row, gated by `Enabled` and `Revision`. Mounting
a guest — compile under the pin, ABI admit, instantiate, run `puck_init` — is
prepared as the addon runtime's own half of `IWorldAddonHost.TryPrepare`, the
LAST fallible gate `WorldServer.TryApplyMutation` runs (after authority,
compose, whole-document validation, capacity, and solids). A LIVE mutation
reaches it only when it touches the `addons` section (`UpsertAddon`/
`RemoveAddon` — every other mutation kind never calls it); a whole-document
swap (`world.reset`/`.load`/`.reload`, and the final step of `world.undo`)
reaches it UNCONDITIONALLY, because any section can move a channel-table
dependency the row-level predicate cannot see. Preparation builds a
disposable, uncommitted `PreparedAddonInstall` covering the WHOLE runtime
delta (every guest the candidate document would mount, plus the complete
replacement `AddonHost` registry and, when the candidate's channel
declarations moved, a freshly staged channel table and host). A row reuses
its guest — memory AND fault state alike — only when it is STRUCTURALLY
equal to the row that guest was last prepared under (every field, including
`Requests`/`MemoryWatches` content) AND the channel table is unchanged;
runtime fault state never participates, so a sticky-faulted guest stays
faulted until ITS OWN row's structural identity moves, and resubmitting an
identical row never resets a healthy guest's memory either. A channel-table
change replaces every enabled row's guest at once, even one that compares
structurally equal to its own prior self. `IWorldAddonHost.Commit` then
publishes the whole plan by reference adoption alone — no I/O, allocation,
compilation, or fallible call; narration and superseded-guest disposal wait
for a separate `Finish` call the caller makes only after its own
document/journal publication is itself durable. An enabled row that cannot
prepare refuses the WHOLE mutation (or rebuild, or undo), the candidate
discarded, the live document byte-identical, the tick surviving. A server
with no addon host attached refuses an addon-affecting mutation by name
rather than accepting it with no effect. A disabled row is never compiled —
it reports `DISABLED` in `world.addons` (see "Verbs" below) but has no
runtime entry.

Boot uses the identical contract: `WorldAddonRuntime.TryCreate(definition, server)`
(called AFTER the `WorldServer` constructor has applied the document's grant
rows, so the mount-time disclosure reports a settled table) runs `TryPrepare`
against no prior state and `Commit`s it — an enabled row that cannot prepare
refuses the whole world installation rather than silently booting without it.
The composition root (`WorldPostBuildWiring.Install`) resolves the runtime
explicitly and turns that refusal into an ordinary attributed boot refusal
(stderr line, clean non-crashing exit) — the same `false` + printed-reason
shape every sibling boot gate uses; `Create` is the throwing wrapper
`TryCreate` powers for the one caller (the replay tape's `addonHostFactory`
delegate) that must return a value or throw. `world.undo` joins the same door: every addon-bearing
intermediate journal candidate is proved via a throwaway prepare-and-dispose
probe before the kept prefix is accepted, and the FINAL restored document runs
one real prepare-and-commit: a kept journal entry whose pinned module has gone
missing refuses the WHOLE undo. Per-row gates inside a prepare pass: enabled →
compile under the pin → the Response-channel gate (a row with `Requests` but no
Response channel refuses — no verdict could ever reach it) → the
capability-disclosure line (staged as a thunk — evaluated only at `Finish`,
against whatever grant table is live when it prints, so a rebuild's disclosure
reads the candidate's own newly-installed grants)
→ `Admit()` (runs `puck_init` under fuel, against the staged guest's own
private memory only — no host imports, contributions, handles, or output
escape) → receipt. Mount order is document order. The Wasmtime host is
constructed lazily on the first prepare pass that actually needs one (an
addon-free world pays nothing); a discarded plan disposes only the host IT
itself constructed, never one it merely reused.

**Narration waits for committed state.** Mount/disclosure thunks are staged
during prepare. `Finish` evaluates and prints them after `Commit` and the
caller's document/grant publication, so capability disclosure reads the
installed grants. A refused prepare prints no mount claim.

When a narrated mount has requests or holds, its disclosure reports requested vs
granted vs withheld vs `holds beyond its manifest (inert — never
materialized)`. **Requesting is not receiving** (deny-by-default regardless of
manifest), and **a hold outside the manifest mints no handle** — authority
materializes only at `requested ∧ granted`. See [authority.md](authority.md)
for the untrusted class rules (budgets required, handles, reach masks, no
wildcards).

`Observe/all` in a manifest covers concrete Observe holds; it grants nothing by itself.
The mount report and event dispatch share `WorldAddonRuntime.CanReach`: granted lists
the concrete held subjects within manifest reach, withheld lists requests reaching no
held subject, and inert lists holds outside manifest reach. Region and link events use
-1 when admitted through the wildcard without a named manifest entry; named indices
still follow unique manifest requests, including ungranted requests.

## The three pump points

Guests are pumped ONLY from inside `WorldServer.Step`, at three pinned
points — which is what keeps guest driving reproducible under replay
WITHOUT recording it (the tape pins receipts and re-runs the guests):

1. `TickAddons` — first guest pump, after recorded contributions have entered
   the ordered mutation door but before edits apply: compose the input batch (tick
   cell, then last tick's staged pending), run `puck_on_tick`, decode and
   vocabulary-validate. APPLIES NOTHING.
2. `ApplyContributions` — after the intent drain: resolve Drive handles,
   check authority, fold acts per body, submit through the same
   `ApplyIntentSubmission` path seats use (on a human-occupied body the
   contribution enters the co-driving pool; on an unoccupied body it
   overwrites).
3. `ResolveReads` — after the population advances: disclosures → asks →
   queries, merged (budgeted, multi-part answers atomic) into the NEXT
   tick's batch, so a verdict, a minted handle, and a pose all describe the
   same settled instant.

## Channels and the wire

`AddonChannelKind`: `Input = 1`, `Request = 2`, `Response = 3` (ordinals 4
and 5 are unassigned; a descriptor naming them refuses the mount). Pairing
rules: Request without
Response (or vice versa) refuses; declaring Input requires the
Request+Response pair (disclosures ride Response — an Input-only guest is
provably inert).

`WorldAddonChannelResolver` (in `WorldAddonWire.cs`) is the ONE place guest channel
names meet the world's `WorldChannelTable`: the guest addresses its own
declared name table by position; resolution returns the world ordinal (every
declared channel occupies its consecutive document-order slot, and role claims
are table metadata; the guest's index and the world's ordinal are separate
namespaces, so a contribution is written only through the resolved ordinal); unresolved is a `-1` sentinel and the declaration is reported inert,
never a mount fault. `Fold` writes `FixedQ4816.FromRawBits(act.Value)`
verbatim — the world channel's convention IS the wire convention, no
negation, no remap. `Submit` splits role ordinals into
`IntentSubmission.Intent` and composition ordinals into `HeldChannels`
(the same split `SeatController` uses). Every channel is per-tick
declarative — the host holds no cross-tick channel state; a guest that
stops emitting reads zero next tick.

## Requests, queries, verdicts

Output cells are `Act` (drive) or `Ask` (request a handle). The request
vocabulary (`Puck.Scripting.AddonAbi.RequestVerbs`) is closed — `AddonAbi.cs`
is the one authoritative member list; do not restate its size here, since a
new verb is prefix growth the ABI pin never bumps for. Its members today:
`BodyPose` (a query, no arguments, producing `BodyPoseAnswerParts` answer
cells), `SubmitMutation` (a guest holding a Mutate handle over a document
section acts through it with a JSON payload — the request cell's `A`/`B`/`C`
lanes carry the mutation-kind ordinal, an unsigned guest-memory pointer, and a
byte length — rather than a query; producing `SubmitMutationAnswerParts`
answer cell), and `Designate` (a guest acts through a Drive handle over its
OWN source body to designate a target: `A` is the target body index, `B` the
target-register index, `C` zero; producing `DesignateAnswerParts` answer
cell). `RequestVerbs.Count` bounds a guest's declared `VerbCount`, which may
be any non-empty prefix of the vocabulary — growing the vocabulary must never
refuse a guest built against fewer verbs.
**A guest CAN edit the document at the ABI/authority level** — this is not
withheld/inert. `Addons.WorldAddonMutationDecoder` wires 12 of
the declared kinds today: the 5 HUD kinds
(`UpsertHudPanel`/`RemoveHudPanel`/`UpsertHudElement`/`RemoveHudElement`/
`SetHudDefaults`, ordinals 39-43), the 2 placement kinds
(`UpsertPlacement`/`RemovePlacement`, ordinals 19-20 — the FULL
`WorldPlacement` wire shape the document validator accepts: transform
(position/yawDegrees/scale), repeat, mirror, emission, solid, inhabit,
faceSources — each face read through the document's own `WorldPlacementFace`
contract (every source arm, `portal` and `filter`), repeated keys refused —
region, and attach), the 2 state kinds
(`UpsertStateRow`/`RemoveStateRow`, ordinals 44-45, every non-generator
`WorldStateRow` variant: int/fixed/bool/text), the 2 state-cell kinds
(`UpsertStateCell`/`RemoveStateCell`, ordinals 47-48), and `SetInputHold`
(ordinal 46). Every OTHER declared `WorldMutation` kind still
decodes to `AddonMutateRefusal.DecodeFailed` → `Verdict::MalformedPayload`
regardless of grants or verb masks — a decoder gap, not an authority one;
wiring a new kind in is additive (a new `case` arm), never a change to the
decoder's own contract. The decoder's own division of labor: it turns wire
JSON into TYPED values and enforces a row's own intrinsic shape invariants
(a rect's width must be positive, a region's numbers must be finite (the
validator owns their positivity), a repeat's counts must be at least 1) — cross-referencing checks
that need the whole document (does `creationId` resolve, does a `state` row's
`Min`/`Max` pair validate, does a placement's `scale` sit inside the
authoring envelope) stay with `WorldDefinitionValidator`, exactly like the
HUD arms already left capacity/authoring checks to it.

Development tools extend this surface without changing ABI 1. `BodyKinematics`
(request 3, Observe/Body) reads height, world vertical speed, body facts and
grounded/obstruction witnesses in two cells. `ReadStateCell` (4) reads a numeric
cell through an Observe/State handle, acquired by a named `State` Ask (wire
kind 5). `Log` (5) emits up to eight attributed 2048-byte UTF-8 lines per guest per tick
into the World's `host.log` ring. State names and keys use strict UTF-8;
numeric values remain raw fixed-point or integer values. `BodyPoses` (13) reads an ordered
array of Observe/body handles into guest memory, one 64-byte pose/verdict record per handle,
with one completion cell instead of four cells per body. It shares each body's Observe budget
with individual reads and prepays bounded host fuel; the watchdog uses it for every observed
body every tick. ReadStateText (6) provides bounded text chunks; vector reads remain an open gap. The [ABI reference](../../../../docs/reference/scripting.md#request-channelquery-acts-through-a-handle)
owns the exact layouts and remaining-fuel charges.

The decoder also serves `UpsertStateCell`/`RemoveStateCell` (47/48), through
the same typed mutation, Edit/state grant, kind mask, dispatch/byte budgets,
receipt and replay paths as whole rows. Payloads are `{row,key,kind,value,text?}`
for an upsert (`kind` is `set` or `add`; numeric `value` is required), and
`{row,key}` for a removal. Repeated and unknown JSON members refuse.
`ObservationVerbs` (`AddonAbi.cs`, again the one authoritative list) is
`GrantedBody` — the disclosure of a minted handle over a granted body, not an
event — plus the world-events verbs the "World events" section below
documents in full: region enter/exit, seat join/leave, collision begin/end,
control-application engaged/disengaged, federation link established/dropped
(`EventLinkEstablished`/`EventLinkDropped`), machine-memory-changed (the one
ADDON-scoped family beside the five WORLD-scoped ones "World events" names),
and the per-mount `EventGap` overflow summary.

Ask resolution gates on the manifest BEFORE subject inspection — an
unrequested or out-of-range ask answers `AttenuatedToEmpty`, never
`NoSuchSubject` (which would be a body-enumeration oracle). Query order:
resolve handle → `IsRequested` → `Allows` → budget → dispatch. A state read
(`ReadStateCell`, `ReadStateText`) dispatches through `TryReadDisclosed`, which asks
`WorldRecipientView.Discloses` for the addon's live capability. Hidden and absent cells both
answer `NoSuchSubject`. Binding or writing a cell asks `WorldRecipientView.Admits` before
key resolution, under the same whole-row policy as every mutation and guard. A row that can
withhold any member refuses every key with `NotDisclosed`, including absent and readable keys;
Edit and Mutate grants never override disclosure. A bound address caches no policy decision.
`AddonVerdict`: `None`, `HeldConcrete`, `HeldWildcard`, `HeldAsReserver`,
`NoHold`, `BeatenByReserver`, `AttenuatedToEmpty`, `NoSuchSubject`,
`QuotaExhausted`, `StaleHandle`, `Applied`, `MalformedPayload`,
`PayloadTooLarge`, `Rejected`, `NotDisclosed`. An outer cell or ABI malformation faults the
whole batch and sticks the instance; a `SubmitMutation` pointer/JSON fault is
localized to `MalformedPayload` or `PayloadTooLarge`, and an authority denial
answers with its verdict cell. Starvation is not denial (a starved ordinal is
retryable). Handle pairs validate at APPLICATION, never at decode. The
`addon.mutate` refusal catalog declares 11 reasons and maps each to this wire
vocabulary through `AddonMutateRefusals.ToVerdict`. An addon's applied
mutation narrates on the console like any other but raises no toast
(`WorldToastPolicy`) and no
`mutation.applied` cue (`WorldPostBuildWiring`'s echo tap), since a guest may
write every few ticks; its refusals still toast.

`AddonCapabilityMask` bits: `Drive = 1<<0`, `Observe = 1<<1`,
`Control = 1<<2`, `Mutate = 1<<3`, `Edit = 1<<4`; any other bit in an Ask resolves
to no capability.

## Machine debugging

The generic debugger is authored in [machine-debugger.puck](../../../../worlds/debug/machine-debugger.puck)
and [its WAT guest](../../../../worlds/debug/addons/machine-debugger.wat); its runtime
configuration and agent recipe are in [the debug addon guide](../../../../worlds/debug/addons.md#machine-debugger).
It starts idle, draws no panel, and tests every hosted arcade device through an engaged
body. Runtime byte probes, RAM hashes, bounded checkpoints and provider operations use
Screen Observe/Control handles; engagement uses Drive/Body plus Control/Screen.
The [scripting ABI](../../../../docs/reference/scripting.md) owns request ordinals 6–12.
Reuse ReadStateCell and Log rather than adding another numeric/log protocol.

A runtime text payload is not an asset reference and test staging cannot relocate a
path embedded inside it. Use MachineOperation's contentName to reuse the existing
content-folder resolver; never bake a staged path into a guest. Report operation refusals
with the provider's reason. Checkpoints stay mount-local, bounded and tied to one runtime.

## Fuel

Per-row `Fuel` (0 → `AddonAbi.DefaultFuelPerTick` = 1,000,000). Measured
every tick regardless of outcome (determinism); totals saturate — a
lifetime figure that survives an unrelated reprepare pass reusing this guest
untouched (including a resubmission of the byte-identical row), and also
survives a sticky fault (a faulted guest is reused, not rebuilt, by an
unrelated reprepare pass — see "The row, mounting, and the prepare/commit
transaction" above), but resets for a guest a reprepare actually
re-instantiated (a `revision` bump or any other structural row change),
since that is a genuinely fresh instance. Exhaustion traps deterministically
→ `OutOfFuel`, a sticky fault: the guest is skipped every tick until its own
row's structural identity moves (bump `revision`, or change any other
field) — resubmitting the byte-identical row never restarts it. Fuel bounds
a guest's compute and charged host query work, never its authority. Host queries debit the same store's remaining fuel and contribute to last/peak/total counters.

## Receipts and replay

`WorldAddonReceipt(Name, Hash, Fuel)` — taken from the INSTANCE that
mounted, never the row; only guests that reached the admitted set get one.
The replay tape pins the receipts at record-start (and Drive re-checks them
before tick zero on every re-drive) and refuses a re-drive whose fresh
mounts disagree (see [replay.md](replay.md)). The ABI and replay format
admit only their current build's shape. Re-record tapes after changing their
layout or execution semantics; do not preserve obsolete fields or add
development version histories. A changed guest hash is independently
refused by the receipt comparison. A live `world.row.set addons`/`world.row.remove addons` mutation
is captured and re-executed on replay through the ordinary tape-covered
mutation leaf (see [replay.md](replay.md)'s mutation-outcome pin) — there is
no separate lifecycle leaf left to reason about arming against.

A post-boot `replay.record`, including one sent over MCP, captures live guest
memory and host continuations with the surrounding authority state. Arming never
replaces guests, pending answers or input controllers. Recording, history and
persistence share `IWorldAddonHost`'s mandatory checkpoint boundary:
memory, private numeric globals, fault/fuel state and the mount's cross-tick host
state. The [runtime README](../../../../src/Puck.World.Addons/README.md#durable-guest-state)
owns its inventory and named unsupported-resource refusals. Silo activations
mount through the same `WorldAddonRuntime.TryCreate` as World, and restore this
section before replaying their journal tail. Arming before the first step
uses the boot image as before. `replay.drive` prepares fresh guests for either
kind of recorded start, then restores the captured guest image when present.

When piping the startup script, close stdin after the replay arm. Headless
startup drains that script before stepping; leaving the pipe open waiting for
more lines holds mutations at tick zero even though control reads already
answer. Continue through the named World's MCP attachment, then quit it there.

## Verbs

- `world.row.set addons <row-json>` / `world.row.remove addons <name>` — the
  ONE door. `Enabled` and `Revision` express the whole lifecycle: an absent
  row is unmounted; an `Enabled: false` row is disabled (never compiled); a
  STRUCTURAL change to an already-mounted, still-enabled row (content,
  `Revision`, or any other field — including `Requests`/`MemoryWatches`
  content) is a reload — fresh guest instantiation, memory wiped, lifetime
  fuel counters restarted; resubmitting the byte-identical row is a no-op
  for the runtime (the existing guest, healthy or faulted, is reused
  untouched). Buffers and applies at the tick boundary like any mutation;
  the addon-prepare gate (see above) is the LAST fallible step, so a bad
  row's refusal is loud, names the reason, and leaves the document (and the
  mounted set) untouched.
- `world.addons` — Immediate, ungated: one segment per DOCUMENT row, in
  document order — the joined configuration/runtime read-back, never a
  mounted-guest-only enumeration. A disabled row reads `DISABLED` with no
  cost figures; an enabled row always reads
  `<name> <ENABLED|FAULTED(detail)> fuel-budget fuel-last-tick fuel-peak-tick fuel-total
  answers-dropped-total` — the cost surface — because an enabled row that
  cannot prepare refuses the whole mutation/rebuild/boot that would have
  installed it, so the document and the runtime can never disagree about
  what is actually mounted.

## World events

The host delivers world events as host-written `Observation` cells (verbs
1-12 on `AddonAbi.ObservationVerbs`, prefix growth beside `GrantedBody` —
the ABI pin never bumps). Five families are WORLD-scoped, collected once per
tick by `src/Puck.World.Server/WorldEventFeed.cs` after the population settles: seat
join/leave, region enter/exit (a placement's `WorldPlacementRegion` facet —
a named sphere or oriented box, addressed by the carrying placement's own `Id`; the cell's `B`
is the region's position among the guest's own `Observe/region:` requests, in
manifest order, so a guest's table of regions follows its row), collision
pairs (a flat proximity test, independent of physical contact resolution),
control-application engaged/disengaged, and
federation link established/dropped.
Application edges are queued from `WorldGrants`' own set writes, so every
member added or removed fires one — including the context-button auto-engage
and a revoke-driven dissolution. Link edges compare a per-adjacency staleness
count against that row's authored `livenessGraceSeconds` (`0`, the default,
disables the row's sensing entirely, so an unauthored world emits none). The
server feed retains document ordinals internally; at the guest boundary `A`
is the adjacency's 0-based index among the manifest's unique
`Observe/adjacency:<name>` requests. Duplicate requests retain their first
index and ungranted requests still occupy their slot, so a grant change never
renumbers the guest's table. A wildcard-only observation carries -1 because it
supplies no named entry. `B` is the staleness in simulation ticks on a drop and
`0` on an establish. The sixth,
machine-memory watches, is ADDON-scoped (`WorldAddonRow.MemoryWatches`, each
a `(screen, address, length)` row) and reads `Server.WorldMachineHost`
DIRECTLY (`WorldMachineHost` implements `IWorldMachineMemoryPeek` itself,
reached through the always-present `WorldServer.Machines`) —
**publishes in every boot shape**: machines boot and step server-side,
headless included.

A family materializes for a guest through the SAME requested ∧ granted rule
every other capability here uses: `WorldAddonRuntime.EventGate`
(`WorldAddonRuntime.Events.cs`) checks `IsRequested ∧ Allows ∧
TryGetEventBudget`, then reports the family `Available` or `Exhausted`
against the per-subject event count. The gating subject IS the
family — `Observe/body:<n>` (collision + route), `Observe/region:<name>`
(enter/exit), `Observe/seat:<n>` (join/leave), `Observe/screen:<n>`
(machine-memory), `Observe/adjacency:<name>` (link established/dropped —
the authored `adjacencies` row's own name, Region's federation-seam twin) —
legitimate for UNTRUSTED principals only (no trusted
principal reads Observation cells). `WorldGrant.EventBudget` is a SIBLING of
`Budget` on the same row: the edges a tick may deliver for that subject, each
delivered edge charging the first qualifying row; it is REQUIRED (with
`events:<n>` on `world.grant`) for
`screen:`/`region:`/`seat:`/`adjacency:` subjects — which still ALSO need the
pre-existing `budget:<n>` untrusted-Observe requirement, since that door
does not know a subject carries no query verb — and OPTIONAL on `body:<n>`.

**Overflow behavior: ordered prefix, drop-newest, per-mount
gap counter.** `EmitEvents` writes edges into whatever ring room remains
after reservations/disclosures, in `WorldEventFeed`'s pinned collection
order; once the ring runs out, the rest of that tick's qualifying edges
drop and a per-mount saturating `EventGapCount` increments. An `EventGap`
cell (verb 10) reports the count at most once per batch, only when it moved
since the last report and room remains; otherwise the current count is
reported by the next batch with room. An edge whose every qualifying row has
spent its `EventBudget` this tick drops into the same gap count.

Four of the five families are never taped — they re-derive from sim state
during replay. The link family is the exception: whether a neighbour
delivered is transport ingress no sim state determines, so the tape carries a
`LinkDelivery(adjacencyName)` entry per refreshed row per tick and the
re-drive feeds it through the same `WorldEventFeed.ObserveLinkDelivery`
entry point the live poll uses. The delivered CONTENT is still absent, so a
replay reproduces WHEN a seam went dark and never what the neighbour showed.
`world.grant`/`world.revoke`, which do ride the tape, carry
`GrantSubjectKind.Region`/`Seat` and `WorldGrant.EventBudget` through the
shared grant leaf.

## The shipped examples

The debug world mounts six WebAssembly-text guests, each in its own module
([worlds/debug/addons.md](../../../../worlds/debug/addons.md)): the watchdog
(`watchdog.puck`), which checks invariants every tick and records violations
in state rows; the gallery guide (`guide.puck`), which names the exhibit the
Moth stands at through region events; and the companion (`companion.puck`),
which follows her through Drive and pose queries. The optional fuzzer,
traversal bot and kinematics scope demonstrate seeded driving, authored
numeric reads, kinematics, bounded logging and per-cell mutations. All three
start off; addon HUD panels additionally require `addonHud` to be 1. They are the worked
examples of a hand-written guest: the cell layouts, a Section ask, pose
queries, region and collision events, and `SubmitMutation` of whole state
rows, with no toolchain beyond the engine.

`wasm/puck-addon-default/dist/puck-addon-default.wasm` (source under
`wasm/puck-addon-default/`) — no world mounts it; its logical module derives from its
crate through the counted `DerivedBytes` cache, ready to author into any world's `addons` row: the
dead-reckoning clamp-walk ghost — consumes the `GrantedBody` disclosure for
a Drive handle, asks for Observe, dead-reckons off pose answers, and emits
NOTHING when no pose is held (a refused grant leaves the ghost standing,
not guessing). Boot it into action with
`world.grant addon:default drive body:1 budget:60` plus
`world.grant addon:default observe body:1 budget:60` (both untrusted
budgets are required). Its `Mutate/section:kits` request is the worked
withheld-request example.

## Puck.Scripting in one paragraph

`docs/reference/scripting.md` is the single home of the ABI contract:
cell/descriptor byte tables, the guest exports, the ten-step mount order,
the per-tick batch order, fault-vs-verdict postures. Determinism: Wasmtime
pinned EXACTLY (the package version is the native engine version; fuel
accounting is codegen-dependent, so a silent bump can move the
fuel-exhaustion tick and break stored replays — the pin never floats);
every knob explicit (fuel on, threads/SIMD off, NaN canonicalization on);
NO host imports (`AddonModuleValidator` refuses any import, keeping guests
runnable in any wasm runtime); no float crosses the boundary
(`FixedQ4816` raw i64).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall