@vgai/engine 0.5.15 → 0.5.16

package/dist/adapter/ingest/game-contract-seams.d.ts

@@ -0,0 +1,214 @@
+/** Exhaustive proof requirements for the game→host contract. Declarations are
+ * intentionally insufficient for lifecycle, navigation, commands, state, and
+ * system carriers: their consumers must produce stronger receipts. */
+export declare const GAME_CONTRACT_SHAPE: {
+    readonly contractVersion: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly root: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly presentation: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly world: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly ready: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly lifecycle: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly scenes: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly systems: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+};
+export declare const GAME_LIFECYCLE_SHAPE: {
+    readonly start: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly pause: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+    readonly resume: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+};
+export declare const GAME_SCENES_SHAPE: {
+    readonly list: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "operation";
+    };
+    readonly current: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "operation";
+    };
+    readonly goTo: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+};
+export declare const GAME_SCENE_SHAPE: {
+    readonly id: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly label: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+};
+export declare const GAME_COMMAND_SHAPE: {
+    readonly name: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly description: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly argsJsonSchema: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly run: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "effect";
+    };
+};
+export declare const GAME_STATE_PROVIDER_SHAPE: {
+    readonly name: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly tier: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly read: {
+        readonly optional: false;
+        readonly kind: "function";
+        readonly required: "operation";
+    };
+};
+export declare const GAME_HIERARCHY_GROUP_SHAPE: {
+    readonly id: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly label: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly count: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+};
+export declare const GAME_SYSTEMS_SHAPE: {
+    readonly commands: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly state: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly hierarchy: {
+        readonly optional: true;
+        readonly kind: "function";
+        readonly required: "operation";
+    };
+    readonly systemAdapters: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+};
+export declare const GAME_SYSTEM_ADAPTERS_SHAPE: {
+    readonly physics: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly networking: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly navigation: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "operation";
+    };
+    readonly audio: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly camera: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+    readonly renderDebug: {
+        readonly optional: true;
+        readonly kind: "value";
+        readonly required: "effect";
+    };
+};
+export declare const GAME_SYSTEM_EMPTY_SHAPE: {
+    readonly present: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "shape";
+    };
+    readonly evidence: {
+        readonly optional: false;
+        readonly kind: "value";
+        readonly required: "claim";
+    };
+};
+//# sourceMappingURL=game-contract-seams.d.ts.map

package/dist/adapter/ingest/game-contract-seams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-contract-seams.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract-seams.ts"],"names":[],"mappings":"AAAA;;sEAEsE;AAgBtE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAS9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;CAI/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAI5B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAG3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;CAK7B,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;CAIpC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;CAIrC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;CAK7B,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOrC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;CAGlC,CAAC"}

package/dist/adapter/ingest/game-contract-seams.js

