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/mutations.md

View on GitHub
# The mutation substrate

One pipeline for ALL durable change. A `WorldMutation`
(`src/Puck.World.Protocol/Protocol/WorldMutation.cs`) is a closed union of nested
sealed records — one coarse record per `WorldDefinition` section, addressed by
stable id, whole-row upsert, never a field poke. A genre world arrives as
different DATA through these same messages, never a new message shape.

`Batch` can carry a full `expectedDefinition` fingerprint, named placement/state `expectedInputs`, bounded
three-dimensional `expectedSpatialReads`, and numeric `expectedCells` comparisons evaluated at commit time.
Spatial reads include referenced state values and catch new or moved blockers entering the region.
Each cell can also require an exact post-composition `change` and `kind`; failure discards the whole candidate.
Observation grants cover guarded rows. Members must carry the enclosing principal, checked at codec and server
admission. Reflow uses this ordinary batch and ordered submission path; Immediate preview starts bounded background work,
status reviews detached positions and price, and Simulation commit submits the resulting payload. A preview is
not a simulation write. Do not replace that submission with direct server enqueue in the console: the link is
what records the accepted payload for replay.
Successful base rebuilds clear deal sweep memos so a reset or live replay materializes children even when
the replacement inventory equals the prior session's. Ordinary edits and undo retain their reconciliation semantics.

Rule-driven state, placement, and HUD mutations share one firing-order queue. Document effects validate a
speculative candidate including earlier queued writes; scope rollback discards its entire tail. The end-of-rule
fold installs through the ordinary mutation door once. Keep this boundary intact when adding an effect; see
the [rule-effects-land-on-the-arena contract](../../../../src/Puck.World.Server/README.md#rule-effects-land-on-the-arena-worldrulehostcs-worldserverarenacs-worldrulehostarmscs).

## Contents

- The tick (`WorldServer.Step`)
- Applying one mutation (`TryApplyMutation`)
- Whole-document rebuild-and-swap and undo
- The kind catalog
- Adding a mutation kind, end to end

## The tick (`WorldServer.Step`, which runs `WorldTick.StepCore` in `src/Puck.World.Server/WorldTick.Step.cs`)

The per-tick order of the steps this document cares about, transcribed from
`StepCore` (it also runs the federated-intent taps, the music director, the rule
host's `EvaluateWorldRules`, board, search and field steps, and the deadline
sweeps between steps 9 and 10):

1. `WorldAddonRuntime.TickAddons` — run every mounted guest FIRST; decodes and
   validates, applies nothing (a guest's effect never depends on where in the
   tick it was pumped).
2. `DrainPendingOps` — drain the buffered live edits FIFO (mutations,
   whole-document swaps, undo), each applying at this tick boundary; deliver
   the new definition to the client sink ONCE if at least one applied. A
   mutation that changes a part the addon host's last preparation read (the
   addon rows, the channels) passes the addon-prepare gate — the LAST fallible
   step before install — see [addons.md](addons.md).
3. Drain the tick's buffered intents (`m_intents` → `ApplyIntentSubmission`,
   under the per-tick Drive check).
4. `WorldAddonRuntime.ApplyContributions` — the guests' staged contributions
   enter the same `ApplyIntentSubmission` path.
5. `FoldChannelContributions` — fold each human-occupied body's owning-seat
   base with its tick's pooled/unpooled contributions (see
   [authority.md](authority.md)).
6. Settle per-body contention for the tick as a whole (the `m_contended`
   write-back — dequeue order proves nothing about contention).
7. `ResolveEngageProbes`: resolve context-button candidates against pre-move
   positions.
8. `WorldPopulation.AdvanceSimulated`, then `AdvanceSeats`: advance the
   integration roster (stand-ins/peers first, seats second), then apply fired
   auto-engages. A rigid island woken after the roster snapshot joins this
   tick's contacts with empty support scratch and zero hold time; its first
   integration is next tick. Wake a contacted sleeper before recording the
   pair's new support. A late wake re-queries current static support before the
   pair split and contact finalization, so clearing stale scratch cannot let
   correction push it into its floor. Checkpoint restore retains support/gravity
   sleep rows only for surviving bodies and wakes components that lost a member or support.
9. `WorldEventFeed.Collect`: collect settled collision, region, seat, and
   route edges.
10. `WorldAddonRuntime.ResolveReads`: guests' reads resolve against the
   stepped state, so a verdict, a minted handle, and a pose describe the same
   settled instant.
