@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/multiplayer-logic.md

@@ -41,6 +41,8 @@ Lives in `public/helix.json` (manifest `helixVersion: "0.3"`, with `maxPlayers >
   "states":  { "initial": "…", "phases": […] },        // §12 state machine
   "events":  { "<name>": {…} },   // §13 server→client broadcasts
   "actions": { "<name>": {…} },   // §14 client→server intents
+  "counters":     { "<name>": {} },        // §18 world-global atomic totals
+  "leaderboards": { "<name>": {…} },       // §18 keep-best rankings
   "rules":   [ { "when": …, "if": …, "then": […] } ]   // §3 behavior
 }
 ```
@@ -75,7 +77,13 @@ their own `vars` (§9). A var declaration is a discriminated union on `type`:
 ```
 
 **Reserved built-ins (read-only — don't redeclare):** players expose `position` (vec3), `connected` (bool), `active`
-(bool); the room exposes `phase` (string). Read them like any var (`self.position`, `room.phase`).
+(bool), `crouched` (bool) and `ragdolled` (bool — limp, whether alive or dead); the room exposes `phase` (string).
+Read them like any var (`self.crouched`, `room.phase`). A `playerVars` entry named like any of these fails publish.
+
+**`persistent: true`** makes a var survive the session (§18). On a **playerVar**: scalars only
+(`number`/`string`/`boolean`/`vec3`), no `merge`. On a **roomVar**: scalars AND collections, and a `merge` policy is
+then **required** (plus an optional `key` naming its own document). Never on entity vars, `ref`, or `list of ref`:
+publish rejects those — a ref is a session identity.
 
 ---
 
@@ -92,7 +100,8 @@ their own `vars` (§9). A var declaration is a discriminated union on `type`:
   `destroyEntity`→`entityDestroy`, `takeover`/`requestOwnership`→`ownershipChanged`) queue and drain **breadth-first
   after** the primary rules, bounded by `maxCascadeDepth` (16). Publish rejects cascades that could cycle. (`varReached`
   is separate — it is edge-checked once at the **end** of the rule phase, not part of the cascade drain.)
-- Caps: `rules` ≤128, effects per `then` ≤16, `if` depth ≤8 / ≤64 nodes.
+- Caps: `rules` ≤768, effects per `then` ≤16, `if` depth ≤8 / ≤64 nodes. (The rule cap is a declaration
+  ceiling — the per-tick `tickNodeBudget` in §16 is unchanged and binds long before it.)
 
 ---
 
@@ -107,6 +116,7 @@ their own `vars` (§9). A var declaration is a discriminated union on `type`:
 | `zoneInside` | `zone` | `self`; `source` = carrier (attached zones) | every tick while inside |
 | `playerContact` | `radius` | `self`, `other` | once per pair entering `radius` (the tag primitive) |
 | `action` | `name` | `self` = actor | a client sent a declared action (args pre-validated); read `action.args.<x>` |
+| `purchase` | — | `self` = the buyer | the platform settled an in-world purchase for this seat; read `purchase.productKey` / `purchase.purchaseId` (§20) |
 | `stateEnter` / `stateExit` | `phase` | — (room) | on `transitionTo` in/out of a phase (cascade) |
 | `timerElapsed` | `timer` | `self` = the timer's key (if keyed) | a timer deadline passed |
 | `entitySpawn` / `entityDestroy` | `kind` | `self` = the entity | once on spawn / destroy |
@@ -157,6 +167,30 @@ A `HelixExpr` is one of:
 - `{"op":"hostLoad","of":<ref>}` → number of entities that player controls
 - `{"op":"sameRef","a":<ref>,"b":<ref>}` → boolean (identity; false if either unset)
 
+**Entitlements** (in-world purchases — §20). `of` is **required** on both (no implicit `self`) and must be a player:
+- `{"op":"hasPass","passKey":"<key>","of":<ref>}` → boolean — does that player hold the pass?
+- `{"op":"balanceOf","code":"<code>","of":<ref>}` → number — their balance of that currency
+
+**Weapon damage** (guns as published definitions — the `shooter-range` template is the worked config):
+- `{"op":"weaponDamage","of":<ref>,"target":<ref>?,"part":<string expr>?,"default":<number>?}` → number — the
+  damage of the gun the `of` player is HOLDING, read from its PUBLISHED definition (base × pellets; with `target`,
+  the definition's distance falloff applies over the of→target distance; a `part` resolving to `"head"` then
+  multiplies by the definition's `damage.headMultiplier` — publish-capped 1..3, absent = ×1, any other part
+  value = ×1. Pattern: `"part": {"var":"action.args.bodyPart"}` off a string-enum action arg — see
+  `shooter-worlds.md` §damage for both rule shapes). Requires the block-level
+  **`weaponItems`** declaration: `"weaponItems": ["<vaultAssetId>@<version>", …]` (≤16) — the room fetches
+  each pinned, checksummed definition ITSELF, so the number is server-trusted and a client can never name
+  its own damage. A player holding no declared gun yields `default` (0 when omitted) — your rule still owns
+  the consequences (clamp, scale, ignore).
+- `{"op":"itemDamage","item":"<vaultAssetId>@<version>","default":<number>?}` → number — the damage of the
+  definition that literal PIN names, whoever is holding what (base × pellets, room-resolved). The pin must
+  itself be one of the declared `weaponItems`, or the world fails validation; any miss yields `default` (0
+  when omitted). NO falloff leg by design — a blast's distance term is blast-point→victim, which your own
+  `forEachPlayer` rule computes.
+- **HELD vs THROWN:** `weaponDamage` for a weapon still in the hand (a rocket claimed at the impact),
+  `itemDamage` for one that has left it (a grenade fuse) — there `weaponDamage` silently returns whatever
+  gun the thrower now holds. Explosives, rule by rule: `shooter-worlds.md` §9.
+
 ---
 
 ## 7. Refs (`HelixRef`)
@@ -181,7 +215,9 @@ pattern for cross-player writes, subject to the firewall in §17).
 
 **State** `{"do":"add","target":<lv>,"by":<expr>}` · `{"do":"set","target":<lv>,"to":<expr>}` ·
 `{"do":"setRef","target":<lv>,"to":<ref>|null}`
-**Movement** `{"do":"teleport"|"respawn","player":<ref>,"to":<vec3>}` (server-authoritative; re-anchors the move gate)
+**Movement** `{"do":"teleport"|"respawn","player":<ref>,"to":<vec3>}` (server-authoritative; re-anchors the move gate).
+The ONLY legal way to move a player across the map: a client that teleports its own body trips the movement gate and its
+avatar freezes for everyone else (wire `LocalReconciler` to land these locally; round resets = `forEachPlayer` → `respawn`)
 **Loops**
 - `{"do":"forEachPlayer","as":"p","where":<expr>?,"includeEliminated":false?,"then":[…]}`
 - `{"do":"forEachEntity","kind":"<k>","as":"e","where":?,"then":[…]}`
@@ -201,6 +237,11 @@ pattern for cross-player writes, subject to the firewall in §17).
 
 **Turns & elimination** `{"do":"advanceTurn","order":<lv list-of-ref>,"index":<lv number>}` (skips inactive, wraps) ·
 `{"do":"eliminate","player":<ref>}` / `{"do":"revive","player":<ref>}` (eliminated = `active:false`, still connected/spectating)
+**Persistence (§18)** `{"do":"save","player":<ref>}` · `{"do":"saveRoom","key":"<destination>"?}` ·
+`{"do":"increment","counter":"<c>","field":"<f>"?,"by":<expr>}` ·
+`{"do":"submitScore","board":"<b>","player":<ref>,"score":<expr>}`
+**Achievements (§19)** `{"do":"awardAchievement","key":"<key>","player":<ref>}`
+**In-world purchases (§20)** `{"do":"consume","code":"<code>","amount":<literal int 1..1000000000>,"player":"self"}`
 
 ---
 
@@ -228,6 +269,7 @@ Server- or client-hosted objects beyond players. Declare per kind under `entitie
 | `idleTimeout` | seconds | a hostless shared entity despawns after this |
 | `zone` | attached zone | an entity-attached spatial volume (§10) |
 | `physics` | physics block | opt-in client-simulated **dynamic rigid body** (colliding) — needs `authority:"owner"`; see "Networked physics" below |
+| `group` | name (`[a-z0-9-]{1,32}`) | atomic-claim group for MULTI-body sets (a pool rack) — requires `physics` + `authority:"owner"` + `transferPolicy:"takeover"`; see "Group claims" (§9a) |
 | `rejoinOnRelease` | `nearestPoint` (default) \| `timeIndex` \| `seekBack` | for a HYBRID (physics + non-static `motion`): how it re-bases its server path when released |
 
 **Motion** types: `{"type":"linear","velocity":[…]}`, `{"type":"orbit","center":[…],"radius":r,"speed":rad/s}` (circle in the XZ plane),
@@ -295,6 +337,36 @@ handle) created against one shared `SharedPhysicsWorld` you `step(dt)` each fram
 wiring. Fast/twitchy physics may opt the room up to `uploadHz:20` (§1) — which caps `maxPlayers` at 12. Cap:
 **`physicsKinds` ≤ 8** per world.
 
