@vgai/engine 0.2.0 → 0.3.0

package/dist/adapter/ingest/overlay-applier.js

@@ -0,0 +1,132 @@
+/**
+ * `applyVgaiOverlay` — the T3.8 deliverable (docs/DECISIONS-PENDING.md §D9):
+ * the opt-in runtime overlay applier a game owner adds to THEIR OWN deployment
+ * so an adapted (ingested-then-edited) game ships with the editor's edits
+ * visible, with zero involvement from the editor at runtime.
+ *
+ * The opt-in shape (D9's "minimal source opt-in, consistent with the
+ * zero-diff-unless-opted-in invariant"): one import + one call, placed before
+ * the game's own entry point runs (so the capture trap below is installed
+ * before the game's `WebGLRenderer` is constructed):
+ *
+ *   import * as THREE from 'three';
+ *   import { applyVgaiOverlay } from '@vgai/engine/adapter/ingest/overlay-applier';
+ *
+ *   applyVgaiOverlay({ three: THREE, gameId: 'my-game' }); // fire-and-forget
+ *   import('./my-game-entry.js'); // the UNMODIFIED game, unchanged
+ *
+ * No scene is passed manually — this reuses the SAME render-accessor trap
+ * (`./scene-capture.ts`) the editor's ingest mode uses to obtain the game's
+ * live `Scene`/camera the moment it first renders, so this works for ANY
+ * unmodified three.js game the SAME way ingestion already captures it (per
+ * `scene-capture.ts`'s own caveat, this requires the game to share the host's
+ * `three` module instance — a bundled/vendored copy of `three` cannot be
+ * captured this way, matching the editor's own capture ceiling).
+ *
+ * Failure modes are all graceful (the game always keeps running unmodified)
+ * but never silent — every one is logged via `console.warn` under the shared
+ * `overlay-report` prefix (`./overlay-report.ts`) so ops can grep one string
+ * for every overlay-related issue across both the editor and the ship path:
+ *   - no overlay file at `overlayUrl` (never authored, or a 404/network
+ *     error) → nothing applied, logged, scene never even captured;
+ *   - the game never renders within `captureTimeoutMs` (bundled/non-shared
+ *     three, or the game simply never boots) → nothing applied, logged;
+ *   - a version mismatch and/or orphaned overlay ids (D9) → whatever DOES
+ *     resolve is still applied; the report names what didn't.
+ *
+ * Precedence (D9 "overlay-vs-game-save-system precedence"): the overlay is
+ * applied exactly ONCE, synchronously, in the continuation of the game's
+ * FIRST captured render call — i.e. between that frame finishing and the
+ * game's own next frame starting. Any later mutation of the SAME
+ * property by the game's own logic (its own save/load system, a per-frame
+ * animation, etc.) therefore wins from then on purely by construction: this
+ * applier never re-applies and never re-reads the overlay after this one
+ * pass. A property the game's own logic never revisits stays overlaid for
+ * the life of the session; a property the game's own logic re-derives every
+ * frame reverts to the game's own value on the very next frame. This
+ * ordering is exercised directly by `overlay-applier.test.ts`'s "precedence"
+ * case (apply, then simulate one more game-owned mutation frame).
+ */
+import { applyOverlayToObjects, assignStructuralIds } from './overlay-apply';
+import { overlayPath, parseOverlayFile } from './overlay-file';
+import { buildOverlayApplyReport, logOverlayApplyReport, OVERLAY_REPORT_PREFIX, } from './overlay-report';
+import { installSceneCapture } from './scene-capture';
+/** Shared warn helper — every graceful-failure path below logs through here. */
+function warn(gameId, message) {
+    // biome-ignore lint/suspicious/noConsole: deliberate, greppable (mirrors overlay-report.ts's own console.warn)
+    console.warn(`${OVERLAY_REPORT_PREFIX} game "${gameId}": ${message}`);
+}
+async function fetchOverlayFile(url, gameId, fetchImpl) {
+    const doFetch = fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined);
+    if (!doFetch) {
+        warn(gameId, 'no fetch implementation available — overlay not applied, running unmodified.');
+        return null;
+    }
+    try {
+        const res = await doFetch(url);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const raw = await res.json();
+        return parseOverlayFile(raw);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        warn(gameId, `no overlay applied (${reason}) — running unmodified.`);
+        return null;
+    }
+}
+/**
+ * The opt-in ship-path applier — see this module's header for the full
+ * contract. Installs the scene-capture trap SYNCHRONOUSLY (before the first
+ * `await`), so a caller that follows the documented pattern (call this, THEN
+ * import/boot the game) never races the trap against the game's first frame
+ * — the trap's `captured` slot latches on the game's first render regardless
+ * of when (or whether) this function later calls `waitForCapture` on it.
+ * Only PROCEEDS to actually wait for that capture once an overlay has been
+ * found (fetched first, deliberately) — the common "never edited this game"
+ * case then costs one fetch, never a multi-second capture-timeout wait.
+ */
+export async function applyVgaiOverlay(options) {
+    const { three, gameId, gameVersion = null, upstreamPin = null, fetchImpl } = options;
+    const overlayUrl = options.overlayUrl ?? overlayPath(gameId);
+    // Install the capture trap before anything else in this function (and
+    // before returning control to the caller's microtask queue) — see the
+    // header comment's ordering guarantee.
+    const capture = installSceneCapture(three);
+    const overlayFile = await fetchOverlayFile(overlayUrl, gameId, fetchImpl);
+    if (!overlayFile) {
+        // Nothing to apply (never authored, 404, network error — already logged
+        // by fetchOverlayFile) — don't bother waiting for a render at all.
+        capture.uninstall();
+        return { captured: false, report: null };
+    }
+    let rt;
+    try {
+        rt = await capture.waitForCapture(options.captureTimeoutMs);
+    }
+    catch (err) {
+        capture.uninstall();
+        const reason = err instanceof Error ? err.message : String(err);
+        warn(gameId, `scene capture failed (${reason}) — overlay not applied, running unmodified.`);
+        return { captured: false, report: null };
+    }
+    capture.uninstall(); // one-shot: we have what we need, stop wrapping future renders.
+    const { byId } = assignStructuralIds(rt.scene, rt.camera);
+    const { applied, orphanedIds } = applyOverlayToObjects(byId, overlayFile.overrides);
+    const report = buildOverlayApplyReport({
+        gameId,
+        authoredAgainst: overlayFile.authoredAgainst.gameVersion,
+        currentVersion: gameVersion,
+        applied,
+        orphanedIds,
+        // R5: `authoredUpstreamPin` passes through undefined for a legacy overlay
+        // (the key was never in `authoredAgainst` at all — see overlay-file.ts),
+        // preserving the "never checked" vs. "checked, found nothing" distinction
+        // all the way from disk. `currentUpstreamPin` is this no-op-by-default
+        // option (see its doc comment above) — `null` unless a game owner passes it.
+        authoredUpstreamPin: overlayFile.authoredAgainst.upstreamPin,
+        currentUpstreamPin: upstreamPin,
+    });
+    logOverlayApplyReport(report);
+    return { captured: true, report, scene: rt.scene, camera: rt.camera };
+}