11. `WorldEngagement.FoldTick`: fold routed intents into per-screen pads and
   body-route contributions.
12. `WorldMachineHost.Advance`: step every booted machine directly from
   `WorldEngagement.BuildPadSnapshot()`, with no client or wire round trip.
13. Enqueue body-route contributions through the ordinary intent path for
   the target body's next tick.
14. `EmitSnapshot`: deliver the tick's `WorldSnapshot`.

The shared shell is `src/Puck.World.Server/WorldServerStepShell.cs`: drain pending
QUIC work → replay `InjectDriveTick` (a no-op unless a live drive is in
progress — see [replay.md](replay.md)) → `WorldServer.Step` →
`WorldConsoleWaitGate.PublishTick` (the `world.wait` clock counts completed
simulation ticks) → replay `NoteTick` when armed, looping for a
fast-forwarding drive's burst. `WorldSimulation` wraps it with seat-intent submission before the
shell and seat-context sync plus the per-tick analog clear after it. The launcher
owns time, pacing off `IFixedStepSimulation.RatePerSecond` (authored per world
via the document's `simulation.rateHz` field — a world authoring no `simulation`
section runs at 30 Hz (`WorldDefinition.UnauthoredSimulationRateHz`), and only an
authored `rateHz: 0` is the resident, non-stepping rate; see
[documents-composition.md](documents-composition.md)). A `.puckreplay` tape carries its OWN
`SimulationRate`, stamped at record time from the live world's own rate, and
`Drive` refuses a disagreement with the embedded definition's own
`SimulationRateHz` by name, right after deserializing it, rather than
re-driving at the wrong step size (see [replay.md](replay.md)).

## Applying one mutation (`TryApplyMutation`)

Ordinary contiguous cell upserts from one guest may share a batch preparation
and installation at the drain. This is host coalescing, after the guest's
per-act decode and metering: every member still passes complete authority and
cell admission, and each original act retains its journal entry, narration,
echo and completion. Rows with cross-row meaning or time traits use the
individual path. A failed combined preparation falls back to the original
ordered acts, preserving partial success and per-act refusal details.
The [server reference](../../../../src/Puck.World.Server/README.md) owns the
eligibility checks and scratch-store lifetime. Seed a borrowed compose arena
inside its scope, so rewind empties it on acceptance and rejection alike;
catalog identity alone does not prove unchanged row declarations or lane widths.
Partial seeding recomputes only boards whose inputs it loaded. An unrelated
board's empty scratch inputs must never journal and export over its live row.

Compose → validate → capacity → solids → install (swap + derived rebuild) →
journal → echo. Precisely:

1. **Disclosure, then authority.** `WorldRecipientView.Admits` (the mutation adapter in
   `Puck.World.Protocol/Protocol/WorldRecipientMutations.cs`) refuses every mutation or guard whose
   declared write footprint (its rows, their token domains and the rows keyed over them, an
   incoming declaration's names, a placement's parent chain and dealt templates, the placement,
   machine or kit it replaces or removes, a machine's memory-binding rows, a kit's generate rows)
   holds a row the recipient cannot read whole, before grants, key lookup or composition. A
   mutation of a program section (`WorldSectionFacts.IsProgram`: rules, interactions) is refused
   by kind: a recipient never authors the world's program. This includes seats, which are
   seeded Mutate over every section but grants and the program sections. `TryAdmitCompleteMutation`, live state members and detached composition
   share it; a batch rechecks after earlier members change declarations or reader lists.
   Cell and fingerprint guards use the view's `Fingerprint`, through one `CheckGuards`.
   The write door (`WorldServer.WriteView`) is the policy's own tier for every principal, never a
   session's delivery ceiling or live observation, so a `Frames` session writes a public row its
   grants name. A name no row holds is refused exactly as a withheld row is (a recipient replaces a
   row it reads whole and adds none), a refusal names only what the submission spelled (a
   placement, machine or kit by its own name, a spatial guard as `placements`), and a guard over
   the whole document is refused by shape as `state`, whatever the document declares.
   The echo and typed outcome carry the same refusal; its code is
   `world.mutation.undisclosed`. Addon binds and typed writes use the same row policy and
   answer `NotDisclosed`. `cellVisibility: true` reserves cell policies on empty rows;
   row-level visibility alone lets its admitted owner read the row whole. Then the principal must hold `WorldCapability.Mutate` over
   `GrantSubject.Section(WorldMutationKindCatalog.SectionOf(mutation))`. A denial prints a
   `[world.grant denied: …]` stderr line, fires a `WorldEditEcho`
   (`Denied: true`), and drops.
