@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/debug-registry.ts

@@ -0,0 +1,856 @@
+/**
+ * The game-scoped debug/synthetic-player registry (`docs/SYNTHETIC-PLAYER-SPEC.md`
+ * §3.1). ONE registry per `Game` root — every world's `ctx.debug` (see
+ * `DebugCtxSurface`, `runtime/types.ts`) feeds the SAME registry via
+ * {@link DebugRegistry.forWorld}, so a name a game registers is visible (and
+ * name-collision-checked) across every world, not just the one that
+ * registered it. `createGame` (`runtime/game.ts`) constructs the registry
+ * alongside the state bridge and files it in the `Game -> DebugRegistry`
+ * WeakMap this module owns; later consumers (the react `useDebugProvider`/
+ * `useDebugCommand` hooks, editor panels) reach it via {@link getDebugRegistry}
+ * rather than threading it through every call site.
+ *
+ * Provenance note: a registration's "world" is the MOUNT's adapter id (the
+ * `fromSetup(id, ...)` / `VgaiSceneConfig.id` a project already names each
+ * world's entry with) rather than the `WorldInstance.id` `registerThreeWorld`
+ * assigns — that id isn't known until AFTER `mount()` resolves (`create-
+ * runtime.ts` calls `registerThreeWorld` with it only once `mount()` returns),
+ * which is after every `setup()`-time registration has already run. For the
+ * single-world case (nearly every project today) this is simply `'vgai-scene'`;
+ * a multi-world manifest names each world's adapter to match its declared id
+ * by convention, so collision messages stay meaningful in practice.
+ */
+
+import { z } from 'zod';
+import type { DebugAdapter, DebugCommandInfo, TickStampedEvent } from '../adapter/system-adapter';
+import type { GameLoopLiveness } from '../core/types';
+import type { Game } from './game';
+import type { DebugCommandArgs, DebugCtxSurface, DebugRoomHandle } from './types';
+
+/** Engine-local error for the debug seam — mirrors the `code` + `data` shape
+ *  `packages/vgai-sdk/src/errors.ts` uses (no import: the engine does not
+ *  depend on `@vgai/sdk`). `code` is always machine-readable; nothing reading
+ *  this error may key off `message` prose. */
+export class DebugError extends Error {
+  readonly code: string;
+  readonly data?: Record<string, unknown> | undefined;
+
+  constructor(code: string, message: string, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'DebugError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+const REGISTRATION_HINT =
+  'ctx.debug.registerStateProvider(name, fn) — see the template example component';
+
+/** Task 2.2 — how long `invoke()` waits for a `locus: 'server'` command's
+ *  `__vgai:debugCommandResult` reply before failing loudly. */
+const SERVER_COMMAND_TIMEOUT_MS = 10_000;
+
+/** The virtual-input surface the debug bridge (`runtime/debug-bridge.ts`)
+ *  actuates through — the SAME three methods `InputManager` exposes
+ *  (`setVirtualAction`/`tapVirtualAction`/`clearVirtualActions`, Task 1.4),
+ *  typed narrowly here so this module never imports `InputManager` itself.
+ *  Wired once by the hosting adapter (`vgai-scene-game-adapter.ts`, at the
+ *  same seed spot as `setInputActionsSource`) — absent until then. */
+export interface DebugVirtualInputTarget {
+  setVirtualAction(
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): { delivered: boolean; reason?: string };
+  tapVirtualAction(action: string): { delivered: boolean; reason?: string };
+  clearVirtualActions(): void;
+  /** D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c) — schedule a virtual
+   *  actuation for a specific future (or current) tick, applied at the start
+   *  of that tick's input phase (composes with `runTicks`). */
+  scheduleActionAtTick(
+    tick: number,
+    action: string,
+    value: boolean | number | { x: number; y: number },
+  ): void;
+  startInputRecording(): void;
+  stopInputRecording(): void;
+  isInputRecording(): boolean;
+  /** The four legacy named-test-source injectors (`InputManager`'s own),
+   *  included here so `inject-input`'s non-`action` kinds route through the
+   *  SAME per-world resolution as everything else on this interface (D15
+   *  review objection: routing must never depend on registration order). */
+  injectAxis(sourceId: string, value: number): void;
+  injectVector2(sourceId: string, value: { x: number; y: number }): void;
+  injectPointerDelta(sourceId: string, delta: { x: number; y: number }): void;
+  injectPointerPosition(sourceId: string, value: { x: number; y: number }): void;
+}
+
+/**
+ * D15/T-D15.5 — the `input.trace` builtin provider's shape (docs/D15-
+ * DETERMINISM-DESIGN.md §2.c's format sketch). `seed`/`fixedDt` are
+ * replay-critical metadata a future SP5 consumer needs BESIDE the raw
+ * per-tick action deltas (`ticks`, straight off `InputManager.getInputTrace()`)
+ * to know what to replay the trace AGAINST — recording deltas alone is not
+ * enough to reproduce a run. Both are `null` only when no wiring/no
+ * `ctx.random`/no `Game` exists behind this world (never a fabricated 0).
+ */
+export interface InputTraceSnapshot {
+  version: 1;
+  seed: number | null;
+  fixedDt: number | null;
+  ticks: unknown[];
+}
+
+/** `Game.runTicks`'s options — see `GameInternal.runTicks`'s doc comment
+ *  (`runtime/game.ts`, D15/T-D15.3-.4) for full semantics. Named here (not
+ *  re-declared per-caller) so the bridge (`runtime/debug-bridge.ts`), the
+ *  editor relay (`command-listener.ts`'s `run-ticks` case), and
+ *  `play.runTicks` (`@vgai/sdk`) all reference the SAME type. */
+export interface RunTicksOptions {
+  /** `'last'` (default) — skip `preRender`/`render` for every tick except
+   *  the final one. `'all'` — render every tick. `'none'` — never render,
+   *  not even the last tick. */
+  render?: 'last' | 'all' | 'none';
+}
+
+/** The run-ticks actuation surface a live `Game` wires in (see
+ *  {@link DebugRegistry.setRunTicksTarget}) — just `GameInternal.runTicks`'s
+ *  signature, typed narrowly here so this module never imports `./game`
+ *  as a value (only `Game` as a type, already the case above). */
+export interface RunTicksTarget {
+  runTicks(n: number, opts?: RunTicksOptions): void;
+}
+
+interface PendingServerCommand {
+  resolve(result: unknown): void;
+  reject(err: unknown): void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** Provenance `worldId` for every registration made through the react door
+ *  (`useDebugProvider`/`useDebugCommand`, `packages/engine/src/react/game-
+ *  state.tsx`) — react roots have no `setup()`/`ctx.debug` of their own
+ *  (spec §3.1's "react-world registration door" paragraph), so all of them
+ *  share this one provenance string; a name collision between two DIFFERENT
+ *  react components is therefore the same-world "replace + warn once" case,
+ *  never the cross-world throw (which is reserved for a GameComponent world
+ *  vs. the react door genuinely disagreeing about a name).
+ *
+ *  Defect 7 fix: this used to be the bare string `'react'`, which collided in
+ *  provenance with a manifest world literally named `'react'` (e.g. a
+ *  `kind: 'react'` world whose `id` is `"react"`) — `forWorld('react')` and
+ *  the react door would then be treated as the SAME world for collision
+ *  purposes, which is wrong (they are genuinely different registrants that
+ *  happen to share a display name). Namespaced like `'__engine__'` so no
+ *  real project world id can ever collide with it. */
+const REACT_WORLD_ID = '__react__';
+
+interface ProviderEntry {
+  fn: () => unknown;
+  tier: 'observable' | 'assisted';
+  worldId: string;
+  builtin: boolean;
+  /** Set only by {@link DebugRegistry.registerReactProvider} — lets its
+   *  disposer remove ITS OWN registration and no one else's (a later mount
+   *  under the same react worldId may have legitimately replaced it). */
+  token?: symbol | undefined;
+}
+
+interface CommandEntry {
+  description?: string | undefined;
+  argsSchema?: z.ZodTuple | undefined;
+  locus?: 'client' | 'server' | undefined;
+  fn: (...args: unknown[]) => unknown | Promise<unknown>;
+  worldId: string;
+  /** See {@link ProviderEntry.token}. */
+  token?: symbol | undefined;
+}
+
+/** What {@link createDebugRegistry} returns — the adapter half (`DebugAdapter`,
+ *  for `SystemAdapters.debug`) plus the registration/lifecycle surface the
+ *  hosting adapter (`vgai-scene-game-adapter.ts`) and `createGame` drive. */
+export interface DebugRegistry {
+  /** The `SystemAdapters.debug` implementer — one shared instance, seeded
+   *  onto every world's adapter bag. */
+  readonly adapter: DebugAdapter;
+  /** Build the `ctx.debug` surface for one world/mount — registrations made
+   *  through it carry `worldId` as their provenance for collision messages. */
+  forWorld(worldId: string): DebugCtxSurface;
+  /** Emit from a React root through the same tick-stamped event ring as
+   *  `ctx.debug.emit`. React roots have no setup context, so
+   *  `useDebugEmit()` calls this dedicated door instead of reaching through
+   *  the registry's internal synthetic world id. */
+  emitReact(event: string, detail?: unknown): void;
+  /**
+   * Remove non-built-in registrations (Defect 2 fix — this used to be
+   * unconditionally global, which made a per-mount call like `hotReload`'s
+   * silently wipe every OTHER live world's registrations and every react-door
+   * registration, whose `useEffect` cleanup never re-fires to restore them).
+   *
+   * - `strip(worldId)` — scoped: removes only providers/commands whose
+   *   provenance is exactly `worldId` (and clears their warn-once state), so
+   *   a hot-reloading world re-seeds itself without disturbing anyone else.
+   *   React-door registrations (provenance `'__react__'`) are never touched
+   *   by a world-scoped strip.
+   * - `strip()` (no id) — the original global behavior: every non-built-in
+   *   registration is removed, including react-door ones. Intended for "the
+   *   whole game is going away" (`disposeGame`) or test teardown, not a
+   *   single mount's warm restart.
+   *
+   * Either way, the very next registration of a name just removed is silent —
+   * there is nothing left to collide with or warn about.
+   */
+  strip(worldId?: string): void;
+  /** Manifest wiring lands in a later wave; until then, call this directly
+   *  (default `false`) to exercise the locus-required throw. */
+  setRoomDeclared(declared: boolean): void;
+  /** Wire the built-in `input.actions` provider to a live `InputManager`
+   *  (T1.2), scoped to `worldId` — lazy, since a world's InputManager doesn't
+   *  exist yet when the registry is constructed (`createGame`, before any
+   *  world mounts). Before ANY source is set, `input.actions` reads `[]`;
+   *  once one or more roots have registered, the built-in `input.actions`
+   *  provider reads the DEFAULT world's (see {@link resolveInputWorldId}) —
+   *  same resolution every other per-world seam on this interface uses. */
+  setInputActionsSource(worldId: string, fn: () => { name: string; valueType: string }[]): void;
+  /** D15/T-D15.5 — wire the built-in `input.trace` provider to a live
+   *  `InputManager.getInputTrace`, scoped to `worldId` — same lazy-supplier
+   *  shape/seed spot as {@link setInputActionsSource}, same default-world
+   *  resolution for the read. Before a source is set, `input.trace` reads
+   *  `{version: 1, seed: null, fixedDt: null, ticks: []}`. `seed`/`fixedDt`
+   *  are the two replay-critical metadata fields the design doc's format
+   *  sketch (§2.c) calls for beside the raw per-tick deltas — the wiring
+   *  adapter (`vgai-scene-game-adapter.ts`) assembles them from
+   *  `getSeededRandom(game)?.seed`/`host.game?.loop.fixedDt` alongside
+   *  `InputManager.getInputTrace()`'s own `{version, ticks}`. An `engine`
+   *  (package version) stamp remains a KNOWN GAP — no build-time version
+   *  constant is threaded into the runtime bundle today; a future track
+   *  adding one should extend this shape, not invent a second trace format. */
+  setInputTraceSource(worldId: string, fn: () => InputTraceSnapshot): void;
+  /**
+   * Wire the debug bridge's actuation methods (`runtime/debug-bridge.ts`) to
+   * a live `InputManager` (Task 2.1), scoped to `worldId` — same lazy-
+   * supplier shape as {@link setInputActionsSource}, wired at the same seed
+   * spot (once per world mount, not once per Game).
+   *
+   * Fix for a closed-PR review objection: this used to be a SINGLE slot
+   * (last-writer-wins across every world that mounted), which could route
+   * the debug bridge (`window.__vgai.input.*`, which read this directly) and
+   * the editor relay (which reached the default world's `InputManager`
+   * through a DIFFERENT accessor, `Game.input`) to two DIFFERENT roots in a
+   * multi-world project — the bridge always got whichever world mounted
+   * LAST, the relay always got the FIRST/default world. Now every world's
+   * target is kept, keyed by `worldId`, and {@link getVirtualInputTarget}
+   * resolves ONE of them via {@link resolveInputWorldId} — the SAME
+   * resolution the bridge and the relay both call through, so they can never
+   * disagree again. An explicit `worldId` reaches that world specifically. */
+  setVirtualInputTarget(worldId: string, target: DebugVirtualInputTarget): void;
+  /**
+   * Resolve and return a virtual-input target: `worldId` given and
+   * registered → that world's; omitted → the DEFAULT world's (per
+   * {@link resolveInputWorldId} — the manifest's first/default world when a
+   * `Game` is behind this registry, else the single registered world, else
+   * whichever registered first), consistently, for every caller (the debug
+   * bridge and the editor relay both call this — see this interface's own
+   * doc comment above). `null` when nothing is registered for the resolved
+   * id at all (callers throw a structured `DEBUG_INPUT_UNAVAILABLE` in that
+   * case rather than silently no-op-ing). Throws `DebugError`
+   * (`DEBUG_INPUT_WORLD_NOT_FOUND`) for an EXPLICIT `worldId` that was never
+   * registered — a caller mistake, distinct from "nothing mounted yet".
+   */
+  getVirtualInputTarget(worldId?: string): DebugVirtualInputTarget | null;
+  /**
+   * D15/T-D15.4: wire `Game.runTicks` (`runtime/game.ts`) as the run-ticks
+   * actuation target — called ONCE by `createGame`, immediately (unlike
+   * {@link setVirtualInputTarget}, which waits for a per-world mount, a
+   * `Game`'s own `runTicks` exists the instant the Game shell does). The
+   * SAME target backs `runtime/debug-bridge.ts`'s `window.__vgai.runTicks`
+   * (door a) and the editor relay's `run-ticks` case → `play.runTicks`
+   * (door b) — one implementation, byte-identical semantics across doors
+   * (D17).
+   */
+  setRunTicksTarget(target: RunTicksTarget): void;
+  /** The target {@link setRunTicksTarget} last set, or `null` before any
+   *  `Game` has wired one (a bare `createDebugRegistry()` test stand-in with
+   *  no `createGame` behind it). Consumers throw a structured "unavailable"
+   *  error in that case rather than silently no-op-ing — see
+   *  `debug-bridge.ts`'s `runTicks` method. */
+  getRunTicksTarget(): RunTicksTarget | null;
+  /** D15/T-D15.3/.5 — the CURRENT shared game tick (the same counter the
+   *  built-in `time` provider's `tick` field reads), for a per-world
+   *  `InputManager.poll(tick)` call to key its `scheduleActionAtTick`
+   *  numbering off — see `vgai-scene-game-adapter.ts`'s `systems.add('input',
+   *  ...)` wiring. `0` for a bare `createDebugRegistry()` test stand-in with
+   *  no real `Game`/tick counter behind it (matching `getTick`'s own
+   *  constructor-supplied default in that case). */
+  getGameTick(): number;
+  /** React-door registration (Task 1.5, spec §3.1's "react-world
+   *  registration door") — same accumulator as `forWorld(...)
+   *  .registerStateProvider`, provenance `'__react__'` (see {@link REACT_WORLD_ID}),
+   *  but returns a disposer instead of requiring a separate unregister call.
+   *  Calling the disposer removes the registration ONLY if it is still the
+   *  live entry under `name` — unmount never clobbers a DIFFERENT mount's
+   *  later registration of the same name, and (matching `strip()`) removal
+   *  is silent: the very next registration of that name has nothing to warn
+   *  about. */
+  registerReactProvider(
+    name: string,
+    fn: () => unknown,
+    opts?: { tier?: 'observable' | 'assisted' | undefined },
+  ): () => void;
+  /** See {@link registerReactProvider} — the command-side counterpart. Same
+   *  args-tuple-infers-`fn`-params generic as `DebugCtxSurface.registerCommand`
+   *  ({@link DebugCommandArgs}). */
+  registerReactCommand<T extends z.ZodTuple | undefined = undefined>(
+    name: string,
+    spec: { description?: string; args?: T; locus?: 'client' | 'server' },
+    fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>,
+  ): () => void;
+}
+
+function warnOnce(
+  warned: Set<string>,
+  name: string,
+  kind: 'provider' | 'command',
+  worldId: string,
+): void {
+  if (warned.has(name)) return;
+  warned.add(name);
+  // biome-ignore lint/suspicious/noConsole: structured, greppable — the debug seam's own duplicate-registration signal (spec §3.1)
+  console.warn(`[debug] ${kind} "${name}" re-registered (world "${worldId}")`);
+}
+
+/**
+ * Construct a fresh game-scoped debug registry. `getTick`/`getSimT` are
+ * suppliers (not values) so the built-in `time` provider always reads the
+ * CURRENT counters — `createGame` passes closures over its own mutable
+ * `tick`/`simT`, incremented in `runFrame`'s tail (T1.2). `getDefaultWorldId`
+ * (D15/T-D15.5, optional) resolves the manifest's first/default world id —
+ * `createGame` passes `() => (roots.length ? requireDefaultWorld().id :
+ * null)`; a bare `createDebugRegistry()` test stand-in with no `Game` behind
+ * it omits it (per-world resolution then falls back to "the single
+ * registered world" or "whichever registered first" — see
+ * `resolveInputWorldId`). `getLoopLiveness` (issue #175, optional) supplies
+ * the REAL `GameLoop.liveness` — `createGame` passes `() => opts.loop.
+ * liveness`; a bare `createDebugRegistry()` test stand-in with no loop
+ * behind it omits it, and the built-in `time` provider reports `null`
+ * rather than fabricating `'running'` (this module must never claim health
+ * it cannot observe, same rule the loop's own liveness getter documents).
+ */
+export function createDebugRegistry(opts: {
+  getTick(): number;
+  getSimT(): number;
+  getDefaultWorldId?(): string | null;
+  getLoopLiveness?(): GameLoopLiveness;
+}): DebugRegistry {
+  const providers = new Map<string, ProviderEntry>();
+  const commands = new Map<string, CommandEntry>();
+  const warnedProviders = new Set<string>();
+  const warnedCommands = new Set<string>();
+  const ring: TickStampedEvent[] = [];
+  const RING_CAP = 500;
+  // Run-4 friction #5 — monotonic, registry-lifetime counter backing
+  // `TickStampedEvent.seq`. Never reset, never shared by two events (unlike
+  // `tick`, which a debug-command emission and a fenced consumer's snapshot
+  // can legitimately collide on — see that field's doc comment in
+  // `adapter/system-adapter.ts`).
+  let seqCounter = 0;
+
+  let roomDeclared = false;
+  // D15/T-D15.5 — per-world maps (Map preserves insertion order, which
+  // `resolveInputWorldId`'s "whichever registered first" fallback relies on
+  // when no `getDefaultWorldId` is available to disambiguate).
+  const inputActionsSources = new Map<string, () => { name: string; valueType: string }[]>();
+  const inputTraceSources = new Map<string, () => InputTraceSnapshot>();
+  const virtualInputTargets = new Map<string, DebugVirtualInputTarget>();
+  let runTicksTarget: RunTicksTarget | null = null;
+  let attachedRoom: DebugRoomHandle | null = null;
+  const pendingServerCommands = new Map<string, PendingServerCommand>();
+  let requestCounter = 0;
+
+  /**
+   * The ONE resolution function every per-world input seam shares (D15
+   * review objection: the debug bridge and the editor relay must never be
+   * able to disagree about which world an unqualified actuation targets).
+   *
+   * - `explicit` given: must be a registered world id, else throws
+   *   `DEBUG_INPUT_WORLD_NOT_FOUND` (a caller mistake — distinct from
+   *   "nothing mounted yet", which returns `null` below instead of throwing).
+   * - `explicit` omitted: the manifest's first/default world id
+   *   (`opts.getDefaultWorldId()`) iff that world has actually registered —
+   *   else (no `Game`/no default resolvable, or the default world never
+   *   wired one — e.g. a foreign/opaque mount) the single registered world,
+   *   or, with more than one and no resolvable default, whichever registered
+   *   FIRST (`Map` insertion order) — the closest analogue to this seam's
+   *   pre-D15.5 single-slot behavior, but now a stable, principled choice
+   *   instead of "whichever mounted last".
+   * - Nothing registered at all: `null`.
+   */
+  function resolveInputWorldId(explicit?: string): string | null {
+    if (explicit !== undefined) {
+      if (!virtualInputTargets.has(explicit)) {
+        throw new DebugError(
+          'DEBUG_INPUT_WORLD_NOT_FOUND',
+          `debug: no InputManager wired for world "${explicit}" — registered: ` +
+            (virtualInputTargets.size ? [...virtualInputTargets.keys()].join(', ') : '(none)'),
+          { worldId: explicit, registered: [...virtualInputTargets.keys()] },
+        );
+      }
+      return explicit;
+    }
+    return resolveWorldForSource(virtualInputTargets.keys());
+  }
+
+  /** The same "default world, else the one registered, else whichever
+   *  registered first" fallback {@link resolveInputWorldId} uses for the
+   *  ACTUATION target, generalized over any per-world registration set
+   *  (`inputActionsSources`/`inputTraceSources` included) — every one of
+   *  these maps is keyed by the same world ids, populated at the same
+   *  per-world mount seed spot, so "the default world" means the same thing
+   *  for all of them. Never throws (no explicit-id case here — the two
+   *  builtin providers that call this have no way to accept a caller-chosen
+   *  worldId today; see their own doc comments). */
+  function resolveWorldForSource(registered: IterableIterator<string>): string | null {
+    const ids = [...registered];
+    if (ids.length === 0) return null;
+    const defaultId = opts.getDefaultWorldId?.() ?? null;
+    if (defaultId !== null && ids.includes(defaultId)) return defaultId;
+    return ids[0]!;
+  }
+
+  providers.set('time', {
+    // `loopLiveness` (issue #175): `null` when no loop is wired behind this
+    // registry (a bare `createDebugRegistry()` test stand-in) — never a
+    // fabricated `'running'`. Every real `Game` (`createGame`) wires this,
+    // so every live play session reports a real value.
+    fn: () => ({
+      simSeconds: opts.getSimT(),
+      tick: opts.getTick(),
+      loopLiveness: opts.getLoopLiveness?.() ?? null,
+    }),
+    tier: 'observable',
+    worldId: '__engine__',
+    builtin: true,
+  });
+  providers.set('input.actions', {
+    // Resolves to the DEFAULT world's action list (see `resolveInputWorldId`)
+    // — deterministic across every world that registers, rather than the
+    // pre-D15.5 "whichever mounted last" behavior.
+    fn: () => {
+      const worldId = resolveWorldForSource(inputActionsSources.keys());
+      return (worldId ? inputActionsSources.get(worldId) : undefined)?.() ?? [];
+    },
+    tier: 'observable',
+    worldId: '__engine__',
+    builtin: true,
+  });
+  // D15/T-D15.5 — the post-gate action-delta trace, readable via a provider.
+  // Absent a wired source (no world mounted yet) reads an empty, correctly-
+  // versioned trace rather than throwing. Same default-world resolution as
+  // `input.actions` immediately above.
+  providers.set('input.trace', {
+    fn: () => {
+      const worldId = resolveWorldForSource(inputTraceSources.keys());
+      return (
+        (worldId ? inputTraceSources.get(worldId) : undefined)?.() ?? {
+          version: 1,
+          seed: null,
+          fixedDt: null,
+          ticks: [],
+        }
+      );
+    },
+    tier: 'observable',
+    worldId: '__engine__',
+    builtin: true,
+  });
+
+  function registerStateProvider(
+    worldId: string,
+    name: string,
+    fn: () => unknown,
+    tier: 'observable' | 'assisted',
+    token?: symbol,
+  ): void {
+    const existing = providers.get(name);
+    if (existing?.builtin) {
+      // Defect 1 fix: a builtin name (`time`, `input.actions`) must never be
+      // silently shadowed — the old `!existing.builtin` guard skipped BOTH
+      // the collision throw and the warn for this case, so
+      // `registerStateProvider('time', ...)` quietly replaced engine truth,
+      // and a later `strip()` deleted it outright (leaving NO `time`
+      // provider at all post-hot-reload). Throw loudly instead; there is no
+      // silent-replace path for a builtin.
+      throw new DebugError(
+        'DEBUG_BUILTIN_RESERVED',
+        `debug: "${name}" is a built-in state provider (registered by "${existing.worldId}") — ` +
+          'built-in names cannot be registered over, from a world or the react door',
+        { name, registered: existing.worldId },
+      );
+    }
+    if (existing) {
+      if (existing.worldId !== worldId) {
+        throw new DebugError(
+          'DEBUG_NAME_COLLISION',
+          `debug: state provider "${name}" is registered by both world "${existing.worldId}" ` +
+            `and world "${worldId}" — each provider name must be unique across live roots`,
+          { name, roots: [existing.worldId, worldId] },
+        );
+      }
+      warnOnce(warnedProviders, name, 'provider', worldId);
+    }
+    providers.set(name, { fn, tier, worldId, builtin: false, token });
+  }
+
+  function registerCommand(
+    worldId: string,
+    name: string,
+    spec: { description?: string; args?: z.ZodTuple; locus?: 'client' | 'server' },
+    fn: (...args: unknown[]) => unknown | Promise<unknown>,
+    token?: symbol,
+  ): void {
+    if (spec.locus === undefined && roomDeclared) {
+      throw new DebugError(
+        'DEBUG_COMMAND_LOCUS_REQUIRED',
+        "this project declares a Colyseus room — declare locus: 'client' | 'server' so " +
+          'fixtures mutate authoritative state, not client prediction',
+        { name, worldId },
+      );
+    }
+    const existing = commands.get(name);
+    if (existing) {
+      if (existing.worldId !== worldId) {
+        throw new DebugError(
+          'DEBUG_NAME_COLLISION',
+          `debug: command "${name}" is registered by both world "${existing.worldId}" and ` +
+            `world "${worldId}" — each command name must be unique across live roots`,
+          { name, roots: [existing.worldId, worldId] },
+        );
+      }
+      warnOnce(warnedCommands, name, 'command', worldId);
+    }
+    commands.set(name, {
+      description: spec.description,
+      argsSchema: spec.args,
+      locus: spec.locus,
+      fn,
+      worldId,
+      token,
+    });
+  }
+
+  function emit(event: string, detail?: unknown): void {
+    seqCounter += 1;
+    ring.push({ tick: opts.getTick(), simT: opts.getSimT(), event, detail, seq: seqCounter });
+    if (ring.length > RING_CAP) ring.shift();
+  }
+
+  /** See `DebugAdapter.events`'s doc comment (`adapter/system-adapter.ts`)
+   *  for the full contract — `sinceSeq` (when given) wins over `sinceTick`,
+   *  since it's the unambiguous one. */
+  function events(sinceTick?: number, sinceSeq?: number): TickStampedEvent[] {
+    if (sinceSeq !== undefined) return ring.filter((e) => e.seq > sinceSeq);
+    if (sinceTick === undefined) return ring.slice();
+    return ring.filter((e) => e.tick > sinceTick);
+  }
+
+  /**
+   * Task 2.2 — server-locus command routing (client leg). A `locus: 'server'`
+   * command never calls its own registered `fn` locally: `invoke()` instead
+   * sends the reserved room message `__vgai:debugCommand` and resolves on the
+   * matching `__vgai:debugCommandResult` reply, so a fixture mutates the
+   * AUTHORITATIVE (server) copy of state, not client prediction. Request ids
+   * are a monotonic per-registry counter (`dbg-<n>`), not `Math.random`/
+   * `Date.now`, so two in-flight commands never collide and correlation is
+   * trivially inspectable in logs.
+   */
+  function invokeServerCommand(name: string, args: unknown[]): Promise<unknown> {
+    if (!attachedRoom) {
+      throw new DebugError(
+        'DEBUG_COMMAND_FAILED',
+        `debug: command "${name}" is locus:'server' but no Colyseus room is attached ` +
+          '(call ctx.debug.attachRoom(room) once your game joins its room)',
+        { reason: 'no room connection' },
+      );
+    }
+    const requestId = `dbg-${++requestCounter}`;
+    const room = attachedRoom;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingServerCommands.delete(requestId);
+        reject(
+          new DebugError(
+            'DEBUG_COMMAND_FAILED',
+            `debug: command "${name}" (requestId "${requestId}") timed out waiting for the server`,
+            { reason: 'server timeout' },
+          ),
+        );
+      }, SERVER_COMMAND_TIMEOUT_MS);
+      pendingServerCommands.set(requestId, { resolve, reject, timer });
+      room.send('__vgai:debugCommand', { name, args, requestId });
+    });
+  }
+
+  // Defect 8 fix — the live detach() for whatever room is CURRENTLY attached
+  // (or null if none). `attachRoom` calls this itself before attaching a new
+  // room: without it, a second `attachRoom` call (no explicit `detach()` in
+  // between) left the first room's `__vgai:debugCommandResult` subscription
+  // live forever (a leak — the old room keeps getting messages dispatched to
+  // a handler nothing reads anymore) and stranded any of ITS in-flight
+  // commands riding the full 10s timeout with no way to ever be answered.
+  let detachCurrentRoom: (() => void) | null = null;
+
+  /** {@link DebugCtxSurface.attachRoom} — shared across every world's ctx
+   *  surface (game-scoped, last-attached room wins — and, since Defect 8,
+   *  actually CLEANS UP the previous attachment rather than merely
+   *  overwriting the pointer). Subscribes to the reserved
+   *  `__vgai:debugCommandResult` reply and resolves/rejects the matching
+   *  in-flight {@link invokeServerCommand} promise by `requestId`. */
+  function attachRoom(room: DebugRoomHandle): () => void {
+    // Last-wins, but with cleanup: detach whatever room was attached before
+    // (unsubscribes its listener, rejects ITS in-flight pendings — see
+    // `detach` below) rather than leaking it.
+    detachCurrentRoom?.();
+
+    attachedRoom = room;
+    const unsubscribe = room.onMessage('__vgai:debugCommandResult', (message) => {
+      const reply = message as
+        | { requestId?: string; ok?: boolean; result?: unknown; error?: unknown }
+        | undefined;
+      const requestId = reply?.requestId;
+      if (requestId === undefined) return;
+      const pending = pendingServerCommands.get(requestId);
+      if (!pending) return;
+      pendingServerCommands.delete(requestId);
+      clearTimeout(pending.timer);
+      if (reply?.ok) {
+        pending.resolve(reply.result);
+      } else {
+        pending.reject(
+          new DebugError(
+            'DEBUG_COMMAND_FAILED',
+            `debug: server command failed: ${String(reply?.error)}`,
+            { cause: reply?.error },
+          ),
+        );
+      }
+    });
+
+    const detach = (): void => {
+      // Idempotent, and a no-op if a LATER attachRoom already superseded
+      // this attachment (its own detach ran first via detachCurrentRoom?.()
+      // above) — calling this stale detach again must not clobber the new
+      // attachment's state.
+      if (detachCurrentRoom !== detach) return;
+      detachCurrentRoom = null;
+      if (attachedRoom === room) attachedRoom = null;
+      if (typeof unsubscribe === 'function') (unsubscribe as () => void)();
+      // Defect 8 fix: reject every command still awaiting THIS room's reply
+      // right now, rather than let it silently ride out the full 10s
+      // `SERVER_COMMAND_TIMEOUT_MS` with no room left to ever answer it.
+      for (const [requestId, pending] of pendingServerCommands) {
+        clearTimeout(pending.timer);
+        pending.reject(
+          new DebugError(
+            'DEBUG_COMMAND_FAILED',
+            `debug: command (requestId "${requestId}") failed — its room was detached before a reply arrived`,
+            { reason: 'no room connection' },
+          ),
+        );
+      }
+      pendingServerCommands.clear();
+    };
+    detachCurrentRoom = detach;
+    return detach;
+  }
+
+  const adapter: DebugAdapter = {
+    providers() {
+      return [...providers.entries()].map(([name, entry]) => ({ name, tier: entry.tier }));
+    },
+    state(name: string) {
+      const entry = providers.get(name);
+      if (!entry) {
+        throw new DebugError(
+          'STATE_PROVIDER_NOT_FOUND',
+          `debug: no state provider registered under "${name}"`,
+          {
+            registered: [...providers.keys()],
+            registrationHint: REGISTRATION_HINT,
+          },
+        );
+      }
+      return entry.fn();
+    },
+    stateAll() {
+      const result: Record<string, unknown> = {};
+      for (const [name, entry] of providers) {
+        try {
+          result[name] = entry.fn();
+        } catch (err) {
+          result[name] = { __error: String(err) };
+        }
+      }
+      return result;
+    },
+    commands(): DebugCommandInfo[] {
+      return [...commands.entries()].map(([name, entry]) => ({
+        name,
+        description: entry.description,
+        argsJsonSchema: entry.argsSchema
+          ? z.toJSONSchema(entry.argsSchema, { unrepresentable: 'any' })
+          : undefined,
+        locus: entry.locus ?? 'client',
+      }));
+    },
+    async invoke(name: string, args: unknown[]): Promise<unknown> {
+      const entry = commands.get(name);
+      if (!entry) {
+        throw new DebugError(
+          'DEBUG_COMMAND_NOT_REGISTERED',
+          `debug: no command registered under "${name}"`,
+          { registered: [...commands.keys()], registrationHint: REGISTRATION_HINT },
+        );
+      }
+      let parsedArgs: unknown[] = args;
+      if (entry.argsSchema) {
+        const result = entry.argsSchema.safeParse(args);
+        if (!result.success) {
+          throw new DebugError(
+            'DEBUG_COMMAND_ARGS_INVALID',
+            `debug: command "${name}" received invalid args`,
+            { issues: result.error.issues },
+          );
+        }
+        parsedArgs = result.data as unknown[];
+      }
+      if ((entry.locus ?? 'client') === 'server') {
+        return invokeServerCommand(name, parsedArgs);
+      }
+      try {
+        return await entry.fn(...parsedArgs);
+      } catch (cause) {
+        throw new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" threw`, { cause });
+      }
+    },
+    events(sinceTick?: number, sinceSeq?: number) {
+      return events(sinceTick, sinceSeq);
+    },
+  };
+
+  return {
+    adapter,
+    forWorld(worldId: string): DebugCtxSurface {
+      return {
+        registerStateProvider(name, fn, providerOpts) {
+          registerStateProvider(worldId, name, fn, providerOpts?.tier ?? 'observable');
+        },
+        registerCommand(name, spec, fn) {
+          // Cast: the public generic (`DebugCtxSurface.registerCommand`,
+          // `DebugCommandArgs<T>`) exists purely for the CALLER's inference —
+          // internally, every entry is stored/invoked through the same
+          // untyped `(...args: unknown[])` shape (`invoke()` parses `args`
+          // against `argsSchema` at the seam, not at the type level).
+          registerCommand(
+            worldId,
+            name,
+            spec as { description?: string; args?: z.ZodTuple; locus?: 'client' | 'server' },
+            fn as (...args: unknown[]) => unknown | Promise<unknown>,
+          );
+        },
+        emit(event, detail) {
+          emit(event, detail);
+        },
+        attachRoom(room) {
+          return attachRoom(room);
+        },
+      };
+    },
+    emitReact(event, detail) {
+      emit(event, detail);
+    },
+    strip(worldId?: string) {
+      // Defect 2 fix — scoped when `worldId` is given (a single mount's
+      // hot-reload re-seed), global otherwise (the whole game going away, or
+      // a test's blanket teardown). See this method's interface doc comment.
+      for (const [name, entry] of providers) {
+        if (entry.builtin) continue;
+        if (worldId !== undefined && entry.worldId !== worldId) continue;
+        providers.delete(name);
+        warnedProviders.delete(name);
+      }
+      for (const [name, entry] of commands) {
+        if (worldId !== undefined && entry.worldId !== worldId) continue;
+        commands.delete(name);
+        warnedCommands.delete(name);
+      }
+    },
+    setRoomDeclared(declared: boolean) {
+      roomDeclared = declared;
+    },
+    setInputActionsSource(worldId: string, fn: () => { name: string; valueType: string }[]) {
+      inputActionsSources.set(worldId, fn);
+    },
+    setInputTraceSource(worldId: string, fn: () => InputTraceSnapshot) {
+      inputTraceSources.set(worldId, fn);
+    },
+    setVirtualInputTarget(worldId: string, target: DebugVirtualInputTarget) {
+      virtualInputTargets.set(worldId, target);
+    },
+    getVirtualInputTarget(worldId?: string) {
+      const resolved = resolveInputWorldId(worldId);
+      return resolved !== null ? (virtualInputTargets.get(resolved) ?? null) : null;
+    },
+    setRunTicksTarget(target: RunTicksTarget) {
+      runTicksTarget = target;
+    },
+    getRunTicksTarget() {
+      return runTicksTarget;
+    },
+    getGameTick() {
+      return opts.getTick();
+    },
+    registerReactProvider(name, fn, providerOpts) {
+      const token = Symbol(name);
+      registerStateProvider(REACT_WORLD_ID, name, fn, providerOpts?.tier ?? 'observable', token);
+      return () => {
+        const entry = providers.get(name);
+        if (entry?.token === token) {
+          providers.delete(name);
+          warnedProviders.delete(name);
+        }
+      };
+    },
+    registerReactCommand(name, spec, fn) {
+      const token = Symbol(name);
+      // See the `forWorld().registerCommand` cast above — same reason.
+      registerCommand(
+        REACT_WORLD_ID,
+        name,
+        spec as { description?: string; args?: z.ZodTuple; locus?: 'client' | 'server' },
+        fn as (...args: unknown[]) => unknown | Promise<unknown>,
+        token,
+      );
+      return () => {
+        const entry = commands.get(name);
+        if (entry?.token === token) {
+          commands.delete(name);
+          warnedCommands.delete(name);
+        }
+      };
+    },
+  };
+}
+
+const registryByGame = new WeakMap<Game, DebugRegistry>();
+
+/** Called once by `createGame`, right after both the registry and the Game
+ *  shell object exist, to file the association {@link getDebugRegistry} reads. */
+export function registerDebugRegistry(game: Game, registry: DebugRegistry): void {
+  registryByGame.set(game, registry);
+}
+
+/** The game-scoped registry backing `game.systemAdapters.debug`, or `null` for
+ *  a `Game` built without one (there is always one for every `createGame`
+ *  call — `null` only for a `Game`-shaped stand-in a test builds by hand). */
+export function getDebugRegistry(game: Game): DebugRegistry | null {
+  return registryByGame.get(game) ?? null;
+}