@@ -0,0 +1,62 @@
+/** Exhaustive proof requirements for the game→host contract. Declarations are
+ * intentionally insufficient for lifecycle, navigation, commands, state, and
+ * system carriers: their consumers must produce stronger receipts. */
+import { defineSeamShape } from '../seam-evidence';
+export const GAME_CONTRACT_SHAPE = defineSeamShape()({
+    contractVersion: { optional: false, kind: 'value', required: 'shape' },
+    root: { optional: true, kind: 'value', required: 'effect' },
+    presentation: { optional: true, kind: 'value', required: 'effect' },
+    world: { optional: true, kind: 'value', required: 'effect' },
+    ready: { optional: true, kind: 'value', required: 'effect' },
+    lifecycle: { optional: true, kind: 'value', required: 'effect' },
+    scenes: { optional: true, kind: 'value', required: 'effect' },
+    systems: { optional: true, kind: 'value', required: 'operation' },
+});
+export const GAME_LIFECYCLE_SHAPE = defineSeamShape()({
+    start: { optional: true, kind: 'function', required: 'effect' },
+    pause: { optional: true, kind: 'function', required: 'effect' },
+    resume: { optional: true, kind: 'function', required: 'effect' },
+});
+export const GAME_SCENES_SHAPE = defineSeamShape()({
+    list: { optional: false, kind: 'function', required: 'operation' },
+    current: { optional: false, kind: 'function', required: 'operation' },
+    goTo: { optional: false, kind: 'function', required: 'effect' },
+});
+export const GAME_SCENE_SHAPE = defineSeamShape()({
+    id: { optional: false, kind: 'value', required: 'shape' },
+    label: { optional: false, kind: 'value', required: 'shape' },
+});
+export const GAME_COMMAND_SHAPE = defineSeamShape()({
+    name: { optional: false, kind: 'value', required: 'shape' },
+    description: { optional: true, kind: 'value', required: 'shape' },
+    argsJsonSchema: { optional: true, kind: 'value', required: 'shape' },
+    run: { optional: false, kind: 'function', required: 'effect' },
+});
+export const GAME_STATE_PROVIDER_SHAPE = defineSeamShape()({
+    name: { optional: false, kind: 'value', required: 'shape' },
+    tier: { optional: true, kind: 'value', required: 'shape' },
+    read: { optional: false, kind: 'function', required: 'operation' },
+});
+export const GAME_HIERARCHY_GROUP_SHAPE = defineSeamShape()({
+    id: { optional: false, kind: 'value', required: 'shape' },
+    label: { optional: false, kind: 'value', required: 'shape' },
+    count: { optional: false, kind: 'value', required: 'operation' },
+});
+export const GAME_SYSTEMS_SHAPE = defineSeamShape()({
+    commands: { optional: true, kind: 'value', required: 'operation' },
+    state: { optional: true, kind: 'value', required: 'operation' },
+    hierarchy: { optional: true, kind: 'function', required: 'operation' },
+    systemAdapters: { optional: true, kind: 'value', required: 'operation' },
+});
+export const GAME_SYSTEM_ADAPTERS_SHAPE = defineSeamShape()({
+    physics: { optional: true, kind: 'value', required: 'effect' },
+    networking: { optional: true, kind: 'value', required: 'operation' },
+    navigation: { optional: true, kind: 'value', required: 'operation' },
+    audio: { optional: true, kind: 'value', required: 'effect' },
+    camera: { optional: true, kind: 'value', required: 'effect' },
+    renderDebug: { optional: true, kind: 'value', required: 'effect' },
+});
+export const GAME_SYSTEM_EMPTY_SHAPE = defineSeamShape()({
+    present: { optional: false, kind: 'value', required: 'shape' },
+    evidence: { optional: false, kind: 'value', required: 'claim' },
+});

package/dist/adapter/ingest/game-contract.d.ts

@@ -25,9 +25,11 @@ import type { AudioAdapter, CameraAdapter, NavigationAdapter, NetworkingAdapter,
  * executes, the game may defer its session side-effects (backend connections,
  * narrative, audio) and render a quiet, inspectable scene; the host calls
  * `start()` — at most once per mount — when the user presses ▶. Declaring
- * `pause`/`resume` means the game can genuinely freeze/unfreeze itself; the
- * host prefers these over its outside-in loop gate (which cannot gate a raw
- * requestAnimationFrame loop at all — R3F games, notably).
+ * `pause`/`resume` means the game can genuinely freeze/unfreeze itself. They
+ * are one indivisible pair: the ingest adapter binds that pair as its mounted
+ * lifecycle control, or binds its outside-in loop gate when neither is
+ * declared. Host consumers see only the bound control; they never mix one
+ * declared half with a fallback half.
  */
 export interface VgaiGameLifecycle {
     start?(): void;

package/dist/adapter/ingest/game-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"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"}

package/dist/adapter/ingest/game-contract.js

@@ -18,6 +18,7 @@
  * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems), WO-SYS2
  * (`systems.systemAdapters`).
  */
+import { GAME_SCENES_SHAPE } from './game-contract-seams';
 /**
  * Read the declared contract, if any. The `contractVersion` gate is the
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
@@ -38,7 +39,9 @@ export function readGameContract(scope = typeof window === 'undefined' ? null :
 }
 /** The endpoints a scene surface must carry: every one of them is called by the
  *  projection, so a declaration missing any cannot be honoured. */
