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/documents-composition.md

View on GitHub
# Document composition, boot-authored topology, the validator, serialization

Part of [`puck.world.definition.v1`](documents.md). Field names and defaults are
generated (`puck schema`); this file is the decision/derivation prose the
schema cannot state.

## Boot-authored-only topology/timing members

These carry facts decided once at boot — none has a `WorldSection` axis or a
`MutationKind` ordinal, so nothing mutates them in session and no grant
subject names them:

- **`References`** (`WorldReferences.cs`) — `IReadOnlyList<WorldReference>?`,
  each row `(SafeName Name, string? Document, Guid? Owner, SafeName?
  World)` — exactly one of `Document` (a local document path) or
  `Owner`+`World` together (a remote owner-named world; worlds ARE users) is
  authored, never both, never neither. `NeighbourKey` (computed, never
  serialized) folds whichever arm was authored into the one opaque string
  every `IWorldNeighbourResolver` call site resolves against. This is what a
  portal facet's `destination` resolves against (the debug world's garden painting
  names the garden this way).
- **`Gravity`** (`WorldGravity.cs`) — an acceleration field, deliberately not
  geometry. `uniform` is an authored acceleration vector. `attractors` names a
  placement plus explicit mass; optional `points` instead names a placement,
  positive `surfaceGravity`, and positive `referenceRadius`, then lowers that
  promise through the actual softened Q48.16 Plummer kernel into a mass. The
  thick validator refuses an unrepresentable lowering before boot, requires
  positive `gravitationalConstant` only when `points` is nonempty, and refuses
  a placement duplicated across the two source spellings. Compilation keeps
  explicit attractors first and point presets second, preserving authored order
  within each. A positive constant activates body-to-body gravity even with no
  static sources; a lone body participates with a zero global answer. A source reads only its placement transform — never its SDF or
  solidity. Read back authored/derived values and last deterministic solver
  work with `world.gravity`; `world.budget` echoes the source and evaluation
  price. Optional `areas` are the bounded-local layer over that SAME answer:
  each rides a placement, declares a priority and explicit `Combine`/`Replace`,
  an inclusive analytic `sphere` or yaw-local `box` bound (scaled by the
  placement), and either a placement-local `directional` vector or constant-
  magnitude inward `radial` acceleration. Static rows use authored pose;
  attached rows use `WorldPlacementAttachment.TryResolve` each tick and
  contribute nothing while their carrier is inactive. The fixed fold begins
  with uniform + global solved gravity, then applies areas ascending by
  `(priority, authored index)`; later equal-priority rows therefore apply later.
  A matching zero Replace, exact cancellation, or radial center is participating
  authored zero-G; outside every area in an areas-only field retains kit fallback.
  Global + uniform + Combine composition saturates componentwise at Q48.16
  extrema rather than wrapping, while a later Replace resets the fold.
  Capped at 64 rows. Arbitrary SDF bounds and per-body masks are the future
  asset/query extension seam, not implicit geometry-derived gravity.