package/dist/adapter/ingest/overlay-apply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Ingest overlay application core — the structural-path identity scheme and
+ * override-application loop shared by the EDITOR's `IngestAuthoringAdapter`
+ * (`packages/editor/src/authoring/ingest-authoring-adapter.ts`, which layers
+ * hierarchy/selection/undo bookkeeping over it) and the T3.8 runtime ship-path
+ * applier (`./overlay-applier.ts`, which uses it directly with none of that
+ * editor bookkeeping). Extracted here (rather than duplicated) per D9's task
+ * split (docs/DECISIONS-PENDING.md §D9) — the editor re-exports/reuses this
+ * module so its behavior (and the ids it mints) stay byte-for-byte identical
+ * between "authored in the editor" and "reapplied at ship time".
+ *
+ * Identity: each object gets a deterministic **structural-path id** — stable
+ * for a given scene shape (position in the tree + three.js type + name), so
+ * the SAME id re-binds to the SAME object after an independent fresh walk of
+ * an unmodified game's rebuilt scene (a reload, or a separate page entirely —
+ * this is what lets an overlay authored in the editor apply cleanly in a
+ * shipped build that never ran the editor). It is also written to
+ * `userData.entityId` so the editor's object map / gizmo / selection (which
+ * key on `entityId`) bind to foreign objects with no further shim.
+ */
+import type * as THREE from 'three';
+import type { IngestOverlay } from './overlay-file';
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export declare const CAMERA_ID = "ingest:camera";
+/** The single (non-array) standard-ish material of a mesh, if it has a color. */
+export declare function colorMaterialOf(o: THREE.Object3D): THREE.MeshStandardMaterial | null;
+/** Result of a structural-path walk: the id→object map plus a few reflection stats. */
+export interface StructuralIdWalk {
+    byId: Map<string, THREE.Object3D>;
+    count: number;
+    meshes: number;
+    lights: number;
+}
+/**
+ * (Re)assign structural-path ids to every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — the prerequisite for overlay reapplication
+ * across an independent fresh walk (editor reload, or a shipped build that
+ * never ran the editor at all).
+ */
+export declare function assignStructuralIds(scene: THREE.Object3D, camera?: THREE.Object3D | undefined): StructuralIdWalk;
+/** Result of applying a saved overlay onto a structural-id-walked scene. */
+export interface OverlayApplyOutcome {
+    applied: number;
+    orphanedIds: string[];
+}
+/**
+ * Apply a saved overlay's overrides onto the live objects in `byId` (from
+ * {@link assignStructuralIds}). Ids absent from the map are "orphaned" — e.g. a
+ * dynamic child that didn't respawn, or the vendored game was bumped and
+ * restructured — never an error; the caller reports them (never silently) via
+ * `./overlay-report.ts`. Mutates matched objects in place; does not mutate
+ * `overlay` itself or track dirty/undo state — that bookkeeping is the
+ * editor-side `IngestAuthoringAdapter`'s job (persistable-edit tracking, so
+ * orphans round-trip on the next save) and is irrelevant to the ship-path
+ * applier (which never saves).
+ */
+export declare function applyOverlayToObjects(byId: Map<string, THREE.Object3D>, overlay: IngestOverlay): OverlayApplyOutcome;
+//# sourceMappingURL=overlay-apply.d.ts.map