-const SCENES_REQUIRED_MEMBERS = ['list', 'current', 'goTo'];
+const SCENES_REQUIRED_MEMBERS = Object.entries(GAME_SCENES_SHAPE)
+    .filter(([, spec]) => !spec.optional)
+    .map(([member]) => member);
 /**
  * Read the declared {@link VgaiGameScenes}, refusing a malformed one BY NAME.
  *

package/dist/adapter/ingest/merge-debug-adapters.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ONE `DebugAdapter` out of several projections of the same mount.
+ *
+ * Two feeders exist today and they are peers, not layers: the game's own
+ * declared system surface (`contract-debug-adapter.ts`, from
+ * `window.vgaiGame.systems`) and its adapter module's observation table
+ * (`observation-debug-adapter.ts`). Both project onto the ONE runtime door the
+ * editor and `vgai eval` already read (`SystemAdapters.debug`), so the merge
+ * belongs here rather than in a second slot — a consumer must not be able to
+ * tell a name's provenance, which is the whole point of both projections.
+ *
+ * ## A collision REFUSES the name; it never shadows it
+ *
+ * When two feeders declare the same provider or command name, one of them would
+ * otherwise win silently and an agent would read the wrong thing with every log
+ * line still saying success. So the merged adapter:
+ *
+ *   - LISTS the name once (it is declared, and hiding it would be its own lie);
+ *   - REFUSES to answer it with a coded `DEBUG_NAME_COLLISION` naming BOTH
+ *     sources, at `state()` / `invoke()` and per-key inside `stateAll()`;
+ *   - reports the collisions to the caller ({@link MergedDebugAdapters}) so the
+ *     mount can say so out loud where a person will see it, instead of the
+ *     refusal waiting to be discovered by whoever calls the name first.
+ *
+ * The refusal is per-NAME, not per-mount, deliberately: killing the mount would
+ * cost a user their whole game to protect against one ambiguous read, and the
+ * per-name refusal already gives the same guarantee — nothing is silently
+ * shadowed — with none of the collateral.
+ */
+import type { DebugAdapter } from '../system-adapter';
+/** One feeder, with the words a collision message names it by. */
+export interface DebugAdapterSource {
+    /** How this projection is named to a reader — its provenance, in prose. */
+    readonly label: string;
+    /** `null` when this feeder projected nothing (the honest floor both return). */
+    readonly adapter: DebugAdapter | null;
+}
+export interface MergedDebugAdapters {
+    /** The one door, or `null` when no feeder projected anything. */
+    readonly adapter: DebugAdapter | null;
+    /** One sentence per colliding name, naming both sources. Empty is the norm. */
+    readonly collisions: readonly string[];
+}
+/**
+ * Fold every projection of one mount onto a single {@link DebugAdapter}.
+ *
+ * `events()` concatenates, because an event ring is append-only and two rings
+ * genuinely both happened — there is no name to collide on. Everything else is
+ * name-keyed and therefore goes through the collision rule above.
+ */
+export declare function mergeDebugAdapters(sources: readonly DebugAdapterSource[]): MergedDebugAdapters;
+//# sourceMappingURL=merge-debug-adapters.d.ts.map

package/dist/adapter/ingest/merge-debug-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-debug-adapters.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/merge-debug-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAsC,MAAM,mBAAmB,CAAC;AAE1F,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAsCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,mBAAmB,CA0F9F"}

package/dist/adapter/ingest/merge-debug-adapters.js

