@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/script-side-grandfather.ts

@@ -0,0 +1,62 @@
+// SERVER-PARITY SS7's grandfather list (meta docs/plans/SERVER-PARITY-PLAN.md): the live products admitted with a
+// warning in place of a script side refusal (`script-sides.ts`). SS11 empties it.
+
+/** The product a validator is admitting: its slug and declared source hash. Both validators check that hash against
+ *  the admitted sections before they return, so a forged index cannot borrow a grandfathered product's. */
+interface ScriptSideProduct {
+  readonly slug: string
+  readonly sourceHash: string
+}
+
+/** One live product admitted with a warning in place of a script side refusal. */
+interface GrandfatheredScript extends ScriptSideProduct {
+  /** The script id the refusal names. */
+  readonly script: string
+  /** Why it still passes, and the row that removes it. */
+  readonly why: string
+}
+
+/**
+ * GRANDFATHERED (SERVER-PARITY SS7, 2026-11-12; removed by SS11 in meta `docs/plans/SERVER-PARITY-PLAN.md`): live
+ * products that still break a script side rule, admitted with a warning so engine can take this format. Each entry is
+ * one exact product (slug and source hash) and one script id; any other product, a new upload of the same shard
+ * included, is still refused. Drop the entry's line when SS11 re-uploads the shard without the pattern.
+ */
+// prettier-ignore
+const SCRIPT_SIDE_GRANDFATHER: readonly GrandfatheredScript[] = [
+  { slug: 'pine-hollow', sourceHash: 'a255585456ff289330fc0a8f7b417b67dca608ebeebcec59b676a7b361f79c15', script: 'pine.life', why: 'the live product; SS5 (engine 2f5e6965) runs its hollow-log secret on the server too, and SS11 moves its page half to a view row' },
+]
+
+/** The grandfather entry that covers one refusal line of this product, or `undefined`. */
+function grandfatherFor(
+  line: string,
+  product: ScriptSideProduct,
+): GrandfatheredScript | undefined {
+  return SCRIPT_SIDE_GRANDFATHER.find(
+    (entry: GrandfatheredScript): boolean =>
+      entry.slug === product.slug &&
+      entry.sourceHash === product.sourceHash &&
+      line.startsWith(`sim script ${entry.script} runs in page-only feature `),
+  )
+}
+
+/** A product's side refusal lines, split: lines a grandfather entry covers become warnings, the rest stay refusals. */
+function splitGrandfathered(
+  lines: readonly string[],
+  product: ScriptSideProduct,
+): { refused: string[]; warnings: string[] } {
+  const refused: string[] = []
+  const warnings: string[] = []
+  for (const line of lines) {
+    const entry = grandfatherFor(line, product)
+    if (entry === undefined) {
+      refused.push(line)
+    } else {
+      warnings.push(`grandfathered: ${line} (${product.slug}: ${entry.why})`)
+    }
+  }
+  return { refused, warnings }
+}
+
+export { SCRIPT_SIDE_GRANDFATHER, splitGrandfathered }
+export type { GrandfatheredScript, ScriptSideProduct }

package/src/format/script-sides.ts