package/dist/adapter/ingest/overlay-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-apply.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,0FAA0F;AAC1F,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAEzC,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAKpF;AAED,uFAAuF;AACvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,MAAM,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,GAClC,gBAAgB,CA4BlB;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACjC,OAAO,EAAE,aAAa,GACrB,mBAAmB,CAkBrB"}

package/dist/adapter/ingest/overlay-apply.js

@@ -0,0 +1,101 @@
+/**
+ * Ingest overlay application core — the structural-path identity scheme and
+ * override-application loop shared by the EDITOR's `IngestAuthoringAdapter`
+ * (`packages/editor/src/authoring/ingest-authoring-adapter.ts`, which layers
+ * hierarchy/selection/undo bookkeeping over it) and the T3.8 runtime ship-path
+ * applier (`./overlay-applier.ts`, which uses it directly with none of that
+ * editor bookkeeping). Extracted here (rather than duplicated) per D9's task
+ * split (docs/DECISIONS-PENDING.md §D9) — the editor re-exports/reuses this
+ * module so its behavior (and the ids it mints) stay byte-for-byte identical
+ * between "authored in the editor" and "reapplied at ship time".
+ *
+ * Identity: each object gets a deterministic **structural-path id** — stable
+ * for a given scene shape (position in the tree + three.js type + name), so
+ * the SAME id re-binds to the SAME object after an independent fresh walk of
+ * an unmodified game's rebuilt scene (a reload, or a separate page entirely —
+ * this is what lets an overlay authored in the editor apply cleanly in a
+ * shipped build that never ran the editor). It is also written to
+ * `userData.entityId` so the editor's object map / gizmo / selection (which
+ * key on `entityId`) bind to foreign objects with no further shim.
+ */
+import { setUserData } from '../../scene/user-data';
+/** Fixed id for the captured render camera (not a scene child, so no structural path). */
+export const CAMERA_ID = 'ingest:camera';
+/** The single (non-array) standard-ish material of a mesh, if it has a color. */
+export function colorMaterialOf(o) {
+    const mat = o.material;
+    if (!mat || Array.isArray(mat))
+        return null;
+    const m = mat;
+    return m.color ? m : null;
+}
+/**
+ * (Re)assign structural-path ids to every object under `scene` (and, if
+ * given, the separately-captured render `camera`, under the fixed
+ * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
+ * (position + type + name) — the prerequisite for overlay reapplication
+ * across an independent fresh walk (editor reload, or a shipped build that
+ * never ran the editor at all).
+ */
+export function assignStructuralIds(scene, camera) {
+    const byId = new Map();
+    let count = 0;
+    let meshes = 0;
+    let lights = 0;
+    const visit = (o, path) => {
+        const id = `ingest:${path}:${o.type}:${o.name || ''}`;
+        setUserData(o, 'entityId', id);
+        byId.set(id, o);
+        count++;
+        if (o.isLight)
+            lights++;
+        else if (o.isMesh)
+            meshes++;
+        o.children.forEach((c, i) => {
+            visit(c, `${path}/${i}`);
+        });
+    };
+    scene.children.forEach((c, i) => {
+        visit(c, `${i}`);
+    });
+    if (camera) {
+        setUserData(camera, 'entityId', CAMERA_ID);
+        byId.set(CAMERA_ID, camera);
+        count++;
+    }
+    return { byId, count, meshes, lights };
+}
+/**
+ * Apply a saved overlay's overrides onto the live objects in `byId` (from
+ * {@link assignStructuralIds}). Ids absent from the map are "orphaned" — e.g. a
+ * dynamic child that didn't respawn, or the vendored game was bumped and
+ * restructured — never an error; the caller reports them (never silently) via
+ * `./overlay-report.ts`. Mutates matched objects in place; does not mutate
+ * `overlay` itself or track dirty/undo state — that bookkeeping is the
+ * editor-side `IngestAuthoringAdapter`'s job (persistable-edit tracking, so
+ * orphans round-trip on the next save) and is irrelevant to the ship-path
+ * applier (which never saves).
+ */
+export function applyOverlayToObjects(byId, overlay) {
+    let applied = 0;
+    const orphanedIds = [];
+    for (const [id, ov] of Object.entries(overlay)) {
+        const o = byId.get(id);
+        if (!o) {
+            orphanedIds.push(id);
+            continue;
+        }
+        if (ov.position)
+            o.position.set(ov.position[0], ov.position[1], ov.position[2]);
+        if (ov.rotation)
+            o.quaternion.set(ov.rotation[0], ov.rotation[1], ov.rotation[2], ov.rotation[3]);
+        if (ov.scale)
+            o.scale.set(ov.scale[0], ov.scale[1], ov.scale[2]);
+        if (ov.color)
+            colorMaterialOf(o)?.color.set(ov.color);
+        if (ov.visible !== undefined)
+            o.visible = ov.visible;
+        applied++;
+    }
+    return { applied, orphanedIds };
+}