2. **Compose.** `TryCompose(current, mutation, out candidate)` builds the
   candidate document as a with-expression. A compose failure (unknown id,
   dangling reference, foreign asset hash) rejects loudly, definition
   unchanged.
3. **Validate.** `WorldDefinitionValidator.TryValidate` over the WHOLE
   candidate — builders and appliers never repeat semantic checks. A
   state-value write validates only the rows it touched
   (`TryValidateStateMutation`).
4. **Plan the products.** `WorldDocument.PlanProducts` compares the
   candidate with the installed document part by part
   (`WorldDocumentInputs.Changed`) and rebuilds each compiled product whose
   recorded inputs hold a changed part: the render envelope's fit, the solid
   field, the addon and machine hosts' preparations, the population and the
   input owners (`WorldInputRuntime.BuiltFrom`). A candidate that changes the
   document's overlap terms (`WorldOverlapTerms`) while it declares adjacencies
   is refused: the neighbour proof is remade only by a load or reload. A
   product records its inputs by building inside `WorldDocumentReads.Begin`,
   which every `WorldDefinition` member property notes into, so no list of
   mutation kinds decides what rebuilds. A reload's install and an undo's
   replay follow the same plan; a load or a reset changes every part.
5. **Capacity.** When the plan names the envelope, `m_envelope.TryFit(candidate)`
   counts the candidate's render scene on the CPU (`WorldSceneEnvelope`,
   registered on every boot) against the engine's instance and material
   ceilings — a loud apply-time rejection, never a later GPU allocation failure.
6. **Solids.** When the plan names the solid field, rebuild the SDF contact
   field (`WorldSolidField.TryBuild`) — a solid naming an op the warp-free
   evaluator cannot interpret is a loud apply-time rejection. A plan whose
   only changed field input is `collision` re-wraps the live field with new
   tuning instead of recompiling (`WorldSolidField.WithTuning`).
7. **Install.** Swap the live definition; `Install` installs the field
   lattices and rebuilds the population when the plan says so (a part it was
   built from changed, or it receives a new solid field), then reconfigures
   the input owners when a part they read changed or the population rebuilt. The
   `[world.products]` line (`host.log category world.products`) names what
   changed, what rebuilt and what each rebuild was moved by.
8. **Journal.** Append a `WorldJournalEntry(Tick, EngineTick, Mutation)` to `WorldDocument`'s journal. The `dirty` count in
   `world.status` IS the journal length.
9. **Echo.** One `[world.mutation: … applied]` stderr line plus a
   `WorldEditEcho` carrying the submitting envelope's
   connection/correlation identity, so a deferred echo routes to its
   submitter.

A mutation's visual effect is a side effect of the delivered definition —
rendering derives from it on revision moves, never from a draw call.

**Responses are not mutations.** A placement's `holding` mask is runtime state
the response sweep (`WorldTick.SweepPlacementResponses`) derives from state
cells and the field lattice. A tick's moved masks install together through
`WorldDocument.InstallResponseSelection`: the live rows are replaced by
`WorldDefinition.WithPlacementHoldings` (frames, spatial index and, for
face-free creations, the face catalog carry over), nothing is journalled or
validated, no rule, arena, body or input hold moves, and the change reaches
sinks as a value delivery (`DeliverState`). A solid row's colliders are
compiled for every creation it can show when the contact field builds
(`WorldColliderSet` `Shows`), so a change whose creations compile to the same
colliders (a lit and an unlit floor) leaves the contact field, navigation and
the population revision as they were (`WorldColliderSet.TryCarryAcrossHolding`);
otherwise only the solid consumers compile again
(`WorldPopulation.InstallResponseSolids`). A client bumps its response
revision for a face-free change, which recomposes the
program once and rebuilds the presentation field, and its definition revision
only when a creation shown before or after carries a face, camera or sound
(`WorldPlacementResponse.ComparePlacements`). The same comparison covers every
placement projection a value delivery carries: a dealt child added, moved or
removed by the deal sweep, and a contribution, are rows it replaces, adds or
removes, and each recomposes the program on the tick it lands. A checkpoint carries the masks in
the exported rows. A console upsert that writes `holding` is an ordinary
placement edit, and the next sweep derives the mask again.

