@forgeax/engine-project 0.1.2

package/src/__tests__/errors.test.ts

@@ -0,0 +1,254 @@
+// errors.test.ts — w3: GameProjectError code union exhaustive tests
+import { describe, expect, it } from 'vitest';
+import type { GameProjectErrorCode, GameProjectErrorDetail } from '../errors.js';
+import { GameProjectError } from '../errors.js';
+
+// ── helper ───────────────────────────────────────────────────────────────────
+function makeErr(): GameProjectError {
+  return new GameProjectError({
+    code: 'forge-missing',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json' },
+  });
+}
+
+const errors: GameProjectError[] = [
+  new GameProjectError({
+    code: 'forge-missing',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json' },
+  }),
+  new GameProjectError({
+    code: 'forge-read-failed',
+    expected: 'forge.json to be readable',
+    hint: 'retry the project reader',
+    detail: { path: '/fake/forge.json', cause: 'transient' },
+  }),
+  new GameProjectError({
+    code: 'forge-parse-failed',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', rawMessage: 'invalid JSON' },
+  }),
+  new GameProjectError({
+    code: 'forge-schema-invalid',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', zodErrors: [] },
+  }),
+  new GameProjectError({
+    code: 'forge-unknown-field',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', fieldNames: ['scenes'] },
+  }),
+  new GameProjectError({
+    code: 'forge-guid-malformed',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { field: 'defaultScene', rawInput: 'bad-guid', cause: new Error('bad GUID') },
+  }),
+  new GameProjectError({
+    code: 'forge-scene-unresolved',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { guid: '15acc839-d847-527c-8284-bfb36d7c50de' },
+  }),
+];
+
+// ── four-property surface ───────────────────────────────────────────────────
+describe('GameProjectError — structural surface', () => {
+  it('has .code, .expected, .hint, .detail', () => {
+    const err = makeErr();
+    expect(err).toHaveProperty('code');
+    expect(err).toHaveProperty('expected');
+    expect(err).toHaveProperty('hint');
+    expect(err).toHaveProperty('detail');
+  });
+
+  it('.code is readonly (TS compile-time, not runtime)', () => {
+    const err = makeErr();
+    // TS `readonly` is compile-time only; at runtime the property exists and
+    // holds its value. AI users cannot assign via the type (charter P2).
+    expect(err.code).toBe('forge-missing');
+    expect(typeof err.code).toBe('string');
+  });
+
+  it('.expected is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.expected).toBe('test expected');
+    expect(typeof err.expected).toBe('string');
+  });
+
+  it('.hint is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.hint).toBe('test hint');
+    expect(typeof err.hint).toBe('string');
+  });
+
+  it('.detail is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.detail).toBeDefined();
+    expect(typeof err.detail).toBe('object');
+  });
+});
+
+// ── code union membership ───────────────────────────────────────────────────
+describe('GameProjectError — code union', () => {
+  const codes: GameProjectErrorCode[] = [
+    'forge-missing',
+    'forge-read-failed',
+    'forge-parse-failed',
+    'forge-schema-invalid',
+    'forge-unknown-field',
+    'forge-guid-malformed',
+    'forge-scene-unresolved',
+  ];
+
+  it('code union has exactly 7 members', () => {
+    expect(codes).toHaveLength(7);
+  });
+
+  it('each code is constructable', () => {
+    expect(errors.map((error) => error.code)).toEqual(codes);
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toBeInstanceOf(GameProjectError);
+    }
+  });
+
+  it('compiles exhaustive switch without default', () => {
+    function switchOnCode(code: GameProjectErrorCode): string {
+      switch (code) {
+        case 'forge-missing':
+          return 'missing';
+        case 'forge-read-failed':
+          return 'read-failed';
+        case 'forge-parse-failed':
+          return 'parse-failed';
+        case 'forge-schema-invalid':
+          return 'schema-invalid';
+        case 'forge-unknown-field':
+          return 'unknown-field';
+        case 'forge-guid-malformed':
+          return 'guid-malformed';
+        case 'forge-scene-unresolved':
+          return 'scene-unresolved';
+      }
+    }
+    expect(switchOnCode('forge-missing')).toBe('missing');
+    expect(switchOnCode('forge-read-failed')).toBe('read-failed');
+    expect(switchOnCode('forge-scene-unresolved')).toBe('scene-unresolved');
+  });
+});
+
+function describeError(error: GameProjectError): string {
+  switch (error.code) {
+    case 'forge-missing':
+      return `missing:${error.detail.path}`;
+    case 'forge-read-failed':
+      return `read-failed:${error.detail.path}:${error.detail.cause}`;
+    case 'forge-parse-failed':
+      return `parse:${error.detail.path}:${error.detail.rawMessage}`;
+    case 'forge-schema-invalid':
+      return `schema:${error.detail.path}:${error.detail.zodErrors.length}`;
+    case 'forge-unknown-field':
+      return `unknown:${error.detail.path}:${error.detail.fieldNames.join(',')}`;
+    case 'forge-guid-malformed':
+      return `guid:${error.detail.field}:${error.detail.rawInput}`;
+    case 'forge-scene-unresolved':
+      return `scene:${error.detail.guid}`;
+  }
+}
+
+describe('GameProjectError — code-correlated error narrowing', () => {
+  it('narrows representative detail payloads from error.code', () => {
+    expect(errors.map(describeError)).toEqual([
+      'missing:/fake/forge.json',
+      'read-failed:/fake/forge.json:transient',
+      'parse:/fake/forge.json:invalid JSON',
+      'schema:/fake/forge.json:0',
+      'unknown:/fake/forge.json:scenes',
+      'guid:defaultScene:bad-guid',
+      'scene:15acc839-d847-527c-8284-bfb36d7c50de',
+    ]);
+  });
+});
+
+// ── per-code detail narrowing ───────────────────────────────────────────────
+describe('GameProjectError — detail narrowing per code', () => {
+  it('forge-missing detail contains path:string', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string }> = {
+      path: '/some/game/forge.json',
+    };
+    expect(_detail.path).toBe('/some/game/forge.json');
+  });
+
+  it('forge-read-failed detail contains path + bounded cause', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; cause: string }> = {
+      path: '/some/game/forge.json',
+      cause: 'permission-denied',
+    };
+    expect(_detail.cause).toBe('permission-denied');
+  });
+
+  it('forge-parse-failed detail contains path + rawMessage', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; rawMessage: string }> = {
+      path: '/some/forge.json',
+      rawMessage: 'Unexpected token',
+    };
+    expect(_detail.rawMessage).toBe('Unexpected token');
+  });
+
+  it('forge-schema-invalid detail contains path + zodErrors', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; zodErrors: unknown }> = {
+      path: '/some/forge.json',
+      zodErrors: [],
+    };
+    expect(_detail.path).toBe('/some/forge.json');
+  });
+
+  it('forge-unknown-field detail contains path + fieldNames', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; fieldNames: string[] }> = {
+      path: '/some/forge.json',
+      fieldNames: ['scenes'],
+    };
+    expect(_detail.fieldNames).toEqual(['scenes']);
+  });
+
+  it('forge-guid-malformed detail contains field + rawInput', () => {
+    const _detail: Extract<GameProjectErrorDetail, { field: string; rawInput: string }> = {
+      field: 'defaultScene',
+      rawInput: 'rogue-encampment',
+    };
+    expect(_detail.rawInput).toBe('rogue-encampment');
+  });
+
+  it('forge-scene-unresolved detail contains guid:string', () => {
+    const _detail: Extract<GameProjectErrorDetail, { guid: string }> = {
+      guid: '15acc839-d847-527c-8284-bfb36d7c50de',
+    };
+    expect(_detail.guid).toBe('15acc839-d847-527c-8284-bfb36d7c50de');
+  });
+});
+
+// ── error message ───────────────────────────────────────────────────────────
+describe('GameProjectError — message', () => {
+  it('is an instance of Error', () => {
+    const err = makeErr();
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('has name GameProjectError', () => {
+    const err = makeErr();
+    expect(err.name).toBe('GameProjectError');
+  });
+
+  it('message contains code for human readability', () => {
+    const err = makeErr();
+    expect(err.message).toContain('GameProjectError');
+    expect(err.message).toContain('forge-missing');
+  });
+});

package/src/__tests__/fixtures/games/cow-level/forge.json

@@ -0,0 +1,7 @@
+{
+  "id": "test3",
+  "name": "test3",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d"
+}

package/src/__tests__/fixtures/games/cow-survivor/forge.json

@@ -0,0 +1,8 @@
+{
+  "id": "cow-survivor",
+  "name": "Cow-Level Survivor",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d",
+  "defaultScene": "7b4d43d4-5b19-5903-8966-f89671d21565"
+}

package/src/__tests__/fixtures/games/fps/forge.json

@@ -0,0 +1,7 @@
+{
+  "id": "fps",
+  "name": "Sector Strike",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "pointerLock": true
+}

package/src/__tests__/fixtures/games/hellforge/forge.json

@@ -0,0 +1,24 @@
+{
+  "id": "hellforge",
+  "name": "ForgeaX: Hellforge",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d",
+  "pointerLock": true,
+  "defaultScene": "15acc839-d847-527c-8284-bfb36d7c50de",
+  "preview": {
+    "skin": {
+      "sceneGuid": "5e3028dd-ddf6-4104-86d9-318d3e8fb5a6",
+      "clipGuids": [
+        "c530adf2-8de6-486a-afaa-9af3a6e6dfd1",
+        "f9355148-5ddc-45a4-80d4-ef80fce559b0",
+        "9bb05e7d-6156-424f-8a20-f80373507f65",
+        "7faedc58-49cd-4fc9-93b7-66eca1b79674",
+        "ca6e7f12-8e1a-4b3c-9d50-2a4f1b8c6d04"
+      ],
+      "clipDefault": "idle",
+      "scale": 1,
+      "pos": [0, 0, 0]
+    }
+  }
+}

package/src/__tests__/fixtures/games/shoot-opt/forge.json

@@ -0,0 +1,6 @@
+{
+  "id": "shoot-opt",
+  "name": "shoot-opt",
+  "schemaVersion": "1.0.0",
+  "entry": "src/main.ts"
+}

package/src/__tests__/fixtures/games/spin-cube/forge.json

@@ -0,0 +1,6 @@
+{
+  "id": "spin-cube",
+  "name": "spin-cube",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts"
+}

package/src/__tests__/loader.test.ts

@@ -0,0 +1,364 @@
+// loader.test.ts — w4: loadGameProject 5 return paths + sync companion tests
+import { describe, expect, it } from 'vitest';
+import { loadGameProject, loadGameProjectSync, validateGameProject } from '../loader.js';
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+function makeRead(content: string): (path: string) => Promise<string> {
+  return async (_path: string) => content;
+}
+
+function makeReadThrow(err: Error): (path: string) => Promise<string> {
+  return async (_path: string) => {
+    throw err;
+  };
+}
+
+function makeReaderError(code: string, message = `reader refusal: ${code}`): Error {
+  const error = new Error(message);
+  Object.assign(error, { code });
+  return error;
+}
+
+const VALID_FORGE_JSON = JSON.stringify({
+  id: 'test-game',
+  name: 'Test Game',
+  schemaVersion: '1.0.0',
+});
+
+const VALID_WITH_DEFAULT_SCENE = JSON.stringify({
+  id: 'test-game',
+  name: 'Test Game',
+  schemaVersion: '1.0.0',
+  defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
+});
+
+const INVALID_JSON = '{id: broken';
+
+const WITH_SCENES_ARRAY = JSON.stringify({
+  id: 'has-scenes',
+  name: 'Has Scenes',
+  schemaVersion: '1.0.0',
+  scenes: [{ id: 'l1', name: 'Level 1', pack: 'scenes/level1.pack.json' }],
+});
+
+const WITH_BAD_GUID = JSON.stringify({
+  id: 'bad-guid',
+  name: 'Bad GUID',
+  schemaVersion: '1.0.0',
+  defaultScene: 'not-a-guid',
+});
+
+const WITHOUT_DEFAULT_SCENE = JSON.stringify({
+  id: 'no-default',
+  name: 'No Default',
+  schemaVersion: '1.0.0',
+});
+
+const WITH_NPC_POLICY = JSON.stringify({
+  id: 'npc-game',
+  name: 'NPC Game',
+  schemaVersion: '1.0.0',
+  npc: {
+    model: 'deepseek-v4-flash-openai',
+    maxTokens: 220,
+    budget: { maxCallsPerMinute: 30, maxTokensPerMinute: 120000, maxConcurrent: 4 },
+  },
+});
+
+// ── return path 1: forge.json missing ──────────────────────────────────────
+describe('loadGameProject — return path 1: file missing', () => {
+  it('returns {ok:false} with code forge-missing when read throws', async () => {
+    const notFound = new Error('ENOENT: no such file');
+    (notFound as NodeJS.ErrnoException).code = 'ENOENT';
+    const result = await loadGameProject(makeReadThrow(notFound));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-missing');
+    }
+  });
+
+  it('preserves forge-missing only for ENOENT', async () => {
+    const result = await loadGameProject(makeReadThrow(makeReaderError('EACCES')));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-read-failed');
+      expect(result.error.detail).toEqual({ path: 'forge.json', cause: 'permission-denied' });
+      expect(result.error.message).not.toContain('reader refusal');
+    }
+  });
+
+  it.each([
+    ['EPERM', 'permission-denied'],
+    ['EAGAIN', 'transient'],
+    ['ETIMEDOUT', 'transient'],
+    ['EUNKNOWN', 'unknown'],
+  ] as const)('maps %s to bounded cause %s', async (code, cause) => {
+    const result = await loadGameProject(
+      makeReadThrow(makeReaderError(code, 'secret reader source')),
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-read-failed');
+      expect(result.error.detail).toEqual({ path: 'forge.json', cause });
+      expect(result.error.message).not.toContain('secret reader source');
+    }
+  });
+
+  it('retries a repaired injected reader in the same process', async () => {
+    let refused = true;
+    const reads: string[] = [];
+    const read = async (path: string): Promise<string> => {
+      reads.push(path);
+      if (refused) {
+        throw makeReaderError('EAGAIN', 'temporary refusal');
+      }
+      return VALID_FORGE_JSON;
+    };
+
+    const first = await loadGameProject(read);
+    expect(first).toMatchObject({
+      ok: false,
+      error: { code: 'forge-read-failed', detail: { path: 'forge.json', cause: 'transient' } },
+    });
+
+    refused = false;
+    const second = await loadGameProject(read);
+    expect(second).toEqual({ ok: true, value: JSON.parse(VALID_FORGE_JSON) });
+    expect(reads).toEqual(['forge.json', 'forge.json']);
+  });
+});
+
+// ── return path 2: invalid JSON ─────────────────────────────────────────────
+describe('loadGameProject — return path 2: parse failed', () => {
+  it('returns {ok:false} with code forge-parse-failed for invalid JSON', async () => {
+    const result = await loadGameProject(makeRead(INVALID_JSON));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-parse-failed');
+    }
+  });
+});
+
+// ── return path 3: strict rejects unknown fields (scenes[]) ─────────────────
+describe('loadGameProject — return path 3: unknown fields', () => {
+  it('returns {ok:false} with code forge-unknown-field when scenes[] present', async () => {
+    const result = await loadGameProject(makeRead(WITH_SCENES_ARRAY));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-unknown-field');
+    }
+  });
+});
+
+// ── return path 4: defaultScene GUID format invalid ─────────────────────────
+describe('loadGameProject — return path 4: GUID malformed', () => {
+  it('returns {ok:false} with code forge-guid-malformed for bad GUID', async () => {
+    const result = await loadGameProject(makeRead(WITH_BAD_GUID));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-guid-malformed');
+    }
+  });
+});
+
+// ── return path 5: completely valid forge.json ──────────────────────────────
+describe('loadGameProject — return path 5: valid forge.json', () => {
+  it('returns {ok:true} with GameProject value for valid forge.json', async () => {
+    const result = await loadGameProject(makeRead(VALID_FORGE_JSON));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBeDefined();
+      expect(result.value.id).toBe('test-game');
+      expect(result.value.name).toBe('Test Game');
+      expect(result.value.schemaVersion).toBe('1.0.0');
+    }
+  });
+
+  it('returns {ok:true} for valid forge.json with defaultScene', async () => {
+    const result = await loadGameProject(makeRead(VALID_WITH_DEFAULT_SCENE));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.defaultScene).toBeDefined();
+    }
+  });
+
+  it('returns {ok:true} when defaultScene is absent (optional)', async () => {
+    const result = await loadGameProject(makeRead(WITHOUT_DEFAULT_SCENE));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.id).toBe('no-default');
+      expect(result.value.defaultScene).toBeUndefined();
+    }
+  });
+
+  it('accepts the Digital Life NPC policy in forge.json', async () => {
+    const result = await loadGameProject(makeRead(WITH_NPC_POLICY));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.npc?.model).toBe('deepseek-v4-flash-openai');
+      expect(result.value.npc?.budget?.maxConcurrent).toBe(4);
+    }
+  });
+
+  it('is idempotent — same read returns same result', async () => {
+    const read = makeRead(VALID_FORGE_JSON);
+    const r1 = await loadGameProject(read);
+    const r2 = await loadGameProject(read);
+    expect(r1.ok).toBe(r2.ok);
+    if (r1.ok && r2.ok) {
+      expect(r1.value.id).toBe(r2.value.id);
+    }
+  });
+
+  it('does NOT call resolveGuid internally', async () => {
+    // loadGameProject only accepts `read` — no resolveGuid in signature
+    // Signature-level verification: the function is callable with just read
+    const read = makeRead(VALID_FORGE_JSON);
+    const result = await loadGameProject(read);
+    expect(result).toBeDefined();
+  });
+});
+
+// ── missing schemaVersion → schema-invalid ──────────────────────────────────
+describe('loadGameProject — missing required fields', () => {
+  it('returns {ok:false} when schemaVersion is missing', async () => {
+    const noSchemaVersion = JSON.stringify({ id: 'test', name: 'Test' });
+    const result = await loadGameProject(makeRead(noSchemaVersion));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-schema-invalid');
+    }
+  });
+});
+
+// ── validateGameProject: sync pure core ─────────────────────────────────────
+function makeSyncRead(content: string): (path: string) => string {
+  return (_path: string) => content;
+}
+
+function makeSyncReadThrow(err: Error): (path: string) => string {
+  return (_path: string) => {
+    throw err;
+  };
+}
+
+describe('validateGameProject — sync pure core', () => {
+  it('returns {ok:true} for valid forge.json', () => {
+    const result = validateGameProject(VALID_FORGE_JSON);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.id).toBe('test-game');
+      expect(result.value.name).toBe('Test Game');
+    }
+  });
+
+  it('returns {ok:false, code:forge-parse-failed} for invalid JSON', () => {
+    const result = validateGameProject(INVALID_JSON);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-parse-failed');
+    }
+  });
+
+  it('returns {ok:false, code:forge-unknown-field} when scenes[] present', () => {
+    const result = validateGameProject(WITH_SCENES_ARRAY);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-unknown-field');
+    }
+  });
+
+  it('returns {ok:false, code:forge-guid-malformed} for bad GUID', () => {
+    const result = validateGameProject(WITH_BAD_GUID);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-guid-malformed');
+    }
+  });
+
+  it('returns {ok:false, code:forge-schema-invalid} when schemaVersion missing', () => {
+    const noSchemaVersion = JSON.stringify({ id: 'test', name: 'Test' });
+    const result = validateGameProject(noSchemaVersion);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-schema-invalid');
+    }
+  });
+});
+
+// ── loadGameProjectSync: sync companion ─────────────────────────────────────
+describe('loadGameProjectSync — sync companion', () => {
+  it('returns {ok:true} for valid forge.json', () => {
+    const result = loadGameProjectSync(makeSyncRead(VALID_FORGE_JSON));
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.id).toBe('test-game');
+      expect(result.value.name).toBe('Test Game');
+    }
+  });
+
+  it('returns {ok:false, code:forge-missing} when read throws', () => {
+    const notFound = new Error('ENOENT: no such file');
+    (notFound as NodeJS.ErrnoException).code = 'ENOENT';
+    const result = loadGameProjectSync(makeSyncReadThrow(notFound));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-missing');
+    }
+  });
+
+  it.each([
+    ['EACCES', 'permission-denied'],
+    ['EAGAIN', 'transient'],
+    ['EUNKNOWN', 'unknown'],
+  ] as const)('maps sync %s to bounded cause %s', (code, cause) => {
+    const result = loadGameProjectSync(
+      makeSyncReadThrow(makeReaderError(code, 'secret sync source')),
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-read-failed');
+      expect(result.error.detail).toEqual({ path: 'forge.json', cause });
+      expect(result.error.message).not.toContain('secret sync source');
+    }
+  });
+
+  it('retries a repaired sync reader in the same process', () => {
+    let refused = true;
+    const reads: string[] = [];
+    const read = (path: string): string => {
+      reads.push(path);
+      if (refused) {
+        throw makeReaderError('EAGAIN', 'temporary sync refusal');
+      }
+      return VALID_FORGE_JSON;
+    };
+
+    const first = loadGameProjectSync(read);
+    expect(first).toMatchObject({
+      ok: false,
+      error: { code: 'forge-read-failed', detail: { path: 'forge.json', cause: 'transient' } },
+    });
+
+    refused = false;
+    const second = loadGameProjectSync(read);
+    expect(second).toEqual({ ok: true, value: JSON.parse(VALID_FORGE_JSON) });
+    expect(reads).toEqual(['forge.json', 'forge.json']);
+  });
+
+  it('returns {ok:false, code:forge-unknown-field} when scenes[] present', () => {
+    const result = loadGameProjectSync(makeSyncRead(WITH_SCENES_ARRAY));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-unknown-field');
+    }
+  });
+
+  it('returns {ok:false, code:forge-guid-malformed} for bad GUID', () => {
+    const result = loadGameProjectSync(makeSyncRead(WITH_BAD_GUID));
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-guid-malformed');
+    }
+  });
+});