package/dist/adapter/ingest/overlay-file.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Ingest overlay envelope — the on-disk shape shared by every consumer of a
+ * saved ingest overlay: the editor (`packages/editor/src/authoring/ingest-overlay.ts`,
+ * which persists it through the storage-backend seam) AND the T3.8 runtime ship-path
+ * applier (`./overlay-applier.ts`, which fetches it over plain HTTP in a deployed
+ * game with no editor/storage-backend dependency at all).
+ *
+ * This module is the dependency-free core (types + pure parsing) both share — moved
+ * here (from the editor-only module that used to own it) per D9's task split
+ * (docs/DECISIONS-PENDING.md §D9): the editor keeps the storage-backend-aware
+ * `loadOverlay`/`saveOverlay` and re-exports everything below unchanged so its
+ * existing import sites don't churn.
+ */
+/** A single object's persisted overrides (only the fields the user changed). */
+export interface IngestOverride {
+    position?: [number, number, number];
+    rotation?: [number, number, number, number];
+    scale?: [number, number, number];
+    color?: string;
+    visible?: boolean;
+}
+/** id (structural-path) → overrides. */
+export type IngestOverlay = Record<string, IngestOverride>;
+/** Current on-disk envelope format version (D9, docs/DECISIONS-PENDING.md §D9). */
+export declare const OVERLAY_FORMAT_VERSION = 1;
+/**
+ * The on-disk overlay envelope (D9 — overlay versioning + orphan reporting).
+ * Wraps the flat `IngestOverlay` (id → overrides) with save-time provenance:
+ * which game version the edits were authored against, so a later mount (editor
+ * OR shipped runtime) can detect drift and report it (`./overlay-report.ts`'s
+ * `OverlayApplyReport`).
+ *
+ * `formatVersion` distinguishes this from the PRE-D9 flat file (the whole JSON
+ * file WAS the `IngestOverlay`): {@link parseOverlayFile} recognizes both. An
+ * object with `formatVersion` + `overrides` parses as the real envelope; any
+ * other shape (or unparseable content) parses as a legacy flat file, wrapped as
+ * `{ formatVersion: 0, authoredAgainst: { gameVersion: null }, overrides: <the flat object> }`
+ * — never rejected, never warned about by itself.
+ *
+ * `authoredAgainst.upstreamPin` (R5, docs/MASTER-ARCHITECTURE-REVIEW.md
+ * §4(c)/§7.1 item 9 — the overlay-identity gap `gameVersion` alone doesn't
+ * close: `gameVersion` is the manifest's own `version` field, which a
+ * re-vendor of the upstream game need not bump — see every `public/ingest/*`
+ * game's `vgai.game.json`, all pinned at `"version": "0.1.0"` regardless of
+ * upstream commit) is an OPTIONAL sibling key, deliberately absent from this
+ * type's older call sites' literal shape: its ABSENCE (the key missing from
+ * `authoredAgainst` entirely) is the "legacy overlay" signal — saved by code
+ * that predates this field, so the pin concept never existed for it, and
+ * `./overlay-report.ts`'s apply-time check must skip it (not treat it as a
+ * guaranteed mismatch OR a guaranteed match — anti-shim, no guessing). A
+ * `null` VALUE (key present, value `null`) means R5-aware save-time code DID
+ * look for a pin and honestly found none (e.g. an externally-authored,
+ * non-vendored project opened via the CLI-on-folder route, which has no
+ * `UPSTREAM.md` at all). See `./upstream-pin.ts` for the pure extraction, and
+ * `packages/editor/src/ingest-mode.ts` for where it's read at save/apply
+ * time. This is purely additive — {@link parseOverlayFile} never invents the
+ * key for an envelope that didn't have it.
+ */
+export interface OverlayFile {
+    formatVersion: number;
+    authoredAgainst: {
+        gameVersion: string | null;
+        upstreamPin?: string | null;
+    };
+    overrides: IngestOverlay;
+}
+/** Where a game's overlay lives, project-root-relative (also the ship path's default fetch URL). */
+export declare function overlayPath(gameId: string): string;
+/** The empty envelope — no overlay found / nothing authored yet. */
+export declare function emptyOverlayFile(): OverlayFile;
+/**
+ * Parse a loaded/fetched overlay's raw JSON into the {@link OverlayFile} shape,
+ * transparently upgrading a legacy (pre-D9) flat file — the whole parsed value
+ * IS the `IngestOverlay` in that case. Pure — no I/O, no storage backend, so
+ * it's usable from any context (editor `loadOverlay`, the ship-path applier's
+ * `fetch().then(r => r.json())`).
+ */
+export declare function parseOverlayFile(raw: unknown): OverlayFile;
+//# sourceMappingURL=overlay-file.d.ts.map

