@helixdev/helix-manifest 0.3.0-staging.13 → 0.3.0-staging.14

package/dist/src/index.js

@@ -99,6 +99,14 @@ exports.PLATFORM_MAX_PLAYERS_PER_ROOM = 24;
 // land. (Var-NAME length is capped by the schema's varDecls propertyNames pattern — 32 chars — not here.)
 // Over any cap → publish fails.
 exports.MULTIPLAYER_CAPS = {
+    /** Accepted `multiplayer.uploadHz` tiers (client→server upload cadence). 10 = default, 20 = opt-in fast tier.
+     *  SYNC: mirrors the contract's MESSAGE_RATE.{stateHz=10, maxUploadHz=20} (helix-sdk multiplayer-contract) — the
+     *  manifest takes no SDK dep, so widen both in lockstep if a tier is ever added. */
+    uploadHzAllowed: [10, 20],
+    /** The 20 Hz player cap: `uploadHz:20` requires maxPlayers ≤ this (the ~2× upstream cost is bounded by capacity).
+     *  SYNC: mirrors the room's ROOM_MAX_CLIENTS_CAP_20HZ (helix-colyseus-server src/tuning.ts) — publish gate here,
+     *  runtime backstop there. */
+    maxPlayersAt20Hz: 12,
     /** Declared room-level vars. */
     roomVars: 64,
     /** Declared per-player vars (these are realized once PER PLAYER at runtime, so the effective cost scales). */
@@ -111,6 +119,8 @@ exports.MULTIPLAYER_CAPS = {
     listMaxLen: 256,
     /** Keys in a `counterMap` collection var's declared key enum (4.5.13). */
     counterKeys: 64,
+    /** Fields in a `list` of `record` element (P3 Collections — bounds one synced record's flat scalar fields). */
+    recordFields: 8,
     /** Declared behavior rules (Tier 2 Phase 2). */
     rules: 128,
     /** Effects in a single rule's `then`. */
@@ -152,6 +162,10 @@ exports.MULTIPLAYER_CAPS = {
     /** Max live entities of a single kind in a room — bounds the synced entities collection + per-tick entity work.
      *  Enforced at RUNTIME (a spawn over the cap is skipped + counted in the H3 metric, never throws). */
     entitiesPerKind: 256,
+    /** networked-physics (Phase 0): max entity kinds that may declare a `physics` block per world. Bounds the
+     *  client-side dynamic-body count alongside entitiesPerKind — the worst case a client may simulate is
+     *  physicsKinds × entitiesPerKind dynamic Rapier bodies, so keep this small (a casual world needs 1–2). */
+    physicsKinds: 8,
     /** Ceiling on a zone's extent — any box dimension or a sphere radius, in meters. A sanity bound (a zone
      *  test is O(1) regardless of size), generous enough for whole-level kill-planes. */
     zoneMaxExtent: 10000,
@@ -195,6 +209,17 @@ function applyV03CrossFieldRules(m, strict) {
     if (minPlayers !== undefined && minPlayers > m.maxPlayers) {
         errors.push(`manifest: multiplayer.minPlayers ${minPlayers} exceeds maxPlayers ${m.maxPlayers}`);
     }
+    // Upload-rate tier. The schema enum normally gates the value (and defaults absent → 10); this defensive enum check
+    // covers manifests built outside the schema path. The maxPlayers coupling is cross-field, so it lives here only.
+    const uploadHz = m.multiplayer?.uploadHz;
+    if (uploadHz !== undefined) {
+        if (!exports.MULTIPLAYER_CAPS.uploadHzAllowed.includes(uploadHz)) {
+            errors.push(`manifest: multiplayer.uploadHz ${uploadHz} must be ${exports.MULTIPLAYER_CAPS.uploadHzAllowed.join(' or ')}`);
+        }
+        else if (uploadHz === 20 && m.maxPlayers > exports.MULTIPLAYER_CAPS.maxPlayersAt20Hz) {
+            errors.push(`manifest: multiplayer.uploadHz 20 caps maxPlayers at ${exports.MULTIPLAYER_CAPS.maxPlayersAt20Hz} (got ${m.maxPlayers}) — lower maxPlayers to ${exports.MULTIPLAYER_CAPS.maxPlayersAt20Hz} or uploadHz to 10`);
+        }
+    }
     // v0.3 declared state (Tier 2 Phase 1.3): the JSON schema validated each VarType's SHAPE; here we add the
     // cross-field semantics it can't express — declared state requires the multiplayer permission, and every
     // var's default must satisfy its own declared constraints.
@@ -210,8 +235,14 @@ function applyV03CrossFieldRules(m, strict) {
         for (const [scope, decls] of bags) {
             if (!decls)
                 continue;
-            for (const [name, vt] of Object.entries(decls))
+            // A declared var may not shadow a reserved built-in (else it's silently unreadable/unwritable — the built-in
+            // wins). roomVars vs room built-ins (phase); playerVars vs player built-ins (position/connected/active).
+            const reserved = scope === 'roomVars' ? ROOM_BUILTIN_TYPES : PLAYER_BUILTIN_TYPES;
+            for (const [name, vt] of Object.entries(decls)) {
+                if (name in reserved)
+                    errors.push(`multiplayer.state.${scope}.${name}: "${name}" is a reserved ${scope === 'roomVars' ? 'room' : 'player'} built-in — rename the var`);
                 errors.push(...checkVarDefault(`multiplayer.state.${scope}.${name}`, vt));
+            }
         }
     }
     const entities = m.multiplayer?.entities;
@@ -281,7 +312,7 @@ function applyV03CrossFieldRules(m, strict) {
         errors.push(...cascade.errors);
         // §9/§11.3 (4.5) reject a within-tick unbounded entitySpawn → spawnEntity loop (the entity twin of the above).
         errors.push(...analyzeEntityCascade(m.multiplayer.rules));
-        errors.push(...checkBudget(m.multiplayer.rules, m.multiplayer.timers ?? {}, cascade.maxDepth, joinLateCost(states)));
+        errors.push(...checkBudget(m.multiplayer.rules, m.multiplayer.timers ?? {}, cascade.maxDepth, states, maxDeclaredListLen(m)));
         // §14 (4.5) single-player-safe gate: a solo-declared world (minPlayers 1) must not gate a phase transition
         // behind playerCount ≥ 2 (a solo player would be soft-locked). Warns; strict (launch) flips it to an error.
         const solo = checkSoloSafety(m, strict);
@@ -550,8 +581,9 @@ function checkTimerRefs(path, rule, timers, bound, roomVars, playerVars, zoneIds
             if (kr.errors.length === 0 && keyedKind !== undefined && kr.kind !== undefined) {
                 const wantEntity = keyedKind.startsWith('entity:');
                 const gotEntity = kr.kind.type === 'entity';
-                if (wantEntity !== gotEntity || (wantEntity && kr.kind.kind !== keyedKind.slice('entity:'.length))) {
-                    const got = gotEntity ? `entity:${kr.kind.kind}` : 'player';
+                const gotKind = bindingKind(kr.kind);
+                if (wantEntity !== gotEntity || (wantEntity && gotKind !== keyedKind.slice('entity:'.length))) {
+                    const got = gotEntity ? `entity:${gotKind}` : 'player';
                     e.push(`${u.path}.key: timer "${u.timer}" is keyed:'${keyedKind}' but its key resolves to a ${got} ref — they must match`);
                 }
             }
@@ -581,7 +613,10 @@ function collectEffectTimerUses(effects, path, bound, uses, e) {
         const p = `${path}[${j}]`;
         if (eff.do === 'startTimer') {
             uses.push({ timer: eff.timer, key: eff.key, path: p, bound });
-            if (eff.seconds < exports.MULTIPLAYER_CAPS.timerMinSeconds)
+            // The static floor only binds a LITERAL duration; an expression's value is unknown at publish, so its
+            // sub-floor/NaN/∞/negative handling is deferred to the runtime clamp/skip (spec §3.2). The expr's type +
+            // node budget are validated in validateEffect like any other effect-borne expression.
+            if (typeof eff.seconds === 'number' && eff.seconds < exports.MULTIPLAYER_CAPS.timerMinSeconds)
                 e.push(`${p}: startTimer "${eff.timer}" seconds ${eff.seconds} is below the ${exports.MULTIPLAYER_CAPS.timerMinSeconds}s floor (one sim tick)`);
         }
         else if (eff.do === 'cancelTimer') {
@@ -607,7 +642,7 @@ function collectEffectTimerUses(effects, path, bound, uses, e) {
 }
 // Wire message-type names a declared event (or action) name may not shadow — kept in sync with
 // RESERVED_MESSAGE_TYPES in @hypersoniclabs/helix-sdk/multiplayer-contract (the manifest takes no SDK dep).
-const RESERVED_EVENT_NAMES = new Set(['state', 'ability', 'action', 'entityState', 'entityStateBatch', 'ping', 'pong']);
+const RESERVED_EVENT_NAMES = new Set(['state', 'ability', 'action', 'entityState', 'entityStateBatch', 'ping', 'pong', 'stateAck', 'entityStateAck']);
 // §10.3 events: count + reserved-name + payload-field caps. A `ref` payload field must declare `of` (the
 // schema enforces shape + the identifier name pattern; this adds the cross-field semantics).
 function checkEvents(events) {
@@ -624,8 +659,25 @@ function checkEvents(events) {
             e.push(`multiplayer.events."${name}": payload has ${fields.length} fields — the cap is ${exports.MULTIPLAYER_CAPS.broadcastFields}`);
         }
         for (const f of fields) {
-            if (payload[f].type === 'ref' && payload[f].of === undefined)
+            const ft = payload[f];
+            if (ft.type === 'ref' && ft.of === undefined)
                 e.push(`multiplayer.events."${name}".payload.${f}: a ref field must declare "of"`);
+            // §10.3 (P3-B6) a collection-snapshot field — validate its element/keys shape like a var collection.
+            if (ft.type === 'list' && typeof ft.of === 'object' && ft.of.type === 'record') {
+                const rfields = Object.keys(ft.of.fields);
+                if (rfields.length > exports.MULTIPLAYER_CAPS.recordFields)
+                    e.push(`multiplayer.events."${name}".payload.${f}: a record element declares ${rfields.length} fields — the cap is ${exports.MULTIPLAYER_CAPS.recordFields}`);
+                for (const rn of rfields)
+                    e.push(...checkRecordField(`multiplayer.events."${name}".payload.${f}.of.fields.${rn}`, ft.of.fields[rn]));
+            }
+            if (ft.type === 'counterMap') {
+                if (ft.keys.length === 0)
+                    e.push(`multiplayer.events."${name}".payload.${f}: counterMap needs at least one key`);
+                else if (ft.keys.length > exports.MULTIPLAYER_CAPS.counterKeys)
+                    e.push(`multiplayer.events."${name}".payload.${f}: counterMap has ${ft.keys.length} keys — the cap is ${exports.MULTIPLAYER_CAPS.counterKeys}`);
+                if (new Set(ft.keys).size !== ft.keys.length)
+                    e.push(`multiplayer.events."${name}".payload.${f}: counterMap keys must be unique`);
+            }
         }
     }
     return e;
@@ -655,19 +707,40 @@ function checkActions(actions) {
     return e;
 }
 // §11.2 static per-tick budget: a conservative WORST-CASE count of node-evaluations one tick could do across
+// §5 (P3 ext) the worst-case element count the cost model charges a list-scan op (forEachInList / removeWhere /
+// listCount / listIndexOf) — set to the LARGEST declared list maxLen in the config (a sound, much tighter bound than
+// the global listMaxLen cap, since no list can exceed its own declared maxLen, and a {ref,var} scan can't exceed the
+// largest declared list). checkBudget assigns it before the cost walk; defaults to the global cap (no lists declared).
+let budgetListCap = exports.MULTIPLAYER_CAPS.listMaxLen;
+// The largest declared `list` maxLen across roomVars / playerVars / every entity kind's vars (capped at the global
+// ceiling); the global cap when no list is declared. Bounds the per-tick cost of list-scan ops precisely.
+function maxDeclaredListLen(m) {
+    let max = 0;
+    const scan = (decls) => {
+        for (const vt of Object.values(decls ?? {}))
+            if (vt.type === 'list')
+                max = Math.max(max, vt.maxLen);
+    };
+    scan(m.multiplayer?.state?.roomVars);
+    scan(m.multiplayer?.state?.playerVars);
+    for (const e of Object.values(m.multiplayer?.entities ?? {}))
+        scan(e.vars);
+    return max > 0 ? Math.min(max, exports.MULTIPLAYER_CAPS.listMaxLen) : exports.MULTIPLAYER_CAPS.listMaxLen;
+}
 // all rules — Σ fireCount(event) × ruleCost. fireCount is how many times an event can fire per tick (tick=1;
 // player/zone events ≤ playerCap; playerContact ≤ playerCap²; self varReached ≤ playerCap; a keyed timerElapsed
 // ≤ playerCap / entitiesPerKind — so `timers` is threaded in). ruleCost sums the `if` + each effect, weighting
 // reductions (aggregate/nearest*) + forEach fanout by the player cap. Over budget → publish fails. Shape-based,
-// so it runs after the schema validated the rule shapes.
-function checkBudget(rules, timers, maxCascadeDepth = 0, joinLate = 0) {
+// so it runs after the schema validated the rule shapes. `listCap` bounds list-scan cost (largest declared maxLen).
+function checkBudget(rules, timers, maxCascadeDepth = 0, states, listCap = exports.MULTIPLAYER_CAPS.listMaxLen) {
+    budgetListCap = listCap; // set before the cost walk (covers ruleCost + joinLateCost list-scan charges)
     let base = 0;
     for (const rule of rules)
         base += fireCount(rule.when, timers) * ruleCost(rule);
     // §11.2 cascade term (N9): each cascade level can re-evaluate the matched state rules, so the worst case is
     // the base batch ×(1 + maxCascadeDepth). maxCascadeDepth is the cycle-free longest chain from analyzeCascade.
     // `joinLate` is the worst-case onLateJoin cost (≤ player cap joins/tick) from joinPolicy (§8/3.5).
-    const total = base * (1 + maxCascadeDepth) + joinLate;
+    const total = base * (1 + maxCascadeDepth) + joinLateCost(states);
     if (total > exports.MULTIPLAYER_CAPS.tickNodeBudget) {
         return [
             `manifest: multiplayer.rules worst-case ~${total} node-evaluations/tick (incl. the ×${1 + maxCascadeDepth} cascade factor) exceeds the per-tick budget of ${exports.MULTIPLAYER_CAPS.tickNodeBudget} — simplify rules (fewer effects, less forEach/aggregate, fewer playerContact rules, shallower phase cascades) or split the world`,
@@ -694,7 +767,7 @@ function fireCount(event, timers) {
         case 'tick':
             return 1; // everyN doesn't lower the worst case (the tick it fires)
         case 'varReached':
-            return event.scope === 'self' ? p : 1;
+            return event.scope === 'self' ? p : event.scope === 'entity' ? exports.MULTIPLAYER_CAPS.entitiesPerKind : 1; // entity scope evaluates once per live instance of the kind
         case 'playerContact':
             return p * p;
         case 'stateEnter':
@@ -733,7 +806,7 @@ function exprCost(expr) {
     const node = expr;
     if (node.op === 'aggregate' || node.op === 'nearestPlayer')
         return exports.PLATFORM_MAX_PLAYERS_PER_ROOM; // O(members) scan
-    if (node.op === 'playerCount' || node.op === 'random' || node.op === 'timeInState' || node.op === 'timerRemaining')
+    if (node.op === 'playerCount' || node.op === 'random' || node.op === 'timeInState' || node.op === 'timerRemaining' || node.op === 'now')
         return 1; // O(1) leaves
     if (node.op === 'randomPoint')
         return 1; // O(1) leaf → vec3
@@ -741,12 +814,37 @@ function exprCost(expr) {
         return 1; // §5 (4.5.13) O(1) collection reads
     if (node.op === 'listAt')
         return 1 + exprCost(node.index ?? 0); // O(1) + the index expr
+    if (node.op === 'listCount' || node.op === 'listIndexOf')
+        return budgetListCap * (1 + exprCost(node.where ?? true)); // §5 (P3 ext) O(maxLen) scan × the where
+    if (node.op === 'controlledBy') {
+        const cb = expr;
+        return 1 + refCost(cb.entity) + refCost(cb.by);
+    } // §9 (P3) O(1) + the two ref resolutions
+    if (node.op === 'sameRef') {
+        const sr = expr;
+        return 1 + refCost(sr.a) + refCost(sr.b);
+    } // §7.3 (P3-B2) O(1) identity + the two ref resolutions
+    if (node.op === 'hostLoad')
+        return exports.MULTIPLAYER_CAPS.entitiesPerKind; // §9 (P3) O(entities) scan of the owner map
     if (node.op === 'and' || node.op === 'or')
         return 1 + node.of.reduce((s, e) => s + exprCost(e), 0);
     if (node.op === 'not')
         return 1 + exprCost(node.of);
     return 1 + exprCost(node.a) + exprCost(node.b); // distance / binary cmp / arith
 }
+// §5 (P3 Collections) a record-list element literal vs an Expr/Ref node, for the static cost/taint walks: a plain
+// object that is NOT a recognized expr/ref node (no op/var/vec3/ref key). A record field named op/var/vec3/ref is
+// disambiguated by the list's declared element type at validation/runtime — this heuristic is only the static walk.
+function isRecordLiteral(value) {
+    return (typeof value === 'object' && value !== null && !Array.isArray(value) && !('op' in value) && !('var' in value) && !('vec3' in value) && !('ref' in value));
+}
+// §5 (P3 Collections) cost of an append/setField value: a record literal sums its field expr costs; a scalar/ref
+// value costs as an expr (exprCost tolerates the ref forms structurally).
+function collectionValueCost(value) {
+    if (isRecordLiteral(value))
+        return 1 + Object.values(value).reduce((s, v) => s + exprCost(v), 0);
+    return exprCost(value);
+}
 // Node-evals to resolve a Ref once. A bound name / ref-var deref is O(1); a ref-returning op is an
 // O(members) scan (the player cap).
 function refCost(ref) {
@@ -758,6 +856,12 @@ function refCost(ref) {
         return exports.PLATFORM_MAX_PLAYERS_PER_ROOM + exprCost(ref.from);
     if (ref.op === 'nearestEntity')
         return exports.MULTIPLAYER_CAPS.entitiesPerKind + exprCost(ref.from); // O(entities of a kind)
+    if (ref.op === 'controllerOf')
+        return 1 + refCost(ref.entity); // §9 (P3) O(1) field read + the entity ref resolution
+    if (ref.op === 'leastLoadedPlayer')
+        return exports.PLATFORM_MAX_PLAYERS_PER_ROOM + (ref.where !== undefined ? exprCost(ref.where) : 0); // §9 (P3) O(players) scan
+    if (ref.op === 'listAt')
+        return 1 + exprCost(ref.index); // §5 (P3-B2) O(1) element read + the index expr
     return exports.PLATFORM_MAX_PLAYERS_PER_ROOM; // aggregate argmax|argmin
 }
 function lvalueCost(lvalue) {
@@ -786,11 +890,18 @@ function effectCost(eff) {
             const body = (eff.where !== undefined ? exprCost(eff.where) : 0) + eff.then.reduce((s, e) => s + effectCost(e), 0);
             return exports.MULTIPLAYER_CAPS.entitiesPerKind * body;
         }
+        case 'forEachInList': {
+            // §5 (P3 ext) bounded by the list's maxLen ceiling (the worst-case element count); the body is O(1) per
+            // iteration (reductions forbidden inside, like the other loops).
+            const body = (eff.where !== undefined ? exprCost(eff.where) : 0) + eff.then.reduce((s, e) => s + effectCost(e), 0);
+            return lvalueCost(eff.list) + budgetListCap * body;
+        }
         case 'transitionTo':
             return 1; // O(1): set the phase + enqueue stateExit/stateEnter (the cascade itself is the ×depth budget term)
         case 'startTimer':
+            return 1 + exprCost(eff.seconds); // O(1) set + the (possibly dynamic) duration expr
         case 'cancelTimer':
-            return 1; // O(1): set/delete one deadline entry
+            return 1; // O(1): delete one deadline entry
         case 'broadcast': {
             const toCost = typeof eff.to === 'string' ? (eff.to === 'all' ? exports.PLATFORM_MAX_PLAYERS_PER_ROOM : 1) : 'team' in eff.to ? exports.PLATFORM_MAX_PLAYERS_PER_ROOM : refCost(eff.to);
             const payload = Object.values(eff.payload ?? {}).reduce((s, v) => s + exprCost(v), 0);
@@ -806,11 +917,22 @@ function effectCost(eff) {
             // O(1): resolve the refs + set controller/epoch (the ownershipChanged it fires is the ×depth cascade term).
             return 1 + refCost(eff.entity) + (eff.to === null ? 0 : refCost(eff.to));
         case 'append':
-            return 1 + exprCost(eff.value); // §5 (4.5.13) O(1) push (+ the value expr)
+            return 1 + collectionValueCost(eff.value); // §5 (4.5.13 + P3) O(1) push (+ the value's expr / record-field costs)
         case 'clear':
             return 1; // §5 (4.5.13) O(1) — empty the list / reset keys
         case 'addCount':
             return 1 + exprCost(eff.by); // §5 (4.5.13) O(1) key bump (+ the by expr)
+        case 'removeAt':
+            return 1 + exprCost(eff.index); // §5 (P3) O(1) splice (+ the index expr) — amortized; the shift is bounded by maxLen
+        case 'removeWhere':
+            return lvalueCost(eff.target) + budgetListCap * (1 + exprCost(eff.where)); // §5 (P3 ext) O(maxLen) scan × the where
+        case 'setField':
+            return 1 + (eff.index !== undefined ? exprCost(eff.index) : 0) + collectionValueCost(eff.to); // §5 (P3) O(1) field write
+        case 'advanceTurn':
+            return exports.PLATFORM_MAX_PLAYERS_PER_ROOM + lvalueCost(eff.order) + lvalueCost(eff.index); // §7.4 (P3-B2) O(order) skip-scan, bounded by the player cap
+        case 'eliminate':
+        case 'revive':
+            return 1 + refCost(eff.player); // §7.4 (P3-B2) O(1) flag toggle + the player ref resolution
     }
 }
 // §6 zones: count cap, unique ids, an extent sanity bound, and (4.5.8) the `tracks` target. The schema already
@@ -849,20 +971,39 @@ function checkEntities(entities) {
     if (kinds.length > exports.MULTIPLAYER_CAPS.entityKinds) {
         e.push(`manifest: multiplayer.entities declares ${kinds.length} kinds — the cap is ${exports.MULTIPLAYER_CAPS.entityKinds}`);
     }
+    // networked-physics (Phase 0): bound the per-world dynamic-body kind count — physicsKinds × entitiesPerKind is the
+    // worst-case client physics-body simulation load, so a small cap keeps the casual-world path cheap.
+    const physicsKindCount = kinds.filter((k) => entities[k].physics).length;
+    if (physicsKindCount > exports.MULTIPLAYER_CAPS.physicsKinds) {
+        e.push(`manifest: multiplayer.entities declares ${physicsKindCount} physics kinds — the cap is ${exports.MULTIPLAYER_CAPS.physicsKinds}`);
+    }
+    // §5 (P3 Collections) entity collections ARE allowed (P3-A1) — they're realized into the entity-var union. The
+    // union is one merged schema, so a COLLECTION var name shared across kinds must agree on its exact shape (a
+    // differing element/keys would mis-realize the shared ArraySchema/MapSchema and crash the encoder). Track shapes.
+    const seenColl = new Map();
     for (const kind of kinds) {
         const vars = entities[kind].vars ?? {};
         const names = Object.keys(vars);
         if (names.length > exports.MULTIPLAYER_CAPS.entityVars) {
             e.push(`multiplayer.entities.${kind}.vars declares ${names.length} vars — the cap is ${exports.MULTIPLAYER_CAPS.entityVars}`);
         }
-        for (const name of names)
+        for (const name of names) {
+            // An entity var may not shadow a UNIVERSAL member built-in (position). connected/active are player-only, so an
+            // entity is free to declare those (e.g. a coin's `active` = is-collectible) — see playerBuiltin.
+            if (name in PLAYER_BUILTIN_TYPES && !PLAYER_ONLY_BUILTINS.has(name))
+                e.push(`multiplayer.entities.${kind}.vars.${name}: "${name}" is a reserved member built-in — rename the var`);
             e.push(...checkVarDefault(`multiplayer.entities.${kind}.vars.${name}`, vars[name]));
-        // §5 (4.5.13) collection vars (list/counterMap) live on roomVars/playerVars only — not entity vars (they
-        // can't be owner-uploaded or seeded at spawn, and the realized entity-var union stays scalar).
+        }
         for (const name of names) {
-            const t = vars[name].type;
-            if (t === 'list' || t === 'counterMap')
-                e.push(`multiplayer.entities.${kind}.vars.${name}: a "${t}" collection isn't allowed on an entity — declare it under multiplayer.state (room/player vars)`);
+            const vt = vars[name];
+            if (vt.type !== 'list' && vt.type !== 'counterMap')
+                continue;
+            const sig = JSON.stringify(vt);
+            const prior = seenColl.get(name);
+            if (prior === undefined)
+                seenColl.set(name, sig);
+            else if (prior !== sig)
+                e.push(`multiplayer.entities.${kind}.vars.${name}: a "${name}" collection is declared with a different shape on another entity kind — collection vars shared across kinds must be identical (the entity-var union is one merged schema)`);
         }
         // §9 (Phase 4.6a) seek motion: `target` must name one of THIS kind's own ref vars (the member to home toward),
         // and `speed` must be positive. The server reads `vars[target]` → that member's position each tick.
@@ -886,14 +1027,18 @@ function checkEntities(entities) {
         // relay's movement-plausibility ceiling). `maxSpeed` on a `server` kind is ignored (server motion isn't gated) → warn.
         const authority = entities[kind].authority ?? 'server';
         const maxSpeed = entities[kind].maxSpeed;
+        const physics = entities[kind].physics;
         if (authority === 'owner') {
             if (maxSpeed === undefined)
                 e.push(`multiplayer.entities.${kind}: authority:'owner' requires a declared maxSpeed (m/s — the movement-plausibility ceiling for its relayed transform)`);
             else if (!(maxSpeed > 0))
                 e.push(`multiplayer.entities.${kind}.maxSpeed: must be > 0, got ${maxSpeed}`);
-            // An owner entity is client-simulated; server-authoritative `motion` would fight its uploaded transform.
-            if (entities[kind].motion && entities[kind].motion.type !== 'static')
-                e.push(`multiplayer.entities.${kind}: authority:'owner' is client-simulated — it can't also declare server motion "${entities[kind].motion.type}" (drop motion, or use authority:'server')`);
+            // An owner entity is client-simulated; server motion would fight its uploaded transform — UNLESS it also
+            // declares `physics` (the networked-physics HYBRID, Phase 3.5: the server runs `motion` while the body is
+            // unowned, a client takes over the dynamic physics on contact, then it rejoins the path). So a non-static
+            // motion is only an error when there is NO physics block to make it the hybrid.
+            if (entities[kind].motion && entities[kind].motion.type !== 'static' && !physics)
+                e.push(`multiplayer.entities.${kind}: authority:'owner' is client-simulated — it can't also declare server motion "${entities[kind].motion.type}" (drop motion, use authority:'server', or add a physics block for the server-behaved hybrid)`);
         }
         else if (maxSpeed !== undefined) {
             warnings.push(`multiplayer.entities.${kind}.maxSpeed: ignored on a server-authoritative kind (server motion is deterministic, not gated) — set authority:'owner' or remove maxSpeed`);
@@ -918,6 +1063,27 @@ function checkEntities(entities) {
         if (transferPolicy !== 'fixed' && authority !== 'owner') {
             e.push(`multiplayer.entities.${kind}: transferPolicy:'${transferPolicy}' requires authority:'owner' (only a client-simulated entity has a transferable controller)`);
         }
+        // networked-physics (Phase 0/2): the dynamic-body opt-in + its per-capability cross-field coherence. The schema
+        // already bounds the block's SHAPE (bodyType/shape dims/mass/restitution); here are the rules it can't express —
+        // incoherent combos fail at PUBLISH, not runtime. (mass/restitution/shape bounds: enforced by the JSON schema.)
+        if (physics) {
+            if (authority !== 'owner')
+                e.push(`multiplayer.entities.${kind}.physics: requires authority:'owner' (only an owner kind simulates a dynamic body — a server kind stays kinematic)`);
+            // claim-on-contact fires the auto-takeover verb, so the kind must permit a takeover; dual-sim is the
+            // controlled×controlled path, which by definition never transfers (sticky), so it needs the 'fixed' policy.
+            if (physics.claimOnContact && transferPolicy !== 'takeover')
+                e.push(`multiplayer.entities.${kind}.physics.claimOnContact: requires transferPolicy:'takeover' (the verb the auto-handoff fires); got '${transferPolicy}'`);
+            if (physics.dualSimOnContact && transferPolicy !== 'fixed')
+                e.push(`multiplayer.entities.${kind}.physics.dualSimOnContact: requires transferPolicy:'fixed' (a controlled body never transfers); got '${transferPolicy}'`);
+            for (const other of physics.collidesWith ?? []) {
+                if (!kinds.includes(other))
+                    e.push(`multiplayer.entities.${kind}.physics.collidesWith: references unknown entity kind "${other}"${didYouMean(other, kinds)} (declared entities: ${kinds.join(', ') || 'none'})`);
+            }
+        }
+        // rejoinOnRelease only means anything for the server-behaved HYBRID (physics + a non-static motion).
+        if (entities[kind].rejoinOnRelease !== undefined && !(physics && entities[kind].motion && entities[kind].motion.type !== 'static')) {
+            warnings.push(`multiplayer.entities.${kind}.rejoinOnRelease: ignored — it only applies to a server-behaved hybrid (a kind with both physics and a non-static motion)`);
+        }
         // §6 (4.5.8) attached-zone tracks: 'entity:<kind>' (entity-vs-entity overlap) must name a declared kind;
         // the carrier never detects itself at runtime. 'players' (default) is unconstrained.
         const zone = entities[kind].zone;
@@ -936,7 +1102,7 @@ function checkEntities(entities) {
 // ruleEffect permissive branch lets an unknown node through to here; these sets MUST stay in sync with the
 // HelixRuleEvent/HelixRuleEffect unions + those schema `not` enums.
 const KNOWN_EVENTS = new Set(['tick', 'playerJoin', 'playerLeave', 'playerDisconnect', 'playerReconnect', 'zoneEnter', 'zoneExit', 'zoneInside', 'playerContact', 'action', 'stateEnter', 'stateExit', 'timerElapsed', 'entitySpawn', 'entityDestroy', 'ownershipChanged', 'varReached']);
-const KNOWN_EFFECTS = new Set(['add', 'set', 'setRef', 'teleport', 'respawn', 'forEachPlayer', 'forEachEntity', 'broadcast', 'transitionTo', 'startTimer', 'cancelTimer', 'spawnEntity', 'destroyEntity', 'requestOwnership', 'takeover', 'append', 'clear', 'addCount']);
+const KNOWN_EFFECTS = new Set(['add', 'set', 'setRef', 'teleport', 'respawn', 'forEachPlayer', 'forEachEntity', 'forEachInList', 'broadcast', 'transitionTo', 'startTimer', 'cancelTimer', 'spawnEntity', 'destroyEntity', 'requestOwnership', 'takeover', 'append', 'clear', 'addCount', 'removeAt', 'removeWhere', 'setField', 'advanceTurn', 'eliminate', 'revive']);
 // Reserved nodes for a named LATER phase (provisional names — the grammar lands with that phase). A node here
 // publishes with a warning + is a runtime no-op; any other unknown node is a typo (hard error with did-you-mean).
 // (4.5.12 promoted the ownership-transfer trio to KNOWN; this set is empty until the next reserved seam lands.)
@@ -1020,7 +1186,7 @@ function checkRules(m) {
             ? { ...ec, boundKinds, actionArgs: m.multiplayer?.actions?.[rule.when.name]?.args ?? {} }
             : { ...ec, boundKinds };
         if (rule.when.on === 'varReached') {
-            e.push(...checkVarReached(`multiplayer.rules[${i}].when`, rule.when, roomVars, playerVars));
+            e.push(...checkVarReached(`multiplayer.rules[${i}].when`, rule.when, roomVars, playerVars, bound, zoneIds, ruleEc));
         }
         if (rule.when.on === 'zoneEnter' || rule.when.on === 'zoneExit' || rule.when.on === 'zoneInside') {
             const zone = rule.when.zone;
@@ -1116,11 +1282,14 @@ function firewallBindings(when, timers, entityZoneKinds, zoneSelfKinds) {
                 return { self: { type: 'entity', kind: keyed.slice('entity:'.length) } };
             return {};
         }
+        case 'varReached':
+            // §7.5 (P3-B5) room scope binds nothing; self binds the player; entity binds the watched kind's instance.
+            return when.scope === 'entity' ? { self: { type: 'entity', kind: when.kind ?? '' } } : when.scope === 'self' ? { self: { type: 'player' } } : {};
         case 'tick':
         case 'stateEnter':
         case 'stateExit':
             return {};
-        default: // playerJoin/Leave/Disconnect/Reconnect, action, varReached — all self=player (self-scoped)
+        default: // playerJoin/Leave/Disconnect/Reconnect, action — all self=player (self-scoped)
             return { self: { type: 'player' } };
     }
 }
@@ -1136,6 +1305,8 @@ function walkRuleEffects(rules, timers, entityZoneKinds, zoneSelfKinds, visit) {
                 walk(p, eff.then, { ...b, [eff.as]: { type: 'player' } });
             if (eff.do === 'forEachEntity')
                 walk(p, eff.then, { ...b, [eff.as]: { type: 'entity', kind: eff.kind } });
+            if (eff.do === 'forEachInList')
+                walk(p, eff.then, { ...b, [eff.as]: { type: 'listElem' } }); // §5 (P3 ext) element type unresolved here → coarse (untainted) binding
             if (eff.do === 'spawnEntity' && eff.bind === 'spawned')
                 b = { ...b, spawned: { type: 'entity', kind: eff.kind } };
         });
@@ -1146,8 +1317,13 @@ function walkRuleEffects(rules, timers, entityZoneKinds, zoneSelfKinds, visit) {
 // clean. A `{var:'scope.name'}` is a ref var used as a reference → tainted iff that var is in the taint set:
 // an owner entity's ref var (seeded), or a var transitively setRef'd from a tainted ref.
 function refTainted(ref, bindings, taint) {
-    if (ref === null || typeof ref !== 'object' || 'op' in ref)
+    if (ref === null || typeof ref !== 'object')
         return false;
+    // §9 (P3) the controller of a tainted (client-uploaded) entity is itself tainted — propagate through controllerOf so
+    // it's caught in a {ref,var} read or a target sink. Other ref ops (nearestPlayer/leastLoadedPlayer/aggregate) are
+    // server reductions over server state → never client-tainted.
+    if ('op' in ref)
+        return ref.op === 'controllerOf' && refTainted(ref.entity, bindings, taint);
     const path = ref.var;
     const dot = path.indexOf('.');
     if (dot < 0)
@@ -1159,6 +1335,8 @@ function refTainted(ref, bindings, taint) {
     const b = bindings[scope];
     if (!b)
         return false;
+    if (b.type !== 'player' && b.type !== 'entity')
+        return false; // §5 (P3 ext) a list-element binding — server-written, never client-tainted
     return b.type === 'player' ? taint.player.has(name) : taint.entity.has(`${b.kind}.${name}`);
 }
 // Mark the var an lvalue writes as tainted (used when setRef stores a tainted ref into it). A {ref,var} lvalue
@@ -1179,8 +1357,8 @@ function taintLvalue(target, bindings, taint, allKinds) {
             return;
         if (b.type === 'player')
             taint.player.add(name);
-        else
-            taint.entity.add(`${b.kind}.${name}`);
+        else if (b.type === 'entity')
+            taint.entity.add(`${b.kind}.${name}`); // a list-element binding is never a string-lvalue scope (self is player/entity)
         return;
     }
     const r = target.ref;
@@ -1280,11 +1458,41 @@ function checkFirewall(m) {
                     flag(eff.to, `${eff.do} to`);
                 break;
             case 'append':
-                flagReads(eff.value, b, path, 'append value'); // §5 (4.5.13) row-13 read-leak in the appended value
+                // §5 (P3) a ref-addressed target is a cross-member write — taint-flag it like add/set; the value's reads too.
+                if (typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'append write-through-ref');
+                if (isRecordLiteral(eff.value))
+                    for (const v of Object.values(eff.value))
+                        flagReads(v, b, path, 'append value');
+                else
+                    flagReads(eff.value, b, path, 'append value');
+                break;
+            case 'clear':
+                if (typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'clear write-through-ref'); // §5 (P3) cross-member write
                 break;
             case 'addCount':
+                if (typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'addCount write-through-ref'); // §5 (P3) cross-member write
                 flagReads(eff.by, b, path, 'addCount value'); // §5 (4.5.13) row-13 read-leak in the count delta
                 break;
+            case 'removeAt':
+                if (typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'removeAt write-through-ref'); // §5 (P3) cross-member write
+                flagReads(eff.index, b, path, 'removeAt index');
+                break;
+            case 'setField':
+                if (eff.target !== undefined && typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'setField write-through-ref'); // §5 (P3) cross-member write (index-form; the as-form has no target)
+                if (eff.index !== undefined)
+                    flagReads(eff.index, b, path, 'setField index');
+                flagReads(eff.to, b, path, 'setField value');
+                break;
+            case 'removeWhere':
+                if (typeof eff.target !== 'string')
+                    flag(eff.target.ref, 'removeWhere write-through-ref'); // §5 (P3 ext) cross-member write
+                flagReads(eff.where, { ...b, [eff.as]: { type: 'listElem' } }, path, 'removeWhere where'); // the element binding shadows an outer name + is untainted
+                break;
             case 'startTimer':
             case 'cancelTimer':
                 if (eff.key !== undefined)
@@ -1307,6 +1515,9 @@ function checkFirewall(m) {
             case 'forEachPlayer':
                 flagReads(eff.where, b, path, 'forEachPlayer where'); // row 13
                 break;
+            case 'forEachInList':
+                flagReads(eff.where, { ...b, [eff.as]: { type: 'listElem' } }, path, 'forEachInList where'); // row 13 (the element binding is untainted; the body is walked separately)
+                break;
             case 'broadcast':
                 // Forward-defense: the schema's broadcast `to` accepts only a bound name / server reduction (refOp) /
                 // team filter — never a {var} ref-var deref — so a client-uploaded id can't reach the TARGET today. This
@@ -1327,24 +1538,51 @@ function checkFirewall(m) {
     });
     return errors;
 }
-// Validate a varReached event (§7.5): the watched var must be a declared scalar in its scope (vec3/ref
-// aren't comparable), the `value` type must match it, and ordering cmps need a number var.
-function checkVarReached(path, w, roomVars, playerVars) {
-    const decls = w.scope === 'room' ? roomVars : playerVars;
-    const vt = decls[w.var];
-    if (!vt) {
-        const declared = Object.keys(decls);
-        return [`${path}: varReached watches unknown ${w.scope} var "${w.var}"${didYouMean(w.var, declared)} (declared ${w.scope} vars: ${declared.join(', ') || 'none'})`];
+// Validate a varReached event (§7.5): the watched var must be a declared scalar in its scope (vec3/ref/collection
+// aren't comparable), ordering cmps need a number var, and the threshold (a literal, or a {var}/{ref,var} read —
+// P3-B5) must match the watched var's type. Entity scope (P3-B5) watches a declared `kind`'s var (binds self=entity).
+function checkVarReached(path, w, roomVars, playerVars, bound, zoneIds, ec) {
+    let vt;
+    let scopeLabel;
+    if (w.scope === 'entity') {
+        if (w.kind === undefined)
+            return [`${path}: varReached scope:"entity" requires "kind" (the entity kind to watch)`];
+        if (!ec.kinds.has(w.kind))
+            return [`${path}: varReached watches unknown entity kind "${w.kind}"${didYouMean(w.kind, [...ec.kinds])} (declared entities: ${[...ec.kinds].join(', ') || 'none'})`];
+        const kv = ec.kindVars[w.kind] ?? {};
+        vt = kv[w.var];
+        scopeLabel = `entity:${w.kind}`;
+        if (!vt)
+            return [`${path}: varReached watches unknown var "${w.var}" for entity kind "${w.kind}"${didYouMean(w.var, Object.keys(kv))} (declared: ${Object.keys(kv).join(', ') || 'none'})`];
     }
-    if (vt.type === 'vec3' || vt.type === 'ref') {
-        return [`${path}: varReached can't compare a "${vt.type}" var (${w.scope}.${w.var}) — use a number/string/boolean var`];
+    else {
+        if (w.kind !== undefined)
+            return [`${path}: varReached "kind" is only valid with scope:"entity"`];
+        const decls = w.scope === 'room' ? roomVars : playerVars;
+        vt = decls[w.var];
+        scopeLabel = w.scope;
+        if (!vt) {
+            const declared = Object.keys(decls);
+            return [`${path}: varReached watches unknown ${w.scope} var "${w.var}"${didYouMean(w.var, declared)} (declared ${w.scope} vars: ${declared.join(', ') || 'none'})`];
+        }
+    }
+    if (vt.type === 'vec3' || vt.type === 'ref' || vt.type === 'list' || vt.type === 'counterMap') {
+        return [`${path}: varReached can't compare a "${vt.type}" var (${scopeLabel}.${w.var}) — use a number/string/boolean var`];
     }
     const e = [];
     const ordering = w.cmp === '<' || w.cmp === '<=' || w.cmp === '>' || w.cmp === '>=';
     if (ordering && vt.type !== 'number')
-        e.push(`${path}: cmp "${w.cmp}" needs a number var, but ${w.scope}.${w.var} is "${vt.type}"`);
-    if (typeof w.value !== vt.type)
-        e.push(`${path}: value (${JSON.stringify(w.value)}) does not match ${w.scope}.${w.var} ("${vt.type}")`);
+        e.push(`${path}: cmp "${w.cmp}" needs a number var, but ${scopeLabel}.${w.var} is "${vt.type}"`);
+    if (typeof w.value === 'object' && w.value !== null) {
+        // P3-B5 a dynamic threshold ({var}/{ref,var}) — validate as an expr; its type must match the watched var.
+        const r = validateExpr(`${path}.value`, w.value, bound, roomVars, playerVars, zoneIds, ec, 1);
+        e.push(...r.errors);
+        if (r.type !== undefined && r.type !== vt.type)
+            e.push(`${path}: threshold value is "${r.type}" but ${scopeLabel}.${w.var} is "${vt.type}"`);
+    }
+    else if (typeof w.value !== vt.type) {
+        e.push(`${path}: value (${JSON.stringify(w.value)}) does not match ${scopeLabel}.${w.var} ("${vt.type}")`);
+    }
     return e;
 }
 // Reserved binding/scope names a `forEachPlayer as:` (or future bind) may not shadow (§7.1).
@@ -1361,6 +1599,8 @@ function checkEffect(path, eff, bound, roomVars, playerVars, zoneIds, events, ph
         return checkForEach(path, eff, bound, roomVars, playerVars, zoneIds, events, phases, ec);
     if (eff.do === 'forEachEntity')
         return checkForEachEntity(path, eff, bound, roomVars, playerVars, zoneIds, events, phases, ec);
+    if (eff.do === 'forEachInList')
+        return checkForEachInList(path, eff, bound, roomVars, playerVars, zoneIds, events, phases, ec);
     if (eff.do === 'broadcast')
         return checkBroadcast(path, eff, bound, roomVars, playerVars, zoneIds, events, ec);
     if (eff.do === 'spawnEntity') {
@@ -1383,6 +1623,12 @@ function checkEffect(path, eff, bound, roomVars, playerVars, zoneIds, events, ph
                     e.push(`${path}.vars: unknown var "${name}" for entity kind "${eff.kind}"${didYouMean(name, Object.keys(decls))} (declared vars: ${Object.keys(decls).join(', ') || 'none'})`);
                     continue;
                 }
+                // §5 (P3 Collections) a collection entity var can't be seeded at spawn (it has no scalar literal — it starts
+                // empty/zeroed). Populate it with append/addCount in an entitySpawn rule (self = the new entity) instead.
+                if (vt.type === 'list' || vt.type === 'counterMap') {
+                    e.push(`${path}.vars.${name}: a "${vt.type}" collection can't be seeded at spawn — it starts empty; populate it via append/addCount in an {on:'entitySpawn'} rule`);
+                    continue;
+                }
                 if (vt.type === 'ref') {
                     e.push(...resolveRefSlot(`${path}.vars.${name}`, val, bound, roomVars, playerVars, zoneIds, ec).errors);
                 }
@@ -1419,8 +1665,19 @@ function checkEffect(path, eff, bound, roomVars, playerVars, zoneIds, events, ph
         const declared = [...phases];
         return [`${path}: transitionTo references unknown phase "${eff.phase}"${didYouMean(eff.phase, declared)} (declared phases: ${declared.join(', ') || 'none — add multiplayer.states'})`];
     }
-    if (eff.do === 'startTimer' || eff.do === 'cancelTimer')
-        return []; // §8 timer effects — name/duration validated in checkTimerRefs
+    if (eff.do === 'cancelTimer')
+        return []; // §8 timer effect — name validated in checkTimerRefs (no duration)
+    if (eff.do === 'startTimer') {
+        // §8 timer name + literal-floor live in checkTimerRefs; here we type-check the (possibly dynamic) `seconds`
+        // duration expr to number + cap its node count, exactly like add.by / set.to.
+        const r = validateExpr(`${path}.seconds`, eff.seconds, bound, roomVars, playerVars, zoneIds, ec, 1);
+        const e = [...r.errors];
+        if (r.type !== undefined && r.type !== 'number')
+            e.push(`${path}.seconds: startTimer needs a number duration, got "${r.type}"`);
+        if (r.nodes > exports.MULTIPLAYER_CAPS.exprNodes)
+            e.push(`${path}.seconds has ${r.nodes} expression nodes — the cap is ${exports.MULTIPLAYER_CAPS.exprNodes}`);
+        return e;
+    }
     if (eff.do === 'teleport' || eff.do === 'respawn') {
         const e = resolveRefSlot(`${path}.player`, eff.player, bound, roomVars, playerVars, zoneIds, ec).errors;
         const r = validateExpr(`${path}.to`, eff.to, bound, roomVars, playerVars, zoneIds, ec, 1);
@@ -1430,44 +1687,121 @@ function checkEffect(path, eff, bound, roomVars, playerVars, zoneIds, events, ph
         return e;
     }
     if (eff.do === 'append') {
-        // §5 (4.5.13) append a value to a list var; the value must match the list's element type.
-        const c = resolveCollectionVar(`${path}.target`, eff.target, bound, roomVars, playerVars);
+        // §5 (4.5.13 + P3 Collections) append a value to a list var (string or {ref,var} target); the value must match
+        // the list's ELEMENT type (a scalar Expr, a ref, or a record literal).
+        const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
         if (c.errors.length)
             return c.errors;
-        const e = [];
         if (c.vt.type !== 'list')
-            return [`${path}: "append" needs a list var, but "${eff.target}" is "${c.vt.type}"`];
-        const r = validateExpr(`${path}.value`, eff.value, bound, roomVars, playerVars, zoneIds, ec, 1);
-        e.push(...r.errors);
-        if (r.type !== undefined && r.type !== c.vt.of)
-            e.push(`${path}.value: a "${r.type}" can't be appended to a list of "${c.vt.of}"`);
-        return e;
+            return [`${path}: "append" needs a list var, but ${lvalueLabel(eff.target)} is "${c.vt.type}"`];
+        return validateListElementValue(`${path}.value`, eff.value, c.vt.of, bound, roomVars, playerVars, zoneIds, ec);
     }
     if (eff.do === 'clear') {
         // §5 (4.5.13) empty a list OR reset every counterMap key to 0.
-        const c = resolveCollectionVar(`${path}.target`, eff.target, bound, roomVars, playerVars);
+        const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
         if (c.errors.length)
             return c.errors;
         if (c.vt.type !== 'list' && c.vt.type !== 'counterMap')
-            return [`${path}: "clear" needs a list or counterMap var, but "${eff.target}" is "${c.vt.type}"`];
+            return [`${path}: "clear" needs a list or counterMap var, but ${lvalueLabel(eff.target)} is "${c.vt.type}"`];
         return [];
     }
     if (eff.do === 'addCount') {
         // §5 (4.5.13) add a number `by` to a counterMap's declared `key`.
-        const c = resolveCollectionVar(`${path}.target`, eff.target, bound, roomVars, playerVars);
+        const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
         if (c.errors.length)
             return c.errors;
         const e = [];
         if (c.vt.type !== 'counterMap')
-            e.push(`${path}: "addCount" needs a counterMap var, but "${eff.target}" is "${c.vt.type}"`);
+            e.push(`${path}: "addCount" needs a counterMap var, but ${lvalueLabel(eff.target)} is "${c.vt.type}"`);
         else if (!c.vt.keys.includes(eff.key))
-            e.push(`${path}.key: "${eff.key}" is not a declared key of "${eff.target}"${didYouMean(eff.key, c.vt.keys)} (keys: ${c.vt.keys.join(', ')})`);
+            e.push(`${path}.key: "${eff.key}" is not a declared key of ${lvalueLabel(eff.target)}${didYouMean(eff.key, c.vt.keys)} (keys: ${c.vt.keys.join(', ')})`);
         const r = validateExpr(`${path}.by`, eff.by, bound, roomVars, playerVars, zoneIds, ec, 1);
         e.push(...r.errors);
         if (r.type !== undefined && r.type !== 'number')
             e.push(`${path}.by: "addCount" needs a number, got "${r.type}"`);
         return e;
     }
+    if (eff.do === 'removeAt') {
+        // §5 (P3) remove the element at `index` from a list (shift). The index is a number expr; out-of-range = no-op.
+        const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
+        if (c.errors.length)
+            return c.errors;
+        if (c.vt.type !== 'list')
+            return [`${path}: "removeAt" needs a list var, but ${lvalueLabel(eff.target)} is "${c.vt.type}"`];
+        const r = validateExpr(`${path}.index`, eff.index, bound, roomVars, playerVars, zoneIds, ec, 1);
+        const e = [...r.errors];
+        if (r.type !== undefined && r.type !== 'number')
+            e.push(`${path}.index: "removeAt" needs a number index, got "${r.type}"`);
+        return e;
+    }
+    if (eff.do === 'removeWhere')
+        return checkRemoveWhere(path, eff, bound, roomVars, playerVars, zoneIds, ec);
+    if (eff.do === 'setField') {
+        // §5 (P3) write a record element's `field`. AS-form: address a record element `as` bound by an enclosing
+        // forEachInList (no target/index). INDEX-form: address element `index` of the list `target`. A helper validates
+        // the `to` value matches the resolved record field `ft`.
+        const checkTo = (ft) => {
+            if (ft.type === 'ref')
+                return resolveRefSlot(`${path}.to`, eff.to, bound, roomVars, playerVars, zoneIds, ec).errors;
+            const vr = validateExpr(`${path}.to`, eff.to, bound, roomVars, playerVars, zoneIds, ec, 1);
+            const e = [...vr.errors];
+            if (vr.type !== undefined && vr.type !== ft.type)
+                e.push(`${path}.to: a "${vr.type}" doesn't match the record field "${eff.field}" ("${ft.type}")`);
+            return e;
+        };
+        if (eff.as !== undefined) {
+            const e = [];
+            if (eff.index !== undefined)
+                e.push(`${path}: "setField" can't take both "as" and "index" — "as" addresses the element forEachInList bound`);
+            const k = ec.boundKinds?.[eff.as];
+            if (!bound.has(eff.as) || k?.type !== 'listRecord')
+                return [...e, `${path}.as: "${eff.as}" is not a record element bound by an enclosing forEachInList`];
+            const ft = k.fields[eff.field];
+            if (!ft)
+                return [...e, `${path}.field: unknown record field "${eff.field}"${didYouMean(eff.field, Object.keys(k.fields))} (fields: ${Object.keys(k.fields).join(', ')})`];
+            return [...e, ...checkTo(ft)];
+        }
+        if (eff.target === undefined)
+            return [`${path}: "setField" needs a "target" (with an "index"), or an "as" bound by an enclosing forEachInList`];
+        const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
+        if (c.errors.length)
+            return c.errors;
+        if (c.vt.type !== 'list' || typeof c.vt.of !== 'object' || c.vt.of.type !== 'record') {
+            return [`${path}: "setField" needs a list of records, but ${lvalueLabel(eff.target)} is "${c.vt.type === 'list' ? `list of ${typeof c.vt.of === 'string' ? c.vt.of : c.vt.of.type}` : c.vt.type}"`];
+        }
+        if (eff.index === undefined)
+            return [`${path}: "setField" needs an "index" (or an "as" bound by forEachInList)`];
+        const e = [];
+        const r = validateExpr(`${path}.index`, eff.index, bound, roomVars, playerVars, zoneIds, ec, 1);
+        e.push(...r.errors);
+        if (r.type !== undefined && r.type !== 'number')
+            e.push(`${path}.index: "setField" needs a number index, got "${r.type}"`);
+        const ft = c.vt.of.fields[eff.field];
+        if (!ft)
+            e.push(`${path}.field: unknown record field "${eff.field}"${didYouMean(eff.field, Object.keys(c.vt.of.fields))} (fields: ${Object.keys(c.vt.of.fields).join(', ')})`);
+        else
+            e.push(...checkTo(ft));
+        return e;
+    }
+    if (eff.do === 'advanceTurn') {
+        // §7.4 (P3-B2) `order` must be a `list of ref:player`; `index` a writable number var.
+        const c = resolveCollectionLvalue(`${path}.order`, eff.order, bound, roomVars, playerVars, zoneIds, ec);
+        if (c.errors.length)
+            return c.errors;
+        const ofElem = c.vt.type === 'list' ? c.vt.of : undefined;
+        if (c.vt.type !== 'list' || typeof ofElem !== 'object' || ofElem.type !== 'ref' || ofElem.of !== 'player') {
+            return [`${path}.order: "advanceTurn" needs a list of player refs (got ${lvalueLabel(eff.order)})`];
+        }
+        const idx = resolveLvalue(`${path}.index`, eff.index, bound, roomVars, playerVars, zoneIds, ec);
+        const e = [...idx.errors];
+        if (idx.type !== undefined && idx.type !== 'number')
+            e.push(`${path}.index: "advanceTurn" needs a number var, but ${lvalueLabel(eff.index)} is "${idx.type}"`);
+        return e;
+    }
+    if (eff.do === 'eliminate' || eff.do === 'revive') {
+        // §7.4 (P3-B2) `player` is a Ref (firewall-checked); the room toggles its reserved `active` flag.
+        return resolveRefSlot(`${path}.player`, eff.player, bound, roomVars, playerVars, zoneIds, ec).errors;
+    }
     // add | set | setRef — all have a target lvalue. (TS can't reliably narrow this recursive union past the
     // early returns above, so assert the remaining subtype; `ve.do` still discriminates `to` within it.)
     const ve = eff;
@@ -1528,7 +1862,7 @@ function checkForEach(path, eff, bound, roomVars, playerVars, zoneIds, events, p
         e.push(`${path}.then has ${eff.then.length} effects — the cap is ${exports.MULTIPLAYER_CAPS.ruleThen}`);
     let running = inner;
     eff.then.forEach((sub, j) => {
-        if (sub.do === 'forEachPlayer' || sub.do === 'forEachEntity') {
+        if (sub.do === 'forEachPlayer' || sub.do === 'forEachEntity' || sub.do === 'forEachInList') {
             e.push(`${path}.then[${j}]: ${sub.do} can't nest inside forEachPlayer (single level only)`);
             return;
         }
@@ -1562,7 +1896,7 @@ function checkForEachEntity(path, eff, bound, roomVars, playerVars, zoneIds, eve
     let running = inner;
     let runningEc = innerEc;
     eff.then.forEach((sub, j) => {
-        if (sub.do === 'forEachPlayer' || sub.do === 'forEachEntity') {
+        if (sub.do === 'forEachPlayer' || sub.do === 'forEachEntity' || sub.do === 'forEachInList') {
             e.push(`${path}.then[${j}]: ${sub.do} can't nest inside forEachEntity (single level only)`);
             return;
         }
@@ -1576,6 +1910,95 @@ function checkForEachEntity(path, eff, bound, roomVars, playerVars, zoneIds, eve
     });
     return e;
 }
+// §5 (P3 ext) the static binding kind for a list element of type `elem` (the name a forEachInList / listCount /
+// listIndexOf scan binds). A ref element flows like the member it points at (player/entity); a record element
+// exposes its fields ({ref:as,var:field}); a scalar element is a bound value ({var:as}). undefined elem (the list
+// didn't resolve) → the coarse listElem so downstream errors are about the list, not a spurious binding mismatch.
+function elemBinding(elem) {
+    if (elem === undefined)
+        return { type: 'listElem' };
+    if (typeof elem === 'string')
+        return { type: 'listScalar', scalar: elem };
+    if (elem.type === 'ref')
+        return ofToKind(elem.of) ?? { type: 'listElem' };
+    return { type: 'listRecord', fields: elem.fields };
+}
+// §5 (P3 ext) two lvalues address the same collection (structural equality — a dotted path or a {ref,var}). Used to
+// forbid structurally mutating the very list a forEachInList iterates (the indices/elements would shift mid-scan).
+function sameLvalue(a, b) {
+    if (typeof a === 'string' || typeof b === 'string')
+        return a === b;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+// §5 (P3 ext) does `sub` STRUCTURALLY mutate the list `list` (append/clear/removeAt/removeWhere on the same lvalue)?
+// A setField (record-field write, no length change) is allowed on the iterated list — it's the point of the loop.
+function mutatesIteratedList(sub, list) {
+    if (sub.do === 'append' || sub.do === 'clear' || sub.do === 'removeAt' || sub.do === 'removeWhere')
+        return sameLvalue(sub.target, list);
+    return false;
+}
+// §5 (P3 Collections ext) validate forEachInList — the bounded loop over a list's ELEMENTS (the §13 sublanguage
+// completion). Like forEachEntity (single level, optional `where`, reductions forbidden inside) but iterates a
+// collection lvalue and binds `as` to the element (its kind from elemBinding — scalar value / member Ref / record).
+// Can't structurally mutate the list it iterates (use removeWhere); the per-tick budget charges maxLen × body.
+function checkForEachInList(path, eff, bound, roomVars, playerVars, zoneIds, events, phases, ec) {
+    const e = [];
+    const c = resolveCollectionLvalue(`${path}.list`, eff.list, bound, roomVars, playerVars, zoneIds, ec);
+    if (c.errors.length)
+        e.push(...c.errors);
+    else if (c.vt.type !== 'list')
+        e.push(`${path}.list: forEachInList needs a list var, but ${lvalueLabel(eff.list)} is "${c.vt.type}"`);
+    if (RESERVED_REF_NAMES.has(eff.as))
+        e.push(`${path}.as: "${eff.as}" is a reserved name`);
+    const elem = c.vt?.type === 'list' ? c.vt.of : undefined;
+    const inner = new Set([...bound, eff.as]);
+    const innerEc = { ...ec, boundKinds: { ...ec.boundKinds, [eff.as]: elemBinding(elem) } };
+    if (eff.where !== undefined) {
+        e.push(...validateExpr(`${path}.where`, eff.where, inner, roomVars, playerVars, zoneIds, innerEc, 1).errors);
+        if (exprHasReduction(eff.where))
+            e.push(`${path}.where: aggregate/nearest* are forbidden inside forEachInList`);
+    }
+    if (eff.then.length > exports.MULTIPLAYER_CAPS.ruleThen)
+        e.push(`${path}.then has ${eff.then.length} effects — the cap is ${exports.MULTIPLAYER_CAPS.ruleThen}`);
+    let running = inner;
+    let runningEc = innerEc;
+    eff.then.forEach((sub, j) => {
+        if (sub.do === 'forEachPlayer' || sub.do === 'forEachEntity' || sub.do === 'forEachInList') {
+            e.push(`${path}.then[${j}]: ${sub.do} can't nest inside forEachInList (single level only)`);
+            return;
+        }
+        if (mutatesIteratedList(sub, eff.list))
+            e.push(`${path}.then[${j}]: "${sub.do}" can't mutate the list forEachInList is iterating — use removeWhere to scan-and-remove, or setField to edit an element in place`);
+        e.push(...checkEffect(`${path}.then[${j}]`, sub, running, roomVars, playerVars, zoneIds, events, phases, runningEc));
+        if (effectHasReduction(sub))
+            e.push(`${path}.then[${j}]: aggregate/nearest* are forbidden inside forEachInList`);
+        if (sub.do === 'spawnEntity' && sub.bind === 'spawned') {
+            running = new Set([...running, 'spawned']);
+            runningEc = { ...runningEc, boundKinds: { ...runningEc.boundKinds, spawned: { type: 'entity', kind: sub.kind } } };
+        }
+    });
+    return e;
+}
+// §5 (P3 Collections ext) validate removeWhere — drop ALL elements of a list matching `where` (a bounded scan that
+// binds `as` to the element, exactly like forEachInList's binding). No nested effects; the `where` is read-only and
+// can't contain a reduction (O(maxLen) scan already). Used to scan-and-remove (cull broken/dead elements).
+function checkRemoveWhere(path, eff, bound, roomVars, playerVars, zoneIds, ec) {
+    const e = [];
+    const c = resolveCollectionLvalue(`${path}.target`, eff.target, bound, roomVars, playerVars, zoneIds, ec);
+    if (c.errors.length)
+        e.push(...c.errors);
+    else if (c.vt.type !== 'list')
+        e.push(`${path}.target: "removeWhere" needs a list var, but ${lvalueLabel(eff.target)} is "${c.vt.type}"`);
+    if (RESERVED_REF_NAMES.has(eff.as))
+        e.push(`${path}.as: "${eff.as}" is a reserved name`);
+    const elem = c.vt?.type === 'list' ? c.vt.of : undefined;
+    const inner = new Set([...bound, eff.as]);
+    const innerEc = { ...ec, boundKinds: { ...ec.boundKinds, [eff.as]: elemBinding(elem) } };
+    e.push(...validateExpr(`${path}.where`, eff.where, inner, roomVars, playerVars, zoneIds, innerEc, 1).errors);
+    if (exprHasReduction(eff.where))
+        e.push(`${path}.where: aggregate/nearest* are forbidden inside removeWhere`);
+    return e;
+}
 // Does an expression contain an aggregate / a ref-returning op (nearestPlayer / aggregate argmax|argmin)? The
 // reductions, which are O(members) scans and so forbidden inside forEachPlayer (would be O(members²)).
 function exprHasReduction(expr) {
@@ -1592,12 +2015,28 @@ function exprHasReduction(expr) {
         return node.of.some(exprHasReduction);
     if (node.op === 'not')
         return exprHasReduction(node.of);
+    if (node.op === 'controlledBy') {
+        const cb = node;
+        return refHasReduction(cb.entity) || refHasReduction(cb.by);
+    } // §9 (P3) O(1) itself — only its refs can reduce
+    if (node.op === 'sameRef') {
+        const sr = node;
+        return refHasReduction(sr.a) || refHasReduction(sr.b);
+    } // §7.3 (P3-B2) O(1) itself — only its refs can reduce
+    if (node.op === 'hostLoad')
+        return true; // §9 (P3) O(entities) scan — a reduction, forbidden inside forEach
     if (node.a !== undefined)
         return exprHasReduction(node.a) || exprHasReduction(node.b);
     return false;
 }
 function refHasReduction(ref) {
-    return typeof ref !== 'string' && 'op' in ref; // nearestPlayer / aggregate argmax|argmin (a {var} deref is fine)
+    if (typeof ref === 'string' || !('op' in ref))
+        return false; // a bound name / {var} deref — O(1)
+    if (ref.op === 'controllerOf')
+        return refHasReduction(ref.entity); // §9 (P3) O(1) field read — only a reducing inner entity ref counts
+    if (ref.op === 'listAt')
+        return exprHasReduction(ref.index); // §5 (P3-B2) O(1) element read — only a reducing index expr counts
+    return true; // nearestPlayer / nearestEntity / aggregate argmax|argmin / leastLoadedPlayer — O(members) scans
 }
 // Validate a `broadcast` effect (§7.4/§10.3): the event must be declared; `to` must be a valid target; the
 // payload must exactly match the event's declared fields (no unknown, none missing), each value a Ref for a
@@ -1624,6 +2063,10 @@ function checkBroadcast(path, eff, bound, roomVars, playerVars, zoneIds, events,
         if (ft.type === 'ref') {
             e.push(...resolveRefSlot(`${path}.payload.${field}`, val, bound, roomVars, playerVars, zoneIds, ec).errors);
         }
+        else if (ft.type === 'list' || ft.type === 'counterMap') {
+            // §10.3 (P3-B6) a collection-snapshot field: the value must reference a collection var of the matching shape.
+            e.push(...checkCollectionPayload(`${path}.payload.${field}`, ft, val, bound, roomVars, playerVars, ec));
+        }
         else {
             const r = validateExpr(`${path}.payload.${field}`, val, bound, roomVars, playerVars, zoneIds, ec, 1);
             e.push(...r.errors);
@@ -1633,6 +2076,26 @@ function checkBroadcast(path, eff, bound, roomVars, playerVars, zoneIds, events,
     }
     return e;
 }
+// §10.3 (P3-B6) validate a collection-snapshot payload field's value: a `{var:"room/self.<coll>"}` reference to a
+// declared collection var whose type + shape (element / keys) equals the field's. The room serializes that live
+// collection into the broadcast. (A literal collection value isn't expressible — a snapshot is always of a var.)
+function checkCollectionPayload(path, ft, val, bound, roomVars, playerVars, ec) {
+    if (typeof val !== 'object' || val === null || !('var' in val) || typeof val.var !== 'string') {
+        return [`${path}: a "${ft.type}" payload field must reference a collection var ({ "var": "room.<v>" | "self.<v>" }) to snapshot`];
+    }
+    const c = resolveCollectionVar(path, val.var, bound, roomVars, playerVars, ec);
+    if (c.errors.length)
+        return c.errors;
+    if (c.vt.type !== ft.type)
+        return [`${path}: field is a "${ft.type}" but "${val.var}" is a "${c.vt.type}"`];
+    if (ft.type === 'list' && c.vt.type === 'list' && JSON.stringify(c.vt.of) !== JSON.stringify(ft.of)) {
+        return [`${path}: the referenced list's element type doesn't match the declared payload field element`];
+    }
+    if (ft.type === 'counterMap' && c.vt.type === 'counterMap' && JSON.stringify([...c.vt.keys].sort()) !== JSON.stringify([...ft.keys].sort())) {
+        return [`${path}: the referenced counterMap's keys don't match the declared payload field keys`];
+    }
+    return [];
+}
 // Validate a broadcast `to` target: "all", a Ref (bound name / ref-var / ref-op), or {team:"<playerVar>=<val>"}.
 function checkBroadcastTarget(path, to, bound, roomVars, playerVars, zoneIds, ec) {
     if (to === 'all')
@@ -1665,6 +2128,9 @@ function effectHasReduction(eff) {
             return exprHasReduction(eff.at) || Object.values(eff.vars ?? {}).some((v) => exprHasReduction(v));
         case 'destroyEntity':
             return refHasReduction(eff.entity);
+        case 'eliminate':
+        case 'revive':
+            return refHasReduction(eff.player); // §7.4 (P3-B2) only a reducing player ref counts
         default:
             return false;
     }
@@ -1690,7 +2156,7 @@ function boundNames(event, timers, entityZoneKinds) {
         case 'action':
             return new Set(['self']); // the player who sent the action
         case 'varReached':
-            return event.scope === 'self' ? new Set(['self']) : new Set(); // self-scope binds the player instance
+            return event.scope === 'room' ? new Set() : new Set(['self']); // self/entity scope binds the watched instance (player/entity); room binds nothing
         case 'stateEnter':
         case 'stateExit':
             return new Set(); // §8 room-scoped phase machine — no member bound
@@ -1708,7 +2174,11 @@ function boundNames(event, timers, entityZoneKinds) {
 }
 // Player built-in reads (§7.1) addressable as `self.<name>` or `{ref,var}` — NOT declared vars, can't be
 // shadowed. Phase-2.4a exposes `position` (vec3); Phase-3 presence adds `connected` (boolean, read-only).
-const PLAYER_BUILTIN_TYPES = { position: 'vec3', connected: 'boolean' };
+const PLAYER_BUILTIN_TYPES = { position: 'vec3', connected: 'boolean', active: 'boolean' };
+// `connected`/`active` are PLAYER-only presence/participation built-ins — an ENTITY member's same-named DECLARED var
+// wins (entities have no connection/participation). `position` is universal (players + entities both have a transform).
+const PLAYER_ONLY_BUILTINS = new Set(['connected', 'active']);
+const playerBuiltin = (name, isEntity) => name in PLAYER_BUILTIN_TYPES && !(isEntity && PLAYER_ONLY_BUILTINS.has(name));
 // Room built-in reads addressable as `room.<name>` — NOT declared roomVars. Phase-3 (§8) exposes `phase` (the
 // current state-machine phase, a string); it is read-only here (change it via transitionTo, not `set`).
 const ROOM_BUILTIN_TYPES = { phase: 'string' };
@@ -1760,14 +2230,37 @@ function validateExpr(path, expr, bound, roomVars, playerVars, zoneIds, ec, dept
     // op node — the schema already validated its shape, so read children via a generic view (TS can't reliably
     // narrow this recursive union past the `op` discriminant). Gather labelled child sub-expressions:
     const node = expr;
-    if (node.op === 'playerCount' || node.op === 'random' || node.op === 'timeInState' || node.op === 'timerRemaining')
+    if (node.op === 'playerCount' || node.op === 'random' || node.op === 'timeInState' || node.op === 'timerRemaining' || node.op === 'now')
         return { errors: [], nodes: 1, type: 'number' }; // leaf ops (timer-name refs resolved in checkTimerRefs)
     if (node.op === 'randomPoint')
         return { errors: [], nodes: 1, type: 'vec3' }; // leaf → a random vec3 in the [min,max] box (shape schema-validated)
     if (node.op === 'aggregate')
         return { errors: validateAggregate(path, node, bound, roomVars, playerVars, zoneIds, ec), nodes: 1, type: 'number' };
-    if (node.op === 'listLength' || node.op === 'listAt' || node.op === 'count')
-        return validateCollectionOp(path, expr, bound, roomVars, playerVars, zoneIds, ec, depth); // §5 (4.5.13) collection reads
+    if (node.op === 'listLength' || node.op === 'listAt' || node.op === 'count' || node.op === 'listCount' || node.op === 'listIndexOf')
+        return validateCollectionOp(path, expr, bound, roomVars, playerVars, zoneIds, ec, depth); // §5 (4.5.13 + P3 ext) collection reads
+    if (node.op === 'controlledBy') {
+        // §9 (P3 Ownership/A3) boolean: is `entity` controlled by the player `by` resolves to? Both are ref slots.
+        const cb = expr;
+        const e = [
+            ...resolveRefSlot(`${path}.entity`, cb.entity, bound, roomVars, playerVars, zoneIds, ec).errors,
+            ...resolveRefSlot(`${path}.by`, cb.by, bound, roomVars, playerVars, zoneIds, ec).errors,
+        ];
+        return { errors: e, nodes: 1, type: 'boolean' };
+    }
+    if (node.op === 'sameRef') {
+        // §7.3 (P3-B2) boolean: do two Refs resolve to the same live member? Both are ref slots (O(1) identity test).
+        const sr = expr;
+        const e = [
+            ...resolveRefSlot(`${path}.a`, sr.a, bound, roomVars, playerVars, zoneIds, ec).errors,
+            ...resolveRefSlot(`${path}.b`, sr.b, bound, roomVars, playerVars, zoneIds, ec).errors,
+        ];
+        return { errors: e, nodes: 1, type: 'boolean' };
+    }
+    if (node.op === 'hostLoad') {
+        // §9 (P3 Ownership/B8) the count of live entities the player `of` controls → number. O(entities) scan.
+        const hl = expr;
+        return { errors: resolveRefSlot(`${path}.of`, hl.of, bound, roomVars, playerVars, zoneIds, ec).errors, nodes: 1, type: 'number' };
+    }
     let children;
     if (node.op === 'not')
         children = [[`${path}.of`, node.of]];
@@ -1865,12 +2358,15 @@ function validateAggregate(path, node, bound, roomVars, playerVars, zoneIds, ec)
         e.push(`${path}: aggregate "${node.agg}" needs a "field" (a number ${entityDomain ? 'entity' : 'player'} var)`);
         return e;
     }
-    // The field is a number var of the reduced collection — entity vars for an entity domain (entities:<kind> or a
-    // zone tracking 'entity:<kind>'), else player vars.
-    const fieldType = entityDomain ? ec.varTypes[node.field] : playerVars[node.field]?.type;
+    // The field is a number var of the reduced collection. (P3-B4) For an entity domain (entities:<kind> or a zone
+    // tracking 'entity:<kind>') resolve `field` against the SPECIFIC tracked kind's vars, not the entity-var union — a
+    // field absent on that kind is a publish error, not a silent runtime 0. Player domain → player vars.
+    const kindVars = entityDomain && memberKind.kind !== undefined ? (ec.kindVars[memberKind.kind] ?? {}) : undefined;
+    const fieldType = entityDomain ? (kindVars ? kindVars[node.field]?.type : ec.varTypes[node.field]) : playerVars[node.field]?.type;
     if (fieldType === undefined) {
-        const declared = entityDomain ? Object.keys(ec.varTypes) : Object.keys(playerVars);
-        e.push(`${path}: aggregate field — unknown ${entityDomain ? 'entity' : 'player'} var "${node.field}"${didYouMean(node.field, declared)} (declared: ${declared.join(', ') || 'none'})`);
+        const declared = entityDomain ? Object.keys(kindVars ?? ec.varTypes) : Object.keys(playerVars);
+        const domainLabel = entityDomain ? (memberKind.kind !== undefined ? `entity kind "${memberKind.kind}"` : 'entity') : 'player';
+        e.push(`${path}: aggregate field — unknown ${domainLabel} var "${node.field}"${didYouMean(node.field, declared)} (declared: ${declared.join(', ') || 'none'})`);
     }
     else if (fieldType !== 'number') {
         e.push(`${path}: aggregate "${node.agg}" needs a number field, but "${node.field}" is "${fieldType}"`);
@@ -1883,6 +2379,17 @@ function resolveVarRead(path, dotted, bound, roomVars, playerVars, ec) {
     const dot = dotted.indexOf('.');
     const scope = dot >= 0 ? dotted.slice(0, dot) : '';
     const name = dot >= 0 ? dotted.slice(dot + 1) : '';
+    // §5 (P3 ext) a bare bound name (no scope) → a list element bound by forEachInList / listCount / listIndexOf. A
+    // SCALAR element reads as its value; a record/ref element points the author at its proper read form.
+    if (dot < 0 && bound.has(dotted)) {
+        const k = ec.boundKinds?.[dotted];
+        if (k?.type === 'listScalar')
+            return { errors: [], type: k.scalar };
+        if (k?.type === 'listRecord')
+            return { errors: [`${path}: "${dotted}" is a record list element — read a field via {ref:"${dotted}",var:"<field>"}, not {var}`] };
+        if (k?.type === 'player' || k?.type === 'entity')
+            return { errors: [`${path}: "${dotted}" is a ref element — use it as a ref ({ref:"${dotted}",var:…}), not {var}`] };
+    }
     if (scope === 'action') {
         // §11.5 (4.7) action.args.<arg> — readable only inside an {on:action} rule (ec.actionArgs set). The type is
         // the matched action's declared arg type; a ref arg returns 'ref' (resolveRefSlot then accepts it as a Ref).
@@ -1900,7 +2407,7 @@ function resolveVarRead(path, dotted, bound, roomVars, playerVars, ec) {
         return { errors: [`${path}: var "${dotted}" must be "room.<var>", "self.<var>", or "action.args.<arg>"`] };
     if (scope === 'self' && !bound.has('self'))
         return { errors: [`${path}: "self.${name}" — this rule's event binds no member (no "self" here)`] };
-    if (scope === 'self' && name in PLAYER_BUILTIN_TYPES)
+    if (scope === 'self' && playerBuiltin(name, ec.boundKinds?.self?.type === 'entity'))
         return { errors: [], type: PLAYER_BUILTIN_TYPES[name] };
     if (scope === 'room' && name in ROOM_BUILTIN_TYPES)
         return { errors: [], type: ROOM_BUILTIN_TYPES[name] };
@@ -1934,10 +2441,10 @@ function collectionReadError(path, dotted, t) {
     const how = t === 'list' ? 'read it via listLength/listAt, mutate via append/clear' : 'read it via count, mutate via addCount/clear';
     return `${path}: "${dotted}" is a ${t} collection — it can't be used as a scalar value (${how})`;
 }
-// §5 (4.5.13) resolve a "room.<var>"/"self.<var>" path to its declared COLLECTION var (list/counterMap). Collections
-// live on roomVars/playerVars only, so `self` resolves against playerVars (an entity-self has none). Returns the
-// declared HelixVarType (caller checks list vs counterMap) or an error. `self` needs the event to bind a member.
-function resolveCollectionVar(path, dotted, bound, roomVars, playerVars) {
+// §5 (4.5.13 + P3) resolve a "room.<var>"/"self.<var>" path to its declared COLLECTION var (list/counterMap).
+// `self` resolves against playerVars, OR — when the event binds self to an entity (P3 entity collections) — against
+// that entity kind's vars. Returns the declared HelixVarType (caller checks list vs counterMap) or an error.
+function resolveCollectionVar(path, dotted, bound, roomVars, playerVars, ec) {
     const dot = dotted.indexOf('.');
     const scope = dot >= 0 ? dotted.slice(0, dot) : '';
     const name = dot >= 0 ? dotted.slice(dot + 1) : '';
@@ -1945,50 +2452,134 @@ function resolveCollectionVar(path, dotted, bound, roomVars, playerVars) {
         return { errors: [`${path}: "${dotted}" must be a "room.<var>" or "self.<var>" collection`] };
     if (scope === 'self' && !bound.has('self'))
         return { errors: [`${path}: "self.${name}" — this rule's event binds no member (no "self" here)`] };
+    if (scope === 'self' && ec.boundKinds?.self?.type === 'entity') {
+        const kind = ec.boundKinds.self.kind;
+        const vt = ec.kindVars[kind]?.[name];
+        if (!vt)
+            return { errors: [`${path}: unknown var "${name}" for entity kind "${kind}"${didYouMean(name, Object.keys(ec.kindVars[kind] ?? {}))} (declared: ${Object.keys(ec.kindVars[kind] ?? {}).join(', ') || 'none'})`] };
+        return { errors: [], vt };
+    }
     const decls = scope === 'room' ? roomVars : playerVars;
     const vt = decls[name];
     if (!vt)
         return { errors: [`${path}: unknown ${scope} collection var "${name}"${didYouMean(name, Object.keys(decls))} (declared ${scope} vars: ${Object.keys(decls).join(', ') || 'none'})`] };
     return { errors: [], vt };
 }
+// §5 (P3) resolve a collection LVALUE — a "room/self.<var>" path OR a ref-addressed {ref,var} (push onto an
+// iterated/other member's or an entity's collection). The {ref,var} ref resolves to a player (→ playerVars) or a
+// known entity kind (→ that kind's vars). Returns the declared collection VarType, or an error.
+function resolveCollectionLvalue(path, target, bound, roomVars, playerVars, zoneIds, ec) {
+    if (typeof target === 'string')
+        return resolveCollectionVar(path, target, bound, roomVars, playerVars, ec);
+    const r = resolveRefSlot(`${path}.ref`, target.ref, bound, roomVars, playerVars, zoneIds, ec);
+    if (r.errors.length)
+        return { errors: r.errors };
+    const name = target.var;
+    if (r.kind?.type === 'entity') {
+        const vt = ec.kindVars[r.kind.kind]?.[name];
+        if (!vt)
+            return { errors: [`${path}.var: unknown var "${name}" for entity kind "${r.kind.kind}"${didYouMean(name, Object.keys(ec.kindVars[r.kind.kind] ?? {}))} (declared: ${Object.keys(ec.kindVars[r.kind.kind] ?? {}).join(', ') || 'none'})`] };
+        return { errors: [], vt };
+    }
+    const vt = playerVars[name]; // a player ref (or an untracked-kind ref) addresses a player collection
+    if (!vt)
+        return { errors: [`${path}.var: unknown player collection var "${name}"${didYouMean(name, Object.keys(playerVars))} (declared player vars: ${Object.keys(playerVars).join(', ') || 'none'})`] };
+    return { errors: [], vt };
+}
 // §5 (4.5.13) validate a collection-read op (listLength/listAt/count): resolve its var, check the var's kind
 // matches the op, and (listAt) validate the index expr. Returns the op's value type (number, or the list's
 // element type for listAt). Mirrors validateExpr's contract (errors + node count + inferred type).
 function validateCollectionOp(path, expr, bound, roomVars, playerVars, zoneIds, ec, depth) {
     const n = expr;
+    // §5 (P3 ext) listCount / listIndexOf — a bounded element scan that binds `as` to the element + counts / finds the
+    // first index matching `where` (→ number). The list is any collection lvalue; the where reads the bound element
+    // (scalar via {var:as}, record field via {ref:as,var:field}, ref element as a Ref) and can't itself reduce.
+    if (n.op === 'listCount' || n.op === 'listIndexOf') {
+        const sc = expr;
+        const c = resolveCollectionLvalue(`${path}.list`, sc.list, bound, roomVars, playerVars, zoneIds, ec);
+        if (c.errors.length)
+            return { errors: c.errors, nodes: 1 };
+        if (c.vt.type !== 'list')
+            return { errors: [`${path}: "${n.op}" needs a list var, but ${lvalueLabel(sc.list)} is "${c.vt.type}"`], nodes: 1 };
+        const e = [];
+        if (RESERVED_REF_NAMES.has(sc.as))
+            e.push(`${path}.as: "${sc.as}" is a reserved name`);
+        const inner = new Set([...bound, sc.as]);
+        const innerEc = { ...ec, boundKinds: { ...ec.boundKinds, [sc.as]: elemBinding(c.vt.of) } };
+        const w = validateExpr(`${path}.where`, sc.where, inner, roomVars, playerVars, zoneIds, innerEc, depth + 1);
+        e.push(...w.errors);
+        if (exprHasReduction(sc.where))
+            e.push(`${path}.where: aggregate/nearest* are forbidden inside ${n.op}`);
+        return { errors: e, nodes: 1 + w.nodes, type: 'number' };
+    }
     if (n.op === 'count') {
-        const c = resolveCollectionVar(`${path}.map`, n.map ?? '', bound, roomVars, playerVars);
+        // §5 (P3 ext) `map` is any counterMap lvalue (room/self path OR a {ref,var} addressing another member's / an entity's counterMap).
+        const c = resolveCollectionLvalue(`${path}.map`, n.map ?? '', bound, roomVars, playerVars, zoneIds, ec);
         if (c.errors.length)
             return { errors: c.errors, nodes: 1 };
         if (c.vt.type !== 'counterMap')
-            return { errors: [`${path}: "count" needs a counterMap var, but "${n.map}" is "${c.vt.type}"`], nodes: 1 };
+            return { errors: [`${path}: "count" needs a counterMap var, but ${lvalueLabel(n.map ?? '')} is "${c.vt.type}"`], nodes: 1 };
         if (!c.vt.keys.includes(n.key ?? ''))
-            return { errors: [`${path}.key: "${n.key}" is not a declared key of "${n.map}"${didYouMean(n.key ?? '', c.vt.keys)} (keys: ${c.vt.keys.join(', ')})`], nodes: 1 };
+            return { errors: [`${path}.key: "${n.key}" is not a declared key of ${lvalueLabel(n.map ?? '')}${didYouMean(n.key ?? '', c.vt.keys)} (keys: ${c.vt.keys.join(', ')})`], nodes: 1 };
         return { errors: [], nodes: 1, type: 'number' };
     }
-    const c = resolveCollectionVar(`${path}.list`, n.list ?? '', bound, roomVars, playerVars);
+    // §5 (P3 ext) listLength / listAt — `list` is any list lvalue (room/self path OR {ref,var}).
+    const c = resolveCollectionLvalue(`${path}.list`, n.list ?? '', bound, roomVars, playerVars, zoneIds, ec);
     if (c.errors.length)
         return { errors: c.errors, nodes: 1 };
     if (c.vt.type !== 'list')
-        return { errors: [`${path}: "${n.op}" needs a list var, but "${n.list}" is "${c.vt.type}"`], nodes: 1 };
+        return { errors: [`${path}: "${n.op}" needs a list var, but ${lvalueLabel(n.list ?? '')} is "${c.vt.type}"`], nodes: 1 };
     if (n.op === 'listLength')
         return { errors: [], nodes: 1, type: 'number' };
-    // listAt — the index is a number expr; the value type is the list's element type. Out-of-range → typed zero at runtime.
+    // listAt — the index is a number expr. A SCALAR list → the element type (no `field`); a RECORD list → the named
+    // `field`'s scalar type (`field` required). A ref-list element-as-Ref is a deferred follow-up.
     const r = validateExpr(`${path}.index`, n.index, bound, roomVars, playerVars, zoneIds, ec, depth + 1);
     const e = [...r.errors];
     if (r.type !== undefined && r.type !== 'number')
         e.push(`${path}.index: "listAt" needs a number index, got "${r.type}"`);
-    return { errors: e, nodes: 1 + r.nodes, type: c.vt.of };
+    const of = c.vt.of;
+    if (typeof of === 'string') {
+        if (n.field !== undefined)
+            e.push(`${path}: "listAt" on a scalar list takes no "field"`);
+        return { errors: e, nodes: 1 + r.nodes, type: of };
+    }
+    if (of.type === 'record') {
+        if (n.field === undefined) {
+            e.push(`${path}: "listAt" on a record list needs a "field" to read (fields: ${Object.keys(of.fields).join(', ')})`);
+            return { errors: e, nodes: 1 + r.nodes };
+        }
+        const ft = of.fields[n.field];
+        if (!ft) {
+            e.push(`${path}.field: unknown record field "${n.field}"${didYouMean(n.field, Object.keys(of.fields))} (fields: ${Object.keys(of.fields).join(', ')})`);
+            return { errors: e, nodes: 1 + r.nodes };
+        }
+        return { errors: e, nodes: 1 + r.nodes, type: ft.type };
+    }
+    e.push(`${path}: "listAt" can't read a ref list element as a scalar`);
+    return { errors: e, nodes: 1 + r.nodes };
 }
 // Resolve a ref-addressed read `{ref:<Ref>, var:"<name>"}` (§7.1) — read a member's var. The ref is any Ref
 // (a bound name, a ref-var deref, or a ref-returning op — validated by resolveRefSlot); the referenced member
 // is a player, so `var` resolves against playerVars or a player built-in (e.g. `position`).
 function resolveRefRead(path, ref, name, bound, roomVars, playerVars, zoneIds, ec) {
+    // §5 (P3 ext) a {ref,var} whose ref is a bound RECORD element reads the record's FIELD (not a cross-member deref);
+    // a scalar element has no fields (read it via {var:as}). A ref element falls through to the member-ref path below.
+    if (typeof ref === 'string' && bound.has(ref)) {
+        const k = ec.boundKinds?.[ref];
+        if (k?.type === 'listRecord') {
+            const ft = k.fields[name];
+            if (!ft)
+                return { errors: [`${path}.var: unknown record field "${name}"${didYouMean(name, Object.keys(k.fields))} (fields: ${Object.keys(k.fields).join(', ')})`] };
+            return { errors: [], type: ft.type };
+        }
+        if (k?.type === 'listScalar')
+            return { errors: [`${path}: "${ref}" is a scalar list element — read it via {var:"${ref}"}, not {ref,var}`] };
+    }
     const r = resolveRefSlot(`${path}.ref`, ref, bound, roomVars, playerVars, zoneIds, ec);
     if (r.errors.length)
         return { errors: r.errors };
-    if (name in PLAYER_BUILTIN_TYPES)
-        return { errors: [], type: PLAYER_BUILTIN_TYPES[name] }; // position/connected — member built-ins
+    if (playerBuiltin(name, r.kind?.type === 'entity'))
+        return { errors: [], type: PLAYER_BUILTIN_TYPES[name] }; // position (universal) + connected/active (player-only — an entity's declared var wins)
     // §9 (4.5, row 16) if the ref resolves to a known ENTITY kind, resolve `var` against THAT kind's decls (a
     // wrong-kind var now errors); a player ref / untracked kind falls back to player vars then the entity-var union.
     if (r.kind?.type === 'entity') {
@@ -2020,6 +2611,11 @@ function ofToKind(of) {
         return { type: 'entity', kind: of.slice('entity:'.length) };
     return undefined;
 }
+// The entity sub-kind of a binding, or undefined (a player / a non-member list-element binding). Narrows the
+// widened FwBinding union at the sites that read `.kind` (only the entity variant carries one).
+function bindingKind(b) {
+    return b.type === 'entity' ? b.kind : undefined;
+}
 // §9 (4.5) the static member kind a `{var:"scope.name"}` ref-var deref resolves to — the declared ref var's `of`,
 // looked up against the right scope (room vars; self vars per self's kind; an action ref arg). undefined = untracked.
 function refVarKind(dotted, roomVars, playerVars, ec) {
@@ -2043,7 +2639,14 @@ function resolveRefSlot(path, value, bound, roomVars, playerVars, zoneIds, ec) {
     if (typeof value === 'string') {
         if (!bound.has(value))
             return { errors: [`${path}: "${value}" is not a bound ref (${[...bound].join(', ') || 'none bound here'})`] };
-        return { errors: [], kind: ec.boundKinds?.[value] }; // the bound name's static member kind (if the event tracks it)
+        const k = ec.boundKinds?.[value]; // the bound name's static member kind (if the event/loop tracks it)
+        // §5 (P3 ext) a SCALAR / RECORD list element is NOT a member ref. A record field read ({ref:as,var:field}) is
+        // resolved in resolveRefRead before reaching here, so anything landing here is a misuse in a plain ref slot.
+        if (k?.type === 'listScalar')
+            return { errors: [`${path}: "${value}" is a scalar list element, not a member ref — read its value via {var:"${value}"}`] };
+        if (k?.type === 'listRecord')
+            return { errors: [`${path}: "${value}" is a record list element, not a member ref — read a field via {ref:"${value}",var:"<field>"} or write via {do:"setField",as:"${value}",…}`] };
+        return { errors: [], kind: k }; // a ref element resolves to its member kind (player/entity) — flows like any bound ref
     }
     if (typeof value !== 'object' || value === null) {
         return { errors: [`${path}: expected a ref (a bound name, a ref var, or a ref-returning op), got ${value === null ? 'null' : typeof value}`] };
@@ -2074,6 +2677,51 @@ function resolveRefSlot(path, value, bound, roomVars, playerVars, zoneIds, ec) {
         // A kinded nearestEntity resolves to that kind (per-kind reads); kindless = any entity (kind untracked).
         return { errors: e, kind: value.kind !== undefined ? { type: 'entity', kind: value.kind } : undefined };
     }
+    if (value.op === 'controllerOf') {
+        // §9 (P3 Ownership/A3) the player controlling `entity` — a player ref ('' = server/unowned). O(1) field read.
+        const r = resolveRefSlot(`${path}.entity`, value.entity, bound, roomVars, playerVars, zoneIds, ec);
+        return { errors: r.errors, kind: { type: 'player' } };
+    }
+    if (value.op === 'leastLoadedPlayer') {
+        // §9 (P3 Ownership/B8) the least-busy connected player (optional where/as filter, validated like aggregate's
+        // over the player domain). A reduction (O(players)) → forbidden inside forEach by refHasReduction.
+        const e = [];
+        if (value.where !== undefined || value.as !== undefined) {
+            if (value.as === undefined)
+                e.push(`${path}: leastLoadedPlayer "where" requires "as" (a name for each candidate player)`);
+            else if (RESERVED_REF_NAMES.has(value.as))
+                e.push(`${path}.as: "${value.as}" is a reserved name`);
+            else if (value.where === undefined)
+                e.push(`${path}: leastLoadedPlayer "as" requires a "where" filter`);
+            else {
+                const inner = new Set([...bound, value.as]);
+                const innerEc = { ...ec, boundKinds: { ...ec.boundKinds, [value.as]: { type: 'player' } } };
+                e.push(...validateExpr(`${path}.where`, value.where, inner, roomVars, playerVars, zoneIds, innerEc, 1).errors);
+                if (exprHasReduction(value.where))
+                    e.push(`${path}.where: aggregate/nearest* are forbidden inside a leastLoadedPlayer "where"`);
+            }
+        }
+        return { errors: e, kind: { type: 'player' } };
+    }
+    if (value.op === 'listAt') {
+        // §5 (P3-B2 + P3 ext) a `list of ref` element AS a Ref (the turn-order current actor). The list is any list
+        // lvalue (room/self path OR {ref,var}); its element must be a ref; the index a number. The resolved member kind is
+        // the ref element's `of`. O(1) — not a reduction.
+        const c = resolveCollectionLvalue(`${path}.list`, value.list, bound, roomVars, playerVars, zoneIds, ec);
+        if (c.errors.length)
+            return { errors: c.errors };
+        const vt = c.vt;
+        const elem = vt.type === 'list' ? vt.of : undefined;
+        if (vt.type !== 'list' || typeof elem !== 'object' || elem.type !== 'ref') {
+            const what = vt.type === 'list' ? `a list of ${typeof elem === 'string' ? elem : elem.type}` : `a "${vt.type}"`;
+            return { errors: [`${path}: listAt is a Ref only over a list of refs (${lvalueLabel(value.list)} is ${what})`] };
+        }
+        const r = validateExpr(`${path}.index`, value.index, bound, roomVars, playerVars, zoneIds, ec, 1);
+        const errs = [...r.errors];
+        if (r.type !== undefined && r.type !== 'number')
+            errs.push(`${path}.index: listAt needs a number index, got "${r.type}"`);
+        return { errors: errs, kind: ofToKind(elem.of) };
+    }
     // aggregate argmax|argmin — the reduced scope's member kind (players → player; entities:<kind> or a zone
     // tracking 'entity:<kind>' → that entity).
     const e = validateAggregate(path, value, bound, roomVars, playerVars, zoneIds, ec);
@@ -2090,7 +2738,7 @@ function resolveLvalue(path, lvalue, bound, roomVars, playerVars, zoneIds, ec) {
         const r = resolveRefSlot(`${path}.ref`, ref, bound, roomVars, playerVars, zoneIds, ec);
         if (r.errors.length)
             return { errors: r.errors };
-        if (name in PLAYER_BUILTIN_TYPES)
+        if (playerBuiltin(name, r.kind?.type === 'entity'))
             return { errors: [`${path}: can't write the built-in "${name}" — use teleport/respawn`] };
         // §9 (4.5, row 16) write-through to an ENTITY var resolves against the ref's specific kind when known.
         if (r.kind?.type === 'entity') {
@@ -2118,7 +2766,7 @@ function resolveLvalue(path, lvalue, bound, roomVars, playerVars, zoneIds, ec) {
         return { errors: [`${path}: "${lvalue}" must be "room.<var>" or "self.<var>"`] };
     if (scope === 'self' && !bound.has('self'))
         return { errors: [`${path}: "self.${name}" — this rule's event binds no member (no "self" here)`] };
-    if (scope === 'self' && name in PLAYER_BUILTIN_TYPES)
+    if (scope === 'self' && playerBuiltin(name, ec.boundKinds?.self?.type === 'entity'))
         return { errors: [`${path}: can't write the built-in "self.${name}" — use teleport/respawn`] };
     if (scope === 'room' && name in ROOM_BUILTIN_TYPES)
         return { errors: [`${path}: can't write the built-in "room.${name}" — use transitionTo`] };
@@ -2189,6 +2837,14 @@ function checkVarDefault(path, vt) {
             e.push(`${path}: list maxLen must be a positive integer, got ${vt.maxLen}`);
         else if (vt.maxLen > exports.MULTIPLAYER_CAPS.listMaxLen)
             e.push(`${path}: list maxLen ${vt.maxLen} exceeds the ceiling of ${exports.MULTIPLAYER_CAPS.listMaxLen}`);
+        // §5 (P3 Collections) a record element: cap its field count + validate each flat scalar field (no nesting).
+        if (typeof vt.of === 'object' && vt.of.type === 'record') {
+            const names = Object.keys(vt.of.fields);
+            if (names.length > exports.MULTIPLAYER_CAPS.recordFields)
+                e.push(`${path}: a record element declares ${names.length} fields — the cap is ${exports.MULTIPLAYER_CAPS.recordFields}`);
+            for (const fn of names)
+                e.push(...checkRecordField(`${path}.of.fields.${fn}`, vt.of.fields[fn]));
+        }
     }
     else if (vt.type === 'counterMap') {
         // §5 (4.5.13) a counterMap starts with every declared key at 0; keys must be non-empty, unique, within the cap.
@@ -2201,6 +2857,82 @@ function checkVarDefault(path, vt) {
     }
     return e;
 }
+// §5 (P3 Collections) cross-field check a record element's flat scalar field (the part JSON Schema can't express:
+// default-vs-bounds, integer-ness, enum membership, the shared maxLen/enum ceilings). Mirrors checkVarDefault but
+// the field default is OPTIONAL — only validate it when present.
+function checkRecordField(path, f) {
+    const e = [];
+    if (f.type === 'number') {
+        if (f.min !== undefined && f.max !== undefined && f.min > f.max)
+            e.push(`${path}: min ${f.min} exceeds max ${f.max}`);
+        if (f.default !== undefined) {
+            if (f.integer && !Number.isInteger(f.default))
+                e.push(`${path}: default ${f.default} must be an integer`);
+            if (f.min !== undefined && f.default < f.min)
+                e.push(`${path}: default ${f.default} is below min ${f.min}`);
+            if (f.max !== undefined && f.default > f.max)
+                e.push(`${path}: default ${f.default} is above max ${f.max}`);
+        }
+    }
+    else if (f.type === 'string') {
+        if (f.maxLen !== undefined && f.maxLen > exports.MULTIPLAYER_CAPS.stringMaxLen)
+            e.push(`${path}: maxLen ${f.maxLen} exceeds the ceiling of ${exports.MULTIPLAYER_CAPS.stringMaxLen}`);
+        if (f.enum && f.enum.length > exports.MULTIPLAYER_CAPS.enumValues)
+            e.push(`${path}: enum has ${f.enum.length} values — the cap is ${exports.MULTIPLAYER_CAPS.enumValues}`);
+        if (f.default !== undefined) {
+            if (f.maxLen !== undefined && f.default.length > f.maxLen)
+                e.push(`${path}: default "${f.default}" exceeds maxLen ${f.maxLen}`);
+            if (f.enum && !f.enum.includes(f.default))
+                e.push(`${path}: default "${f.default}" is not one of the declared enum values [${f.enum.join(', ')}]`);
+        }
+    }
+    return e;
+}
+// §5 (P3 Collections) validate a value written into a list whose element type is `elem`: a scalar Expr of the
+// matching type, a ref (a Ref of the matching kind), or a record literal { field: Expr|Ref } (each provided field
+// type-matches its declared field; an unknown field errors; an omitted field takes its default/zero at runtime).
+// Reused by append (C1) and the record-element mutators (C3/C4).
+function validateListElementValue(path, value, elem, bound, roomVars, playerVars, zoneIds, ec) {
+    if (typeof elem === 'string') {
+        const r = validateExpr(path, value, bound, roomVars, playerVars, zoneIds, ec, 1);
+        const e = [...r.errors];
+        if (r.type !== undefined && r.type !== elem)
+            e.push(`${path}: a "${r.type}" can't go into a list of "${elem}"`);
+        return e;
+    }
+    if (elem.type === 'ref') {
+        const r = resolveRefSlot(path, value, bound, roomVars, playerVars, zoneIds, ec);
+        const e = [...r.errors];
+        const want = ofToKind(elem.of);
+        if (r.kind && want && (r.kind.type !== want.type || bindingKind(r.kind) !== bindingKind(want))) {
+            const lbl = (k) => (k.type === 'player' ? 'player' : `entity:${bindingKind(k)}`);
+            e.push(`${path}: a "${lbl(r.kind)}" ref can't go into a list of "${lbl(want)}" refs`);
+        }
+        return e;
+    }
+    // record element — the value is a record literal (a plain object of field → Expr|Ref).
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return [`${path}: a record list needs a record literal { field: value, ... }`];
+    }
+    const e = [];
+    for (const [fn, fv] of Object.entries(value)) {
+        const ft = elem.fields[fn];
+        if (!ft) {
+            e.push(`${path}.${fn}: unknown record field "${fn}"${didYouMean(fn, Object.keys(elem.fields))} (fields: ${Object.keys(elem.fields).join(', ')})`);
+            continue;
+        }
+        if (ft.type === 'ref') {
+            e.push(...resolveRefSlot(`${path}.${fn}`, fv, bound, roomVars, playerVars, zoneIds, ec).errors);
+        }
+        else {
+            const r = validateExpr(`${path}.${fn}`, fv, bound, roomVars, playerVars, zoneIds, ec, 1);
+            e.push(...r.errors);
+            if (r.type !== undefined && r.type !== ft.type)
+                e.push(`${path}.${fn}: a "${r.type}" value doesn't match the declared "${ft.type}"`);
+        }
+    }
+    return e;
+}
 // The valid declared-var type discriminants — the single source for the did-you-mean below + the authoring
 // vocabulary the schema's varDecls oneOf enumerates. (Bounds/enum/of live on each variant; this is the tag.)
 exports.VAR_TYPES = ['number', 'string', 'boolean', 'vec3', 'ref', 'list', 'counterMap'];