@@ -0,0 +1,141 @@
+/**
+ * ONE `DebugAdapter` out of several projections of the same mount.
+ *
+ * Two feeders exist today and they are peers, not layers: the game's own
+ * declared system surface (`contract-debug-adapter.ts`, from
+ * `window.vgaiGame.systems`) and its adapter module's observation table
+ * (`observation-debug-adapter.ts`). Both project onto the ONE runtime door the
+ * editor and `vgai eval` already read (`SystemAdapters.debug`), so the merge
+ * belongs here rather than in a second slot — a consumer must not be able to
+ * tell a name's provenance, which is the whole point of both projections.
+ *
+ * ## A collision REFUSES the name; it never shadows it
+ *
+ * When two feeders declare the same provider or command name, one of them would
+ * otherwise win silently and an agent would read the wrong thing with every log
+ * line still saying success. So the merged adapter:
+ *
+ *   - LISTS the name once (it is declared, and hiding it would be its own lie);
+ *   - REFUSES to answer it with a coded `DEBUG_NAME_COLLISION` naming BOTH
+ *     sources, at `state()` / `invoke()` and per-key inside `stateAll()`;
+ *   - reports the collisions to the caller ({@link MergedDebugAdapters}) so the
+ *     mount can say so out loud where a person will see it, instead of the
+ *     refusal waiting to be discovered by whoever calls the name first.
+ *
+ * The refusal is per-NAME, not per-mount, deliberately: killing the mount would
+ * cost a user their whole game to protect against one ambiguous read, and the
+ * per-name refusal already gives the same guarantee — nothing is silently
+ * shadowed — with none of the collateral.
+ */
+import { DebugError } from '../../runtime/debug-registry';
+function collisionError(name, labels) {
+    return new DebugError('DEBUG_NAME_COLLISION', `"${name}" is declared by more than one source (${labels.join(' and ')}) — refusing to ` +
+        'answer rather than picking one silently. Rename it in whichever source you own.', { name, sources: [...labels] });
+}
+/** Names each feeder claims, in listing order, de-duplicated within a feeder. */
+function claimedNames(sources, face) {
+    const order = [];
+    const labelsByName = new Map();
+    for (const source of sources) {
+        if (!source.adapter)
+            continue;
+        const names = face === 'state'
+            ? source.adapter.providers().map((provider) => provider.name)
+            : source.adapter.commands().map((command) => command.name);
+        for (const name of new Set(names)) {
+            if (!labelsByName.has(name)) {
+                labelsByName.set(name, []);
+                order.push(name);
+            }
+            labelsByName.get(name)?.push(source.label);
+        }
+    }
+    return { order, labelsByName };
+}
+/**
+ * Fold every projection of one mount onto a single {@link DebugAdapter}.
+ *
+ * `events()` concatenates, because an event ring is append-only and two rings
+ * genuinely both happened — there is no name to collide on. Everything else is
+ * name-keyed and therefore goes through the collision rule above.
+ */
+export function mergeDebugAdapters(sources) {
+    const live = sources.filter((source) => source.adapter !== null);
+    if (live.length === 0)
+        return { adapter: null, collisions: [] };
+    if (live.length === 1)
+        return { adapter: live[0].adapter, collisions: [] };
+    const providers = claimedNames(live, 'state');
+    const commands = claimedNames(live, 'command');
+    const collisions = [];
+    for (const [face, claimed] of [
+        ['state provider', providers],
+        ['command', commands],
+    ]) {
+        for (const name of claimed.order) {
+            const labels = claimed.labelsByName.get(name) ?? [];
+            if (labels.length > 1) {
+                collisions.push(`${face} "${name}" is declared by ${labels.join(' and ')}`);
+            }
+        }
+    }
+    /** The feeder that owns `name`, or a thrown collision error when several do. */
+    const ownerOf = (claimed, name, face) => {
+        const labels = claimed.labelsByName.get(name);
+        if (!labels)
+            return null;
+        if (labels.length > 1)
+            throw collisionError(name, labels);
+        return (live.find((source) => {
+            const owned = face === 'state'
+                ? source.adapter?.providers().some((provider) => provider.name === name)
+                : source.adapter?.commands().some((command) => command.name === name);
+            return owned === true;
+        })?.adapter ?? null);
+    };
+    return {
+        adapter: {
+            providers: () => live.flatMap((source) => source.adapter?.providers() ?? []).filter(uniqueByName()),
+            state: (name) => {
+                const owner = ownerOf(providers, name, 'state');
+                if (!owner) {
+                    throw new DebugError('STATE_PROVIDER_NOT_FOUND', `No state provider named "${name}" is declared by this game.`, { registered: providers.order });
+                }
+                return owner.state(name);
+            },
+            stateAll: () => {
+                const out = {};
+                for (const name of providers.order) {
+                    try {
+                        out[name] = ownerOf(providers, name, 'state')?.state(name);
+                    }
+                    catch (err) {
+                        out[name] = { __error: String(err) };
+                    }
+                }
+                return out;
+            },
+            commands: () => live.flatMap((source) => source.adapter?.commands() ?? []).filter(uniqueByName()),
+            invoke: async (name, args) => {
+                const owner = ownerOf(commands, name, 'command');
+                if (!owner) {
+                    throw new DebugError('DEBUG_COMMAND_NOT_REGISTERED', `No command named "${name}" is declared by this game.`, { registered: commands.order });
+                }
+                return owner.invoke(name, args);
+            },
+            events: (sinceSeq) => live.flatMap((source) => source.adapter?.events(sinceSeq) ?? []),
+        },
+        collisions,
+    };
+}
+/** Keep the FIRST listing of each name — the merged listing advertises a name
+ *  once, whatever `state()`/`invoke()` then decide to do with it. */
+function uniqueByName() {
+    const seen = new Set();
+    return (value) => {
+        if (seen.has(value.name))
+            return false;
+        seen.add(value.name);
+        return true;
+    };
+}