@@ -0,0 +1,289 @@
+// SERVER-PARITY SS7 (meta docs/plans/SERVER-PARITY-PLAN.md): a script's declared side must match where it is hosted. A v1
+// row says `sim` or `view` (`decisionScripts.ts`), and a `view` row writes no gameplay (a row rule there). Against the
+// whole product: a `sim` row that a page-only feature runs has no server half there, and a `view` row in `sim/scripts`
+// would run on the server's decision host. v1 sides and v2 lanes map onto SS2's side words (`feature-sides.ts`).
+// oxlint-disable typescript/prefer-readonly-parameter-types -- OutputIndex and the byte arrays are only read
+import { CLIENT_FEATURE_SIDES } from './feature-sides.ts'
+import { parseNamedJson } from './json.ts'
+import { splitGrandfathered } from './script-side-grandfather.ts'
+
+import type { FeatureSide } from './feature-sides.ts'
+import type { OutputIndex } from './outputIndex.ts'
+import type { ScriptSideProduct } from './script-side-grandfather.ts'
+import type { ScriptV1CommandName } from './scriptAbiV1.ts'
+import type { V2Lane } from './scriptFuelV2.ts'
+
+/** A v1 row's declared side. */
+const SCRIPT_V1_SIDES = ['sim', 'view'] as const
+
+type ScriptV1Side = (typeof SCRIPT_V1_SIDES)[number]
+
+/** Each v1 side in SS2's words: a `sim` row's gameplay is the server's, and the page may also project it (return
+ *  programs run on both sides); a `view` row is page only. */
+const SCRIPT_V1_FEATURE_SIDES: Readonly<Record<ScriptV1Side, FeatureSide>> =
+  Object.freeze({ sim: 'both', view: 'view' })
+
+/** Each v2 lane in SS2's words: `sim` runs only in the server's owned batch; `project` is a stateless return program
+ *  both sides run, the server owning its gameplay; `view` runs on the page only. */
+const SCRIPT_V2_LANE_SIDES: Readonly<Record<V2Lane, FeatureSide>> =
+  Object.freeze({ project: 'both', sim: 'server', view: 'view' })
+
+/** The only commands a `view` row may emit: a timer, a cue and a projection channel. Every other v1 command writes
+ *  gameplay: moves, strikes, fields, spawns, flags, signals, grants, rewards, impulses, encounters, weather, bodies. */
+const SCRIPT_V1_VIEW_COMMANDS: ReadonlySet<ScriptV1CommandName> = new Set([
+  'channel',
+  'cue',
+  'timer',
+])
+
+const VIEW_WRITES_GAMEPLAY =
+  'view script writes no gameplay (only timer, cue and channel commands)'
+
+/** Whether a `view` row may emit this command. */
+function isViewCommand(command: ScriptV1CommandName): boolean {
+  return SCRIPT_V1_VIEW_COMMANDS.has(command)
+}
+
+/**
+ * The `view` feature kinds whose named file (`file`) carries a return program that only the page runs, with the path
+ * of the script row inside that file. A `sim` row run here is page-only gameplay: Pine's `pine.life` sets
+ * `secret:log` from engine's client `pageLife` alone (SERVER-PARITY inventory row 3). SS5 runs it on the server too,
+ * and the live product passes on `SCRIPT_SIDE_GRANDFATHER` until SS11.
+ *
+ * `practice.course` has the same shape (a `sim` row only the page runs) but is cosmetic; it joins this table once
+ * Nalati and Nine Dragon declare their `practice.course` rows `view`.
+ */
+const PAGE_ONLY_PROGRAM_HOSTS: ReadonlyMap<string, readonly string[]> = new Map(
+  [['page.life', ['program', 'script']]],
+)
+
+/** Reads one named JSON file of the product by its name: `undefined` when it is absent or not JSON. */
+type NamedJson = (name: string) => unknown
+
+/** The product files a validator reads before its inventory pass, and its hash check (`whole` as in
+ *  `ProductValidationPorts.verify`). */
+interface UncheckedFiles {
+  readonly read: (path: string, bytes: number) => Uint8Array | undefined
+  readonly paths: () => Iterable<string>
+  readonly verify: (
+    bytes: Uint8Array,
+    expected: string,
+    whole: boolean,
+  ) => boolean
+}
+
+/** An own property of a plain object, or `undefined`. */
+function propOf(value: unknown, key: string): unknown {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    Array.isArray(value) ||
+    !Object.hasOwn(value, key)
+  ) {
+    return undefined
+  }
+  const found: unknown = Reflect.get(value, key)
+  return found
+}
+
+/** A string property, or `undefined`. */
+function textOf(value: unknown, key: string): string | undefined {
+  const text = propOf(value, key)
+  return typeof text === 'string' ? text : undefined
+}
+
+/** An array, or an empty list. */
+function rowsOf(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+/** The value at `keys` under `value`, or `undefined`. */
+function pathOf(value: unknown, keys: readonly string[]): unknown {
+  let found = value
+  for (const key of keys) {
+    found = propOf(found, key)
+  }
+  return found
+}
+
+/** Whether two JSON values are equal by value, whatever their key order. */
+function sameJson(left: unknown, right: unknown): boolean {
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((item: unknown, at: number): boolean =>
+        sameJson(item, right[at]),
+      )
+    )
+  }
+  if (typeof left !== 'object' || left === null) {
+    return left === right
+  }
+  const keys = Object.keys(left)
+  return (
+    typeof right === 'object' &&
+    right !== null &&
+    Object.keys(right).length === keys.length &&
+    keys.every((key: string): boolean =>
+      sameJson(propOf(left, key), propOf(right, key)),
+    )
+  )
+}
+
+/** A page-only host feature's kind, file and the script row inside that file, or `undefined`. */
+function hostedScript(
+  feature: unknown,
+  named: NamedJson,
+): { kind: string; file: string; script: unknown } | undefined {
+  const kind = textOf(feature, 'kind') ?? ''
+  const host = PAGE_ONLY_PROGRAM_HOSTS.get(kind)
+  const file = textOf(feature, 'file')
+  const script =
+    host === undefined || file === undefined
+      ? undefined
+      : pathOf(named(file), host)
+  return script === undefined || file === undefined
+    ? undefined
+    : { file, kind, script }
+}
+
+/** The script a page-only host feature runs, as refusal lines: a copy that is not its admitted `actors/return-scripts`
+ *  row (so its side and rules are the admitted row's), or a `sim` row, which no server host runs there. */
+function pageOnlyRefusal(
+  feature: unknown,
+  named: NamedJson,
+  returns: readonly unknown[],
+): string[] {
+  const hosted = hostedScript(feature, named)
+  if (hosted === undefined) {
+    return []
+  }
+  const { file, kind, script } = hosted
+  const id = textOf(script, 'id') ?? '(no id)'
+  const admitted = returns.find(
+    (row: unknown): boolean => textOf(row, 'id') === id,
+  )
+  if (admitted === undefined || !sameJson(admitted, script)) {
+    return [
+      `${kind} program ${id} (${file}) is not its actors/return-scripts row`,
+    ]
+  }
+  return textOf(admitted, 'side') === 'sim'
+    ? [
+        `sim script ${id} runs in page-only feature ${kind} (${file}), which no server host runs`,
+      ]
+    : []
+}
+
+/** A `view` row in `sim/scripts`, as a refusal line, or nothing. */
+function serverViewRefusal(row: unknown): string[] {
+  if (textOf(row, 'side') !== 'view') {
+    return []
+  }
+  const id = textOf(row, 'id') ?? '(no id)'
+  return [
+    `view script ${id} is in sim/scripts, which only the server's decision host runs`,
+  ]
+}
+
+/** Every side refusal in a product: its parsed sections, and a reader of its named JSON files. */
+function scriptSideRefusals(
+  sections: ReadonlyMap<string, unknown>,
+  named: NamedJson,
+): string[] {
+  const features = rowsOf(propOf(sections.get('client/plan'), 'features'))
+  const returns = rowsOf(sections.get('actors/return-scripts'))
+  const hosted = features.flatMap((feature: unknown): string[] =>
+    pageOnlyRefusal(feature, named, returns),
+  )
+  const decisions = rowsOf(sections.get('sim/scripts')).flatMap(
+    (row: unknown): string[] => serverViewRefusal(row),
+  )
+  return [...new Set([...hosted, ...decisions])]
+}
+
+/** A reader of the product's named JSON files that never throws and reads only bytes that match the index: a missing,
+ *  resized, changed or malformed file is `undefined` here, and the inventory or its schema refuses it later. */
+function namedJsonReader(index: OutputIndex, files: UncheckedFiles): NamedJson {
+  const present = new Set(files.paths())
+  return (name: string): unknown => {
+    const file = index.files.find(
+      (entry: OutputIndex['files'][number]): boolean =>
+        entry.kind === 'json' && entry.name === name,
+    )
+    if (file === undefined || !present.has(file.path)) {
+      return undefined
+    }
+    try {
+      const bytes = files.read(file.path, file.compressed)
+      return bytes?.length === file.compressed &&
+        files.verify(bytes, file.hash, false)
+        ? parseNamedJson(bytes)
+        : undefined
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/** A product's side refusals, split: lines a grandfather entry covers become warnings, the rest stay refusals. */
+function scriptSideVerdict(
+  sections: ReadonlyMap<string, unknown>,
+  named: NamedJson,
+  product: ScriptSideProduct,
+): { refused: string[]; warnings: string[] } {
+  return splitGrandfathered(scriptSideRefusals(sections, named), product)
+}
+
+/** Refuse a product whose scripts run on the wrong side, and return its grandfathered lines as warnings. Both
+ *  validators call it once their sections are read. */
+function assertScriptSides(
+  sections: ReadonlyMap<string, unknown>,
+  index: OutputIndex,
+  files: UncheckedFiles,
+): string[] {
+  const { refused, warnings } = scriptSideVerdict(
+    sections,
+    namedJsonReader(index, files),
+    { slug: index.identity.slug, sourceHash: index.build.sourceHash },
+  )
+  const [first, ...rest] = refused
+  if (first !== undefined) {
+    throw new Error(`Script side refused: ${[first, ...rest].join('; ')}`)
+  }
+  return warnings
+}
+
+/** The side SS2's table gives each page-only host (a test pins them all to `view`). */
+function pageOnlyHostSides(): Map<string, FeatureSide | undefined> {
+  const sides = new Map<string, FeatureSide>(
+    Object.entries(CLIENT_FEATURE_SIDES).map(
+      ([kind, entry]): [string, FeatureSide] => [kind, entry.side],
+    ),
+  )
+  return new Map(
+    [...PAGE_ONLY_PROGRAM_HOSTS.keys()].map(
+      (kind: string): [string, FeatureSide | undefined] => [
+        kind,
+        sides.get(kind),
+      ],
+    ),
+  )
+}
+
+export {
+  PAGE_ONLY_PROGRAM_HOSTS,
+  SCRIPT_V1_FEATURE_SIDES,
+  SCRIPT_V1_SIDES,
+  SCRIPT_V1_VIEW_COMMANDS,
+  SCRIPT_V2_LANE_SIDES,
+  VIEW_WRITES_GAMEPLAY,
+  assertScriptSides,
+  isViewCommand,
+  pageOnlyHostSides,
+  scriptSideRefusals,
+  scriptSideVerdict,
+}
+export type { NamedJson, ScriptV1Side, UncheckedFiles }

package/src/format/scriptAbi.ts

@@ -0,0 +1,14 @@
+/** Core numeric script ABI v0. Compiler/instrumenter revisions are part of this contract. */
+export const SCRIPT_ABI: Readonly<{ version: 0; assemblyscript: "0.28.20"; binaryen: "132.0.0"; maxBytes: 262144; memoryPages: 64; maxFunctions: 512; maxGlobals: 128; maxLocals: 1024; callDepth: 64; }> = Object.freeze({ version: 0, assemblyscript: '0.28.20', binaryen: '132.0.0', maxBytes: 262144, memoryPages: 64, maxFunctions: 512, maxGlobals: 128, maxLocals: 1024, callDepth: 64 });
+/** Required export signatures; parameter types followed by the numeric result, or zero for void. */
+export const SCRIPT_EXPORTS: Readonly<Record<string, readonly number[]>> = Object.freeze({
+  abi_version: [0x7f], __start: [], init: [0x7f, 0x7f, 0], in_ptr: [0x7f], in_cap: [0x7f], out_ptr: [0x7f], out_cap: [0x7f], out_count: [0x7f], on_tick: [],
+});
+/** Import signatures: parameter types followed by a single result, or zero for void. */
+export const SCRIPT_IMPORTS: Readonly<Record<string, readonly number[]>> = Object.freeze({
+  enter: [0], leave: [0], fuel: [0x7f, 0], abort: [0x7f, 0x7f, 0x7f, 0x7f, 0], query: [0x7f, 0x7f, 0x7f, 0x7f],
+  finite32: [0x7d, 0x7d], finite64: [0x7c, 0x7c],
+});
+
+/** Read-only declared numeric parameters; the host supplies the trusted calling entity to the query adapter. */
+export const SCRIPT_PARAMETER_QUERY = 410;

package/src/format/scriptAbiV1.ts

@@ -0,0 +1,56 @@
+/** ABI-v1 numeric transport. These ids are shared by admission, generated bindings and the decision host. */
+export const SCRIPT_V1_EVENTS: Readonly<{ start: 1; tick: 2; timer: 3; 'zone.enter': 4; 'zone.leave': 5; interact: 6; hit: 7; threshold: 8; death: 9; 'move.done': 10; 'strike.done': 11; flag: 12; signal: 13; 'strike.target': 14; 'player.join': 15; 'player.leave': 16; spawned: 17; stop: 18; field: 30; cue: 31; channel: 32; }> = Object.freeze({
+  start: 1, tick: 2, timer: 3, 'zone.enter': 4, 'zone.leave': 5, interact: 6, hit: 7, threshold: 8,
+  death: 9, 'move.done': 10, 'strike.done': 11, flag: 12, signal: 13, 'strike.target': 14,
+  'player.join': 15, 'player.leave': 16, spawned: 17, stop: 18, field: 30, cue: 31, channel: 32,
+});
+/** Scalar reads; timer and random are answered by the host's own binding state. */
+export const SCRIPT_V1_READS: Readonly<{ x: 1; y: 2; z: 3; yaw: 4; hpShare: 5; alive: 6; field: 7; distance: 8; nearestPlayer: 9; flag: 10; timerLeft: 11; random: 12; actorInZone: 13; playersInZone: 14; moving: 15; strikeState: 16; playerFlag: 17; spawnGroupAlive: 18; bearing: 19; bodyX: 20; bodyY: 21; bodyZ: 22; bodyAlive: 23; bodyYaw: 24; bodyVisible: 25; playerIntent: 26; }> = Object.freeze({
+  x: 1, y: 2, z: 3, yaw: 4, hpShare: 5, alive: 6, field: 7, distance: 8, nearestPlayer: 9,
+  flag: 10, timerLeft: 11, random: 12, actorInZone: 13, playersInZone: 14, moving: 15,
+  strikeState: 16, playerFlag: 17, spawnGroupAlive: 18, bearing: 19,
+  bodyX: 20, bodyY: 21, bodyZ: 22, bodyAlive: 23, bodyYaw: 24, bodyVisible: 25, playerIntent: 26,
+});
+/** Bounded list queries. Ground/navigation keep the existing physics query semantics. */
+export const SCRIPT_V1_LISTS: Readonly<{ actorsInZone: 1; playersWithin: 2; groundHeight: 3; nearestWalkable: 4; path: 5; radial: 6; declaredFloor: 7; }> = Object.freeze({ actorsInZone: 1, playersWithin: 2, groundHeight: 3, nearestWalkable: 4, path: 5, radial: 6, declaredFloor: 7 });
+/** Command ids; view commands occupy a disjoint range and may not run in a simulation binding. */
+export const SCRIPT_V1_COMMANDS: Readonly<{ move: 1; strike: 2; stop: 3; field: 4; spawn: 5; despawn: 6; flag: 7; timer: 8; signal: 9; grant: 10; reward: 11; cue: 12; channel: 13; impulse: 14; encounter: 15; weather: 16; 'body.spawn': 17; 'body.teleport': 18; 'collider.enabled': 19; 'body.place': 20; 'body.visible': 21; 'body.retire': 22; 'view.channel': 100; 'view.clip': 101; 'view.vfx': 102; 'view.sound': 103; 'view.visible': 104; 'view.field': 105; }> = Object.freeze({
+  move: 1, strike: 2, stop: 3, field: 4, spawn: 5, despawn: 6, flag: 7, timer: 8,
+  signal: 9, grant: 10, reward: 11, cue: 12, channel: 13, impulse: 14, encounter: 15, weather: 16,
+  'body.spawn': 17, 'body.teleport': 18, 'collider.enabled': 19,
+  'body.place': 20, 'body.visible': 21, 'body.retire': 22,
+  'view.channel': 100, 'view.clip': 101, 'view.vfx': 102, 'view.sound': 103, 'view.visible': 104, 'view.field': 105,
+});
+export type ScriptV1EventName = keyof typeof SCRIPT_V1_EVENTS;
+export type ScriptV1ReadName = keyof typeof SCRIPT_V1_READS;
+export type ScriptV1ListName = keyof typeof SCRIPT_V1_LISTS;
+export type ScriptV1CommandName = keyof typeof SCRIPT_V1_COMMANDS;
+/** f64 slot counts and fixed-step scheduling, not byte addresses. */
+export const SCRIPT_V1_LAYOUT: Readonly<{ major: 1; slotBytes: 8; header: 8; state: 16; params: 32; events: 16; eventWidth: 6; commands: 32; commandWidth: 5; fixedHz: 60; decisionDivisor: 6; maximumPages: 4; }> = Object.freeze({
+  major: 1, slotBytes: 8, header: 8, state: 16, params: 32, events: 16, eventWidth: 6,
+  commands: 32, commandWidth: 5, fixedHz: 60, decisionDivisor: 6, maximumPages: 4,
+});
+/** Numeric inbox/outbox records, little-endian f64 throughout. */
+export type ScriptV1Event = readonly [kind: number, subject: number, a: number, b: number, c: number, d: number];
+export type ScriptV1Command = readonly [op: number, target: number, a: number, b: number, c: number];
+/** Compute the row-sized IO layout without guessing a generated module's memory address. */
+export function scriptV1Layout(states: number, params: number): { state: number; params: number; inbox: number; outbox: number; bytes: number } {
+  if (!Number.isInteger(states) || states < 0 || states > SCRIPT_V1_LAYOUT.state
+    || !Number.isInteger(params) || params < 0 || params > SCRIPT_V1_LAYOUT.params) throw new Error('Invalid decision IO dimensions');
+  const state = SCRIPT_V1_LAYOUT.header;
+  const parameters = state + states;
+  const inbox = parameters + params;
+  const outbox = inbox + SCRIPT_V1_LAYOUT.events * SCRIPT_V1_LAYOUT.eventWidth;
+  return { state, params: parameters, inbox, outbox, bytes: (outbox + SCRIPT_V1_LAYOUT.commands * SCRIPT_V1_LAYOUT.commandWidth) * SCRIPT_V1_LAYOUT.slotBytes };
+}
+
+/** Required decision entry points: arguments followed by the result, zero for void. */
+export const SCRIPT_V1_EXPORTS: Readonly<Record<string, readonly number[]>> = Object.freeze({
+  ws_abi: [0x7f], ws_init: [0x7f, 0x7f, 0], ws_io: [0x7f], ws_handle: [0x7f],
+});
+/** Only deterministic reads plus the existing compiler guards may enter a decision module. */
+export const SCRIPT_V1_IMPORTS: Readonly<Record<string, readonly number[]>> = Object.freeze({
+  enter: [0], leave: [0], fuel: [0x7f, 0], abort: [0x7f, 0x7f, 0x7f, 0x7f, 0],
+  finite32: [0x7d, 0x7d], finite64: [0x7c, 0x7c],
+  ws_read: [0x7f, 0x7c, 0x7c, 0x7c], ws_list: [0x7f, 0x7c, 0x7c, 0x7f, 0x7f, 0x7f],
+});

package/src/format/scriptActionsV2.ts

@@ -0,0 +1,101 @@
+/** Finite H4 world actions. These are ABI-v2 additions; v0/v1 declarations,
+ * generated bindings and shipped module hashes are unchanged. */
+import { SCRIPT_V1_COMMANDS } from './scriptAbiV1.ts';
+import type { V2Layout } from './scriptWireV2.ts';
+
+export const V2_ACTION_OPS: Readonly<{ impulse: 14; dismount: 23; ignite: 24; trust: 26; ownership: 27; lead: 28; mount: 29; hurt: 30; pose: 31; adopt: 32; bond: 33; release: 34; hide: 35; retire: 36; breaking: 37; notice: 38; playerPose: 39; }> = Object.freeze({ impulse: SCRIPT_V1_COMMANDS.impulse,dismount: 23,ignite: 24,trust:26,ownership:27,lead:28,mount:29,hurt:30,pose:31,adopt:32,bond:33,release:34,hide:35,retire:36,breaking:37,notice:38,playerPose:39 });
+export type V2ActionOperation = typeof V2_ACTION_OPS[keyof typeof V2_ACTION_OPS];
+export type V2ActionTargetKind = 'player' | 'mount' | 'cell-field' | 'taming' | 'taming-herd' | 'taming-actor';
+const operations:ReadonlySet<number>=new Set(Object.values(V2_ACTION_OPS));
+const targetKinds:ReadonlySet<string>=new Set(['player','mount','cell-field','taming','taming-herd','taming-actor']);
+function declaredOperations(input:ReadonlySet<V2ActionOperation>):boolean {
+  // Consume the complete borrowed iterator before testing its private copy.
+  const values=[...input];
+  for(let index=0;index<values.length;index++){const value=values[index];if(value===undefined||!operations.has(value))return false;}
+  return true;
+}
+export interface V2ActionTarget { readonly identity: string; readonly kind: V2ActionTargetKind }
+export interface V2ActionBinding {
+  readonly identity: string; readonly handle: number;
+  readonly targets: ReadonlyMap<number,V2ActionTarget>;
+  readonly operations: ReadonlySet<V2ActionOperation>;
+  readonly maxCommands: number;
+  /** Explicit admitted bounds, in world coordinates and metres per second. */
+  readonly bounds: { readonly coordinate: number; readonly velocity: number };
+}
+interface Target { readonly binding: string; readonly target: string }
+export type V2WorldAction = Target & (
+  { readonly kind: 'dismount'; readonly thrown: boolean }
+  | { readonly kind: 'ignite'; readonly x: number; readonly z: number }
+  | { readonly kind: 'impulse'; readonly x: number; readonly y: number; readonly z: number }
+  | { readonly kind:'taming'; readonly operation:V2ActionOperation; readonly values:readonly [number,number,number,number,number,number] }
+);
+function positive(value: number): boolean { return Number.isInteger(value) && value > 0 && value <= 0x7fffffff; }
+/** Decode and validate the WHOLE ordered bank before borrowing or mutating an
+ * owner. Unknown ops, target kinds, reserved words and over-quota suffixes refuse
+ * the entire bank. This is used after validateV2Frame checks host-owned bytes. */
+export function readV2WorldActions(view: DataView,layout: V2Layout,count: number,bindings: ReadonlyMap<number,V2ActionBinding>,selection?:readonly number[]): readonly V2WorldAction[] {
+  const region = layout.regions[9];
+  if (region === undefined || view.byteLength !== layout.pages*65536 || !Number.isInteger(count) || count < 0 || count > region.capacity || count > 128) throw new Error('Invalid v2 world action bank');
+  let identities:Set<string>|undefined;
+  if (bindings.size > 64) throw new Error('V2 action binding capacity');
+  for (const [handle,binding] of bindings) {
+    if (binding.handle !== handle || !positive(handle) || binding.identity.length === 0 || identities?.has(binding.identity)===true
+      || !positive(binding.maxCommands) || binding.maxCommands > 32 || binding.targets.size > 256
+      || !Number.isFinite(binding.bounds.coordinate) || binding.bounds.coordinate <= 0 || !Number.isFinite(binding.bounds.velocity) || binding.bounds.velocity < 0
+      || !declaredOperations(binding.operations)) throw new Error('Invalid v2 action binding');
+    (identities??=new Set()).add(binding.identity);
+    const targets = new Set<string>();
+    for (const [target,owner] of binding.targets) {
+      if (!positive(target) || owner.identity.length === 0 || targets.has(owner.identity) || !targetKinds.has(owner.kind)) throw new Error('Invalid v2 action target');
+      targets.add(owner.identity);
+    }
+  }
+  const rows: V2WorldAction[] = [];let used:Map<number,number>|undefined;
+  const indices=selection??Array.from({length:count},(_,index)=>index);
+  if(indices.length>count||new Set(indices).size!==indices.length||indices.some(index=>!Number.isInteger(index)||index<0||index>=count))throw new Error('Invalid world action selection');
+  for (const index of indices) {
+    const at = layout.io+region.offset+index*64, handle = view.getUint32(at,true), binding = bindings.get(handle);
+    const action = readV2WorldAction(view,at,binding);
+    if (binding === undefined) throw new Error('Undeclared v2 world action');
+    const n = (used?.get(handle) ?? 0)+1;if (n > binding.maxCommands) throw new Error('V2 world action quota');(used??=new Map()).set(handle,n);
+    rows.push(action);
+  }
+  for(let index=0;index<rows.length;index++)Object.freeze(rows[index]);
+  return Object.freeze(rows);
+}
+
+/** Exact single record decoder for a combined bank. The combined authority
+ * still validates EVERY record, aggregate quotas and all native loans before
+ * any operation runs; this reader never skips unknown operations. */
+export function readV2WorldAction(view: DataView,at: number,binding: V2ActionBinding | undefined): V2WorldAction {
+  if (!Number.isSafeInteger(at) || at < 0 || at%8 !== 0 || at > view.byteLength-64) throw new Error('Invalid v2 world action record');
+  const handle = view.getUint32(at,true),op = view.getUint32(at+4,true),target = view.getUint32(at+8,true);
+    if (binding === undefined || binding.handle !== handle || !positive(handle) || binding.identity.length === 0 || ![...binding.operations].some(allowed => allowed === op) || !positive(binding.maxCommands) || binding.maxCommands > 32
+      || !Number.isFinite(binding.bounds.coordinate) || binding.bounds.coordinate <= 0 || !Number.isFinite(binding.bounds.velocity) || binding.bounds.velocity < 0
+      || view.getUint32(at+12,true) !== 0) throw new Error('Undeclared v2 world action');
+    const owner = binding.targets.get(target);
+    if (!positive(target) || owner === undefined || owner.identity.length === 0) throw new Error('Unowned v2 world action target');
+    const values = Array.from({ length: 6 },(_,i) => view.getFloat64(at+16+i*8,true));
+    if (!values.every(Number.isFinite)) throw new Error('Non-finite v2 world action');
+    const [x,y,z] = values;if (x === undefined || y === undefined || z === undefined) throw new Error('Missing v2 world action values');
+    const zero = (from: number): boolean => values.slice(from).every(value => Object.is(value,0));
+    if (op === V2_ACTION_OPS.dismount && (owner.kind === 'mount'||owner.kind==='taming') && (x === 0 || x === 1) && zero(1)) return Object.freeze({ binding: binding.identity,target: owner.identity,kind: 'dismount',thrown: x === 1 });
+    if (op === V2_ACTION_OPS.ignite && owner.kind === 'cell-field' && Math.abs(x) <= binding.bounds.coordinate && Math.abs(y) <= binding.bounds.coordinate && zero(2)) return Object.freeze({ binding: binding.identity,target: owner.identity,kind: 'ignite',x,z: y });
+    if (op === V2_ACTION_OPS.impulse && owner.kind === 'player' && Math.hypot(x,y,z) <= binding.bounds.velocity && zero(3)) return Object.freeze({ binding: binding.identity,target: owner.identity,kind: 'impulse',x,y,z });
+    if(validV2TamingAction(op,owner.kind,values,binding.bounds.coordinate))return Object.freeze({binding:binding.identity,target:owner.identity,kind:'taming',operation:op,values:Object.freeze([values[0]??0,values[1]??0,values[2]??0,values[3]??0,values[4]??0,values[5]??0] as const)});
+    throw new Error('Invalid v2 world action operands');
+}
+
+/** Exact taming operands. Finite deltas and yaw stay unbounded, preserving
+ * long-frame native laws; unused words must be positive zero. */
+export function validV2TamingAction(op:number,kind:string,values:readonly number[],coordinate:number):op is V2ActionOperation {
+  if(values.length!==6||!values.every(Number.isFinite))return false;
+  const [a=0,b=0,c=0,d=0,e=0,f=0]=values,bit=(n:number):boolean=>n===0||n===1,zero=(n:number):boolean=>values.slice(n).every(x=>Object.is(x,0));
+  if(kind==='taming-herd')return op===26&&bit(b)&&c>=0&&c<=100&&(b===1||Object.is(c,0))&&zero(3)
+    ||op===27&&bit(a)&&zero(1)||op===28&&Math.abs(a)<=coordinate&&Math.abs(b)<=coordinate&&zero(2)||op===34&&zero(0);
+  if(kind==='taming-actor')return (op===29||op===33)&&bit(a)&&zero(1)||(op===35||op===36)&&zero(0)
+    ||op===31&&a>=0&&a<=1&&(b===-1||b===1)&&c>=-1&&c<=1&&bit(d)&&bit(e)&&Number.isFinite(f);
+  return kind==='taming'&&(op===23&&bit(a)&&zero(1)||op===30&&a>=0&&zero(1)||op===32&&Math.abs(a)<=coordinate&&Math.abs(b)<=coordinate&&bit(d)&&zero(4)
+    ||op===37&&bit(a)&&zero(1)||op===38&&(a===0||a===1||a===2)&&zero(1)||op===39&&Math.abs(b)<=Math.PI/2&&zero(2));
+}