@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/adapter/ingest/merge-debug-adapters.ts

@@ -0,0 +1,197 @@
+/**
+ * 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,
+  DebugCommandInfo,
+  TickStampedEvent,
+} from '@volter/editor-project/adapter/system-adapter';
+import { DebugError } from '../../debug-registry';
+
+/** 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[];
+}
+
+function collisionError(name: string, labels: readonly string[]): DebugError {
+  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: readonly DebugAdapterSource[],
+  face: 'state' | 'command',
+): {
+  order: string[];
+  labelsByName: Map<string, string[]>;
+} {
+  const order: string[] = [];
+  const labelsByName = new Map<string, string[]>();
+  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: readonly DebugAdapterSource[]): MergedDebugAdapters {
+  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: string[] = [];
+  for (const [face, claimed] of [
+    ['state provider', providers],
+    ['command', commands],
+  ] as const) {
+    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: ReturnType<typeof claimedNames>,
+    name: string,
+    face: 'state' | 'command',
+  ): DebugAdapter | null => {
+    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: string): unknown => {
+        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: (): Record<string, unknown> => {
+        const out: Record<string, unknown> = {};
+        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: (): DebugCommandInfo[] =>
+        live.flatMap((source) => source.adapter?.commands() ?? []).filter(uniqueByName()),
+
+      invoke: async (name: string, args: unknown[]): Promise<unknown> => {
+        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?: number): TickStampedEvent[] =>
+        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<T extends { name: string }>(): (value: T) => boolean {
+  const seen = new Set<string>();
+  return (value) => {
+    if (seen.has(value.name)) return false;
+    seen.add(value.name);
+    return true;
+  };
+}

package/src/runtime/adapter/ingest/observation-debug-adapter.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 '@volter/editor-project/adapter/adapter-module';
+import type {
+  DebugAdapter,
+  DebugCommandInfo,
+  TickStampedEvent,
+} from '@volter/editor-project/adapter/system-adapter';
+import { DebugError } from '../../debug-registry';
+
+/**
+ * An adapter-declared read is DERIVED by the host-side table from the game's own
+ * handles — which is precisely what `assisted` means in the tier vocabulary
+ * (`game-contract.ts`: "`observable` is a value the game already computes,
+ * `assisted` is one the shim derives"). Reporting `observable` would claim the
+ * game itself publishes the value.
+ */
+const DECLARED_TIER = 'assisted' as const;
+
+function unanswered(id: string, kind: string): DebugError {
+  return new DebugError(
+    'OBSERVATION_UNANSWERED',
+    `Observation "${id}" (${kind}) is declared by this game's adapter with no \`answer\` — ` +
+      'the slot exists and nothing binds it yet, which is not the same as the game having none.',
+    { id, kind },
+  );
+}
+
+/**
+ * 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 function createObservationDebugAdapter(
+  declarations: readonly ObservationDeclaration[] | undefined | null,
+  game: unknown,
+): DebugAdapter | null {
+  const all = declarations ?? [];
+  if (all.length === 0) return null;
+
+  // Snapshot into id-keyed maps once, exactly as the contract projection does:
+  // a later duplicate shadows an earlier one and the listing de-duplicates with
+  // it, so a listed id can never resolve differently than it reads.
+  const byProvider = new Map(all.filter((d) => d.kind === 'state').map((d) => [d.id, d]));
+  const byCommand = new Map(all.filter((d) => d.kind === 'command').map((d) => [d.id, d]));
+
+  return {
+    providers: () => [...byProvider.keys()].map((name) => ({ name, tier: DECLARED_TIER })),
+
+    state: (name: string): unknown => {
+      const declaration = byProvider.get(name);
+      if (!declaration) {
+        throw new DebugError(
+          'STATE_PROVIDER_NOT_FOUND',
+          `No state provider named "${name}" is declared by this game's adapter.`,
+          { registered: [...byProvider.keys()] },
+        );
+      }
+      if (!declaration.answer) throw unanswered(name, 'state');
+      return declaration.answer(game);
+    },
+
+    stateAll: (): Record<string, unknown> => {
+      const out: Record<string, unknown> = {};
+      for (const [name, declaration] of byProvider) {
+        // One throwing declaration must not cost the caller every other
+        // reading — the same per-key isolation the first-party registry gives.
+        try {
+          out[name] = declaration.answer
+            ? declaration.answer(game)
+            : (() => {
+                throw unanswered(name, 'state');
+              })();
+        } catch (err) {
+          out[name] = { __error: String(err) };
+        }
+      }
+      return out;
+    },
+
+    commands: (): DebugCommandInfo[] =>
+      [...byCommand.keys()].map((name) => ({
+        name,
+        // An ingested game runs entirely in the browser realm the host mounted
+        // it in; there is no server leg for its verbs to route to.
+        locus: byCommand.get(name)?.locus ?? ('client' as const),
+      })),
+
+    invoke: async (name: string, args: unknown[]): Promise<unknown> => {
+      const declaration = byCommand.get(name);
+      if (!declaration) {
+        throw new DebugError(
+          'DEBUG_COMMAND_NOT_REGISTERED',
+          `No command named "${name}" is declared by this game's adapter.`,
+          { registered: [...byCommand.keys()] },
+        );
+      }
+      if (!declaration.answer) throw unanswered(name, 'command');
+      try {
+        // The game handle first, then the invoked argument list — a declared
+        // verb is a function OF the mounted game, which is the whole reason
+        // `answer` takes one.
+        return await (declaration.answer as (game: unknown, ...rest: unknown[]) => unknown)(
+          game,
+          ...args,
+        );
+      } catch (err) {
+        throw new DebugError('DEBUG_COMMAND_FAILED', `Command "${name}" threw: ${String(err)}`, {
+          name,
+        });
+      }
+    },
+
+    events: (): TickStampedEvent[] => [],
+  };
+}

package/src/runtime/adapter/ingest/upstream-pin.ts

@@ -0,0 +1,51 @@
+/**
+ * Upstream-pin extraction — R5 ((c)/ §7.1 item 9): the fix for the overlay identity
+ * gap the structural-id + `authoredAgainst.gameVersion` scheme (T7.7/D9) does not
+ * close. A re-vendor of a vendored upstream game that keeps a slot's shape (index +
+ * three.js type + name unchanged) reapplies a saved overlay onto a semantically
+ * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning success
+ * — because `authoredAgainst.gameVersion` is the MANIFEST's own `version` (hand-set
+ * by whoever wrote the ingest manifest, e.g. every `public/ingest/*` vendored game
+ * ships `"version": "0.1.0"` regardless of which upstream commit it vendors), never
+ * tied to the thing that actually changes on a re-vendor: the `UPSTREAM.md` pin.
+ *
+ * This module is the pure, dependency-free half (parse text -> pin, or
+ * `null`): NO file I/O here, so it is usable from any context (editor
+ * save/apply-time hooks over a fetched `/UPSTREAM.md`, a future Node-side
+ * CLI check, tests). READ-ONLY by construction — it has no writer; this
+ * codebase never generates or edits an `UPSTREAM.md` (the anti-shim rule:
+ * adapters never fabricate first-party data, and a game's own vendoring
+ * provenance is exactly that).
+ *
+ * Format (established convention, not invented here — see every
+ * `public/ingest/*\/UPSTREAM.md`'s `## Upstream` section, e.g.
+ * `public/ingest/tanks/UPSTREAM.md`):
+ *
+ *   ## Upstream
+ *
+ *   - Repo: https://github.com/colyseus/realtime-tanks-demo
+ *   - Commit: **`6339493130b4b1d4d28f0f52d17b2fba738c7d47`**
+ *
+ * i.e. a Markdown bullet whose label is `Commit:` and whose value is a bold,
+ * backtick-code full (or abbreviated) git SHA. Every BUNDLE-vendored game in
+ * this repo (`tanks`, `simcity`) follows this exact shape. Source-tree
+ * vendored games carry their pin in `vendor/games/<id>.UPSTREAM.lock`'s
+ * machine-readable `commit` instead and never reach this parser.
+ */
+
+/** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */
+const COMMIT_BULLET_RE = /-\s*Commit:\s*\*\*`([0-9a-fA-F]{7,40})`\*\*/;
+
+/**
+ * Extract the pinned upstream commit hash from a vendored game's
+ * `UPSTREAM.md` prose, or `null` if the file doesn't follow the convention
+ * (or wasn't found — the caller decides what a missing file means; this
+ * function only parses text it's handed). Never throws — an unparseable
+ * document is an honest `null`, not an error (anti-shim: no guessing, no
+ * fabricating a pin from a game folder that doesn't declare one, e.g. an
+ * externally-authored non-vendored project opened via the CLI-on-folder
+ * route).
+ */
+export function extractUpstreamPin(markdown: string): string | null {
+  return COMMIT_BULLET_RE.exec(markdown)?.[1] ?? null;
+}