@vgai/engine 0.5.21 → 0.5.23

package/src/input/schema.ts

@@ -37,62 +37,74 @@
 import { z } from 'zod';
 import type { InputAction, InputBinding, InputMapFile } from './input-types';
 
-const KeyBindingSchema = z.object({
-  type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
-  code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
-});
+const KeyBindingSchema = z
+  .object({
+    type: z.literal('key').describe('Binding kind: a keyboard key (KeyboardEvent.code)'),
+    code: z.string().describe('KeyboardEvent.code value, e.g. "KeyW", "Space", "ArrowUp"'),
+  })
+  .strict();
 
-const MouseButtonBindingSchema = z.object({
-  type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
-  button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
-});
+const MouseButtonBindingSchema = z
+  .object({
+    type: z.literal('mouse_button').describe('Binding kind: a mouse button'),
+    button: z.number().describe('MouseEvent.button index (0 = left, 1 = middle, 2 = right)'),
+  })
+  .strict();
 
-const MouseMoveBindingSchema = z.object({
-  type: z
-    .literal('mouse_move')
-    .describe(
-      'Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
-        "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
-        "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
-        'circle-clamped via `deadzone`).',
-    ),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
-        "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
-        'deadzoned).',
-    ),
-});
+const MouseMoveBindingSchema = z
+  .object({
+    type: z
+      .literal('mouse_move')
+      .describe(
+        'Binding kind: raw mouse movement (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+          "'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and " +
+          "can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-" +
+          'circle-clamped via `deadzone`).',
+      ),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType " +
+          "action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never " +
+          'deadzoned).',
+      ),
+  })
+  .strict();
 
-const GamepadButtonBindingSchema = z.object({
-  type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
-  button: z.number().describe('Standard Gamepad API button index'),
-});
+const GamepadButtonBindingSchema = z
+  .object({
+    type: z.literal('gamepad_button').describe('Binding kind: a gamepad face/shoulder button'),
+    button: z.number().describe('Standard Gamepad API button index'),
+  })
+  .strict();
 
-const GamepadAxisBindingSchema = z.object({
-  type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
-  axis: z.number().describe('Standard Gamepad API axis index'),
-  direction: z
-    .enum(['positive', 'negative'])
-    .describe('Which side of the deadzone counts as "pressed"'),
-  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
-});
+const GamepadAxisBindingSchema = z
+  .object({
+    type: z.literal('gamepad_axis').describe('Binding kind: a single thresholded gamepad axis'),
+    axis: z.number().describe('Standard Gamepad API axis index'),
+    direction: z
+      .enum(['positive', 'negative'])
+      .describe('Which side of the deadzone counts as "pressed"'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+  })
+  .strict();
 
-const GamepadAxisPairBindingSchema = z.object({
-  type: z
-    .literal('gamepad_axis_pair')
-    .describe(
-      'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
-        '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
-        "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
-        'circle-clamped the same way a real analog stick is.',
-    ),
-  xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
-  yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
-  deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
-});
+const GamepadAxisPairBindingSchema = z
+  .object({
+    type: z
+      .literal('gamepad_axis_pair')
+      .describe(
+        'Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector ' +
+          '(look/aim/movement) (F2, spec §12 "Complete Device Backends"). Feeds a ' +
+          "'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-" +
+          'circle-clamped the same way a real analog stick is.',
+      ),
+    xAxis: z.number().describe('Standard Gamepad API axis index for the X component'),
+    yAxis: z.number().describe('Standard Gamepad API axis index for the Y component'),
+    deadzone: z.number().optional().describe('Deadzone magnitude (default 0.15 if omitted)'),
+  })
+  .strict();
 
 // ---------------------------------------------------------------------------
 // F1 (spec §12) — injected test input bindings. LIVE (real runtime readers in
@@ -102,78 +114,86 @@ const GamepadAxisPairBindingSchema = z.object({
 // aggregation path these exercise today.
 // ---------------------------------------------------------------------------
 
-const TestAxisBindingSchema = z.object({
-  type: z
-    .literal('test_axis')
-    .describe(
-      "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
-        '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
-        "built in F1 as the typed scalar value model's testable source.",
-    ),
-  sourceId: z
-    .string()
-    .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      '1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
-        'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
-        'deadzone edge) to ±1 (at |raw| = 1), sign preserved.',
-    ),
-});
+const TestAxisBindingSchema = z
+  .object({
+    type: z
+      .literal('test_axis')
+      .describe(
+        "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action " +
+          '(InputManager.injectAxis/getScalar) — the "injected test input" backend named in F2, ' +
+          "built in F1 as the typed scalar value model's testable source.",
+      ),
+    sourceId: z
+      .string()
+      .describe('Names the injected test source this binding reads (InputManager.injectAxis).'),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        '1D deadzone magnitude applied to the injected raw value before combine (default 0 — no ' +
+          'deadzone). Values below it read as 0; values at/above it rescale from 0 (at the ' +
+          'deadzone edge) to ±1 (at |raw| = 1), sign preserved.',
+      ),
+  })
+  .strict();
 
-const TestVector2BindingSchema = z.object({
-  type: z
-    .literal('test_vector2')
-    .describe(
-      "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
-        '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
-        "F2, built in F1 as the typed Vector2 value model's testable source.",
-    ),
-  sourceId: z
-    .string()
-    .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      'Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
-        '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
-        'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
-        'then the result is clamped to the unit circle (magnitude <= 1).',
-    ),
-});
+const TestVector2BindingSchema = z
+  .object({
+    type: z
+      .literal('test_vector2')
+      .describe(
+        "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action " +
+          '(InputManager.injectVector2/getVector2) — the "injected test input" backend named in ' +
+          "F2, built in F1 as the typed Vector2 value model's testable source.",
+      ),
+    sourceId: z
+      .string()
+      .describe('Names the injected test source this binding reads (InputManager.injectVector2).'),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        'Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 ' +
+          '— no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, ' +
+          'direction is preserved and magnitude rescales the same way the scalar deadzone does, ' +
+          'then the result is clamped to the unit circle (magnitude <= 1).',
+      ),
+  })
+  .strict();
 
