@forgeax/engine-project 0.1.2

package/dist/schema.d.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+export declare const GuidString: z.ZodEffects<z.ZodString, string, string>;
+export declare const PluginRealmSchema: z.ZodEnum<["host", "engine", "build"]>;
+export interface GameProjectPluginEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly config?: unknown;
+    readonly group?: boolean | null | undefined;
+    readonly disabled?: boolean | null | undefined;
+    readonly inject?: readonly string[] | Readonly<Record<string, unknown>> | null | undefined;
+    readonly realm?: z.infer<typeof PluginRealmSchema> | undefined;
+}
+export declare const GameProjectPluginEntrySchema: z.ZodType<GameProjectPluginEntry>;
+export declare const GameProjectPluginsSchema: z.ZodEffects<z.ZodArray<z.ZodType<GameProjectPluginEntry, z.ZodTypeDef, GameProjectPluginEntry>, "many">, GameProjectPluginEntry[], GameProjectPluginEntry[]>;
+export declare const GameProjectSchema: z.ZodObject<{
+    /** Stable game slug; matches the `.forgeax/games/<id>/` directory name. */
+    id: z.ZodString;
+    /** Human-facing display name (may contain any unicode). */
+    name: z.ZodString;
+    /** forge.json schema version, e.g. "1.0.0" — required so loaders can gate on format. */
+    schemaVersion: z.ZodString;
+    /** Optional bootstrap hook: entry module relative to game root (e.g. "main.ts", "src/main.ts"). */
+    entry: z.ZodOptional<z.ZodString>;
+    /** Optional realm-local ExecutionBootstrapEntry module relative to game root. */
+    executionEntry: z.ZodOptional<z.ZodString>;
+    /** Optional GUID of the scene to load first; must be a real scene asset GUID (GuidString-validated). */
+    defaultScene: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Optional physics backend: enum tag ('3d'/'2d'/'rapier-3d'/'rapier-2d') or boolean on/off. */
+    physics: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["3d", "2d", "rapier-3d", "rapier-2d"]>, z.ZodBoolean]>>;
+    /** Optional flag requesting pointer-lock (FPS-style mouse capture) at play time. */
+    pointerLock: z.ZodOptional<z.ZodBoolean>;
+    /** Optional input scheme hint consumed by play-runtime (e.g. "fps"). */
+    input: z.ZodOptional<z.ZodString>;
+    /** Optional editor preview config (skin scene/clips for the launcher card). */
+    preview: z.ZodOptional<z.ZodObject<{
+        skin: z.ZodObject<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        skin: z.ZodObject<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        skin: z.ZodObject<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    /** Native DeepSeek Harness Entry tree, plus the ForgeaX build-only realm selector. */
+    plugins: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodType<GameProjectPluginEntry, z.ZodTypeDef, GameProjectPluginEntry>, "many">, GameProjectPluginEntry[], GameProjectPluginEntry[]>>;
+    /** Optional Digital Life NPC Brain policy consumed by the server adapter. */
+    npc: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        budget: z.ZodOptional<z.ZodObject<{
+            maxCallsPerMinute: z.ZodOptional<z.ZodNumber>;
+            maxTokensPerMinute: z.ZodOptional<z.ZodNumber>;
+            maxConcurrent: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        }, {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        budget?: {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        } | undefined;
+    }, {
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        budget?: {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        } | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    schemaVersion: string;
+    entry?: string | undefined;
+    executionEntry?: string | undefined;
+    defaultScene?: string | undefined;
+    physics?: boolean | "3d" | "2d" | "rapier-3d" | "rapier-2d" | undefined;
+    pointerLock?: boolean | undefined;
+    input?: string | undefined;
+    preview?: z.objectOutputType<{
+        skin: z.ZodObject<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    plugins?: GameProjectPluginEntry[] | undefined;
+    npc?: {
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        budget?: {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    id: string;
+    name: string;
+    schemaVersion: string;
+    entry?: string | undefined;
+    executionEntry?: string | undefined;
+    defaultScene?: string | undefined;
+    physics?: boolean | "3d" | "2d" | "rapier-3d" | "rapier-2d" | undefined;
+    pointerLock?: boolean | undefined;
+    input?: string | undefined;
+    preview?: z.objectInputType<{
+        skin: z.ZodObject<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            sceneGuid: z.ZodOptional<z.ZodString>;
+            clipGuids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            clipDefault: z.ZodOptional<z.ZodString>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            pos: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        }, z.ZodTypeAny, "passthrough">>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    plugins?: GameProjectPluginEntry[] | undefined;
+    npc?: {
+        model?: string | undefined;
+        maxTokens?: number | undefined;
+        budget?: {
+            maxCallsPerMinute?: number | undefined;
+            maxTokensPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+export type GameProject = z.infer<typeof GameProjectSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,UAAU,2CAOtB,CAAC;AAqCF,eAAO,MAAM,iBAAiB,wCAAsC,CAAC;AAerE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,GAAG,SAAS,CAAC;CAChE;AAED,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAW1E,CAAC;AAEF,eAAO,MAAM,wBAAwB,+JAiBjC,CAAC;AAKL,eAAO,MAAM,iBAAiB;IAE1B,2EAA2E;;IAE3E,2DAA2D;;IAE3D,wFAAwF;;IAExF,mGAAmG;;IAEnG,iFAAiF;;IAEjF,wGAAwG;;IAExG,gGAAgG;;IAEhG,oFAAoF;;IAEpF,wEAAwE;;IAExE,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE/E,sFAAsF;;IAEtF,6EAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGtE,CAAC;AAGZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@forgeax/engine-project",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Game-project SSOT — zod schema + injectable loader + resolve layer for forge.json, the authoritative game manifest contract.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-pack": "0.1.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "vitest": "4.1.5"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "pure data/contract package; no runtime canvas or frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "no perf-critical hot path in contract layer; throughput not instrumented"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "package-level gate scripts declared in engine CI yaml directly; no standalone binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/ac14-migration.test.ts

@@ -0,0 +1,124 @@
+// ac14-migration.test.ts — w23: AC-14 integration — all 6 migrated forge.json pass loadGameProject
+//
+// Loads each migrated game's forge.json via node:fs readFileSync adapter,
+// asserts r.ok===true, verifies schemaVersion/defaultScene/entry per D-3 GUID table.
+// This is the R-3 risk closure evidence (plan-strategy section 4 R-3, section 5.4).
+//
+// Fixture approach: 6 migrated forge.json copies live under __tests__/fixtures/games/
+// (plan w23 description secondary path: the live paths under packages/games/ use a
+// Chinese directory name that triggers the engine english-only gate; fixtures avoid
+// the CJK path literal while testing the same post-migration forge.json content).
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { loadGameProject } from '../loader.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixturesDir = resolve(__dirname, 'fixtures/games');
+
+function fsRead(filePath: string): (path: string) => Promise<string> {
+  return async () => readFileSync(filePath, 'utf-8');
+}
+
+interface GameFixture {
+  name: string;
+  dir: string;
+  hasDefaultScene: boolean;
+  expectedDefaultScene?: string;
+  expectedEntry?: string;
+}
+
+// 6 migrated games per D-3 GUID table (plan-strategy section 2)
+// Fixture dirs use romanized names (original Chinese dir -> cow-level)
+const GAMES: GameFixture[] = [
+  {
+    name: 'hellforge',
+    dir: 'hellforge',
+    hasDefaultScene: true,
+    expectedDefaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'cow-survivor',
+    dir: 'cow-survivor',
+    hasDefaultScene: true,
+    expectedDefaultScene: '7b4d43d4-5b19-5903-8966-f89671d21565',
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'spin-cube',
+    dir: 'spin-cube',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'cow-level',
+    dir: 'cow-level',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'fps',
+    dir: 'fps',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'shoot-opt',
+    dir: 'shoot-opt',
+    hasDefaultScene: false,
+    expectedEntry: 'src/main.ts',
+  },
+];
+
+describe('AC-14 — migrated game forge.json validation', () => {
+  for (const game of GAMES) {
+    const forgePath = resolve(fixturesDir, game.dir, 'forge.json');
+
+    describe(game.name, () => {
+      it('loads successfully (r.ok === true)', async () => {
+        const result = await loadGameProject(fsRead(forgePath));
+        expect(result.ok).toBe(true);
+      });
+
+      it('has schemaVersion === "1.0.0"', async () => {
+        const result = await loadGameProject(fsRead(forgePath));
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+          expect(result.value.schemaVersion).toBe('1.0.0');
+        }
+      });
+
+      if (game.hasDefaultScene) {
+        it(`has defaultScene === "${game.expectedDefaultScene}"`, async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.defaultScene).toBe(game.expectedDefaultScene);
+          }
+        });
+      } else {
+        it('has no defaultScene (undefined)', async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.defaultScene).toBeUndefined();
+          }
+        });
+      }
+
+      if (game.expectedEntry) {
+        it(`has entry === "${game.expectedEntry}"`, async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.entry).toBe(game.expectedEntry);
+          }
+        });
+      }
+    });
+  }
+});

