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-identity.md

View on GitHub
# Identity conventions and owned-world identity documents

Part of [`puck.world.definition.v1`](documents.md). See
[documents-state.md](documents-state.md) for `state.identity` row mechanics.

## Identity conventions

- Screens are POSITION-ADDRESSED by `WorldScreen.Index` (an engine
  screen-surface index); the derived `WorldMachineCableGroup.Screens` and
  `WorldSpeakerSource.Machine` key off the same int — screen index IS machine
  identity for screen-hosted machines. Cable linking itself is authored
  per-machine: a `Machine` source's `cable` port (`WorldMachineCable` — name +
  position), never a row of its own; `WorldDefinition.MachineCableGroups()`
  derives the groups.
- Everything else is string-addressed: stable ids (`WorldPrototype`,
  `WorldPlacement`, `WorldSpawnPoint`,
  `WorldBindingOverlay`, HUD panels/elements, profiles) or names
  (`WorldCamera`, `WorldKit`, `WorldLook`, `WorldChannel`, `WorldSpeaker`,
  `WorldAddonRow`, `WorldViewLayout`, `WorldStateRow`).
- Spawn points carry both modes deliberately: `Id` is the mutation address,
  but LIST ORDER is seat identity (seat n spawns at `SpawnPoints[n]`).