package/dist/adapter/ingest/overlay-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-file.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAE3D,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,IAAI,WAAW,CAM9C;AAYD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CA0B1D"}

package/dist/adapter/ingest/overlay-file.js

@@ -0,0 +1,66 @@
+/**
+ * Ingest overlay envelope — the on-disk shape shared by every consumer of a
+ * saved ingest overlay: the editor (`packages/editor/src/authoring/ingest-overlay.ts`,
+ * which persists it through the storage-backend seam) AND the T3.8 runtime ship-path
+ * applier (`./overlay-applier.ts`, which fetches it over plain HTTP in a deployed
+ * game with no editor/storage-backend dependency at all).
+ *
+ * This module is the dependency-free core (types + pure parsing) both share — moved
+ * here (from the editor-only module that used to own it) per D9's task split
+ * (docs/DECISIONS-PENDING.md §D9): the editor keeps the storage-backend-aware
+ * `loadOverlay`/`saveOverlay` and re-exports everything below unchanged so its
+ * existing import sites don't churn.
+ */
+/** Current on-disk envelope format version (D9, docs/DECISIONS-PENDING.md §D9). */
+export const OVERLAY_FORMAT_VERSION = 1;
+/** Where a game's overlay lives, project-root-relative (also the ship path's default fetch URL). */
+export function overlayPath(gameId) {
+    return `.vgai/overlays/${gameId}.json`;
+}
+/** The empty envelope — no overlay found / nothing authored yet. */
+export function emptyOverlayFile() {
+    return {
+        formatVersion: OVERLAY_FORMAT_VERSION,
+        authoredAgainst: { gameVersion: null },
+        overrides: {},
+    };
+}
+/** An envelope has both its distinguishing keys — anything else is a legacy flat file. */
+function isEnvelope(raw) {
+    return (!!raw &&
+        typeof raw === 'object' &&
+        'formatVersion' in raw &&
+        'overrides' in raw);
+}
+/**
+ * Parse a loaded/fetched overlay's raw JSON into the {@link OverlayFile} shape,
+ * transparently upgrading a legacy (pre-D9) flat file — the whole parsed value
+ * IS the `IngestOverlay` in that case. Pure — no I/O, no storage backend, so
+ * it's usable from any context (editor `loadOverlay`, the ship-path applier's
+ * `fetch().then(r => r.json())`).
+ */
+export function parseOverlayFile(raw) {
+    if (isEnvelope(raw)) {
+        const rawAuthored = (raw.authoredAgainst ?? { gameVersion: null });
+        const authoredAgainst = {
+            gameVersion: rawAuthored.gameVersion ?? null,
+        };
+        // Preserve ABSENCE vs. explicit `null` (see this field's doc comment
+        // above) — only copy the key over if the raw JSON actually had it, rather
+        // than defaulting it in (which would make every pre-R5 saved overlay look
+        // like a "checked, found nothing" R5 save instead of "never checked").
+        if ('upstreamPin' in rawAuthored)
+            authoredAgainst.upstreamPin = rawAuthored.upstreamPin ?? null;
+        return {
+            formatVersion: raw.formatVersion,
+            authoredAgainst,
+            overrides: raw.overrides ?? {},
+        };
+    }
+    // Legacy flat file (pre-D9): the whole parsed object IS the overrides map.
+    return {
+        formatVersion: 0,
+        authoredAgainst: { gameVersion: null },
+        overrides: (raw ?? {}),
+    };
+}