- **`Portals`** (`WorldPortals.cs`) — `WorldPortalsSection(WorldPortalDefaults
  PortalDefaults)`, whose `travel` is `Party` (the traveling seat's whole
  active local-seat party) or `Body` (one seat). It is the world-scope default
  a placement face's own `WorldPlacementPortal` facet falls back to when it
  authors no `Travel`; a null section resolves every facet to `Body`. A door
  fires when a body's origin passes through its glass, within the opening
  (`WorldFaceAperture.Box`'s slab is `[-Depth, 0]` behind the glass, entered
  only from the front), never on a band in front of it; while a body stands in
  the opening, pushes out of the door from this world's geometry behind the
  glass are taken back (`WorldPortalHoleContactField`), so a door on the ground
  drops a body that walks onto it
  ([decision](../../../../docs/decisions/engine-design.md#a-portal-is-a-plane-a-body-passes-through)).
  A door may lie at any orientation (a shape turned a quarter about +X lays it flat;
  `WorldFaceCatalog` snaps such a quarter-turn frame to exact axes); a mapped
  pair is refused at the crossing, by name, unless it maps world up onto itself
  (`WorldFrameIsometry.PreservesWorldUp`: two walls, or a floor and a ceiling).
  A destination whose reference names the world's own document resolves to the
  running world itself, and a mapped crossing there carries the body in place
  (`WorldInstanceHost.ApplyInPlaceCrossing` → `WorldBody.CrossInPlace`, taped
  as a `Crossing` replay entry) instead of transferring it. It is continuous
  motion, never a teleport: every world-space point and direction the body
  holds, its previous position included, maps through the pair, its momentum,
  followers and facts carry on, and the snapshot's continuity is `Carry` with
  the rigid motion (`WorldPoseCarry`). Presentation carries what it latched the
  same way: the mirrors' interpolation endpoints, `IWorldStampSource.Carries`
  for the stamp pool's followers, gait drivers and effectors and for the
  catalog avatars, while the chase boom is translation-invariant and turns
  through `CrossView` for a turning pair. The debug world's endless fall
  (`worlds/debug/paintings.puck`: a painting in the floor under its twin in the
  ceiling) and its pair of paintings facing each other are the live examples.
  A window's session source may author `ripple: true` (refused off
  `projection: window`): the opening shimmers and rings from every body that
  touches or passes through it, presentation only (`WorldOpeningRipples`
  contacts, `sdfOpeningRipple` in `shade/sdf-environment.hlsli`). A wall
  painting is a thin rim shape with its centre carved out, face 0, because the
  glass fills the face shape a centimetre short of its faces, and the wall
  behind it holds nothing back while a body stands in the opening.
- **`Simulation`** (`WorldSimulationDefaults`, `WorldDefinition.cs`) — one
  field, `RateHz` (required in an authored section), the authoritative
  server's fixed step rate in Hz. Read through
  `WorldDefinition.SimulationRateHz` (`Simulation?.RateHz ?? UnauthoredSimulationRateHz` —
  absence runs the shipped rate, 30 Hz; the distinct rate-0 resident world is
  reached only by authoring `rateHz` 0 by name) — never `Simulation` directly, since every consumer
  wants the resolved value, not the presence/absence of
  the section. MUST be 0 or a positive divisor of
  `Puck.Maths.FixedTickConversion.TicksPerSecond` (50400) exactly, refused
  by `WorldDefinitionValidator.ValidateSimulation` otherwise (naming the
  nearest valid rates). Boot-time only, deliberately: nothing in this codebase
  needs a mid-session rate change today, and building that (recompiling every
  cached tick-derived table live) is real additional scope this field does not
  take on. The derived-floor validation (physics floor from body size/speed,
  interactivity floor from input latency, the substep-derived contact clamp
  `contactHertz <= RateHz * n / 8` at substep count `n` — it coincides with
  `RateHz / 4` only at `n` = 2 — and the representable band) is NOT built;
  `n` is a solver parameter, so `WorldSimulationDefaults` is the seam the
  solver landing that introduces it adds the validator to.
- **`Adjacencies`** (`WorldAdjacencies.cs`) — reciprocal rectangular ownership
  boundaries layered over global persisted `Destinations`. Authors declare
  each destination, counterpart, frame, unavailable treatment, and optional
  failure channel; the compiler derives overlap and diagonal corner interest.
  Runtime, transfer, and verification details live in
  [adjacency-and-federation.md](adjacency-and-federation.md).
- **`Metadata`** (`WorldMetadataSection`, `WorldMetadata.cs`) — free-form
  author-facing facts: `title`, `description`, `authors` (each an optional
  UUID `oid`, checked with `WorldObjectId.IsValid`), `tags`, and a
  `custom` bag (`IDictionary<string, JsonElement>`). Nothing in the engine
  reads any member here. `title`/`description` cross to a Presentation-tier
  peer as `WorldProjectedMetadata`; `authors`/`tags`/`custom` never do (see
  [documents.md](documents.md)'s Disclosure section). `custom` follows `WorldDocumentBasis`'s ordinary
  nested-object merge rule with its two carve-outs: a key literally named
  `$drop`/`$replace` refuses at validation, and a JSON `null` under a key in
  a delta deletes the inherited key rather than storing a literal null.

## Worlds have no in-code definition

Every world is an authored document; the engine ships no content default. A
boot with no `--world` refuses and names what it needs; `--world worlds/debug`
boots the debug world's package (`worlds/debug/manifest.json` names its entry,
`debug.puck`), and a path that cannot be loaded refuses the boot by name
(`src/Puck.World/PuckWorldLoader.cs`, `src/Puck.World.Schema/WorldPackageManifest.cs`). The island
(`experimental/src/Puck.World/Assets/worlds/puck.world.json`), its district
modules and the game packages are quarantined prior art: read them for worked
examples, never boot or repair them.

Engine facts those worlds exercised, which hold for any world:

- **Placement primitives.** A placement `deal` facet deals one child placement
  per cell of a keyed row (`<template>/<key>`, laid out by the template's
  `distribution` region; `PlacementDealLawTests`). An observation writes rows of
  any cell kind and nothing else (`WorldObservationLawTests`). A `respond[].when`
  is a closed union of a lattice-field condition and a state-cell condition
  (`PlacementResponseLawTests`). An `inhabit` facet's `count` may name an Int
  cell: such a placement starts every structural install at zero live bodies,
  and `WorldPopulation.ReconcileInhabitCounts`, called on every state-value
  mutation apply, admits and retires bodies the same tick a rule writes the
  cell, clamped to the peer capacity and the distribution's sample count and
  never retiring a seat-driven body (`InhabitCountLawTests`).
- **Identity facts and machine content.** An owned identity carries a keyed
  Int `facts` row mirrored into the reserved body-scope `identity` row, written
  by the `setIdentityFact` effect and echoed by `identity.facts`
  (`IdentityFactsLawTests`). A `machine` screen's content may be a
  `puck.cartridge.v1` document compiled at bind by the brick's forge
  (`MachineCartridgeLawTests`).
- **Derived limits.** Sixteen drive-reach ordinals across channels and target
  registers; aggregate physical-region primer and sampled-surface byte budgets; and the rule budget
  `RuleCapacity.MaxWorkUnitsPerTick`, where a
  body-pair interaction costs capacity squared.
- **Placement policy.** `placements.policy` is optional, and whole when
  authored (a partial block refuses at parse naming the missing member).
  Unauthored it derives (`WorldPlacementPolicyDefaults.DeriveFrom`): zero
  placement and screen headroom, no derived faces, no candidate ring, no
  preview deadline, and a scale envelope spanning exactly the rows' authored
  scales. Console placement mutations can grow the renderer beyond its initial
  reserve without an authored policy.
- **Author frame.** A `prototypes[].document`'s coordinates are author-frame:
  `puck.creation.v1` authors with +Z the front a shape faces, a half-turn about
  Y from the engine's −Z-forward, and `CreationFrame.ToEngine` converts once at
  `WorldPrototype.EngineDocument` (authored `[x, y, z]` lands at world
  `(−x, y, −z)`; `CreationAuthorFrameLawTests`).
- **Creation shapes and animation** (modifiers, `flare`/`shear`/`bumps`,
  blends, `cells`, `erode`, `volumes`, `panel`/`trims`/`detail`, sweeps, and
  the `drivers`/`swings`/`effectors` animation `WorldCreationInstances.PackTransforms`
  composes, read back with `body.rig`) are `sdf-authoring`'s:
  [shapes](../../sdf-authoring/references/shapes.md),
  [composition](../../sdf-authoring/references/composition.md),
  [rig](../../sdf-authoring/references/rig.md) and
  [surface](../../sdf-authoring/references/surface.md). All of it is
  presentation-only except the shapes' contact geometry.
- **Body scale.** `Server.WorldBody.Scale` (the body's own `state.body` Counter
  register that `bodies.scale` names, with a `range` envelope; the debug world's
  is `size`, `worlds/debug/size.puck`, imported by every world a body can walk
  into so the size crosses with the body) scales collider volumes, move speed
  and turn rate, hold probes, standoff and reach, a hold's own gravity and
  vertical envelope, and a pull's rate; a scaled portal pair's in-place crossing
  writes the register (`WorldServer.TryApplyInPlaceCrossing`), and the client
  multiplies the same register into the rendered rig and
  the seat chase camera's orbit distance and look-at height
  (`Client.WorldFramePresenter.ResolveCamera`). A rigid body's mass, inertia,
  bounding radius, centre of mass and rest threshold scale with it
  (`WorldBody.ScaleRigid`); `body.where`'s `scale=` and `com=` read it back.
  Only the adjacency sweep's remote side still reads an unscaled collider.
- **Contact.** `FixedContactPushMath` treats a non-walkable, non-ceiling
  normal as a wall: penetration resolves across `up` and the approach clamps
  horizontally. There is no authored step height; a capsule climbs only the
  rises its rounded bottom rides. A `Subtraction` carve (`max(a, −b)`) is exact
  only inside the subject: inside the void the field reads the carve box's own
  faces and the subject's carved faces as surfaces, which the contact solver
  grounds on, so a carve that must be exact is built from union geometry.
- **Interactions that write state.** A `Region` interaction that writes a cell
  is `Edge` mode: a `Level` trigger re-fires its `setState` every tick the
  co-occurrence holds, a mutation, a journal line and a client delivery per
  tick. `body.pose spawn:<id> [body]` is the console mirror of a rule's `pose`
  effect naming a spawn point.
- **Expressions.** `src/Puck.State/Expressions/ExpressionOperators.cs` owns
  context-free operator spelling, arity, type signature and cost; keep
  payload-bearing literal, state and board lowering specialized. The compiler
  folds successful constant subexpressions after full validation using the
  runtime evaluator, and never elides a live read or a refusing conditional
  branch. [Reductions](../../../../docs/reference/state/expressions.md#reductions)
  and [periodic bit masks](../../../../docs/reference/state/expressions.md#periodic-bit-masks)
  (`replicationMask`, `repeatBits`) are documented with `Puck.State`.

## Authoring a creation in code — the sculpting library

A creation may be authored in code instead of by hand, through the sculpting
library in `Puck.World.Authoring/Sculpting` (`CreationBuilder`/`StateHoisting`/
`SculptPatch`/`ICreationSculpt`/`CreationSculptRegistry`) — see that project's
README for the primitives; the shipped registry carries no sculpts, so one is
registered by a composition root or a test. The document
stays the source of truth either way: a sculpt only ever produces a patch a
caller applies, validates, and (for the live world) composes into ordinary
`WorldMutation` rows through the `world.row.set`/`.remove` section table under
the issuing principal (`creation.sculpt <name>`) — it never bypasses
whole-document revalidation or the per-section `Mutate` grant check.

## Document composition (`basis` and `imports`)

`WorldDefinition.Basis` is the document-composition member: a file naming a `basis` (a file path resolved against
its own directory) is a DELTA over that document — templates/prefabs for similar worlds. `WorldDefinition.Imports`
is the fan-in half beside it: an ORDERED list of `{"document": "<path>", "as": "<alias>"}` entries (`WorldImport`;
each document resolved against the importing file's own directory, exactly like `basis`; `as` is optional), letting
several documents each own one disjoint slice of a world (the debug world imports `theme` and `controls`) rather
than forcing every slice through the single-parent basis chain. In `.puck`, `import "name"` always names, never
spells a file (`import "name.puck"` is PUCK121), and the named file decides what it brings
(`WorldDocumentVocabulary.TryResolveImport`): a module library, a source emitting no document
(`WorldSourceDeclaration.EmitsDocument` false), brings its `let`s and templates into the compile and lowers to
nothing, so a library such as `shapes.puck` hands its rows over through templates the importing file expands; any
other source or `.world.json` lowers to an `imports` entry. A library that imports a document is refused by name
(PUCK017), since that document would compose into nothing. A keyed
list assembled this way (every import's rows concatenated in import order, then the importing file's own new
rows appended last) never reproduces a monolithic predecessor's own interleaved authoring order — order is not
preserved across a split, only content is; compare two composed trees by canonicalizing each keyed list (sort by
its identity key) before a `JsonNode.DeepEquals`, never by raw array order. The mechanism is
`WorldDocumentBasis` (`Puck.World.Schema/WorldDocumentBasis.cs`), invoked from `WorldDefinitionFileSource` on EVERY
file load (boot, `world.load`/`world.reload`, the replay re-drive's apply-boundary re-read, and both neighbour
resolvers), composing on the raw JSON trees BEFORE the strict parse — a partial template or import fragment cannot
model-parse (required members), so the model only ever sees the finished composition, and the consumed `basis`/
`imports` members are stripped: a LIVE document always carries `Basis == null` and `Imports == null`, the
validator refuses anything else, and every wire egress (replica, replay embed) is self-contained by construction.
Composition order is the basis chain first (each ancestor's own `basis`/`imports` resolved recursively through the
same mechanism), then each import fully resolved and folded left to right in list order, then the file's own body
last — each step an ordinary refine (basis, then the folded import layer, then the file's own body, each one
overriding the layer before it, per the merge rules below).

Merge rules: objects merge member-wise (recursive), omitted inherits, authored `null` clears, a `$type`-changed
union object replaces wholesale, and a row list whose rows all carry the settled identity vocabulary (first of
`id`/`name`/`key`/`index` on every row of BOTH sides — `key` covers a state row's own `cells` and any other list
keyed the same way — or, for grant rows, the `grantee` + `capability` + `subject` triple taken together, so each
imported module can author its own grants) merges BY KEY in basis order — new keys
append, `{"<key>": …, "$drop": true}` tombstones remove (a stale tombstone refuses by name), a leading
`{"$replace": true}` row replaces wholesale. Any other list replaces wholesale too — notably an overlay's `chords`
(unkeyed rows, no settled identity field of their own): adding one chord means restating that row's whole list.
An object can also carry `"$replace": true`: it replaces the inherited object, preserving member order and literal
nulls while consuming the marker. `WorldDocumentBasis.Diff` uses that form when member-wise merging cannot
reproduce the target's key order, including inside a keyed row; reload proves the merge with `OrderedJson.Equals`.
A present list is what replaces, empty included: `.puck` lowers a list only where its source writes one, so
`placements { policy { … } }` leaves `rows` absent and keeps the rows beneath it, and `rows []` clears them.
A rule's `effects` whose effects all carry `key` is such a keyed list too, so a document that restates a basis rule
refuses when two of its effects write one key (`claim-expire`'s `boneHolder[0]` and `reporter[0]`, "the basis list
carries it more than once"). Refine a document over a basis by expanding only the rows that change (the garden's
`pondFlocks` in `worlds/debug/garden-crowd.puck`), never by expanding the whole template again. In `.puck`, a row
drops with `placement "arrival" { $drop: true }`.
A creation's shapes refine the same way, by `id` or `name`: `shape Box "visor" { scale [...] }` in a document that
names a basis or imports changes only the scale of the imported creation's `visor`, and an unnamed, unkeyed `shapes`
list over a non-empty basis list refuses (PUCK035, naming `prototypes[id="…"].document.shapes`) rather than replacing
it. Such a document keeps exactly the members its shape rows write; a row omitting `id`, `position`, `rotation` or
`scale` is completed once, where the composed creation is read (`CreationDocumentJson.Read`: `id` is the row's
position in the composed list). A document that composes nothing is whole, and its compiled rows carry every default.
`$drop`/`$replace` are compose-time vocabulary only; the basis-and-import graph is depth-capped
(`WorldDocumentBasis.MaxChainDepth`, 8, shared across both edge types on any one resolution path) and cycles
refuse by name.

**Collision policy — basis refines, imports collide.** Within the basis chain a derived row REFINES its same-key
basis row (the rule above, unchanged: basis is a single-parent relationship, so there is never an ambiguity about
which side wins). Imports are the opposite: siblings with no priority order between them, so a same-key row, a
same-name object member, or the same list authored by TWO imports is a refusal by name (naming the two colliding
import files) UNLESS the importing file's own body ALSO declares that same path — the explicit resolution, since
the importing file's own body always wins the final override regardless of what the imports disagreed on. Two
imports agreeing on a value (typically because they share a common ancestor somewhere in their own basis/import
graphs — a shared basis diamond) never collide; only a genuine disagreement, which can only arise from each side's
own authored content actually diverging, refuses. An empty list an import authors holds no row to collide with, so
it merges with a sibling's rows rather than refusing (the debug world's `devices.puck` authors `hud { panels [] }`
beside the addons' panels). See `WorldDocumentBasis.TryMergeImports`'s remarks for the exact recursive algorithm.

`WorldDefinitionFileSource.TryComposeChainBytes` returns the content pin with the composed bytes. It folds each
distinct document's SHA-256 digest once, starting with the root, then its basis, then its imports in authored
order. A flat document's pin hashes its own bytes directly. `world.save`
preserves the derivation of the file it OVERWRITES (`SavePreservingBasis`): it peeks the target's `basis` AND
`imports` at save time (the file is the one truth — nothing caches derivation between load and save), composes the
full basis-plus-imports stack (`WorldDefinitionFileSource.TryComposeStackTree`), computes the merge-inverse diff
against that stack (`WorldDocumentBasis.Diff`), PROVES it by re-merging before writing, and degrades to a flat save
with a named note when it cannot (basis/import unreadable, deleted, or the delta cannot reproduce the document).
Read-backs: `world.status` echoes `basis <path|none>`; `world.imports` prints the whole resolved composition stack
in merge order, each file's path paired with its alias and the top-level keys its own JSON declares; `world.save`'s echo names
the preserved basis/import count or the flat-save note. Storage composes a synced delta too, over `basis` only —
`imports` is a local-directory-load feature today, not yet extended to the cloud sync path:
`IWorldDocumentSource`/`WorldDefinitionFileSource.TryComposeChain` generalize the chain walk onto any byte source,
and `Puck.World.Server`'s `WorldStorageDocumentSource` resolves basis members against a flat cloud
`puck/worlds/basis/{name}` namespace (`WorldOwnedWorldSync.BasisAddressFor`) — the storage neighbour resolver and
`storage.pull` both compose before parsing, exactly like a directory load. `storage.push` pushes the whole chain
(each link its own blob) via `WorldDefinitionFileSource.TryResolveChainFiles`, deduplicated per push call when two
owned worlds share a basis. An entry's `as` composes the fragment under a namespace: every name the fragment declares at a `Declares` site of
`WorldNameRegistry` (`src/Puck.World.Schema/WorldNameRegistry.cs`; the generated table is
`docs/world-name-registry.md`, `puck registry --check`) becomes the generated name `<alias>$<name>` and every other
registered site in the fragment — bare name positions, `$` channel segments, `$cell:`/`cell:`/`$expr:` keys, infix and
postfix expressions, `state.<row>` bindings — is rewritten to match (`WorldModuleNamespace`); names the fragment does
not declare stay as written. Placements, prototypes, clocks and screen materials are namespaced too, each in its own
namespace (a material is a `bindings` export, which a screen's or face's `material` names); spawn points,
kits, looks and cameras stay flat. A host writes the document spelling (`world.state kart$lap`, a restated court
`{"id": "dive$diveCourt", ...}`); a `.puck` source writes `alias.name` (`puck-dsl`). An alias is a bare identifier (letter or underscore, then letters, digits, underscores).
One fragment composes twice under two aliases; an entry with no `as` composes its names unchanged. A fragment's
names are private by default: its `exports` record (`WorldExports` — `reads`, `actions`, `bindings`, each naming the
fragment's own declarations) is the surface a host may bind, and at compose time (`WorldModuleExports`, same pass)
every other layer — the importing file's body, its basis, each sibling import — refuses by name the first registered
site spelling a private name, quoting the JSON path and the export list that would admit it (the registry field's
`Facet`: effect destinations, transform targets, and a board facet's `occupancy` are `actions`; HUD/overlay/camera
bindings are `bindings`; every other read position is `reads`). The member is stripped from the composed tree, a
document loaded as a world with `exports` on it refuses at validation, and `world.imports` prints each layer's
`exports[...]`. Law suites: `tests/Puck.World.Games.Tests/ModuleExportsLawTests.cs`,
`tests/Puck.World.Schema.Tests/WorldNameRegistryLawTests.cs`, `tests/Puck.World.Schema.Tests/WorldExportsLawTests.cs`.
Law suite: `tests/Puck.World.Server.Tests/DocumentBasisLawTests.cs`,
`StorageCompositionLawTests.cs`.

**Shared content is authored, never an engine default.** The live debug world
and garden take the Moth avatar (`avatars/moth.puck`: body, channels, bindings,
kit, motion programs, camera, seat camera feel) as their basis and import
`worlds/standard/standard.puck` (the authored inputs, quality presets, skin,
cursor, key hints, icons, binding bar, play wheel, camera feel and editor) as a
document, as the Moth imports the standard's `inputs.puck` and `quality.puck`;
the debug world's `controls.puck` refines the standard with Go/Tour and Places.
A world that imports no theme draws the engine's neutral theme. The standard's
`skies.puck` and `camera.puck`, `worlds/games/chess.puck`, and the debug world's
`shapes.puck` and `studio.puck` are module libraries whose templates the
importing file expands; a template can emit rules and rows, but an `enum` it
emits does not fold its members, so the importing source declares enums itself. The quarantined
`standard.puck` library and the island built on it are prior art. Absent means
absent: `channels` resolves to NONE (a kit whose motion program claims
`MoveAdvance`/`MoveStrafe`/`Turn` refuses by name when nothing declares them),
and `views` resolves to `WorldViewDefaults.Absent`, a placeholder holding the
property non-null between parse and validation which the validator refuses for
any document whose `bodies.capacity` is nonzero — the same derived refusal
`kits` carries, so a seatless document may still author neither. A world that
wants only its own `layouts` and other sections over its basis authors just
those sections in its own body (the ordinary basis-refine rule above).

## The validator — the one thick gate

`WorldDefinitionValidator.cs`: `TryValidate(definition, out reason)` /
`Validate(definition)` run over the ENTIRE composed candidate — at boot, on
every live mutation, on whole-document swap, and on every undo-replay entry —
so builders and appliers never repeat semantic checks. Refusals are an
aggregated STRING list (`"Invalid WorldDefinition: …"`); the one
enum-reasoned section is HUD (`HudRowValidation.Refuse` appends a `HudRefusal`
reason as `hud.<Reason>: …`). There is no separate incomplete-document
refusal: an absent required section resolves through its accessor to the
section's own `Absent`/empty placeholder (`Hud`, `Views`, `Kits`, …), and the
validator refuses it BY NAME from whatever derived rule that placeholder
violates — `views` and `kits` refuse for any document whose
`bodies.capacity` is nonzero, so a seatless document may author neither.

Notable validator constants:
`MaxSurfaceDimension = 4096`, `MaxLookScale = 16f`. Screen indices are
validated unique, `< SdfProgramBuilder.MaxScreenSurfaces`, and leave room after the highest authored index for Authoring.DerivedFaceScreens. The derived band follows that authored index rather than reserving a fixed upper half.

This is what a compiled `.puck` document's `puck compile --validate` runs
before writing JSON — see [documents.md](documents.md)'s "Verifying a change
here".

## Serialization (`WorldDefinitionSerialization.cs`)

- `WorldJsonContext` — System.Text.Json source-generated: camelCase members,
  `UnmappedMemberHandling = Disallow` context-wide, `WriteIndented`.
- **Strict parse, precisely.** An unmapped JSON member on any NESTED row is a
  hard parse failure naming the member and row type. At the document ROOT,
  unknown keys land in `Extensions` and then VALIDATION refuses them unless
  the key starts with `$` or `_` (`DocumentExtensionsPolicy.IsReservedKey`);
  reserved-prefix keys round-trip untouched and are never interpreted.
- **Enums by name** through `StrictEnumConverter<T>` — an unknown or numeric
  enum token is a parse error, never a silent default. (`CommandPhase` from
  `Puck.Commands` registers as a closed generic on the context's `Converters`
  because it cannot carry the attribute.)
- **`Vector2`/`Vector3`/`Quaternion` literals as `[x, y]`/`[x, y, z]`/`[x, y, z, w]`**
  via `Puck.Assets.Documents.Vector2JsonConverter`/`Vector3JsonConverter`/
  `QuaternionJsonConverter` — the one literal spelling every document family
  (world, creation, audio, synth) shares; the object form is refused. World and
  embedded-creation spatial fields additionally use `DocumentVector2`/`DocumentVector3`/
  `DocumentQuaternion`, accepting a `state.<row>[.<key>]` string that names a
  Text cell holding the matching array. `WorldStateDocumentValues` resolves
  those only after the whole world parses, retains the reference for canonical
  write-back, and rehydrates a fresh candidate when a referenced state row is
  mutated — or when a row write introduces a reference (`WorldDocument.TryCompose`;
  the `creations` arm resolves a private copy of the submitted row first, since
  its canonicalizer reads bound values) — so a rejected candidate cannot alter
  the live value holder.
- **State-backed identifiers** use `DocumentIdentifier`: an ordinary string
  remains literal, while a `state.<row>[.<key>]` string reads its identifier
  from a Text state cell. This includes binding-group identifiers on chord,
  context, and wheel rows (see [bindings.md](../../input/references/bindings.md)); creation row/document/shape names; look names and
  creation sources; and kit/look assignment row entries. Put linked names
  behind one cell when they must rename atomically. Resolution precedes
  validation and binding composition, and a live cell write rehydrates,
  re-resolves, recompiles, and validates the complete candidate.
  `WorldStateDocumentValues.TryResolve` is the ONE resolution door and every
  path that turns bytes into a live document runs it — `WorldJsonPayload.
  TryParse` (file loads, both neighbour resolvers, console inline JSON),
  `WorldDefinitionSerialization.Deserialize` (replay embeds, checkpoints,
  the federation replica leaf, a delivered identity document), and
  `WorldProjection.TryToDefinition` (the presentation leaf) — so a DELIVERED
  definition is indistinguishable from a file-loaded one. A new delivery path
  that decodes a document without it is the defect this door exists to
  prevent.
- **`$type`-discriminated unions:** `ActionPredicate`, `ActionEffect`,
  `WorldScreenSource`
  (`none`/`machine`/`producer`/`view`/`session`/`text`/`probe`; a `producer` names a registered image
  producer by id with its own settings object, validated by `WorldImageProducerVocabulary`),
  `WorldLookSource` (`catalog`/`creation`), `WorldAnchor`
  (`entity`/`entityPart`/`placement`/`group`/`seat`/`recentSpeaker`), `WorldCameraProgramOp`
  (`anchor`/`offset`/`lookAt`/`orbit`/`path`/`dynamics`/`clampPitch`/`fieldOfView`/`blend`/`selectProgram`) and
  `WorldCameraSubject` (`reference`/`placement`/`worldPoint`), `WorldSpeakerSource`
  (`none`/`machine`/`tune`/`synth`); `puck search -M 0 JsonPolymorphic src/Puck.World.Schema`
  lists the rest. A state row is not a `$type` union: its `kind` member picks the
  `CellKind`. `$type` failures do NOT all surface as
  `JsonException` — `WorldJsonPayload.IsParseFailure` is the complete set;
  route author-supplied JSON through `WorldJsonPayload.TryParse`.
- **Canonical write-back** (`Serialize`/`Save`): UTF-8 no BOM, LF newlines,
  two-space indent, record-declaration member order, invariant shortest
  round-trip numbers, exactly one trailing newline. A load→save of an
  untouched world reproduces the file byte-for-byte — a useful observation,
  never an acceptance gate.
- Embedded Forge documents (creations) bridge through
  `Puck.Assets.Documents.DocumentJsonOptions.Shared` so the inline embed
  carries exactly the vocabulary its canonicalizer hashes. Tunes/patches are
  never embedded — `WorldTune`/`WorldPatch` are name/source/hash reference
  rows resolved off disk by `WorldAssetRowLoader`, the same shape
  `WorldMusicRow` already uses.

**Adding a schema field — the sweep direction.** Adding a top-level SECTION
refuses at boot until every shipped world carries it (through its own
`Absent`/empty placeholder's derived validator rule — see "The validator"
above). Adding a NESTED member does not refuse at parse — it silently defaults, and
usually (not always) refuses at validation — so sweep the shipped worlds
either way. Adding a JSON key with no model member always refuses. Renaming a
member is doubly fatal. One `world.save` re-canonicalizes a file to the
current model.
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