**Timing classes.** Most kinds apply LIVE on delivery. `IsDocumentDefaults`
(`SetRenderDefaults`, `SetPopulationDefaults`, `SetHostDefaults`) update document
defaults while live session levers keep their values (`world.save` folds levers
back into the fields). This echo classification does not defer fields read from
the delivered definition: authored lighting applies live. Two rows split timing and
the accept echo narrates the split: `SetAuthoringDefaults` (headroom/repeat
caps boot-consumed, candidate/layout/preview live) and `SetPopulationDefaults`
(census figures next boot, spawn policy live for future activations).
`UpsertGrant`/`RemoveGrant` are document-only in a third sense: they edit what
the next boot seeds through `WorldServer.Grant` and never touch the LIVE grant
table — a row added there grants nothing until relaunch.

## Whole-document rebuild-and-swap and undo

- **Rebuild** (`ApplyRebuild`, the `world.reset`/`world.load`/`world.reload`
  path — one `WorldRebuildRequest` closed over `WorldRebuildKind`): resolve
  the candidate and its CAS `sha256-64` content hash FIRST (Reset: the
  server's own `m_base`, hashed fresh via `WorldDefinitionSerialization.
  Serialize`; Load/Reload: the console-resolved document, whose hash the
  console already computed from the exact bytes it read — or, on a REPLAY
  drive, a fresh re-read of a file origin, since the tape carries no
  document; a store origin refuses as `RebuildSourceUnavailable`) → on replay, refuse BY NAME on a content-hash mismatch before
  anything else runs → `RebuildTap` fires (the replay tape's apply-time
  capture point — see [replay.md](replay.md)) → the principal must hold
  Mutate over EVERY section (`WorldGrants.AllowsAllSections`) → (Load-only,
  unless `force`) refuse while the journal is dirty → whole-document validate
  → envelope `TryFit` → wholesale solid rebuild → `Install` with a full
  population rebuild, which recompiles the channel table every channel-name
  door reads live (`WorldPopulation.Channels`: `body.press`, `world.affordances`,
  the engagement fold, each seat's held-channel fold through its routed
  `WorldSeatBindings.Channels`) → every live body's action state re-births
  (`WorldPopulation.RebirthActionState`: `state.body` slots at their initials;
  a `state.identity` slot keeps its value on a body with an identity when the
  previous document declared it under the same name and kind) → journal CLEARS → the transition admitted by
  `WorldGrants.TryPrepareReset` admits replacing and re-seeding the RUNTIME grant table from the
  candidate's complete `Grants` section, with authored consent withheld → every currently-admitted peer
  connection's admission grant re-mints (see [authority.md](authority.md)).
  Reset targets `m_base` WITHOUT moving it; Load/Reload REPLACE it. Fully
  replay-compatible: the trio rides the tape, CAS-pinned, and applies while a
  `replay.record` is armed — see [replay.md](replay.md).
- **Undo** (`ApplyUndo`, the `world.undo [count]` path): Mutate over every
  section; `count` clamps to `1..journal.Count`. Restores the base and
  deterministically replays journal-minus-tail through the SAME per-entry
  gates a live mutation passes (compose, whole-document validate, envelope,
  solid buildability — everything but the per-entry authority check, which the
  every-section hold already re-proves). ALL-OR-NOTHING: any entry failing any
  gate refuses the whole undo, names the failing entry's index and reason on
  stderr, and installs NOTHING. Either outcome echoes through `EchoTap`
  (an acceptance as `dropped <n>, <m> remaining`, then the install it took and
  the parts it changed), so `world.undo` answers its own line like every
  registered verb. There is no per-mutation inverse. When the dropped tail,
  composed again over the restored document, changed only creations in what
  shading reads and shade programs, the undo sets exactly those rows back on
  the live document and takes the reload's presentation install
  (`WorldPersistence.DroppedPresentation`, `WorldDocument.TryInstallEdit`):
  state, deals, draws and every compiled product but the envelope's fit stay,
  and only the changed rows are delivered. Any other undo installs the replayed
  document whole, which also restores the state and deals the document holds. Proven
  in-process by `tests/Puck.World.Server.Tests/MutationAllOrNothingLawTests.cs`
  against the shared apply gate; the replay loop's own early-return on a
  genuine mid-replay failure is unproven (see that law's own remarks).
- **Save** (`world.save`): writes the authored document and compacts the
  journal. `WorldSaveSnapshot.Compose` runs the authority fold
  (`WorldSessionCapture.Capture`: peer-source default, machine declarations,
  magazine selectors, moving `state` cells) and then the lever fold
  (`WorldSessionLevers.Fold`: render levers, view ceilings and floors into
  `views.quality`, master volume, present target, binding bar, the primary
  seat's editor grid; session pins never fold). Each fold reads the `*Raw`
  member and hands it back as the same instance when the session agrees, so an
  omitted section stays omitted and a lever folds only into an authored
  section, except that moved render ceilings, view quality and editor values
  create their valid section when absent. `world.status`'s drift hint names
  each section the snapshot replaced (`WorldSessionCapture.DescribeDrift`).

Named machine rows use the same mutation and undo pipeline. UpsertMachine and
RemoveMachine affect machine preparation independently of screen, population,
solid, and render capacity. Preparation resolves configuration assets and hardware
bindings before installing a replacement; rejected or abandoned candidates retain
the live runtime. Changing only running state or bindings preserves its generation.
The shared world.row verbs author these rows and machine.state reports execution
and binding availability. Undo prepares the restored machine declarations too.

## The kind catalog

Every nested record carries `[MutationKind(ordinal, section)]` — the ordinal
is DECLARED, unique, `0..WorldMutationKindCatalog.MaxOrdinal` (= 127, one bit of
the `MutationKindMask` lane). An ordinal past the lane is refused at boot rather
than left to wrap: .NET masks a shift count by the operand's width, so an
out-of-lane bit aliases a REAL kind and would admit the wrong door silently.
`WorldMutationKindCatalog` (`src/Puck.World.Protocol/Protocol/WorldMutationKindCatalog.cs`)
discovers the set by reflection and `Validate()` fails BOOT loudly on a
missing attribute, an out-of-range ordinal, or a collision.

The lane is `UInt128`, with room past the last ordinal, but a new kind is a substrate
decision that must answer the consolidation question first (see "Adding a mutation
kind" below). Regenerate rather than trust this
table — it is a copy of the `[MutationKind]` attributes on `WorldMutation`'s
nested records, which are the authority:

| Section | Kinds (ordinal) |
|---|---|
| Kits | UpsertKit 0, RemoveKit 1, SetDefaultSeatKit 2, SetKitAssignment 3 |
| Screens | UpsertScreen 4, RemoveScreen 5 |
| Machines | UpsertMachine 76, RemoveMachine 77 |
| Cameras | UpsertCamera 6, RemoveCamera 7 |
| Spawns | SetSpawns 8 |
| Motion | SetMotion 9 |
| Properties | SetProperty 10 |
| Population | SetPopulationDefaults 11, SetPopulationDistribution 68, SetPopulationCensus 69 |
| Render | SetRenderDefaults 12 |
| Addons | UpsertAddon 13, RemoveAddon 14 |
| Bindings | UpsertBindingOverlay 15, RemoveBindingOverlay 16 |
| Creations | UpsertCreation 17, RemoveCreation 18 |
| Placements | UpsertPlacement 19, RemovePlacement 20 |
| Speakers | UpsertSpeaker 21, RemoveSpeaker 22 |
| Tunes | UpsertTune 23, RemoveTune 24 |
| Patches | UpsertPatch 25, RemovePatch 26 |
| Audio | SetAudioDefaults 27 |
| Authoring | SetAuthoringDefaults 28 |
| Collision | SetCollision 29 |
| Host | SetHostDefaults 30 |
| Views | SetViewDefaults 31, UpsertViewLayout 32, RemoveViewLayout 33, SetViewSeatRig 70, SetViewSeatControl 71, UpsertViewGraph 74, RemoveViewGraph 75, CommitViewGraph 78, SetViewPost 79 |
| Looks | UpsertLook 34, RemoveLook 35, SetLookAssignment 36 |
| Grants | UpsertGrant 37, RemoveGrant 38 |
| Hud | UpsertHudPanel 39, RemoveHudPanel 40, UpsertHudElement 41, RemoveHudElement 42, SetHudDefaults 43 |
| State | UpsertStateRow 44, RemoveStateRow 45 (whole row), UpsertStateCell 47, RemoveStateCell 48 (one cell), Generate 49 (one draw at a draw SITE), TransformState 67, Batch 73 |
| InputHold | SetInputHold 46 |
| Rules | UpsertWorldRule 50, RemoveWorldRule 51 |
| Interactions | UpsertInteraction 52, RemoveInteraction 53 |
| Groups | UpsertGroupKind 54, RemoveGroupKind 55, FormGroup 56, JoinGroup 57, LeaveGroup 58, KickMember 59, OfferOwnership 60, SettleOwnership 61 |
| PlayerDefaults | SetPlayerDefaults 62, SetPlayerSeatLook 72 |
| Dynamics | UpsertDynamics 63, RemoveDynamics 64 |
| Curves | UpsertCurve 65, RemoveCurve 66 |

The ordinals are dense from zero (`MutationKindMaskLawTests`); deleting a kind
renumbers the kinds after it. Machine cable linking is authored on
the `Machine` source itself (`WorldMachineCable`), so cable edits ride
`UpsertScreen`; an auction is an escrowed conditional transfer over ordinary
keyed rows, authored as rules — see [documents.md](documents.md)'s `state`
section.

Rules the catalog encodes:

- **Asset hash pinning.** `UpsertCreation` re-canonicalizes its embedded
  document at the compose boundary; `UpsertTune`/`UpsertPatch` load their
  referenced document off disk and canonicalize it there. Both REJECT a
  carried hash the pipeline did not itself compute.
- **A creation row hashes once.** `WorldPrototype.CanonicalHash` (what `Hash`
  falls back to and what the validator compares `HashRaw` against)
  canonicalizes on first read and caches on the row instance, as
  `EngineDocument` does. `Document`'s `init` clears both caches, so a `with`
  that replaces the document re-derives them. An edit builds a new row or
  document, never mutates a creation document's lists in place.
- **Pipeline overrides bind at the mutation door.** `TryPrepareMutation` runs
  `TryAdmitPipelineOverrides` after whole-document validation, for every kind:
  a `views.graphs` row that names a `source` (a `package` row is skipped)
  whose source, `overrides` or `output` changed, and that names overrides or
  an output, has its source read through
  `WorldServer.PipelineSources` (`WorldPipelineSources`, attached by
  `WorldPostBuildWiring` in every boot shape) and its values bound through the
  pass config schema (`ShaderPipelineSource.TryBindOverrides`). A
  `CommitViewGraph` composes against the row's fingerprint
  (`WorldDefinitionFingerprint.ComputeGraph`) and also requires the source's
  content and config-schema identities to equal the installed graph's.
  Refusals read `pipeline.overrides/<WorldPipelineOverrideRefusal>: …`. Undo
  replays compose only and never re-reads a source. A whole document binds
  through the same row check (`WorldDocument.TryBindPipelineRows`): `ApplyRebuild`
  runs it for `world.load` and `world.reload` (not `world.reset`, which
  reinstalls an admitted base), and `WorldPostBuildWiring` runs it at boot
  through `WorldServer.TryBindPipelineRows`, refusing the boot by name.
- **No cascades.** `RemoveCreation`/`RemoveTune`/`RemovePatch` refuse while
  dependents reference them, naming the dependents — remove or retarget the
  dependents first. "Who names a creation" is one walk,
  `WorldDefinitionRows.EnumerateCreationReferences` (a placement's authored,
  `respond`, contribution-slot, and deal-variant creations, a look's source, a
  kit's `fromCreation` collider); `RemoveCreation`, the contribution retraction,
  and the composition decompiler's door-prototype strip all ask it.
- **Cross-row transaction.** `UpsertHudPanel` carries its child elements — the
  one whole-panel commit boundary; `UpsertHudElement` is a single-element
  read-modify-write on an already-declared panel.
- **Double authority check.** The five `State` kinds — `UpsertStateRow`/
  `RemoveStateRow` (whole row, 44/45), `UpsertStateCell`/`RemoveStateCell`
  (one cell, 47/48) and `Generate` (49, which names the row it WRITES) — are the
  ONE set checked TWICE by the admission predicate
  (`WorldServer.TryAdmitMutation`): the standard `Mutate`/`section:state` hold
  every kind requires, PLUS a second, row-scoped `Edit` hold over the CONCRETE
  `state:<name>` subject, the SAME subject at both grains (a slot is a table
  with one key, so there is one row and one subject). Narrower authority than
  any other section (the "concrete rows" ruling; see
  [authority.md](authority.md)'s `GrantSubjectKind.State` entry). The
  domain-seeded `Edit/all` reaches every row and cell until narrowed, so this
  is inert by default. Both holds may additionally carry a
  `MutationKindMask` — the Edit one is what separates bumping a row from
  redefining it (`verbs:UpsertStateCell,RemoveStateCell`); `verbs:Generate` is the
  fire-without-redefine hold: it redraws the site but cannot re-author it.

- **The one structural exemption.** `Principal.World` — the world's own
  authored program (a `rules` effect, a kit's `generate` effect) — is admitted by
  `TryAdmitMutation` BEFORE the table is consulted, keyed on the principal kind.
  The program holds an Edit grant for gameplay transactions, checked at every
  commit; it holds no other capability. The wire refuses it as a submitter,
  and structural document admission still reports
  `allowed (structural)` rather than a verdict about a table that was never
  asked. Every non-authority gate still runs. See [authority.md](authority.md).

- **A draw site's own bookkeeping.** `Generate` names ONE row — the SITE — and
  writes its drawn slot cell together with the site's own `drawCursor` (plus
  `drawnMasks` under an exhausting mode) in one candidate. The row is the authority
  subject; the cursor advance is engine bookkeeping intrinsic to drawing, while
  re-authoring the site's facet, or the `generators` row it references, is an
  `UpsertStateRow` against that row, gated there. Sampling itself lives in
  `src/Puck.State.Generators/GeneratorEngine.cs` because the BOOT resolver — which
  runs before any server exists — must reach the identical code.

## Rule-effect sugar (`.puck`) → state mutation kind

A world rule's body is `.puck` sugar over `Puck.State`'s own effect union
(`ActionEffect`, `src/Puck.State/ActionEffect.cs`) — `Puck.World.Transpiler`
invents no rule-effect shape of its own. Every effect but `transformState`
fires as a `Mutation` (`MutationKind`, `src/Puck.State/IEffectHost.cs`)
applied inside the firing's journal scope by `WorldArenaHost`
(`src/Puck.World.Server/WorldArenaHost.cs`); `transformState` instead calls
`IArenaTransformHost.TryTransform` directly, since a transform addresses a
selection of cells rather than one. Either way the arm folds into one of the
SAME `WorldMutation` state kinds the catalog above already names — never a
shape unique to rules:

| `.puck` effect statement | `ActionEffect` discriminant | `Mutation` | Folds through |
|---|---|---|---|
| `row[key] = rhs` | `setState` | `Write` (`StateWriteKind.Set`), or `WriteText` for a `Text` row | `UpsertStateCell` (47) |
| `row[key] += rhs` | `addState` | `Write` (`StateWriteKind.Add`) | `UpsertStateCell` (47) |
| `schedule row[key] in Ns` | `scheduleState` | `Write` (writes the due tick) | `UpsertStateCell` (47) |
| `remove row[key]` | `removeStateCell` | `Remove` | `RemoveStateCell` (48) |
| `push row = rhs` | `pushState` | `Push` | `TransformState` (67) |
| `transform call(...)` | `transformState` | none — `IArenaTransformHost.TryTransform` | `TransformState` (67) |
| `generate(row: ...)` | `generate` | `Generate` | `Generate` (49) |
| `transaction { } [onFailure { }]` | groups the statements above atomically (`RuleEvaluator.Effects.FireSavepoint`) | — | each grouped effect folds as its own row above |
| `if Gate { } [else if Gate { }]* [else { }]` | `if` | branches to `Then`/`Else`; each fired effect folds as its own row above | — |

Every one of these still lands on the arena first and installs once per
tick — the cross-cutting "rule writes land on the arena" contract in
`SKILL.md` — so the table names the kind a write eventually composes as,
never a second apply path.

Inside `transaction`, an unresolved destination key refuses a write, schedule
or remove, including a valid cell name not interned in the arena. Pool claim,
pair claim and iteration bodies preserve that strictness just as `if` branches
do, so a skipped absent remove cannot leave earlier writes or claims committed.

**A world rule body is mostly straight-line, `if` aside.** The core `.puck`
language parses `if`/`else if`/`else`, `repeat`/`break`, call-form gates, and
compound assignment (`+= -= *= /= %= &= |= ^= <<= >>=`) for every vocabulary,
but the WORLD vocabulary's rule shape still refuses `repeat`, `break`, a
call-form gate by name: control flow with nothing
to lower onto is PUCK037, a call-form gate where only comparisons are legal is
PUCK038. Compound assignment lowers to the existing write effects: `-=` adds
the negated operand, and the other compounds set the computed value. A computed
destination key is evaluated once at the effect. `if` is the control-flow
exception: it lowers to `ActionEffect.If` (`$type: "if"`), branching on a
`condition` compiled the same way a `when` gate is, firing `then` or the
optional `else` — an `else if` chain is one nested `if` node per level, so a
chain of any length lowers, formats, and decompiles the same way a single
branch does. A cartridge rule (`puck.cartridge.v1`, see `rom-forge`) is a
DIFFERENT vocabulary that additionally admits `repeat`/`break` — the refusal
is per-vocabulary, not language-wide. Both branches read the frame at the
effect's own position, so an earlier same-firing write is visible to the
condition exactly as a later effect's own operand would see it; a condition
that fails to evaluate (an arithmetic fault, a missing table key) runs neither
branch and is reported through `world.rule.failures` the same way a failing
top-level effect is — a false condition with no fault is not a failure. Each
branch effect is its own boundary, on the same terms as a top-level effect
(or, inside a transaction, any other step) — a branch is not itself a
transaction. A faulted condition refuses its enclosing scope, rewinding earlier
writes and invoking `onFailure` when the scope has one. An `if` may sit inside
a `transaction`; a `transaction` may sit
inside an `if` only when that `if` is not itself inside one, since
transactions never nest either way. `save` is refused by name inside any `if`
branch, at any nesting depth. Kit actions and body-scope effects refuse `if`
by name — a per-body action compiles to a flat instruction stream with no
branch of its own. `world.rule.trace` shows which branch a captured
evaluation took.

## Adding a mutation kind, end to end

**First, `puck search "\[MutationKind\(" src -M 0` against `WorldMutation.cs`
gives the current kind count and declared ordinals.** A colliding ordinal is a
boot failure. A genuinely new kind is a substrate decision, so first check whether
it is an existing kind's payload. Most proposals
are — a new section reuses `UpsertStateCell`, a rule effect reuses an existing
kind.

Should the 128-bit lane ever fill, the widen is one dedicated substrate commit
— mask type + grant wire codec + document serialization +
`world.grants`/`world.why` echoes — never inside a feature change, and its proof
has two halves that must both be present: dual-run byte-identity over the
existing ordinals (necessary, but it passes on a codec that silently truncates
the new range), and a control exercising a bit past the old ceiling across the
wire. The width is an implementation detail, not protocol: authored grants name
verbs by name and the ordinal is an internal dense index, so widening or
re-packing ordinals is mechanical. Only past the consolidation question do the
steps below apply.

1. **Data:** the nested sealed record on `WorldMutation` with
   `[MutationKind(ordinal, section)]` (the next ordinal past the last, keeping the set dense); the
   attribute's section is the one mapping `WorldMutationKindCatalog.SectionOf` answers for grants and
   the recipient door. XML-doc the row semantics (rejection conditions, timing class) in the
   same style as its neighbors. A kind whose row names state rows adds them to the recipient
   footprint in `WorldRecipientMutations.Admits`, for the incoming row and the row it replaces.
2. **Server:** an arm in `TryCompose` (`WorldDocument.Compose.cs`, compose the candidate),
   membership in `IsDocumentDefaults` when it applies, and a `WorldServer.Describe` arm
   (`WorldServer.Describe.cs`). What the install rebuilds follows from the parts the
   candidate changes (`WorldDocument.PlanProducts`); a new kind joins no list for it. A new
   document member gets a property that notes its part and a row in the read table
   (`WorldDocumentInputs.cs`), which its first build checks.
3. **Validator:** whatever whole-document invariant the new row needs lives in
   `WorldDefinitionValidator`, never in the apply arm.
4. **Console:** a verb in the owning command module submitting
   `WorldSubmissionPayload.Mutation`. Row-valued verbs take one inline-JSON
   argument in the exact wire shape of the section row.
5. **Read-back, same change:** no new decision surface lands without a verb
   that echoes it — a decision nothing can echo can only be asserted through
   downstream inference.
6. **Sweep shipped worlds** if the schema changed (strict parse turns
   stragglers into boot refusals — see [documents.md](documents.md)).
7. **Verify by running** (see the SKILL.md recipes): drive the verb over
   stdin, read the read-back, exercise one rejection path, and check
   `world.undo` restores.

A kind's CONSOLE reachability (steps above) is independent of its ADDON
reachability: a guest submits a mutation through a Mutate handle's own
hand-walked JSON door, `Addons.WorldAddonMutationDecoder`, which wires only a
NAMED SUBSET of the declared kinds (10 — the 5 HUD
kinds plus the 2 placement kinds, the 2 state kinds, and `SetInputHold`; the
Properties/Interactions/Groups kinds are console-only, not addon-reachable; see
[addons.md](addons.md#requests-queries-verdicts) for the exact list and the
decoder's own division of labor against the validator). Adding a kind here
does not make it addon-reachable — that is a separate, optional `case` arm in
the decoder, additive by the same discipline this section already follows.
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