package/dist/adapter/ingest/overlay-report.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Overlay apply report — D9 (docs/DECISIONS-PENDING.md §D9): decide + surface
+ * what happens when a saved ingest overlay is reapplied onto a scene that may
+ * have moved on since the overlay was authored (a vendored game bump, or a
+ * dynamic subtree that never respawned). Two independent signals, either of
+ * which is worth a loud (never silent) structured warning:
+ *   - a GAME-VERSION mismatch: the overlay's `authoredAgainst.gameVersion`
+ *     (`./overlay-file.ts`'s envelope, stamped from the manifest's `version`
+ *     at save time) disagrees with the currently-mounted game's version;
+ *   - ORPHANED ids: structural-path ids in the overlay that resolved to
+ *     nothing on the current scene walk (`./overlay-apply.ts`'s
+ *     `applyOverlayToObjects`).
+ *
+ * Neither condition blocks mounting — the overlay still applies everything it
+ * CAN; this module only decides whether/how to report what it couldn't.
+ *
+ * This is the SEAM T3.8 (the runtime overlay applier, i.e. reapplying an
+ * ingest overlay against a shipped/played build rather than the editor)
+ * reuses: `./overlay-applier.ts`'s `applyVgaiOverlay` builds + logs this EXACT
+ * report shape, same as the editor does. Moved here from the editor-only
+ * module that used to own it (`packages/editor/src/authoring/overlay-report.ts`,
+ * which now re-exports everything below unchanged plus the editor-only
+ * "active report" banner slot) — kept dependency-free (no `editor-console`/
+ * `window` import) so it stays importable from a headless runtime context —
+ * same discipline as `../achieved-tier.ts`.
+ *
+ * R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/§7.1 item 9) adds a THIRD
+ * independent signal alongside version-mismatch/orphans: an UPSTREAM-PIN
+ * mismatch. `gameVersion` alone cannot catch a same-slot substitution after a
+ * re-vendor (structural ids are position+type+name; a re-vendor that keeps a
+ * slot's shape reapplies the overlay onto a semantically different object
+ * with `applied:1, orphanedIds:[]`, and every vendored game's manifest
+ * `version` is hand-set and need not change on a re-vendor). The upstream pin
+ * (`./upstream-pin.ts`, read from the vendored game's `UPSTREAM.md`) is bound
+ * to the thing that actually changes. Like the other two signals, a mismatch
+ * never blocks application — it's a report, not a block (matching orphan
+ * semantics) — so a re-vendor surfaces as an explicit "authored against pin
+ * X, applying onto pin Y" instead of silent success.
+ */
+/** One mount's version + orphan findings — the D9 acceptance-criteria shape. */
+export interface OverlayApplyReport {
+    gameId: string;
+    /** `authoredAgainst.gameVersion` from the loaded overlay envelope, or `null` if never stamped. */
+    authoredAgainst: string | null;
+    /** The currently-mounted game's manifest `version`, or `null` if unknown at this call site. */
+    currentVersion: string | null;
+    /** Both sides known AND different — never true if either side is `null` (anti-shim: no guessing). */
+    versionMismatch: boolean;
+    applied: number;
+    /** Structural-path ids present in the overlay that resolved to nothing on this scene walk. */
+    orphanedIds: string[];
+    /**
+     * R5 — upstream-pin identity check (see this module's header). Distinct
+     * from `versionMismatch`/`orphanedIds`: it catches a same-slot
+     * SUBSTITUTION (id persists, meaning changed) that those two cannot.
+     */
+    upstreamPin: {
+        /** The pin the overlay was authored against, or `null` if never recorded/discoverable. */
+        authored: string | null;
+        /** The currently-mounted game's own discoverable pin, or `null` if undiscoverable here
+         * (e.g. the runtime ship-path applier, which has no `UPSTREAM.md` access at all — a
+         * documented no-op there — or an externally-authored, non-vendored project). */
+        current: string | null;
+        /**
+         * Whether the SAVED overlay envelope recorded the upstream-pin concept at
+         * all (i.e. `authoredAgainst.upstreamPin` was a present key, even if its
+         * value was `null`). `false` means a legacy overlay — saved by pre-R5
+         * code (or the pre-D9 flat-file shape) — for which the pin check is
+         * skipped entirely, not silently treated as a match. This is the
+         * "explicit legacy indication" the report surfaces so a legacy overlay's
+         * clean apply doesn't read as "verified" when it was never checked.
+         */
+        recorded: boolean;
+        /** `recorded` AND both sides known AND different — never true otherwise (anti-shim). */
+        mismatch: boolean;
+    };
+}
+/** Greppable prefix shared by every overlay-related log line (mirrors `achieved-tier.ts`'s `TIER_SHORTFALL_PREFIX`). */
+export declare const OVERLAY_REPORT_PREFIX = "overlay-report";
+/** Build the report from a mount's raw findings — pure, no logging. */
+export declare function buildOverlayApplyReport(args: {
+    gameId: string;
+    authoredAgainst: string | null;
+    currentVersion: string | null;
+    applied: number;
+    orphanedIds: string[];
+    /**
+     * R5: the loaded overlay's `authoredAgainst.upstreamPin`. Pass `undefined`
+     * (or omit) when the saved envelope never had the key at all (legacy
+     * overlay — `upstreamPin.recorded` becomes `false`); pass `null` when the
+     * envelope DID have the key but its value was `null` (R5-aware code
+     * looked, found nothing — `recorded` is `true`, `authored` is `null`); pass
+     * the pin string otherwise.
+     */
+    authoredUpstreamPin?: string | null | undefined;
+    /**
+     * R5: the currently-mounted game's own discoverable pin, or `null`/omitted
+     * when undiscoverable at this call site (anti-shim: never fabricated).
+     */
+    currentUpstreamPin?: string | null | undefined;
+}): OverlayApplyReport;
+/** Whether this report is worth surfacing (mismatch OR any orphan) — pure, no logging. */
+export declare function overlayReportWarrants(report: OverlayApplyReport): boolean;
+/** The one shared message shape — greppable on the prefix, JSON-parseable on the trailing payload. */
+export declare function formatOverlayApplyReportMessage(report: OverlayApplyReport): string;
+/**
+ * Emit the ONE structured `console.warn` this report warrants (mirroring the
+ * tier-shortfall pattern), or do nothing when neither signal fires. Returns
+ * whether it warned (callers that also want the panel-visible `editorConsole`
+ * echo, or the inline banner, use the return value / the report itself).
+ */
+export declare function logOverlayApplyReport(report: OverlayApplyReport): boolean;
+//# sourceMappingURL=overlay-report.d.ts.map

package/dist/adapter/ingest/overlay-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-report.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/overlay-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+FAA+F;IAC/F,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qGAAqG;IACrG,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE;QACX,0FAA0F;QAC1F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB;;wFAEgF;QAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB;;;;;;;;WAQG;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB,wFAAwF;QACxF,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,wHAAwH;AACxH,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAEtD,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAChD,GAAG,kBAAkB,CAwBrB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEzE;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAuBlF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CASzE"}