-const TestPointerDeltaBindingSchema = z.object({
-  type: z
-    .literal('test_pointer_delta')
-    .describe(
-      "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
-        'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
-        'test input" backend named in F2. No deadzone (deltas are not deadzoned).',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
-    ),
-});
+const TestPointerDeltaBindingSchema = z
+  .object({
+    type: z
+      .literal('test_pointer_delta')
+      .describe(
+        "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-" +
+          'valueType action (InputManager.injectPointerDelta/getPointerDelta) — the "injected ' +
+          'test input" backend named in F2. No deadzone (deltas are not deadzoned).',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the injected test source this binding reads (InputManager.injectPointerDelta).',
+      ),
+  })
+  .strict();
 
-const TestPointerPositionBindingSchema = z.object({
-  type: z
-    .literal('test_pointer_position')
-    .describe(
-      "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
-        'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
-        '"injected test input" backend named in F2.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
-    ),
-});
+const TestPointerPositionBindingSchema = z
+  .object({
+    type: z
+      .literal('test_pointer_position')
+      .describe(
+        "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-" +
+          'valueType action (InputManager.injectPointerPosition/getPointerPosition) — the ' +
+          '"injected test input" backend named in F2.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the injected test source this binding reads (InputManager.injectPointerPosition).',
+      ),
+  })
+  .strict();
 
 // ---------------------------------------------------------------------------
 // F2 (spec §12 "Complete Device Backends") — touch/virtual-control bindings.