+### 9a. Group claims — an atomic rack (many bodies, one break)
+
+`claimOnContact` transfers ONE contested body. A **pool break** is sixteen: the shooter must own the whole rack
+for the same tick or the balls desync into per-ball tugs-of-war. That is what an entity **`group`** is for:
+
+```jsonc
+"entities": { "ball": { "authority":"owner", "maxSpeed":18, "transferPolicy":"takeover", "group":"rack",
+                        "physics": { "bodyType":"dynamic", "shape":{"type":"sphere","radius":0.29} } } },
+"actions":  { "breakShot": { "args": { "dir": {"type":"vec3"} }, "claimGroup": "rack" } },
+"rules":    [ { "when": {"on":"action","name":"breakShot"}, "then": [ /* score/turn logic */ ] } ]
+```
+
+Publish enforces all three prerequisites on the kind (`physics`, `authority:"owner"`, `transferPolicy:"takeover"`)
+and that a `{when:{on:"action",name:…}}` rule exists for the `claimGroup` action. Client sequence, all in ONE tick:
+`room.sendAction('breakShot', …)` → wake your local bodies → apply the impulse → let `EntityScene` upload.
+
+Two behaviors you cannot guess:
+- **A contested claim drops the ENTIRE action, rule included.** If any member is held by another actor inside the
+  minimum hold window, nothing transfers and your rule never fires — the world must not assume the action ran
+  (drive follow-up state off the rule's effects, never off having sent the action).
+- **`groupRestSnapshot` is the authoritative settle.** When every member has been at rest ~1.5 s the room broadcasts
+  `room.onMessage('groupRestSnapshot', { group, seq, entities:[{id,pos,rot}] })` (late joiners get a replay).
+  Hard-set your transforms from it and discard stale ones by `seq` — this is what makes every table agree on the
+  final rack.
+
+There is no engine helper for either half yet — the wake/impulse and the snapshot-apply are world code.
+**Compatibility:** a room build that predates group claims silently ignores `claimGroup` — the action still fires,
+just without atomicity, and no snapshot ever arrives. Publish passes either way, so verify the behavior on the
+dev stack (two clients, contest the claim) before shipping a world that depends on it.
+
 ---
 
 ## 10. Zones
@@ -307,7 +379,7 @@ Static volumes (`zones: []`) or entity-attached (`entities.<k>.zone`). Drive `zo
 ```
 `shape`: `"box"` (`center` + full `size` `[x,y,z]` — full dimensions, **not** half-extents; note this differs from a `physics.shape` box, which uses `halfExtents`) or `"sphere"` (`center`+`radius`). `tracks`: `"players"` (default) or
 `"entity:<kind>"`. `requireDwell` (s before a fresh enter fires) / `debounce` (s an exit suppresses re-enter) optional.
-Attached zones add `offset` and omit `id`. Caps: `zones` ≤64, extent ≤10000.
+Attached zones add `offset` and omit `id`. Caps: `zones` ≤256, extent ≤10000.
 
 ## 11. Timers
 
@@ -315,7 +387,7 @@ Attached zones add `offset` and omit `id`. Caps: `zones` ≤64, extent ≤10000.
 "timers": { "round": {}, "cooldown": { "keyed":"player" } }
 ```
 Room-scoped by default; `keyed:"player"` / `keyed:"entity:<kind>"` makes per-member instances (`startTimer`/`timerElapsed`
-then need/bind a `key`). Arm with `startTimer` (`seconds` floors at 0.05). Read `timerRemaining`. Caps: ≤32.
+then need/bind a `key`). Arm with `startTimer` (`seconds` floors at 0.05). Read `timerRemaining`. Caps: ≤192.
 
 ## 12. State machine
 
@@ -325,7 +397,7 @@ then need/bind a `key`). Arm with `startTimer` (`seconds` floors at 0.05). Read
 ```
 `room.phase` is the current phase; change it with `transitionTo` (fires `stateExit`→`stateEnter`). `joinPolicy.<phase>`
 controls late-join: `joinable:false` runs `onLateJoin` instead of the normal `playerJoin` rules (spectate-until-next-round).
-Caps: phases ≤32, cascade depth ≤16.
+Caps: phases ≤64, cascade depth ≤16.
 
 ## 13. Broadcast events (server → client)
 
@@ -334,7 +406,7 @@ Caps: phases ≤32, cascade depth ≤16.
 ```
 Fire with the `broadcast` effect; clients receive via `room.onMessage("scored", cb)`. Payload field types: scalars, `ref`,
 or a **collection snapshot** (`{type:"list",of:…}` / `{type:"counterMap",keys:…}` mirroring a declared var — e.g. a
-leaderboard). `to`: `"all"`, a ref, or `{team:"<playerVar>=<value>"}` (matched stringified — `<value>` is compared as a string). Caps: events ≤64, fields ≤16.
+leaderboard). `to`: `"all"`, a ref, or `{team:"<playerVar>=<value>"}` (matched stringified — `<value>` is compared as a string). Caps: events ≤256, fields ≤16.
 
 ## 14. Actions (client → server)
 
@@ -343,9 +415,13 @@ leaderboard). `to`: `"all"`, a ref, or `{team:"<playerVar>=<value>"}` (matched s
 ```
 Clients call `room.sendAction("claimHit", { target: id })`; the server validates args (types/bounds/liveness) then fires
 `{when:{on:"action",name:"claimHit"}}` with `self` = the actor and `action.args.<name>` readable. Arg types: scalars or
-`ref`. Caps: actions ≤64, args ≤16. **Actions are the cheat-resistant input path** (validated server-side) — prefer them
+`ref`. Caps: actions ≤256, args ≤16. **Actions are the cheat-resistant input path** (validated server-side) — prefer them
 over owner-entity tricks for anything that affects other players.
 
+An action may also declare `"claimGroup": "<group>"` naming a declared entity `group` (§9a): the room then treats the
+action as an atomic ownership claim over every live member of that group before its rule fires (all-or-nothing — see §9a
+for the drop semantics). Publish requires a matching `{when:{on:"action",name:…}}` rule to exist.
+
 ---
 
 ## 15. Consuming declared state on the client
@@ -367,28 +443,395 @@ place → **copy values you cache** (don't alias). **Skip your own `sessionId`**
 
 ## 16. Limits — stay inside the caps (publish enforces them)
 
-The validator rejects an over-cap config with a precise message. Key caps: `roomVars`/`playerVars` 64 · `rules` 128 ·
-effects/rule 16 · `if` depth 8 / nodes 64 · `entityKinds` 32 · `entitiesPerKind` 256 · `entityVars` 64 · `zones` 64 ·
-`timers` 32 · `phases` 32 · `events`/`actions` 64 · `listMaxLen` 256 · `counterKeys` 64 · `recordFields` 8 ·
-`stringMaxLen` 1024 · `physicsKinds` 8 (§9) · `enum` values 64 · `joinPolicy` effects 16. Var **names** are identifiers
+The validator rejects an over-cap config with a precise message. Key caps: `roomVars`/`playerVars` 384 · `rules` 768 ·
+effects/rule 16 · `if` depth 8 / nodes 64 · `entityKinds` 32 · `entitiesPerKind` 256 · `entityVars` 64 · `zones` 256 ·
+`timers` 192 · `phases` 64 · `events`/`actions` 256 · `listMaxLen` 256 · `counterKeys` 64 · `recordFields` 8 ·
+`stringMaxLen` 1024 · `physicsKinds` 8 (§9) · `enum` values 64 · `joinPolicy` effects 16 · `persistentPlayerVars` 16 ·
+`persistedPlayerBytes` 8192 · `persistentRoomVars` 16 · `persistentRoomKeys` 6 · `persistedRoomBytes` 32768 per document ·
+`counters` 16 · `counterFields` 64 per counter · `leaderboards` 8 (§18). Var **names** are identifiers
 ≤32 chars. Also: `uploadHz:20` requires `maxPlayers ≤ 12`, and the platform caps **concurrent players per room** at 24
 (extras spill into a fresh instance) regardless of `maxPlayers`. There is also a **per-tick evaluation budget**
 (`tickNodeBudget` 100000) computed statically from your rules × loop fan-out × cascade depth — a too-large `forEach`
 or deeply-nested expensive ops (`aggregate`/`nearest*`) fails publish. Simplify or spread work across ticks.
+**The raised declaration caps did NOT raise this budget** — a composition-heavy world hits the tick budget long
+before the 768-rule ceiling, so treat the declaration caps as headroom, not a target. (List-scan cost is charged
+against the specific list a rule scans, so a large lookup table read only by `listAt` no longer taxes unrelated rules.)
+`persistedPlayerBytes` is a **static worst-case estimate**, not a measured document: a persistent string counts its
+declared `maxLen` (undeclared = the 1024 ceiling), so shrink a `maxLen` — or persist fewer vars — to get under it.
 
 ## 17. Security — the cross-player write firewall
 
 Clients are not trusted. `owner`-authority entity uploads are sanity-validated, not cheat-proof. Publish **statically blocks**
 owner-entity logic from any cross-player **write OR read** — no `set`/`add`/`teleport`/`respawn`/`destroyEntity`/collection
-mutation/ownership verb/keyed timer/`broadcast` aimed at another member, and no dereferencing a client-supplied ref to
+mutation/ownership verb/keyed timer/`awardAchievement`/`broadcast` aimed at another member, and no dereferencing a client-supplied ref to
 *read* another member's var — that's a publish error, not a runtime no-op. For anything that affects *other*
 players, use a declared **`action`** (server-validated) — e.g. the `claimHit` pattern: validate distance + cooldown in the
 rule, then write to the target via `{ref: action.args.target, var: "health"}`.
 
-## 18. Where Tier-2 stops (use the escape hatch or a different layer)
+Money is stricter than this general firewall: `consume.player` is schema-locked to literal `"self"`, and the room
+independently checks that literal before using the event-bound player. An authored ref can never select whose balance
+is spent, even if an unvalidated config reaches the room.
+
+## 18. Persistence — saves, room state, counters, leaderboards
+
+**Worlds persist.** A player's declared vars can survive the session, a `roomVar` marked persistent survives the room,
+and two world-global primitives accumulate across every instance and every day the world runs. A roomVar you do NOT
+mark persistent still dies with the room — that is correct, match state is not progression. All of them are durable
+storage: you declare them, the room writes them, any client can read them.
+
+**Doctrine — keys are authority boundaries, JSON is everything else.** One writer per key; split into a new key only
+when the *writer* changes, and keep everything else as fields inside one document. World-global state must be
+**commutative** (a counter's `+n`) or **keep-best** (a board's conditional write), so concurrent instances of your world
+can never conflict. Never read-modify-write a shared blob: two instances will silently overwrite each other.
+
+### Persistent playerVars + the `save` verb — per-player progression
+
+Mark a **scalar playerVar** `"persistent": true` (`number`/`string`/`boolean`/`vec3`), then write it with `save`:
+
+```jsonc
+"state": { "playerVars": {
+  "level": {"type":"number","default":1,"min":1,"max":99,"integer":true,"persistent":true},
+  "gems":  {"type":"number","default":0,"min":0,"max":9999,"integer":true,"persistent":true},
+  "title": {"type":"string","default":"bronze","enum":["bronze","silver","gold"],"persistent":true},
+  "runStart": {"type":"number","default":0}          // no flag → session-only, back to 0 next session
+} },
+"rules": [
+  { "when": {"on":"action","name":"levelUp"},
+    "if":   {"op":">=","a":{"var":"self.gems"},"b":5},
+    "then": [ {"do":"add","target":"self.gems","by":-5},
+              {"do":"add","target":"self.level","by":1},
+              {"do":"save","player":"self"} ] },        // save at the MOMENT that matters
+  { "when": {"on":"playerJoin"},                        // restored values are already in place here
+    "if":   {"op":">=","a":{"var":"self.level"},"b":3},
+    "then": [ {"do":"broadcast","event":"veteran","to":"all","payload":{"level":{"var":"self.level"}}} ] }
+]
+```
+
+- **Hydrated before join rules run** — the saved doc is loaded during auth and applied to the seat, so a `playerJoin`
+  rule reads restored values (the `veteran` rule above), not defaults.
+- **`save` is event-driven by design** — fire it on the beat that changed something worth keeping ("on level up", "on
+  checkpoint", "on purchase"), never on a `tick` heartbeat. A save is debounced ~5 s and coalesced; the room also
+  flushes on disconnect, on leave and at shutdown, so you are not responsible for catching the exit.
+- **Caps:** 16 persistent vars, `persistedPlayerBytes` 8192 per player (§16). **Publish fails** if a `save` appears with
+  no persistent var declared — that error means a forgotten `"persistent": true`, not a stray verb.
+- **Failure mode:** a save that cannot be read plays the seat on defaults and **disables saving for that seat** — the
+  platform never overwrites a save it failed to read. A stored doc is re-validated against the CURRENT build on every
+  load: wrong types are discarded, numbers clamp to `min`/`max`, an enum miss falls back to the default, and vars you
+  deleted from the manifest are dropped. Renaming a var therefore resets it — treat persistent names as a schema.
+- **Cannot:** a playerVar that is `ref`, `list` or `counterMap` — a ref to a player who no longer exists is meaningless
+  next session, and a player document holds scalar fields. For durable COLLECTIONS use persistent roomVars below.
+
+### Persistent roomVars + the `saveRoom` verb — world state that outlives the room
+
+Plain `roomVars` die with the room, which is right for match state. Mark one `"persistent": true` and it survives —
+this is where guestbooks, world records, lifetime tallies and a live-editable MOTD live:
+
+```jsonc
+"state": { "roomVars": {
+  "notes":   { "type":"list", "maxLen":10, "persistent":true, "merge":"append", "key":"guestbook",
+               "of": {"type":"record","fields":{"author":{"type":"string","maxLen":24},"text":{"type":"string","maxLen":80}}} },
+  "bestRun": { "type":"number", "default":999999, "persistent":true, "merge":"min" },
+  "tally":   { "type":"counterMap", "keys":["visits","notes"], "persistent":true, "merge":"sum" },
+  "motd":    { "type":"string", "default":"welcome", "maxLen":80, "persistent":true, "merge":"lastWrite" }
+} },
+"rules": [
+  { "when": {"on":"action","name":"postNote"},
+    "then": [ {"do":"append","target":"room.notes",
+               "value":{"author":{"var":"action.args.author"},"text":{"var":"action.args.text"}}},
+              {"do":"addCount","target":"room.tally","key":"notes","by":1},
+              {"do":"saveRoom","key":"guestbook"} ] }      // one destination; bare saveRoom persists all that changed
+]
+```
+
+- **`merge` is REQUIRED on every persistent roomVar.** Many instances of your world run at once and all write the same
+  document, so the policy decides who wins. `lastWrite` (scalars) is **racy by declaration**; `max`/`min` (number),
+  `append` (list) and `sum` (counterMap) are conflict-free. There is no default — you must state which you are taking.
+- **A `min` var's default must be WORSE than any real value** (999999 for a time, not 0), or the default itself wins
+  every merge and the record can never be set. Same in reverse for `max`.
+- **`key` splits documents.** Without one a var lands in the shared default; with one it gets `mp:world:{key}` — its own
+  version guard and byte budget, so posting a note stops rewriting the rest of your world state. Up to 6 destinations.
+- **A room reads its OWN view.** What it hydrated plus its own changes; other instances land in the stored document, not
+  in this room. Read the true cross-instance value with `Helix.dataStore.get("mp:world")`. Same as counters.
+- **Caps:** 16 persistent roomVars, 6 destinations, 32 KB per document (§16). **Publish fails** on a `saveRoom` with no
+  persistent roomVar declared, or on a `key` naming a destination nothing declares.
+- **Durability window:** entries live in room memory until the flush (~5 s debounce, 60 s ceiling), so a hard crash
+  loses the tail. Fine for boards and tallies — **wrong for anything a player paid for**: money-backed goods live in
+  server-held entitlements the backend writes at settle (§20), and per-player progression belongs on `save` or
+  `submitScore` because those are per-event.
+- **Cannot:** `ref` or `list of ref` (session identities), and bulk data too large to be replicated state — ten thousand
+  placed objects can never be roomVars, so no amount of splitting reaches it.
+
+### Counters — world-global atomic totals
+
+`counters` are shared accumulators for community goals, boss HP, world votes, lifetime tallies — anything where every
+instance adds into one number:
+
+```jsonc
+"counters": { "donations": {} },
+"rules": [
+  { "when": {"on":"action","name":"donate"},
+    "if":   {"op":">=","a":{"var":"self.gems"},"b":1},
+    "then": [ {"do":"add","target":"self.gems","by":-1},
+              {"do":"increment","counter":"donations","by":1},                 // field defaults to "value"
+              {"do":"increment","counter":"donations","field":"gifts","by":1} ] }
+]
+```
+
+- **Instance-safe because increments commute.** The room accumulates deltas locally and flushes one call per counter
+  per ~10 s window — an `increment` is never a per-tick write, so it is cheap to fire from a hot rule.
+- **Read from any client:** `Helix.dataStore.get('world:counter:donations')` → the field map (`{value, gifts}`). Poll it
+  or read it on join; the value is world-open, so a spectator page can render it too.
+- **Caps:** 16 counters, 64 fields each, `by` a finite integer with |delta| ≤ 1e9 (§16).
+- **Failure mode:** at-least-once. A flush retried after an ambiguous transport failure can double-apply one batch, so
+  a counter is a *total*, not a ledger — never derive money, ownership or an exact count of anything from it.
+- **Cannot:** counters are **server-only**. A session has no increment path at all (`counter-server-only`); the value
+  moves through a rule or it does not move.
+
+### Leaderboards — keep-best rankings
+
+```jsonc
+"leaderboards": { "main": {"size":10}, "bestTime": {"order":"asc","size":10} },   // desc default; asc = lower wins (times)
+"rules": [
+  { "when": {"on":"action","name":"levelUp"},
+    "then": [ {"do":"submitScore","board":"main","player":"self","score":{"var":"self.level"}} ] },
+  { "when": {"on":"zoneEnter","zone":"runFinish"},
+    "if":   {"op":">","a":{"var":"self.runStart"},"b":0},
+    "then": [ {"do":"set","target":"self.lastRun","to":{"op":"-","a":{"op":"now"},"b":{"var":"self.runStart"}}},
+              {"do":"submitScore","board":"bestTime","player":"self","score":{"var":"self.lastRun"}} ] }
+]
+```
+
+- **Each board is ONE bounded document** keeping its declared top `size` entries (1..100, default 100), at most one
+  per player. Keep-best is the backend's atomic verdict: a worse score — or one below the board's cutoff — is a
+  normal no-op, and a retry writes the same result, so submit freely, including every lap of a race. A score that
+  doesn't place is NOT stored (the board is a podium, not an archive — keep a player's own history in their vars).
+- **One board must be named `main`** (publish-checked): the platform surfaces a world's default board by that name.
+- **Read from any client:** `Helix.leaderboard.top('bestTime', { limit: 10, order: 'asc' })` → ranked entries.
+- **Caps:** 8 boards per build (§16), `size` ≤ 100, `limit` ≤ 100 per read. A board costs ONE durable key however
+  many players score — declare boards for what you'll display, and let `size` match it.
+- **Cannot:** a session may submit only **its own** score (`leaderboard-self-only`), and a client-submitted entry is
+  flagged `source: 'session'` — client-claimed. Scores that must be trusted are submitted by a rule, like the two above.
+- **Shape is the authority's:** a board's `order`/`size` are fixed when the board is created; the room's submits carry
+  the declared shape (so a republished declaration self-heals), while a session can never reshape an existing board
+  and may mint at most 8 new boards per world (`leaderboard-cap`).
+
+## 19. Achievements — badges the platform vouches for
+
+An achievement is a **per-world registry entry** (registered once, outside the bundle — it is NOT part of `helix.json`),
+and earning one mints a **soulbound inventory item** on the player's account. Each entry carries an `unlockMode`, the
+trust marker a player and the platform UI read to know whether a badge means anything: `room` (the authoritative room
+awarded it — unforgeable), `criteria` (the backend verified evidence it owns), `platform` (first-party). **There is no
+client-attested mode** — a world runs in the player's own browser, so it can never award its own achievements; from
+inside a world `Helix.achievements` is read-only (`sdk.md`).
+
+### Register the achievement BEFORE publishing the rule that awards it
+
+Call **`register_achievement`** (or `helix achievement register <world-slug>`): `key`, `name`, a **required 2D icon
+file**, and optionally `description`, `points` (0–1000, summed into gamerscore), `hidden`, a bespoke `.glb` trophy,
+`unlockMode`, and — for `criteria` — the condition below. It is one creator-authenticated multipart round trip
+(`POST /api/v1/achievements/worlds/:worldId`) that also mints the soulbound item behind the badge. `dryRun` validates
+everything locally, logged out. `list_achievements` reads the registry back; `update_achievement` patches the
+presentation (never the key, mode or criteria — see below).
+
+The **`key`** is the stable slug your rules name: `^[a-z0-9][a-z0-9_-]{1,79}$` (2–80 chars, lowercase
+letters/digits/`_`/`-`, starting alphanumeric), publish-checked in the DSL against the same charset registration uses.
+
+**Every achievement has a graphic** — there is no icon-less badge, and a blank or sub-16px placeholder is refused by
+both the tool and the server. If the human has no art, `generate_image` first. No trophy given, your icon is baked onto
+the default plaque, so the badge is still placeable in a home.
+
+**`unlockMode` defaults to `room`** (or `criteria`, the moment you declare a signal) — the two a world can actually
+use. `platform` means first-party code awards it: nothing in your world can, so never pick it.
+
+**Only presentation is patchable afterwards** (name/description/points/hidden/active). The key is what your rules name,
+and re-declaring how a badge is earned would rewrite what every already-granted copy claims — register a new
+achievement instead, and delist the old one with `active: false` (its holders keep theirs).
+
+**The #1 gotcha: publish does NOT check the registry.** A rule awarding a key nobody registered publishes clean and is a
+**counted runtime no-op** — the room queues the grant, the API answers "no such achievement", and the miss lands in the
+room's write counters. Nothing surfaces in the world, and the player is told nothing. Register first, publish second, and
+treat a key as a schema: renaming one needs a fresh registration.
+
+### `awardAchievement` — the room awards the moment it saw
+
+`{"do":"awardAchievement","key":"<key>","player":<ref>}` is the only in-world award path, and the reason `unlockMode:
+"room"` is unforgeable: the room evaluated state it synced itself.
+
+```jsonc
+"events": { "achievementAwarded": { "payload": { "key": {"type":"string"} } } },
+"rules": [
+  { "when": {"on":"varReached","scope":"self","var":"level","cmp":">=","value":5},
+    "then": [ {"do":"awardAchievement","key":"level-5-champion","player":"self"},
+              {"do":"broadcast","event":"achievementAwarded","to":"self","payload":{"key":"level-5-champion"}} ] }
+]
+```
+
+- **Fire-and-forget and idempotent.** The effect hands the key to the award lane and returns; the grant itself happens
+  off-tick, and the backend's grant is idempotent — a re-award is a no-op, so a rule that can retrigger needs no guard.
+- **Pair every award with a `broadcast`** (as above). An award is a durable account write with **no in-world echo**: the
+  platform raises no banner while the player is in your world, so the toast/SFX/HUD line is the broadcast's job.
+- **Unauthenticated seats are silent no-ops** — no account to credit (the `submitScore` precedent) — as is a room that
+  does not persist.
+- **Players only.** An entity ref is a publish error, and an award is inside the cross-player firewall (§17): a
+  client-supplied ref can never pick who gets credited.
+- **Costs 1 + the player-ref resolution** in the per-tick budget (§16) — a bound name is O(1), a ref-op is a scan.
+
+### Criteria unlocks — the backend measures evidence it already owns
+
+`unlockMode: "criteria"` hands the condition to the platform instead of a rule, so it needs no room at all and works in
+a **single-player** world. One declared comparison — `{"signal":…,"op":"gte"|"lte"|"eq","value":<number>}` — plus that
+signal's own field:
+
+| `signal` | Extra field | Measures |
+|---|---|---|
+| `datastore` | `key` + `field` | a numeric field inside one per-user document (below) |
+| `iwp` | `metric`: `count` (default) / `lix` | successful in-world purchases, or LIX spent |
+| `analytics` | `eventName` | count of a **platform** analytics event in this world (`world_entered`, …) — a world cannot mint an event name for criteria |
+| `playtime` | — | seconds the player has spent in this world |
+
+**The `datastore` signal reads exactly two per-user documents, and which one you name IS the trust decision:**
+
+```jsonc
+{"signal":"datastore","op":"gte","value":5,  "key":"mp:player:{userId}","field":"level"}         // room-written ⇒ trustworthy
+{"signal":"datastore","op":"gte","value":10, "key":"player:{userId}",   "field":"stats.summits"} // client-written ⇒ self-reported
+```
+
+- `mp:player:{userId}` is the room's flushed **persistent playerVars** (§18) — `field` names the persistent var
+  DIRECTLY (declare `"persistent": true` on a scalar playerVar; the storage envelope around it is internal). Only the
+  room writes that document, so this is the criteria equivalent of a `room` award.
+- `player:{userId}` is the player's own client-written save (`Helix.dataStore`, `sdk.md`). Accepted and supported
+  deliberately — it is how a single-player world unlocks anything — but the player can write it, so a badge on it is
+  self-reported. Use it for "finished the tutorial", not for the world's prestige badge.
+- `field` is a dot-path of letters, digits and underscores (`"stats.summits"`), and the leaf must be a **real number**:
+  a stringified `"12"` never qualifies.
+
+The same two, as `register_achievement` takes them (the tool flattens `key`/`field` to `criteriaKey`/`criteriaField`,
+because `key` is already the achievement's own; `helix achievement register` uses `--criteria-key`/`--criteria-field`):
+
+```jsonc
+{ "worldSlug":"…", "key":"level_5", "name":"Level 5", "icon":"/abs/level5.png",
+  "signal":"datastore", "value":5, "criteriaKey":"mp:player:{userId}", "criteriaField":"level" }
+```
+
+**Latency.** `datastore` and `iwp` are evaluated within seconds of the evidence changing (the write, or the purchase
+settling). `analytics` and `playtime` are aggregates nothing can poke, so an hourly sweep evaluates them. Every path
+re-derives the measurement from STORED evidence, and registration itself runs one immediate backfill pass over that
+evidence — so registering a criteria achievement later credits every player who ALREADY qualifies at that moment, on
+any signal, without waiting for a sweep or their next write.
+
+**Test the unlock BEFORE registering.** `helix dev` evaluates criteria locally off simulated evidence — seed the same
+rows in `.helix/dev-achievements.json` (validated with the same rules as registration, no icon needed) and play to the
+threshold; a `player:{userId}` criteria unlocks off real `Helix.dataStore` writes, an `mp:player:{userId}` one off the
+debug menu's persistent-var control. Shape note: the seed stores criteria NESTED (`criteria: { signal, op, value, key,
+field }` — the stored shape shown above), where `register_achievement` flattens to `criteriaKey`/`criteriaField`. See
+the sdk doc's *Local development* section.
+
+### The pattern worth copying — a threshold badge AND a moment badge
+
+The `multiplayer-persistent-progress` template ships both halves, because they answer different questions:
+
+- **A threshold** ("this player reached level 5") is a `criteria` achievement on `mp:player:{userId}` field `level`,
+  `gte` 5. No rule, no wiring, and measured from a document only the room can write — so it still reads true long after
+  the session that earned it.
+- **A moment** ("this player became champion, live, in front of everyone") is a `room` award fired by the rule that saw
+  it happen, paired with the broadcast that puts the banner on screen.
+
+Declare `level` persistent, `save` it on the beat that changes it, and both badges follow from that one var.
+
+## 20. In-world purchases — the room's side of a sale
+
+What a world SELLS is a per-world registry entry the creator registers, and the **shell** settles every sale
+(`sdk.md` → `Helix.marketplace`). Fulfilment is the **backend's**: a settled purchase's `grants` land in the buyer's
+**entitlements** — named passes and currency balances held server-side — and those are the durable truth for anything
+a player paid for. The room reads that truth and spends from it; it never writes it. **Never mirror a pass or a
+balance into a playerVar/roomVar**: a session copy resets on the next join while the entitlement does not, and the
+two then disagree about money.
+
+### The `purchase` event — a settled sale lands in the room
+
+```jsonc
+"counters": { "sales": {} },
+"events":   { "boughtVip": { "payload": { "who": {"type":"ref","of":"player"} } } },
+"rules": [
+  { "when": {"on":"purchase"},                                          // no params — filter in `if`
+    "if":   {"op":"==","a":{"var":"purchase.productKey"},"b":"vip_pass"},
+    "then": [ {"do":"set","target":"self.tier","to":"vip"},
+              {"do":"save","player":"self"},                            // durable — `tier` is a persistent playerVar (§18)
+              {"do":"increment","counter":"sales","by":1},
+              {"do":"broadcast","event":"boughtVip","to":"all","payload":{"who":"self"}} ] }
+]
+```
+
+- **Nothing to wire.** The shell settles the purchase and the platform forwards the receipt to the room the buyer
+  occupies (including on the reload-recovery path) — the world calls `Helix.marketplace.purchaseProduct(…)` and this
+  rule fires with `self` = the buyer.
+- **Two read-only fields, readable only here:** `purchase.productKey` (the key the creator registered; `""` if the
+  product has none) and `purchase.purchaseId`. They read like `action.args.<x>` — inside an `{on:"purchase"}` rule and
+  nowhere else — and the set is closed: nothing declares a purchase field. The event itself takes **no params**, so
+  branch on `productKey` in `if` (one rule per product).
+- **Exactly once per purchase**, platform-enforced: a re-forward, a rejoin, a tab that died mid-sale and another
+  instance of your world all collapse to ONE firing. **So grant the consequences durably** — `save`, `increment`,
+  `submitScore`, `awardAchievement` — never into state a disconnect resets, because the rule will never fire again to
+  rebuild it.
+- The buyer's entitlement snapshot is refreshed **before** the rule runs, so `hasPass`/`balanceOf` inside it already
+  see what this sale granted.
+- A guest seat owns no purchase (no account to attribute it to), so nothing fires for one.
+
+### `hasPass` / `balanceOf` — read the entitlement snapshot
+
+```jsonc
+{ "when": {"on":"zoneEnter","zone":"lounge"},
+  "if":   {"op":"hasPass","passKey":"vip","of":"self"},
+  "then": [ {"do":"add","target":"self.coins","by":1} ] }
+```
+
+- Both are **O(1)** reads off a per-seat snapshot the room hydrates at join and refreshes when a receipt lands — a
+  rule never waits on the network. A timed pass lapses on its own (expiry is judged each tick).
+- **`of` is REQUIRED** (there is no implicit `self`) and must be a player — an entity ref is a publish error.
+- **Deny by default:** an unheld or unregistered `passKey` reads `false`, an unheld `code` reads `0`, and a guest seat
+  or a failed snapshot read the same. Nothing paid for is ever *assumed*.
+- `passKey`/`code` are lowercase slugs (`^[a-z0-9][a-z0-9_-]{0,63}$` — the backend's grants charset). Publish does
+  **not** check the product registry: a code nobody registered publishes clean and simply reads empty (§19's gotcha).
+
+### `consume` — spend a balance, server-side
+
+```jsonc
+"actions": { "drink": {} },
+"rules": [
+  { "when": {"on":"action","name":"drink"},
+    "if":   {"op":">","a":{"op":"balanceOf","code":"potion","of":"self"},"b":0},
+    "then": [ {"do":"consume","code":"potion","amount":1,"player":"self"},
+              {"do":"add","target":"self.potions","by":1},               // the world-side effect of the spend
+              {"do":"save","player":"self"} ] }                          // persistent playerVar (§18)
+]
+```
+
+- `amount` is a **literal integer 1..1000000000**, never an expression — how much a spend costs cannot depend on
+  state a client moved. `code` takes the charset above. `player` must be the literal `"self"`, meaning the player
+  bound by the event (the actor for an `action`, the member for a zone/player event, or the buyer for `purchase`). A
+  playerless event such as `tick` cannot spend; publish rejects it.
+- **Verdict-gated continuation:** the room may debit its private snapshot optimistically (floored at zero, keeping
+  same-tick overspend gates coherent), but every sibling after `consume` is suspended. They run exactly once only
+  after the backend returns `resolved:true, applied:true`. `applied:false`, an unresolved verdict, the room rate
+  fence, or queue refusal ends the list without running `add`, `save`, `awardAchievement`, or any other consequence.
+  An authoritative rejected verdict restores/reconciles the balance. Running with no backend configured remains
+  playable in local development and continues immediately because there is no real ledger there.
+- An effect tree may contain **at most one top-level `consume`**, and `consume` cannot appear inside a `forEach*`
+  body. Publish rejects unsafe trees; the room repeats the check and skips the entire tree if an older/unvalidated
+  artifact reaches it. Put the spend before all of its consequences, as in the example above.
+- **Self-only by construction and at runtime.** `player` is not a general ref and cannot be an action arg, loop
+  binding, room ref, or server-selected player: the manifest accepts only literal `"self"`. The room repeats that
+  check and uses the event binding directly, so a stale/unvalidated artifact with another target fails closed before
+  any consume API call.
+- **Rate-fenced per room** (60 spends/minute); past it a spend is refused, counted, and its continuation is dropped.
+  Spend on player-driven beats (an `action`, a zone event, a purchase); a bare `tick` has no player
+  binding and cannot publish a consume effect.
+
+## 21. Where Tier-2 stops (use the escape hatch or a different layer)
 
 Out of scope for the declarative DSL: **cheat-proof collision/raycast/hitscan** and **navmesh pathfinding / autonomous AI**
 (straight-line `seek` is in; *navigating around obstacles* and *deciding* are not — run them on an `owner` entity
-client-side). **Cross-session persistence** (saved currency/progression/inventory across sessions) is a separate storage
-layer, not here — worlds reset per room. **Networked physics** (colliding rigid bodies) IS supported — see §9 "Networked
-physics — colliding dynamic bodies." Nested collections / free-form JSON are intentionally unsupported (flat records only).
+client-side). **Cross-session persistence** IS supported — see §18 — but **persistent room state** and **player-to-player
+mailboxes** (async gifting, offline messages) are not: both need conflict semantics the platform hasn't settled.
+**Networked physics** (colliding rigid bodies) IS supported — see §9 "Networked physics — colliding dynamic bodies."
+Nested collections / free-form JSON are intentionally unsupported (flat records only).