package/dist/adapter/ingest/observation-debug-adapter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Projects an ADAPTER's declared observation slots
+ * (`AdapterDefinition.observation`, `adapter/adapter-module.ts`) onto the host's
+ * existing {@link DebugAdapter} — the one seam `game.providers()` /
+ * `game.state()` / `game.commands()` already read through
+ * (`command-listener.ts`'s `dispatchBridgeMethod` → `getActiveSystems().debug`).
+ *
+ * This is the SIBLING of `contract-debug-adapter.ts` and deliberately the same
+ * shape: a projection rather than a second door. The two differ only in WHO
+ * declared the surface — the game itself, on `window.vgaiGame.systems`, or the
+ * game's adapter module beside it — and a consumer downstream must not be able
+ * to tell them apart. `merge-debug-adapters.ts` is what folds both onto the one
+ * slot.
+ *
+ * ## What `game` is
+ *
+ * The host's to hand over, and for an INGEST mount it is the REALM the game's
+ * own modules ran in. That is not a convenience: an ingest mount runs the game
+ * in the editor's own realm (`game-contract.ts`'s `readGameContract` says so —
+ * "the realm every ingest mount runs the game's modules in, where the game and
+ * the host share one global"), a vendored bundle's adapter is HOST-realm by the
+ * placement rule, and the only handles such a game publishes are the ones on
+ * that realm — its runtime's own public registry, or a host-build seam beside
+ * it. Handing the realm is therefore handing the game everything it actually
+ * exposes; handing anything narrower would make the adapter reach for `window`
+ * itself, which is the same read with the provenance hidden.
+ *
+ * ## The two-state rule, kept
+ *
+ * Declaring a slot and answering it are separate facts. A declaration with NO
+ * `answer` is still listed and refuses BY NAME when read — never omitted,
+ * because omitting it would report "the game has no such state" when the truth
+ * is "the table declared it and nothing binds it yet". Same for a throwing
+ * `answer`: it propagates (exactly as a first-party provider's does), and only
+ * `stateAll()` isolates it per key.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * - **Validate arguments.** A declared command's `answer` receives the invoked
+ *   argument list after the game handle; there is no Zod tuple beside a foreign
+ *   game, so a verb validates itself and throws its own error, surfaced wrapped
+ *   as `DEBUG_COMMAND_FAILED`. Identical to the contract projection's stance.
+ * - **Fabricate an event ring.** Nothing emits behind a declaration, so
+ *   `events()` is empty — accurate, not a stub.
+ */
+import type { ObservationDeclaration } from '../adapter-module';
+import type { DebugAdapter } from '../system-adapter';
+/**
+ * Build a {@link DebugAdapter} over an adapter's observation declarations, or
+ * `null` when it declares none. `null` is the honest floor — the same one
+ * `createContractDebugAdapter` returns — so a game that declared nothing keeps
+ * reporting `DEBUG_ADAPTER_UNAVAILABLE` rather than serving an empty adapter
+ * that reads as "this game has no state".
+ */
+export declare function createObservationDebugAdapter(declarations: readonly ObservationDeclaration[] | undefined | null, game: unknown): DebugAdapter | null;
+//# sourceMappingURL=observation-debug-adapter.d.ts.map

package/dist/adapter/ingest/observation-debug-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-debug-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/observation-debug-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAsC,MAAM,mBAAmB,CAAC;AAoB1F;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,SAAS,sBAAsB,EAAE,GAAG,SAAS,GAAG,IAAI,EAClE,IAAI,EAAE,OAAO,GACZ,YAAY,GAAG,IAAI,CA+ErB"}