@@ -185,44 +205,48 @@ const TestPointerPositionBindingSchema = z.object({
 // thin adapter at the edge, out of scope here — see input-manager.ts).
 // ---------------------------------------------------------------------------
 
-const TouchButtonBindingSchema = z.object({
-  type: z
-    .literal('touch_button')
-    .describe(
-      "Binding kind: a virtual on-screen button for a 'digital' action " +
-        '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
-        'the same way a real mouse/keyboard button is.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
-        'touch-UI-chosen id, not a real device index.',
-    ),
-});
+const TouchButtonBindingSchema = z
+  .object({
+    type: z
+      .literal('touch_button')
+      .describe(
+        "Binding kind: a virtual on-screen button for a 'digital' action " +
+          '(InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) ' +
+          'the same way a real mouse/keyboard button is.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the virtual control zone this binding reads (InputManager.setTouchButton) — a ' +
+          'touch-UI-chosen id, not a real device index.',
+      ),
+  })
+  .strict();
 
-const TouchStickBindingSchema = z.object({
-  type: z
-    .literal('touch_stick')
-    .describe(
-      "Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
-        '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
-        'same way a real gamepad stick is.',
-    ),
-  sourceId: z
-    .string()
-    .describe(
-      'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
-        'touch-UI-chosen id, not a real device index.',
-    ),
-  deadzone: z
-    .number()
-    .optional()
-    .describe(
-      'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
-        'deadzone).',
-    ),
-});
+const TouchStickBindingSchema = z
+  .object({
+    type: z
+      .literal('touch_stick')
+      .describe(
+        "Binding kind: a virtual on-screen analog stick for a 'vector2' action " +
+          '(InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the ' +
+          'same way a real gamepad stick is.',
+      ),
+    sourceId: z
+      .string()
+      .describe(
+        'Names the virtual control zone this binding reads (InputManager.setTouchStick) — a ' +
+          'touch-UI-chosen id, not a real device index.',
+      ),
+    deadzone: z
+      .number()
+      .optional()
+      .describe(
+        'Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no ' +
+          'deadzone).',
+      ),
+  })
+  .strict();
 
 /** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
  *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
@@ -242,31 +266,33 @@ export const InputBindingSchema: z.ZodType<InputBinding> = z.discriminatedUnion(
 ]) as z.ZodType<InputBinding>;
 
 /** An action has a name (the record key) and one or more bindings. */
-export const InputActionSchema: z.ZodType<InputAction> = z.object({
-  valueType: z
-    .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
-    .default('digital')
-    .describe(
-      "This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
-        'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
-        "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
-        "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
-        "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
-        'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
-        'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
-        "'digital' action) throws.",
-    ),
-  bindings: z
-    .array(InputBindingSchema)
-    .describe(
-      'Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
-        'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
-        'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
-        'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
-        'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
-        'written contributing source (last-write-wins).',
-    ),
-});
+export const InputActionSchema: z.ZodType<InputAction> = z
+  .object({
+    valueType: z
+      .enum(['digital', 'scalar', 'vector2', 'pointerDelta', 'pointerPosition'])
+      .default('digital')
+      .describe(
+        "This action's declared value shape (F1, spec §12). 'digital' (boolean, with " +
+          'pressed/justPressed/justReleased edges) is the default when omitted, matching every ' +
+          "action authored before F1. 'scalar' is a single deadzone-rescaled float axis. " +
+          "'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a " +
+          "per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an " +
+          'absolute {x,y}, last-write-wins across sources. InputManager enforces this at read ' +
+          'time: reading an action through the wrong typed getter (e.g. getScalar on a ' +
+          "'digital' action) throws.",
+      ),
+    bindings: z
+      .array(InputBindingSchema)
+      .describe(
+        'Bindings that all trigger/feed this action. Digital actions combine via OR (any one ' +
+          'binding satisfied is enough). Scalar actions combine via max-magnitude across ' +
+          'contributing bindings (ties keep the first-listed binding). Vector2 actions combine ' +
+          'by summing contributing {x,y} values then clamping to the unit circle. PointerDelta ' +
+          'actions sum contributing deltas. PointerPosition actions use the most-recently-' +
+          'written contributing source (last-write-wins).',
+      ),
+  })
+  .strict();
 
 /**
  * The `.inputmap.json` file format (`InputManager.loadMap`).
@@ -275,9 +301,11 @@ export const InputActionSchema: z.ZodType<InputAction> = z.object({
  * same convention `2d.version`/`Scene2DSchema` used before T2.3 gave the 3D
  * scene version axis a real reader; see `schema-consumption-map.ts`).
  */
-export const InputMapFileSchema: z.ZodType<InputMapFile> = z.object({
-  version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
-  actions: z
-    .record(z.string(), InputActionSchema)
-    .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
-}) as z.ZodType<InputMapFile>;
+export const InputMapFileSchema: z.ZodType<InputMapFile> = z
+  .object({
+    version: z.number().describe('Input map file format version (RESERVED — no range check yet)'),
+    actions: z
+      .record(z.string(), InputActionSchema)
+      .describe('Named actions, each with a list of bindings (InputManager.loadMap)'),
+  })
+  .strict() as z.ZodType<InputMapFile>;

package/src/manifest/filename.ts

@@ -1,17 +1,13 @@
 // The project manifest's FILENAME. There is exactly ONE.
 //
-// The manifest is `vgai.project.json`. It used to be `vgai.game.json`, and for
-// a while both names were read — WO-9 #62 recorded that dual-read as
-// permanent, on the presumption of an EXTERNAL constituency of projects
-// already on disk. The owner reversed that on 2026-08-02 (the legacy-removal
-// doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary): this is pre-release
-// software, no such constituency exists, and a second way to spell the
-// manifest is the defect — two accepted names meant both kept being written,
-// and copies of the "try both" probe grew in five modules that agreed with the
-// real resolver only by coincidence.
+// The manifest is `vgai.project.json`, and NOTHING reads a second spelling
+// (the legacy-removal doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary). Two
+// accepted names is the defect, not the convenience: both get written, and
+// copies of the "try both" probe spread into modules that agree with the real
+// resolver only by coincidence.
 //
-// So the old name is REMOVED, and removed means it REJECTS LOUDLY naming the
-// exact one-line fix — never silently ignored, never redirected. A directory
+// The removed name REJECTS LOUDLY, naming the exact one-line fix — never
+// silently ignored, never redirected. A directory
 // carrying only `vgai.game.json` is an error with a `git mv` in the message,
 // not a project that quietly fails to open.
 //
@@ -40,7 +36,7 @@ export function isManifestFilename(name: string): boolean {
 export function removedManifestFilenameMessage(where: string): string {
   return (
     `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. ` +
-    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (WO-LR1; the legacy-removal doctrine, ` +
+    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, ` +
     'docs/ARCHITECTURE-CORE.md §Vocabulary) — nothing reads it any more, and it is ' +
     'deliberately NOT read as a fallback, because a second accepted name is the defect.\n' +
     `Fix: rename it — \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. ` +

package/src/manifest/load.ts

@@ -62,13 +62,6 @@ export type ResolvedAdapter =
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
-      /**
-       * The component this root'''s WORLD is, in the game'''s own source (see the
-       * field'''s schema description). Present ⇒ Edit mounts THAT component
-       * alone as a still design-time document and Play mounts the game
-       * through `entry`; absent ⇒ `entry` is what both modes mount.
-       */
-      readonly world?: { readonly entry: string; readonly export?: string | undefined } | undefined;
     };
 
 export interface ResolvedAdapterRoot {
@@ -77,6 +70,13 @@ export interface ResolvedAdapterRoot {
   readonly description: string | undefined;
   readonly adapter: ResolvedAdapter;
   readonly entry: string | undefined;
+  /**
+   * The component this root's WORLD is, in the game's own source (see the
+   * field's schema description). Present ⇒ Edit mounts THAT component alone as
+   * its design-time document and Play mounts the game through `entry`;
+   * absent ⇒ `entry` is what both modes mount.
+   */
+  readonly world?: { readonly entry: string; readonly export: string | undefined } | undefined;
   readonly zOrder: number;
   readonly pausable: boolean;
   readonly loop: 'gated' | 'self-driven';
@@ -231,7 +231,6 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     assets: ingest.assets,
     domStubs: ingest.domStubs,
     captureTimeoutMs: ingest.captureTimeoutMs,
-    world: ingest.world,
   };
 }
 
@@ -251,11 +250,14 @@ function checkEngineVersionPin(version: string): void {
  * `id` drives uniqueness; `adapter` (incl. its surface and
  * `module`/`ingest.*` sub-fields) drives adapter identity
  * resolution; `entry` drives the entry cross-field rule and is
- * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
+ * carried through; `world` is carried through for the ONE reader that mounts a
+ * design-time document (the editor's design session) and is deliberately not
+ * cross-checked against `entry` — the two name different modules on purpose;
+ * `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
  * `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
- * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
+ * `resolveIngestDescriptor` (packages/editor/src/ingest/resolve-three.ts), which
  * threads an ingest-three root's description into `IngestGame.description`.
  */
 function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
@@ -268,6 +270,8 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     description: root.description,
     adapter,
     entry: root.entry,
+    world:
+      root.world === undefined ? undefined : { entry: root.world.entry, export: root.world.export },
     zOrder: root.zOrder,
     pausable: root.pausable,
     loop: root.loop,
@@ -285,9 +289,9 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
  * any Zod validation failure or cross-field rule violation.
  */
 export function loadGameManifest(raw: unknown): ResolvedGameManifest {
-  // Removed-format guard FIRST, on the raw value: a legacy `.vscn.json` root
-  // would otherwise fail Zod's `roots` discriminated union with a confusing
-  // shape error instead of a migration message (WO-8).
+  // Removed-format guard FIRST, on the raw value: a root declaring a removed
+  // content field would otherwise fail Zod's `roots` discriminated union with
+  // a confusing shape error instead of the named migration message.
   const parsed = GameManifestSchema.safeParse(raw);
   if (!parsed.success) {
     // D-V6: the `roots` `superRefine`'s composition issues — a duplicate root