- Grant rows are keyed by their `(grantee, capability, subject)` triple —
  a grant IS that triple (`Exclusive` and the co-drive fields are row data,
  not key). `GrantSubject`, `Grantee` and `Principal` serialize as the console
  grammar tokens through their own converters (`all`, `body:<n>`,
  `screen:<n>`, `section:<name>`, `state:<name>`,
  `region:<name>`, `seat:<n>`, `creation:<id>`, `placement:<id>`;
  `seat1..seat4`, `console`, `addon:<name>`,
  `peer:<index>:<generation>`, `world`; a grantee adds `group:<id>` and
  `document:<id>`). A member-wise serialization would permit denormalized
  "phantom grant" keys no table lookup could match. Two asymmetries to know:
  `composition` is a write-only subject token (echoed by `world.grants`,
  rejected on read — only the boot seed constructs it). A peer identity is
  always generation-bearing; reusing an index after disconnect mints a new
  token and cannot inherit the previous generation's grant key. `region:`/
  `seat:` are the world-events feed's subjects (Observe-only, untrusted
  principals only — see references/addons.md's "World events" section);
  `WorldPlacement.Region` (`WorldPlacementRegion`) is the document-side
  facet a region name addresses — a sphere or an oriented box in the placement's resolved frame
  (`WorldPlacementRegion.ShapeAt`), keyed by the placement's own `Id`; `body.place` lists the regions a body stands in. `WorldPlacement.Attach`
  (`WorldPlacementAttach`) is a placement's BODY-ATTACHMENT facet — a
  0-based `body:<n>`-indexed target plus a local offset rotated into the
  body's own frame. It derives TWICE off the one authored facet: the
  authoritative fixed-point resolve
  (`WorldPlacementAttachment.TryResolve` in `Puck.World.Server`, called on demand by
  `world.attachments` and every active tick for attached gravity areas), and
  the rendered pose —
  presentation float over the client's INTERPOLATED body pose, packed every
  frame by `src/Puck.World.Client/WorldCreationInstances.cs`. Riding the interpolated pose is what
  keeps an attached row as smooth as its body; reading the authoritative
  resolve in the renderer would judder at the tick rate. An attached row
  draws through live creation storage; it allocates its actual motion slots and has no registration ceiling. Its authored Position/YawDegrees are inert. `Region`, `Solid`
  (under the analytic contact provider), and `Emission` combine with
  `Attach` — each reads the resolved DYNAMIC pose instead of
  the row's static transform (`WorldEventFeed.CollectRegions`,
  `WorldColliderSet.RefreshAttached`,
  `WorldCreationInstances.TryShapePosition`/`RootPose`), so an equipped item's
  aura/hitbox/voice tracks its carrier; an inactive carrier makes the facet
  contribute/sense/sound nothing, the same verdict the render stamp already
  had. `Distribution`/`Mirror` (static-stamp-only) and `Inhabit` (a row
  cannot both spawn its own bodies and ride another's) still refuse by name
  rather than blend, and `Solid` still refuses under the FIELD contact
  provider (it compiles every solid row's geometry once into one SDF
  program, never rebuilt per tick — `collision.requirements` non-empty). An
  out-of-range `BodyIndex` refuses at author time; a valid but
  inactive/despawned target body makes the row contribute nothing at
  RUNTIME — no refusal, `world.attachments` names the reason and the stamp
  parks below the floor. `WorldPlacement.Contribution`
  (`WorldPlacementContribution`) is the CONTRIBUTION SLOT facet — a host world
  authors the frame and a federation partner fills it. Its two halves never
  mix: `tenure` (`Presence`/`Endowed`), `slotCreationId`, `link` (an
  `adjacencies` row name, required for `Presence` and refused for `Endowed`)
  and `graceSeconds` are AUTHORED; `contributor` and `retractDeadlineTick` are
  SERVER-STAMPED and a submission naming either is refused BY NAME
  (`src/Puck.World.Server/WorldDocument.Compose.cs`'s `TryComposeUpsertPlacement` reads the
  contributor off the acting principal — accepting an authored one would be the
  laundering the acting-principal rule forbids). An UNFILLED slot shows its own
  `slotCreationId`, so no creationless placement has to be representable, and
  the validator pins the pair. Retraction — the per-tick
  `SweepContributionTenure` pass, once the watched link has read dropped past
  `graceSeconds` — re-points `creationId` back and clears the stamp through
  ordinary journalled mutations, so the host's FRAME stands, only the piece
  goes, and `world.undo` puts it back. It defers (never orphans) while the
  slot's inhabitant is drive-possessed. Read back with `world.contributions`.
  `WorldPlacement.Respond` (`WorldPlacementResponse` rows) is the RESPONSE
  facet — a state-driven prototype swap: an ordered `{when, prototypeId}`
  list, each `when` the SAME `WorldFieldCondition` grammar a
  `fields.reactions` Transform/Expose condition uses, tested at the
  placement's own coupled lattice cell
  (`Puck.Physics.Fields.FieldLattice.TryBodyCellOf`) by the per-tick
  `SweepPlacementResponses` pass — run right after the field lattice steps,
  so it reads THIS tick's own writes. Every entry is tested; the sweep
  records which held in the row's `holding` mask (bit i for entry i,
  refused on a row without `respond`) through an ordinary `UpsertPlacement`
  under `Principal.World`. The authored `prototypeId` is never
  overwritten: the row shows the FIRST holding entry
  (`WorldPlacement.ShownPrototypeId`, which every draw and collide consumer
  reads), and its authored prototype once none holds — a response lasts as
  long as its condition, so an author who wants it to outlast the cause
  latches the cause in state. A reader whose disclosure withholds a cell an
  entry reads is handed the mask without that entry; a field entry reads the
  lattice, which is not hidden, so it holds for every reader. Refused
  alongside `Attach`/`Inhabit`/`FaceSources`; every candidate prototype (the
  authored one and every entry's) must resolve to a declared, non-animated
  creation, and the analytic solid-collider ceiling counts the WORST CASE
  across every variant the row could show. Read back with `world.responses`
  (shown, authored, and the holding entries) and `world.placements`
  (`prototype=` is the shown one; `authored=` follows while an entry holds).
  `WorldPlacement.Deal` (`WorldPlacementDeal`) is the DEAL facet — the row is
  a template whose children are dealt from a keyed `state.world` row of any
  cell kind, one child placement per cell named `<template>/<cellKey>`,
  parented to the template at an offset of its own `distribution` region
  (Lattice/Noise/Scatter only; the region must materialize at least the
  row's capacity), carrying the template's prototype and `solid`/`grip`/
  `region`/`emission`; `deal.variants` maps a second keyed row's same-keyed
  cell text to a prototype. The per-tick `SweepPlacementDeals` pass
  (`WorldTick.Deals.cs`, right after the response sweep) lands every
  re-dealt template's children through `WorldDocument.InstallPlacementProjection`
  as derived gameplay state (one installed projection, no declaration journal entry or edit echo):
  a child keeps its offset while its cell is present, a departing cell frees
  its offset and moves no sibling, an arriving cell takes the lowest free
  offset. The sweep re-deals when the row, variant row, template or placement
  projection changes. Source membership owns child presence: undo the source
  cell to undo its deal; a child-only removal is reconciled on that tick,
  independently of hidden-only edits. The template renders and collides as nothing; an authored id
  spelling `/` refuses by name. Read back with `world.placements` (`dealt
  from <row> (<n> of <capacity>)` / `dealt by <template>`); `world.budget`
  counts every template's offsets. The debug world's granary board
  (`worlds/debug/granaries.puck`, guide `worlds/debug/granaries.md`) is the
  worked example.

## Owned-world identities

World/owned-world ids (`src/Puck.World.Server/WorldOwnedWorlds.cs`) and `world.instance.start`
names are `SafeName` (`Puck.State/SafeName.cs`); the verb starts through
`WorldInstanceHost.TryStartAuthored`, which refuses a name carrying `~`, the
joiner of the instance names the engine generates itself (`<site>~<n>`,
`WorldSessionResolver.FreshInstanceName`). The rows the engine declares on an
identity are the generated names in `WorldIdentityRows` (`identity$move-speed`,
`chat$log`, `controller$<key>$machine`, `<row>$seq`). `SafeName` is the reserved-character
kernel `CellName` shares, plus a bare `"."`/`".."` refusal instead of the
dot-free rule; `WorldDocumentName.For` takes a `SafeName` and escapes
nothing, so the id→file-name mapping is injective into file-name STRINGS — but
not into storage LOCATIONS, since the catalog directory resolves names
case-insensitively. One id names one location only under the separate
**case-insensitive uniqueness** rule the two admitting doors hold (the seed-list
validator and `WorldOwnedWorlds`).

An identity is an ordinary owned `WorldDefinition` document, not a catalog
row: `WorldOwnedWorlds` (`src/Puck.World.Server/WorldOwnedWorlds.cs`) is the CATALOG (seats
select identities from it; a seat's profile IS a `WorldIdentity` wrapping one
owned document), one file per identity under the local state directory,
named `WorldDocumentName.For(id)` (`"<id>.world.json"`). Every id is a
`SafeName`, so the mapping escapes nothing and is injective into file-name
STRINGS — but a string is not a storage location, and the catalog directory
resolves names case-insensitively, so **ids are unique IGNORING CASE**. That is
the rule the seed-list validator holds (a case-variant pair refuses at
validation) and the rule every id comparison in the catalog holds
(`FindById`, `Create`'s collision guard, `ReplaceFromSync`'s match, and the
file-name check). A loaded file whose name does not match
`WorldDocumentName.For` of its OWN declared identity `id` — ignoring case,
so a case-only rename of a catalog file is ADMITTED and keeps the name it
carries — is refused by name (`[identity] owned world refused: …`,
distinguishing "the name another file in this directory carries" from "a name
no file in this directory carries") rather than silently renamed or merged —
that document parses, so it stays where it is and the refusal names the remedy.

A document the loader refuses is handled by the CLASS of the refusal, and no
refusal is ever a hard boot failure. Only a verdict on the BYTES — the
`{path} is not a valid puck.world.definition.v1 document: …` and `cannot decode …`
classes, which include a document with no `identity` section — is DISCARDED:
the file moves into the `unloadable/` subdirectory (outside the catalog's
`*.world.json` top-directory glob, like `basis/`), once, so the next boot has
nothing left to refuse. Every other class can answer differently on the next
boot — `cannot read …` (locked or half-written), `no file at …`, `… basis
composition refused: …` (a chain link not placed yet), `… document validation
refused: …` (which may rest on an adjacency neighbour the sweep is itself
moving) — so those files STAY where they are and are only named. Quarantining
them would cascade: the neighbour resolver reads the same directory the sweep
empties, and the seeding pass would write defaults over every freed name.

Each half narrates as ONE stderr line — `[identity] discarded N unloadable
owned world(s) into '…'` and `[identity] refused N owned world(s) this boot
could not read …` — grouping file names by their shared reason, with the path
itself stripped out of the reason so one fault across a directory reads as one
group and a lone corrupt file stands in a group of its own. There is no
migration and no read-side tolerance for a retired shape: an emptied catalog
re-seeds from `playerDefaults.identities`, and a catalog that still holds
documents simply lacks the discarded ids.

Retention is exact on both sides. A quarantine destination that is already
taken (deterministic file names, and the catalog re-seeds a freed name) takes
an ordinal suffix rather than overwriting the earlier copy, and the seeding
pass SKIPS any seed id whose catalog path still holds a file or directory — so
a disposal whose move failed, or a document left in place, keeps its authored
bytes for the next boot instead of being replaced by a fresh default, and a
directory occupying a deterministic file name cannot crash startup.
`identity.create` refuses an id whose catalog path is occupied for the same
reason, reading the DIRECTORY rather than the identity list — a boot that
admitted nothing leaves that list empty while the bytes are still on disk. Read
back with `WorldOwnedWorlds.Discarded` + `identity.list`'s `discarded=` column
(disposals — the moved bytes stay readable under `unloadable/`) and
`WorldOwnedWorlds.Refused` + `identity.list`'s `refused=` column (everything
left in place, whatever the class).

Storage narration is path-free, built so at its source. A refusal or narration may name what a document says, such as
its authored `basis` reference exactly as written, and a document by its file name; it never names what the host
resolved: an absolute path, the catalog root, a probe file, or an exception message that quotes either. The loader and
composers (`WorldDefinitionFileSource`, `WorldCompileSession`, the push chain walk, the save-flat note) name documents
through `WorldDocumentLabel.Of` and failures through `WorldDocumentLabel.Failure` (access denied, file in use, no
space left, ...), and a host that must not even show the file's directory passes `displayName` to the loader
(`TryLoadFileForAdmission`; the catalog passes the file name). `NarrationPaths.AssertNone` holds that over the save, discard,
refusal, save-flat and push narration by asserting the test's own paths are absent.

**Seeding.** When the identity directory holds zero admitted documents,
`WorldOwnedWorlds` seeds one owned world per `playerDefaults.identities` row
(`WorldIdentitySeed(Id, Name, Color)`, validated non-empty, ids and names both
unique ignoring case, hex color — `ValidateIdentitySeeds` in
`WorldDefinitionValidator.Identities.cs`; an id is a document name, so a
duplicate is refused in `DocumentName.Collision`'s words) and persists each
immediately.

**`WorldIdentity`** (`Puck.World.Schema/WorldIdentity.cs`) is the runtime
handle over one owned document's `identity` section
(`WorldIdentityDefinition(Id, Name, Color, MoveSpeedState, TurnSpeedState,
Controllers, Voice, Facts, Records)`; `Records` names the capacity-one record pools the identity owns and carries across authority boundaries): `MoveSpeed`/`TurnSpeed` read
and write the owned document's OWN `state` rows named by those state-row
references; `Bindings` is the owned document's own first `bindingOverlays`
row's document (the seat's profile binding layer — see
[bindings.md](../../input/references/bindings.md)); `Hud` is the owned document's first `Hud` panel (the identity's
PRIVATE seat-scope HUD panel, see `hud.md`). `Voice` (`WorldVoiceProfile?` —
a `PatchId` resolving against declared `patches` rows, plus a positive
`CadenceTicks`) selects the identity's synthesized voice-babble pitch/timbre
and cadence. `WorldAudioDirector.TriggerBabble` reads it, drives
`Puck.Audio.Simulation.VoiceBabbler` for the cadence-jittered per-syllable
trigger schedule, resolves the patch, and fires one seeded trigger per
syllable under the `voice.babble` cue token (`voice.state`/`voice.babble` are
its read-back/debug-trigger verbs). Two things stay open: no producer yet
estimates an utterance's syllable count from dialogue/caption text, and a
babbling identity has no live-body correlation, so every syllable voices
listener-placed rather than at a resolved world position.

**Facts.** `Facts` (`WorldIdentityFacts {state, capacity}`, defaulting to
`identity-facts` holding 64) names the keyed `int` row of facts the identity
carries on its own document — minted on the first write, capacity-bounded,
validated as that one number. A world receives them only through a reserved
keyed `int` row named `identity` it declares in `state.world`
(`WorldIdentityFactLane`; cells keyed `<bodyIndex>-<fact>`), loaded into a
body's cells when a seat binds the identity and zeroed when it unbinds. A rule
writes one with the `setIdentityFact` effect (`{key: <body>, fact, value |
expression}` — lane and identity row together through `WorldOwnedWorlds.TrySetFact`,
which persists an identity the catalog owns and keeps a visitor's fact on the
travelling row of the projection it arrived as; the visitor's own authority
adopts it when the seat comes home) and reads one through `$identity:<bodyRef>:<fact>`
(0 when never written or no identity drives the body); a world declaring no
lane refuses both by name at compile (`IdentityLaneUndeclared`). The lane is
trait-free: an `advance`, `dynamics` or `cycle` on the row or any cell is
refused by name at validation and at compile (`IdentityLaneTraited`, one check,
`WorldIdentityFactLane.TryAdmitTraits`), because the server compares and
persists the stored value while the operand reads the live one. A body driving
under no identity refuses the write at fire time (`IdentityUnbound`), and
a lane write the row refuses (its envelope, say) reports that write's own
reason under `IdentityFactUnwritable`; the lane mints a cell only when it holds
none under the key (`StateArena.TryWriteOrMint`). `identity.facts [player]` echoes the identity's row;
`identity.fact.set <key> <value> [player]` writes one from the console (a seat
principal only its own seat's); `world.state identity` echoes the lane.

**Seating.** `SessionRequest.SetIdentity` (gated on `WorldCapability.Drive`
over the targeted slot's body — the same grant `Join`/`Leave` use) sets a
slot's participant to a named owned identity.

**Cross-document durable state.** A body's authored durable-state writes
(`WorldPopulation.DurableStateOutputs`, drained every tick in
`WorldServer.Step`) submit against the OWNER identity's own `state` rows
through `WorldOwnedWorlds.Submit`/`Decide` — gated by a `Mutate` grant the
owner's OWN document declares for the writing document's principal
(`Grantee.Document(sourceDocumentId)`) over `state:<slot>`; refusals
name a missing source id, an unknown owner, a missing/unknown slot, the
absent grant, the wrong storage kind, an out-of-envelope or negative value,
or overflow. `Save()` re-serializes the owner through
`WorldDefinitionSerialization.Save` to its own file on every accepted write;
`ReplaceFromSync` adopts a pulled cloud copy the same way.
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