@volter/editor-game 0.5.65

package/src/ingest/ingest-play-control.ts

@@ -0,0 +1,299 @@
+/**
+ * The play-state control surface over whatever `{ ingest }` root is live —
+ * the one seam `components/PlayBar.tsx` and the CLI relay
+ * (`ingest/ingest-play-commands.ts`) drive ▶/⏸/Step through.
+ *
+ * Reads the single session slot (`active-ingest.ts`) and nothing else; the
+ * mount paths call {@link setIngestPlaying} and the teardown path calls
+ * {@link resetIngestPlaySurface}.
+ */
+
+import { gameContractEpoch } from '../host/coverage/game-contract-seam-evidence';
+import { recordLiveSeamEvidence } from '@volter/editor-core/coverage/live-seam-evidence';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import { activateLiveDocument } from '@volter/editor-core/live-document';
+import type { VgaiGameContract } from '@volter/editor-project/adapter/ingest/game-contract';
+import { activeIngest, type IngestLifecycleControl } from './active-ingest';
+import { readIngestGameContract } from './game-contract-realm';
+
+/**
+ * The play-state control surface for the CURRENT ingest session (F17/F21):
+ * mounts are COLD by doctrine — the adapter sets `window.__vgaiMountCold`
+ * before the game's entry executes, and a session-driven game may defer its
+ * side-effects (backend connection, narrative, audio) until the first
+ * `play()`. Everything is contract-first (game-contract.ts): `lifecycle.start`
+ * is called AT MOST ONCE per mount — later ▶ presses resume rather than
+ * re-start, so games never need an idempotent start;
+ * Mounting normalizes `lifecycle.pause`/`resume` or the substrate's real
+ * `setPaused` fallback into ONE {@link IngestLifecycleControl}. This module's
+ * runtime consumers never choose between raw mechanisms, and a malformed
+ * half-pair never borrows its missing half from the fallback. Games that
+ * declare no `start` still get the pre-contract wire event.
+ */
+export interface IngestPlayControl {
+  readonly playing: boolean;
+  play(): void;
+  pause(): void;
+  resume(): void;
+  /**
+   * True only when the loop gate actually holds this game's
+   * frames (`ingest/same-realm-loop-gate.ts`), which is the only condition
+   * under which a single-frame step is a real thing rather than a button that
+   * lies.
+   */
+  readonly canStep: boolean;
+  /** Advance exactly one frame batch and hold again. No-op when `canStep` is false. */
+  step(): void;
+}
+
+let _ingestPlaying = false;
+
+/** Whether the live session's loop was last told to run (the status facet's
+ *  `playing`). */
+export function ingestPlaying(): boolean {
+  return _ingestPlaying;
+}
+
+/**
+ * THE one write to the ingest play state.
+ *
+ * An ingested game's input is gated by the same mechanisms a first-party play
+ * session's is (the engine's `InputManager.setEnabled` and `gated-globals.ts`'s
+ * lexical window/document shadow), driven by the input gate the mount installs.
+ */
+export function setIngestPlaying(playing: boolean): void {
+  _ingestPlaying = playing;
+}
+
+/**
+ * F26: the play surface's state is session-global (one active session,
+ * whatever its kind), so EVERY per-kind exit path resets it — the playing
+ * flag plus the cold-mount/played window globals the entry paths set.
+ */
+export function resetIngestPlaySurface(): void {
+  setIngestPlaying(false);
+  const w = window as unknown as { __vgaiMountCold?: boolean; __vgaiIngestPlayed?: boolean };
+  delete w.__vgaiMountCold;
+  delete w.__vgaiIngestPlayed;
+}
+
+/**
+ * F26 helper: the active session's kind + its own honest pause capability
+ * (D-V1: dispatches on the single slot, never a per-kind global).
+ * `null` when nothing is ingested.
+ */
+export interface IngestLifecycleFallback {
+  readonly setPaused?: ((paused: boolean) => void) | undefined;
+  readonly pauseGap?: string | undefined;
+  readonly step?: (() => void) | undefined;
+  readonly canStep?: (() => boolean) | undefined;
+}
+
+function runContractLifecycleEffect(
+  contract: VgaiGameContract,
+  member: 'start' | 'pause' | 'resume',
+  run: () => void,
+): void {
+  const receipt = (outcome: 'pass' | 'fail', detail: string): void =>
+    recordLiveSeamEvidence({
+      seam: `contract.lifecycle.${member}`,
+      subject: 'game',
+      epoch: gameContractEpoch(contract),
+      stage: 'effect',
+      outcome,
+      source: 'consumer',
+      detail,
+    });
+  try {
+    run();
+    receipt('pass', `the mounted ingest lifecycle consumed lifecycle.${member}`);
+  } catch (error) {
+    receipt(
+      'fail',
+      `lifecycle.${member} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    throw error;
+  }
+}
+
+/**
+ * Normalize raw lifecycle declarations and a substrate fallback ONCE, at
+ * mount. The declared pause/resume pair wins as one indivisible capability;
+ * a half-pair is malformed and may never silently mix with the fallback.
+ * Step belongs only to the fallback that actually took the hold.
+ */
+export function bindIngestLifecycle(
+  fallback: IngestLifecycleFallback = {},
+): IngestLifecycleControl {
+  const contract = readIngestGameContract();
+  const declared = contract?.lifecycle;
+  const start = () => {
+    if (contract && declared?.start) {
+      runContractLifecycleEffect(contract, 'start', () => declared.start?.());
+      return;
+    }
+    window.dispatchEvent(new CustomEvent('vgai:ingest-play'));
+  };
+
+  const hasPause = typeof declared?.pause === 'function';
+  const hasResume = typeof declared?.resume === 'function';
+  if (contract && hasPause !== hasResume) {
+    return {
+      start,
+      pauseGap: hasPause
+        ? 'the game contract declares lifecycle.pause without lifecycle.resume'
+        : 'the game contract declares lifecycle.resume without lifecycle.pause',
+    };
+  }
+  if (contract && hasPause && hasResume) {
+    return {
+      start,
+      setPaused: (paused) =>
+        runContractLifecycleEffect(contract, paused ? 'pause' : 'resume', () => {
+          if (paused) declared?.pause?.();
+          else declared?.resume?.();
+        }),
+    };
+  }
+  if (fallback.setPaused) {
+    return {
+      start,
+      setPaused: fallback.setPaused,
+      ...(fallback.step ? { step: fallback.step } : {}),
+      ...(fallback.canStep ? { canStep: fallback.canStep } : {}),
+    };
+  }
+  return {
+    start,
+    pauseGap:
+      fallback.pauseGap ??
+      'the game declares no lifecycle.pause/resume pair and its mounted adapter exposes no setPaused capability',
+  };
+}
+
+export function activeIngestPauseGap(): string | null {
+  const active = activeIngest();
+  if (!active) return null;
+  return active.session.lifecycle.pauseGap ?? null;
+}
+
+/**
+ * D-B2 (Slice B): fan a pause/resume state out to
+ * every mounted composite sibling's OPTIONAL `SiblingMount.setPaused`
+ * (`ingest-siblings.ts`), AFTER the primary surface's own pause/resume
+ * already ran — mirrors `exitActiveIngest`'s reverse-order dispose
+ * fan-out (the same "one bad sibling never breaks the rest"
+ * isolation: per-sibling try/catch, loud log on failure, never swallowed
+ * silently). A sibling with no `setPaused` at all (the bare `default-react`
+ * sibling, D-B1 — it has no loop to gate) is silently skipped via the
+ * optional call — never an error, never a fabricated pause. A no-op (empty
+ * `siblings`, or no live session at all) for every non-composite entry
+ * path, unchanged.
+ */
+function fanOutSiblingPause(paused: boolean): void {
+  const active = activeIngest();
+  if (!active) return;
+  for (const sibling of active.siblings) {
+    try {
+      sibling.setPaused?.(paused);
+    } catch (err) {
+      editorConsole.error(`Composite sibling setPaused(${paused}) failed: ${err}`, 'ingest');
+    }
+  }
+}
+
+/**
+ * The DECLARED contract for whatever is ingested right now.
+ *
+ * The game runs in the editor's own realm and declares on the host window —
+ * either from its own entry, or from the host-added module the manifest names
+ * in `ingest.contractShim`, which the mount imports first.
+ */
+export function activeIngestContract(): VgaiGameContract | null {
+  return readIngestGameContract();
+}
+
+export function getIngestPlayControl(): IngestPlayControl | null {
+  const lifecycle = activeIngest()?.session.lifecycle;
+  if (!lifecycle?.setPaused) return null;
+  /** HOLD content time through the mount-normalized lifecycle capability. */
+  const hold = () => {
+    lifecycle.setPaused?.(true);
+    fanOutSiblingPause(true);
+    setIngestPlaying(false);
+  };
+  /** RELEASE through the exact same normalized capability that took the hold. */
+  const release = () => {
+    lifecycle.setPaused?.(false);
+    fanOutSiblingPause(false);
+    setIngestPlaying(true);
+  };
+  return {
+    get playing() {
+      return _ingestPlaying;
+    },
+    play() {
+      // ▶ BRINGS THE GAME DOCUMENT TO THE FRONT. A boot-mounted ingest lands
+      // in Edit on purpose (`ingest-boot-viewport.ts`), so without this the
+      // one gesture that starts the game left the person on the authoring
+      // Scene — for a root whose content exists only under its own loop, the
+      // "No renderable content" card, with the game running unseen behind it
+      // (walk 3, beat 19: `playState: "playing"`, `activeViewportTab: "edit"`,
+      // one canvas in the page). `live-document.ts` owns that activation, and
+      // going through it is also what writes the play tab the input gate
+      // reads — so the game is drivable and not merely visible. A play-time
+      // mount already did this for itself (`deferred-ingest-play.ts`).
+      activateLiveDocument();
+      // Late-constructed game clients must not re-defer: the flag records
+      // that play already happened this session — and makes ▶-after-⏸ a
+      // RESUME, so `lifecycle.start` fires at most once per mount.
+      const w = window as unknown as { __vgaiIngestPlayed?: boolean };
+      if (w.__vgaiIngestPlayed) return release();
+      w.__vgaiIngestPlayed = true;
+      lifecycle.start();
+      // A mount ends HELD (see `ingestContentTimeForMode`), so the first ▶ is
+      // ALSO the release of that hold — same path every later ▶ takes.
+      release();
+    },
+    pause: hold,
+    resume: release,
+    canStep: !!lifecycle.step && (lifecycle.canStep?.() ?? true),
+    step() {
+      if (lifecycle.canStep?.() === false) return;
+      lifecycle.step?.();
+      setIngestPlaying(false);
+    },
+  };
+}
+
+/**
+ * THE hold/release decision for an ingested game's content time — pure, so the
+ * rule is checkable without a browser, a mount or a clock.
+ *
+ * The rule is the ontology's, not this lane's: LOADING CONSTRUCTS, PLAY RUNS
+ * (ARCHITECTURE-CORE). Content time follows the editor's MODE and nothing else
+ * — not whether a mount just finished, not how far a game got into its own
+ * boot. A mount is simply the first moment this decision is evaluated, which is
+ * why "mount in Edit" needs no case of its own.
+ */
+export function ingestContentTimeForMode(mode: 'edit' | 'play'): 'held' | 'released' {
+  return mode === 'edit' ? 'held' : 'released';
+}
+
+/**
+ * Apply {@link ingestContentTimeForMode} to the live session, through the play
+ * control's OWN pause path — so a game that declares `lifecycle.pause` is held
+ * by its own hand rather than by an outside-in loop gate that may not reach it.
+ *
+ * Only the HOLD half acts here, because only the hold half has a caller: ▶
+ * (`play`/`resume` above) is the one thing that releases, and it is a user
+ * action, never something a mode read may fabricate. Returns whether it held,
+ * so a caller can log honestly rather than assume.
+ */
+export function holdIngestContentTimeForMode(mode: 'edit' | 'play'): boolean {
+  if (ingestContentTimeForMode(mode) !== 'held') return false;
+  const control = getIngestPlayControl();
+  if (!control) return false;
+  control.pause();
+  return true;
+}

package/src/ingest/ingest-render-debug.ts

@@ -0,0 +1,320 @@
+/**
+ * `renderDebug` for an INGESTED world — the engine-owned auto-registration
+ * the first-party mount already does (`setup-three-root-adapter.ts` builds the
+ * same wiring under the same real-WebGL2-context guard), reached for a game
+ * whose render loop the host does not own.
+ *
+ * ## Why this is host-owned and not per-game
+ *
+ * `RenderDebugAdapter` needs three things: a real WebGL2 context, the live scene
+ * to attribute draws against, and a bracket around the render pass. A captured
+ * ingest mount has all three and the host already holds them — the capture trap
+ * (`@volter/threejs-runtime/adapter/ingest/scene-capture`) stands between the game and its own
+ * `WebGLRenderer.render`, which is the ONLY place a host can see a
+ * self-driven game's pass begin and end. So no game declares this slot: it is
+ * derived from the mount, exactly like the first-party path, and a game that
+ * declared one would be shimming what the host can measure.
+ *
+ * ## Why the game's own `three` instance is not a problem here
+ *
+ * `dev/render-debug-adapter.ts` never uses `instanceof`: it duck-types
+ * renderables (`isMesh`/`isPoints`/…) and patches `onBeforeRender` on the
+ * objects themselves. `dev/render-memory.ts` is the same shape
+ * (`isTexture`/`isBufferGeometry` flags, numeric format enums), so neither
+ * depends on the captured objects being the host's own classes.
+ *
+ * Returns `null` — the honest absence, which leaves the Frame debugger showing
+ * its own "no adapter" notice — whenever the mount has no real WebGL2 context to
+ * capture from (a headless harness, a stub renderer).
+ *
+ * ## The CANVAS lane, and what it can and cannot say
+ *
+ * The same three things are needed on the Pixi surface, and the mount holds two
+ * and a half of them. `webgl-frame-capture.ts` is GL-LEVEL — it shadows the
+ * five WebGL2 draw entry points on whatever real context it is handed and knows
+ * nothing about three — so it is reused verbatim over the captured Pixi
+ * renderer's own `gl`. The bracket is the renderer's own published seam, its
+ * `prerender`/`postrender` runners (`@volter/game-runtime/pixi/render-pass-bracket`).
+ *
+ * What is NOT there is per-draw attribution, and it is absent for a structural
+ * reason rather than a missing patch point: three calls `onBeforeRender` on the
+ * object it is about to draw, whereas Pixi's batcher merges many display
+ * objects into a single draw, so no display object IS the author of a given
+ * draw. `createCanvasIngestRenderDebug` therefore omits `scene` and every draw
+ * lands in `totals.unattributed` — the Frame debugger reads that count and says
+ * so, which is the honest answer and not a degraded one.
+ *
+ * Render memory is absent on this lane for the same kind of reason.
+ * `RenderMemorySnapshot` is a WHOLE-snapshot shape with non-nullable geometry
+ * counts and byte totals; Pixi's renderer publishes one real managed collection
+ * (`renderer.texture.managedTextures`) and no managed geometry or program
+ * collection at all, so filling the geometry half with zeros is exactly the
+ * fabrication the anti-shim rule forbids. The capability is therefore ABSENT
+ * (`memorySnapshot` undefined), which `frame-debugger-model.ts` already reports
+ * per-capability and the Profiler's memory view already renders as its own
+ * notice.
+ */
+
+import { adapterObservations } from '@volter/editor-core/adapter-observation';
+import { createContractDebugAdapter } from '@volter/game-runtime/adapter/ingest/contract-debug-adapter';
+import {
+  type ContractSurface,
+  projectContractSystemAdapters,
+} from '@volter/game-runtime/adapter/ingest/contract-system-adapters';
+import { mergeDebugAdapters } from '@volter/game-runtime/adapter/ingest/merge-debug-adapters';
+import { createObservationDebugAdapter } from '@volter/game-runtime/adapter/ingest/observation-debug-adapter';
+import {
+  createRenderDebugAdapter,
+  frameCaptureContextFor,
+  type RenderDebugWiring,
+} from '@volter/game-runtime/dev/render-debug-adapter';
+import { collectRenderMemory } from '@volter/game-runtime/dev/render-memory';
+import { createWebGLFrameCapture } from '@volter/game-runtime/dev/webgl-frame-capture';
+import { pixiRenderingContext } from '@volter/game-runtime/pixi/render-pass-bracket';
+import type { ObservationDeclaration } from '@volter/editor-project/adapter/adapter-module';
+import type { VgaiGameSystems } from '@volter/editor-project/adapter/ingest/game-contract';
+import type { SystemAdapters } from '@volter/editor-project/adapter/system-adapter';
+import type { RenderPassHooks } from '@volter/threejs-runtime/adapter/ingest/scene-capture';
+import type * as THREE from 'three';
+import { ingestGameRealmWindow } from './game-contract-realm';
+import {
+  deliverArmedIngestFrame,
+  type IngestFrameSource,
+  setIngestFrameSource,
+} from './ingest-frame-snapshot';
+
+/** The pieces of a captured runtime this needs. Structural so a headless test
+ *  can hand in a mock GL context and a plain scene, exactly as the first-party
+ *  render-debug suite does. */
+export interface IngestRenderDebugRuntime {
+  readonly scene: THREE.Object3D;
+  readonly renderer: {
+    getContext?(): unknown;
+    readonly info?: THREE.WebGLInfo | undefined;
+    /** Read by the same-frame snapshot only (`ingest-frame-snapshot.ts`); a
+     *  runtime without them simply has no snapshot capability. */
+    readonly domElement?: unknown;
+    getRenderTarget?(): unknown;
+  };
+}
+
+/**
+ * Build the render-debug wiring for a captured ingest runtime, or `null` when
+ * the mount cannot host frame capture. The caller installs
+ * `beforeRender`/`afterRender` as the capture handle's render-pass hooks and
+ * calls `dispose()` on unmount.
+ */
+export function createIngestRenderDebug(rt: IngestRenderDebugRuntime): RenderDebugWiring | null {
+  // Reads a renderer the host did not construct: an unfamiliar/stub shape must
+  // degrade to "no adapter", never break the mount.
+  let glContext: unknown;
+  try {
+    glContext = typeof rt.renderer.getContext === 'function' ? rt.renderer.getContext() : undefined;
+  } catch {
+    return null;
+  }
+  // `headless: false` — this path only runs for a mount that actually rendered a
+  // frame; `frameCaptureContextFor` is the ONE predicate deciding whether the
+  // context is real, shared with the first-party mount so both sides agree.
+  const context = frameCaptureContextFor(false, glContext);
+  if (!context) return null;
+  const info = rt.renderer.info;
+  return createRenderDebugAdapter({
+    capture: createWebGLFrameCapture(context),
+    scene: rt.scene,
+    // `memorySnapshot` is the W3a-style OPTIONAL capability: attached only when
+    // the renderer exposes its own `info`, absent otherwise (never a zeroed
+    // snapshot standing in for a count nobody read).
+    ...(info ? { memory: () => collectRenderMemory(rt.scene, info) } : {}),
+  });
+}
+
+/** The pieces of a captured CANVAS runtime this needs — just the game's own
+ *  Pixi renderer, because the two things the three shape carries beyond it
+ *  (a traversable scene, a `renderer.info`) have no honest Pixi analogue (see
+ *  the module header). Structural, so a headless test hands in a plain object
+ *  with a mock `gl` and a pair of runners. */
+export interface CanvasIngestRenderDebugRuntime {
+  readonly renderer: unknown;
+}
+
+/**
+ * Build the render-debug wiring for a captured PIXI ingest runtime, or `null`
+ * when the mount cannot host frame capture — no real WebGL2 context (a WebGPU
+ * or headless renderer), or a renderer that publishes no render-pass runners to
+ * bracket. Both are the same honest absence the three lane's `null` is.
+ *
+ * The caller installs `beforeRender`/`afterRender` through
+ * {@link installPixiRenderPassBracket} and calls `dispose()` on unmount.
+ */
+export function createCanvasIngestRenderDebug(
+  rt: CanvasIngestRenderDebugRuntime,
+): RenderDebugWiring | null {
+  // Reads a renderer the host did not construct: an unfamiliar/stub shape must
+  // degrade to "no adapter", never break the mount.
+  let glContext: unknown;
+  try {
+    glContext = pixiRenderingContext(rt.renderer);
+  } catch {
+    return null;
+  }
+  // The SAME predicate the three lane uses, so both surfaces agree on what
+  // counts as a real context. `headless: false` — this path only runs for a
+  // mount whose game already rendered a capturable frame.
+  const context = frameCaptureContextFor(false, glContext);
+  if (!context) return null;
+  return createRenderDebugAdapter({
+    capture: createWebGLFrameCapture(context),
+    // No `scene`: this surface has no per-draw annotation seam, so every draw
+    // is honestly unattributed. No `memory`: see the module header.
+  });
+}
+
+/** What a three ingest mount publishes to `setActiveSystems`, plus the
+ *  render-debug handle its `dispose()` has to release. */
+export interface IngestSystemsWiring {
+  /** Spread onto the `MountedThreeRoot`. Empty when nothing was reachable —
+   *  the caller omits `systems` entirely then, keeping the pre-contract floor. */
+  readonly systems: SystemAdapters;
+  /** Non-null only when a real frame capture was built; `dispose()` on unmount. */
+  readonly renderDebug: RenderDebugWiring | null;
+  /**
+   * One sentence per name BOTH debug feeders declared — the game's own contract
+   * and its adapter's observation table (`merge-debug-adapters.ts`). Empty is
+   * the norm; non-empty is a defect in whichever of the two the reader owns, and
+   * the mount says so out loud rather than leaving the coded refusal to be
+   * discovered by whoever calls the name first.
+   */
+  readonly debugCollisions: readonly string[];
+}
+
+/**
+ * THE one place an ingest mount's `SystemAdapters` bag is assembled — on EITHER
+ * surface — so a shim never has to know anything about the mount, and no second
+ * assembly can drift into publishing a different surface from the same
+ * declaration.
+ *
+ * Four sources, each with a different provenance:
+ *  - `debug` — projected from the contract's own `commands`/`state`;
+ *  - `debug`, AGAIN — projected from the loaded ADAPTER's observation
+ *    declarations (`@volter/game-runtime/adapter/ingest/observation-debug-adapter`).
+ *    These two are peers onto ONE slot, so they are MERGED
+ *    (`merge-debug-adapters.ts`) rather than layered: a name declared by both
+ *    is refused by a coded error naming both sources, never shadowed;
+ *  - the game-declarable slots — projected from its `systemAdapters` carrier
+ *    (an IMPLEMENTED-EMPTY slot is deliberately NOT bound; it is an answer the
+ *    coverage report reads, not an adapter);
+ *  - `renderDebug` — engine-owned, derived from the captured runtime, and wired
+ *    to that surface's render-pass bracket.
+ *
+ * The observation half is read HERE rather than threaded in by each mount, and
+ * that is the point of "the one place": the adapter's table is a PROJECT fact
+ * the loader already resolved (`project-adapter.ts` loads it per project, not
+ * per mount), so a lane cannot forget to pass it. Both parameters exist only as
+ * a test seam.
+ *
+ * `runtime` and `canvasRuntime` are the SAME source in two surface shapes, and
+ * are mutually exclusive: a mount has captured a three renderer or a Pixi one,
+ * never both. They stay separate types rather than one widened type because the
+ * three shape's `scene`/`info` have no honest Pixi analogue — a union that
+ * merely made them optional would let a three mount silently lose its
+ * attribution. What they share is this function and the `setRenderPassHooks`
+ * slot; the MECHANISM behind that slot is each surface's own (the render
+ * accessor-trap for three, the renderer's runners for Pixi).
+ */
+export function wireIngestSystems(opts: {
+  readonly contractSystems: VgaiGameSystems | undefined;
+  /**
+   * THIS MOUNT'S SURFACE, stated rather than inferred from which runtime is
+   * present — the recognized-Phaser/Babylon canvas branch captures neither
+   * renderer and would infer nothing. The projection needs it to check the
+   * physics slot's keying (`contract-system-adapters.ts` header).
+   */
+  readonly surface: ContractSurface;
+  /** Absent when there is no captured THREE renderer to bracket. */
+  readonly runtime?: IngestRenderDebugRuntime | undefined;
+  /** Absent when there is no captured PIXI renderer to bracket. */
+  readonly canvasRuntime?: CanvasIngestRenderDebugRuntime | undefined;
+  /**
+   * The mount's OWN resolved physics carrier, which REPLACES the projected
+   * `physics` slot when supplied.
+   *
+   * The canvas mount is the case and the reason: the carrier its gizmo path
+   * actually uses is the declared one COMPOSED with the host's registry-backed
+   * one (`mount-canvas-ingest-root.ts`), and the bag must publish that same
+   * object — a coverage row reading `bound` off a different instance than the
+   * editor calls would be true about nothing. Absent ⇒ the projection's own
+   * slot stands, which is every other mount.
+   */
+  readonly physics?: SystemAdapters['physics'] | undefined;
+  readonly setRenderPassHooks?: ((hooks: RenderPassHooks | null) => void) | undefined;
+  /**
+   * TEST SEAM. Omitted — every shipped mount — this is the loaded adapter's own
+   * table, which is what makes the projection impossible for a lane to forget.
+   */
+  readonly observation?: readonly ObservationDeclaration[] | undefined;
+  /**
+   * The mounted game handle an observation `answer` is evaluated against.
+   *
+   * Omitted — every shipped mount — it is THIS REALM: an ingest mount runs the
+   * game's own modules in its gated realm, so the game's public handles are on
+   * that realm's window proxy (not the editor tab's real `window`) and that is
+   * the only honest thing to hand a foreign game's closure
+   * (`observation-debug-adapter.ts` states the whole argument). Passed
+   * explicitly only by tests, which hand a fake realm.
+   */
+  readonly game?: unknown;
+}): IngestSystemsWiring {
+  const contractDebug = createContractDebugAdapter(opts.contractSystems);
+  const observationDebug = createObservationDebugAdapter(
+    opts.observation ?? adapterObservations(),
+    'game' in opts ? opts.game : typeof window === 'undefined' ? null : ingestGameRealmWindow(),
+  );
+  const { adapter: debug, collisions } = mergeDebugAdapters([
+    { label: "the game's own contract (window.vgaiGame.systems)", adapter: contractDebug },
+    { label: "its adapter's observation table (vgai.adapter.ts)", adapter: observationDebug },
+  ]);
+  const declared = projectContractSystemAdapters(opts.contractSystems, opts.surface);
+  const renderDebug = opts.runtime
+    ? createIngestRenderDebug(opts.runtime)
+    : opts.canvasRuntime
+      ? createCanvasIngestRenderDebug(opts.canvasRuntime)
+      : null;
+  // ONE bracket, TWO consumers. `setRenderPassHooks` is a single-writer slot
+  // (last writer wins), so this is the only place that may install it, and
+  // anything needing the game's render pass multiplexes here rather than
+  // opening a second seam. The second consumer is the same-frame canvas
+  // snapshot (`ingest-frame-snapshot.ts`) that makes `vgai screenshot` readable
+  // over a game whose canvas has no `preserveDrawingBuffer`; it costs nothing
+  // until armed, and `deliverArmedIngestFrame` no-ops while no source is set —
+  // which is the canvas lane's state, because a Pixi ingest is already
+  // photographable through its own registered `Application`
+  // (`stories/story-pixi-preview.ts`, registered at the canvas mount) and needs
+  // no second route to the same pixels.
+  if (opts.runtime) setIngestFrameSource(opts.runtime as IngestFrameSource);
+  if (opts.setRenderPassHooks && (renderDebug || opts.runtime)) {
+    opts.setRenderPassHooks({
+      // Neither hook may throw — they run inside the game's own render call.
+      before: () => {
+        renderDebug?.beforeRender();
+      },
+      after: () => {
+        try {
+          renderDebug?.afterRender();
+        } finally {
+          deliverArmedIngestFrame();
+        }
+      },
+    });
+  }
+  return {
+    systems: {
+      ...declared.bound,
+      ...(opts.physics ? { physics: opts.physics } : {}),
+      ...(debug ? { debug } : {}),
+      ...(renderDebug ? { renderDebug: renderDebug.adapter } : {}),
+    },
+    renderDebug,
+    debugCollisions: collisions,
+  };
+}