package/src/__tests__/errors.test-d.ts

@@ -0,0 +1,77 @@
+import type { GameProjectError as GameProjectErrorType } from '../index.js';
+import { GameProjectError } from '../index.js';
+
+const positiveErrors: GameProjectErrorType[] = [
+  new GameProjectError({
+    code: 'forge-missing',
+    expected: 'forge.json to exist',
+    hint: 'create forge.json',
+    detail: { path: 'forge.json' },
+  }),
+  new GameProjectError({
+    code: 'forge-read-failed',
+    expected: 'forge.json to be readable',
+    hint: 'retry the project reader',
+    detail: { path: 'forge.json', cause: 'transient' },
+  }),
+  new GameProjectError({
+    code: 'forge-parse-failed',
+    expected: 'valid JSON',
+    hint: 'fix JSON',
+    detail: { path: 'forge.json', rawMessage: 'Unexpected token' },
+  }),
+  new GameProjectError({
+    code: 'forge-schema-invalid',
+    expected: 'schema-valid JSON',
+    hint: 'fix fields',
+    detail: { path: 'forge.json', zodErrors: [] },
+  }),
+  new GameProjectError({
+    code: 'forge-unknown-field',
+    expected: 'known fields',
+    hint: 'remove the field',
+    detail: { path: 'forge.json', fieldNames: ['scenes'] },
+  }),
+  new GameProjectError({
+    code: 'forge-guid-malformed',
+    expected: 'a valid GUID',
+    hint: 'use a scene GUID',
+    detail: { field: 'defaultScene', rawInput: 'not-a-guid' },
+  }),
+  new GameProjectError({
+    code: 'forge-scene-unresolved',
+    expected: 'a resolvable scene',
+    hint: 'check the scene pack',
+    detail: { guid: '15acc839-d847-527c-8284-bfb36d7c50de' },
+  }),
+];
+
+new GameProjectError({
+  code: 'forge-guid-malformed',
+  expected: 'a valid GUID',
+  hint: 'use a scene GUID',
+  // @ts-expect-error code/detail pairs remain correlated.
+  detail: { path: 'forge.json' },
+});
+
+function describe(error: GameProjectErrorType): string {
+  switch (error.code) {
+    case 'forge-missing':
+      return error.detail.path;
+    case 'forge-read-failed':
+      return error.detail.cause;
+    case 'forge-parse-failed':
+      return error.detail.rawMessage;
+    case 'forge-schema-invalid':
+      return String(error.detail.zodErrors.length);
+    case 'forge-unknown-field':
+      return error.detail.fieldNames.join(',');
+    case 'forge-guid-malformed':
+      return error.detail.rawInput;
+    case 'forge-scene-unresolved':
+      return error.detail.guid;
+  }
+}
+
+void positiveErrors;
+void describe;