@forgeax/engine-ddc 0.1.2

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@forgeax/engine-ddc",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Node-only v2 immutable derived data cache with project-local lifecycle evidence.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": {
+        "import": "./dist/index.mjs"
+      },
+      "default": null
+    },
+    "./key": {
+      "types": "./dist/key.d.ts",
+      "node": {
+        "import": "./dist/key.mjs"
+      },
+      "default": null
+    },
+    "./entry-store": {
+      "types": "./dist/entry-store.d.ts",
+      "node": {
+        "import": "./dist/entry-store.mjs"
+      },
+      "default": null
+    },
+    "./layout": {
+      "types": "./dist/layout.d.ts",
+      "node": {
+        "import": "./dist/layout.mjs"
+      },
+      "default": null
+    },
+    "./status": {
+      "types": "./dist/status.d.ts",
+      "node": {
+        "import": "./dist/status.mjs"
+      },
+      "default": null
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "node": {
+        "import": "./dist/errors.mjs"
+      },
+      "default": null
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "Node-only build-time cache package; no runtime frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "DDC transaction correctness is covered by integration tests; no benchmark contract is declared"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "No package-level binary gate; workspace CI owns cache audit and type gates"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "Not a spike package"
+      }
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "vitest": "4.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -b",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/concurrency.integration.test.ts

@@ -0,0 +1,53 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { type DdcEntry, DdcEntryStore, ddcOutputDigest } from '../entry-store.js';
+
+const KEY = 'a'.repeat(64);
+const entry = (payload: string): DdcEntry => {
+  const value = {
+    key: KEY,
+    guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+    payload: { payload },
+    refs: [],
+    artifacts: {
+      data: { mediaType: 'application/octet-stream', bytes: new Uint8Array([1, 2, 3]) },
+    },
+    receipt: {
+      guid: '019e3969-1d48-7c3b-ac24-6d68f457065f',
+      key: KEY,
+      producer: 'test-producer',
+      inputFingerprint: 'input',
+      outputDigest: '',
+    },
+  } satisfies DdcEntry;
+  return { ...value, receipt: { ...value.receipt, outputDigest: ddcOutputDigest(value) } };
+};
+
+describe('DDC same-key writer concurrency', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('lets one writer publish and makes the loser observe an identical entry', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-concurrency-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    const results = await Promise.all([store.write(entry('same')), store.write(entry('same'))]);
+
+    expect(results.map((result) => result.result).sort()).toEqual(['existing', 'published']);
+    await expect(store.read(KEY)).resolves.toEqual(entry('same'));
+  });
+
+  it('reports a conflict when the same key maps to different bytes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-concurrency-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry('first'));
+    await expect(store.write(entry('second'))).resolves.toEqual({ result: 'conflict', key: KEY });
+    await expect(store.read(KEY)).resolves.toEqual(entry('first'));
+  });
+});

package/src/__tests__/consumer-path.integration.test.ts

@@ -0,0 +1,61 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { type DdcEntry, DdcEntryStore, ddcOutputDigest } from '../entry-store.js';
+
+const guid = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const key = 'a'.repeat(64);
+
+describe('DDC consumer path', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('rebuilds the same output after deleting DDC storage', async () => {
+    const firstRoot = await mkdtemp(join(tmpdir(), 'forgeax-ddc-consumer-'));
+    const secondRoot = await mkdtemp(join(tmpdir(), 'forgeax-ddc-consumer-'));
+    roots.push(firstRoot, secondRoot);
+    const cookedBase = {
+      key,
+      guid,
+      payload: { kind: 'texture', width: 2, height: 1 },
+      refs: [],
+      artifacts: {
+        payload: { mediaType: 'application/octet-stream', bytes: new Uint8Array([1, 2]) },
+      },
+      receipt: {
+        guid,
+        key,
+        producer: 'image-importer@4',
+        inputFingerprint: 'source-bytes',
+        outputDigest: '',
+      },
+    } satisfies DdcEntry;
+    const cooked: DdcEntry = {
+      ...cookedBase,
+      receipt: { ...cookedBase.receipt, outputDigest: ddcOutputDigest(cookedBase) },
+    };
+
+    const firstStore = new DdcEntryStore(firstRoot);
+    await firstStore.write(cooked);
+    const cold = await firstStore.read(key);
+    await rm(firstRoot, { recursive: true, force: true });
+    const secondStore = new DdcEntryStore(secondRoot);
+    await secondStore.write(cooked);
+    const rebuilt = await secondStore.read(key);
+
+    expect(rebuilt).toEqual(cold);
+    expect(rebuilt?.guid).toBe(guid);
+    expect(rebuilt?.receipt.outputDigest).toBe(ddcOutputDigest(cooked));
+  });
+
+  it('keeps a direct product path independent from DDC presence', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-direct-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await expect(store.read(key)).resolves.toBeNull();
+  });
+});

package/src/__tests__/crash-recovery.integration.test.ts

@@ -0,0 +1,84 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DdcEntryStore, ddcOutputDigest } from '../entry-store.js';
+import { DdcLifecycle } from '../lifecycle.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const KEY_A = 'a'.repeat(64);
+const KEY_B = 'b'.repeat(64);
+
+async function writeEntry(root: string, key: string): Promise<void> {
+  const base = {
+    key,
+    guid: GUID,
+    payload: { key },
+    refs: [],
+    artifacts: {},
+    receipt: {
+      guid: GUID,
+      key,
+      producer: 'test',
+      inputFingerprint: key,
+      outputDigest: '',
+    },
+  } as const;
+  await new DdcEntryStore(root).write({
+    ...base,
+    receipt: { ...base.receipt, outputDigest: ddcOutputDigest(base) },
+  });
+}
+
+describe('DDC lease and crash recovery', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('keeps a crashed cooking attempt out of the readable head', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-crash-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    await lifecycle.begin(GUID, KEY_A);
+
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({ state: 'cooking' });
+    await expect(lifecycle.recover(GUID, KEY_A)).resolves.toMatchObject({ state: 'failed' });
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({
+      state: 'failed',
+      currentKey: undefined,
+    });
+  });
+
+  it('rejects a commit after the lease is lost', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-crash-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const lease = await lifecycle.begin(GUID, KEY_A);
+    await lifecycle.revoke(lease);
+
+    await expect(lifecycle.commit(lease, KEY_A)).resolves.toEqual({
+      result: 'lease-lost',
+      key: KEY_A,
+    });
+  });
+
+  it('keeps an old writer stale after a newer desired key starts cooking', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-crash-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const oldLease = await lifecycle.begin(GUID, KEY_A);
+    const newLease = await lifecycle.begin(GUID, KEY_B);
+    await writeEntry(root, KEY_B);
+
+    await expect(lifecycle.commit(oldLease, KEY_A)).resolves.toEqual({
+      result: 'stale',
+      key: KEY_A,
+    });
+    await expect(lifecycle.commit(newLease, KEY_B)).resolves.toEqual({
+      result: 'current',
+      key: KEY_B,
+    });
+  });
+});

package/src/__tests__/entry-store.integration.test.ts

@@ -0,0 +1,83 @@
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { type DdcEntry, DdcEntryStore, ddcOutputDigest } from '../entry-store.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const KEY = 'a'.repeat(64);
+
+const entry = (): DdcEntry => {
+  const value = {
+    key: KEY,
+    guid: GUID,
+    payload: { kind: 'texture', width: 2, height: 1 },
+    refs: ['019e3969-1d48-7c3b-ac24-6d68f457065e'],
+    artifacts: {
+      payload: { mediaType: 'application/octet-stream', bytes: new Uint8Array([1, 2, 3]) },
+    },
+    receipt: {
+      guid: GUID,
+      key: KEY,
+      producer: 'image-importer@4',
+      inputFingerprint: 'input-a',
+      outputDigest: '',
+    },
+  } satisfies DdcEntry;
+  return { ...value, receipt: { ...value.receipt, outputDigest: ddcOutputDigest(value) } };
+};
+
+describe('immutable DDC entry store', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('keeps staged data invisible until an atomic publish', async () => {
+    const root = join(tmpdir(), `forgeax-ddc-entry-${Date.now()}-${Math.random()}`);
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    const staged = await store.stage(entry());
+
+    expect(await store.read(KEY)).toBeNull();
+    expect(await readdir(join(staged.path, 'artifacts'))).toEqual(['payload.bin']);
+    expect(JSON.parse(await readFile(join(staged.path, 'refs.json'), 'utf8'))).toEqual([
+      '019e3969-1d48-7c3b-ac24-6d68f457065e',
+    ]);
+
+    const published = await store.publish(staged);
+    expect(published).toEqual({ result: 'published', key: KEY });
+    await expect(store.read(KEY)).resolves.toEqual(entry());
+  });
+
+  it('does not expose a partial entry when a required artifact is missing', async () => {
+    const root = join(tmpdir(), `forgeax-ddc-entry-${Date.now()}-${Math.random()}`);
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    const staged = await store.stage(entry());
+    await rm(join(staged.path, 'artifacts', 'payload.bin'));
+    await expect(store.publish(staged)).rejects.toMatchObject({ code: 'ddc-entry-incomplete' });
+    await expect(store.read(KEY)).resolves.toBeNull();
+  });
+
+  it('rejects a receipt or integrity mismatch on reread', async () => {
+    const root = join(tmpdir(), `forgeax-ddc-entry-${Date.now()}-${Math.random()}`);
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry());
+    await writeFile(
+      join(root, 'entries', KEY, 'receipt.json'),
+      JSON.stringify({ ...entry().receipt, key: 'b'.repeat(64) }),
+    );
+    await expect(store.read(KEY)).resolves.toBeNull();
+  });
+
+  it('returns an existing immutable entry instead of replacing it', async () => {
+    const root = join(tmpdir(), `forgeax-ddc-entry-${Date.now()}-${Math.random()}`);
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await expect(store.write(entry())).resolves.toEqual({ result: 'published', key: KEY });
+    await expect(store.write(entry())).resolves.toEqual({ result: 'existing', key: KEY });
+  });
+});

package/src/__tests__/errors.unit.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { DDC_ERROR_CODES, DdcStoreError } from '../errors.js';
+
+describe('DDC closed errors', () => {
+  it('exposes the complete closed conflict/configuration code union', () => {
+    expect(DDC_ERROR_CODES).toEqual([
+      'ddc-project-root-required',
+      'ddc-object-conflict',
+      'ddc-head-conflict',
+      'ddc-generation-conflict',
+      'ddc-scope-mismatch',
+      'ddc-lease-expired',
+    ]);
+  });
+
+  it('keeps structured recovery fields and redacts host paths for browser consumers', () => {
+    const error = new DdcStoreError({
+      code: 'ddc-scope-mismatch',
+      detail: 'scope metadata does not match the requested scope',
+      hint: 'reinspect the canonical project root and allocate a new scope',
+      expected: { scopeId: 'editor/main' },
+      actual: { scopeId: 'editor_main' },
+      owner: 'engine-ddc',
+      rootKind: 'project-ddc',
+      scope: 'editor/main',
+      generation: 7,
+      lease: 'lease-7',
+      revision: 3,
+      recoveryActions: [
+        { kind: 'inspect', executable: true },
+        { kind: 'allocate-generation', executable: true },
+      ],
+      hostPath: '/Users/test/game/.forgeax/ddc/v2/scope.json',
+    });
+
+    expect(error).toMatchObject({
+      code: 'ddc-scope-mismatch',
+      expected: { scopeId: 'editor/main' },
+      actual: { scopeId: 'editor_main' },
+      owner: 'engine-ddc',
+      rootKind: 'project-ddc',
+      scope: 'editor/main',
+      generation: 7,
+      lease: 'lease-7',
+      revision: 3,
+      recoveryActions: [
+        { kind: 'inspect', executable: true },
+        { kind: 'allocate-generation', executable: true },
+      ],
+    });
+    expect(error.toBrowserProjection()).not.toHaveProperty('hostPath');
+    expect(JSON.stringify(error.toBrowserProjection())).not.toContain('/Users/test');
+  });
+});

package/src/__tests__/key.unit.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { type SemanticDdcInput, semanticDdcKey } from '../key.js';
+
+const baseInput = (): SemanticDdcInput => ({
+  schemaVersion: 'asset-pack@2',
+  importer: 'image@4',
+  codec: 'basis@3',
+  settings: { colorSpace: 'srgb', mipmap: true },
+  sourceBytes: [new Uint8Array([1, 2, 3, 4])],
+  declaredGuids: ['019e3969-1d48-7c3b-ac24-6d68f457065f'],
+  targetProfile: 'webgpu-release',
+  producer: 'image-importer@4',
+});
+
+describe('semantic DDC key', () => {
+  it('is deterministic for equal semantic inputs', () => {
+    expect(semanticDdcKey(baseInput())).toBe(semanticDdcKey(baseInput()));
+  });
+
+  it('does not include author path or publication environment', () => {
+    const input = baseInput();
+    const moved = { ...input, sourceBytes: [new Uint8Array([1, 2, 3, 4])] };
+    expect(semanticDdcKey(input)).toBe(semanticDdcKey(moved));
+  });
+
+  it.each([
+    ['schemaVersion', { schemaVersion: 'asset-pack@3' }],
+    ['importer', { importer: 'image@5' }],
+    ['codec', { codec: 'basis@4' }],
+    ['settings', { settings: { colorSpace: 'linear', mipmap: true } }],
+    ['sourceBytes', { sourceBytes: [new Uint8Array([1, 2, 3, 5])] }],
+    ['declaredGuids', { declaredGuids: ['019e3969-1d48-7c3b-ac24-6d68f457065e'] }],
+    ['targetProfile', { targetProfile: 'webgpu-debug' }],
+    ['producer', { producer: 'image-importer@5' }],
+  ])('misses when %s changes', (_name, change) => {
+    expect(semanticDdcKey({ ...baseInput(), ...change })).not.toBe(semanticDdcKey(baseInput()));
+  });
+
+  it('canonicalizes object and GUID ordering without changing the digest', () => {
+    const input = baseInput();
+    expect(
+      semanticDdcKey({
+        ...input,
+        settings: { mipmap: true, colorSpace: 'srgb' },
+        declaredGuids: [...input.declaredGuids].reverse(),
+      }),
+    ).toBe(semanticDdcKey(input));
+  });
+});

package/src/__tests__/layout.unit.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { DDC_LAYOUT_VERSION, type DdcServeOptions, resolveDdcLayout } from '../layout.js';
+
+describe('DDC v2 layout contract', () => {
+  it('normalizes both explicitly injected roots without consulting cwd or roots[0]', () => {
+    const result = resolveDdcLayout({
+      buildCacheRoot: '/tmp/forgeax/cache/../cache',
+      projectDdcRoot: '/tmp/forgeax/game/.forgeax/ddc/v2/./',
+    } satisfies DdcServeOptions);
+
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        version: DDC_LAYOUT_VERSION,
+        buildCacheRoot: '/tmp/forgeax/cache',
+        projectDdcRoot: '/tmp/forgeax/game/.forgeax/ddc/v2',
+      },
+    });
+  });
+
+  it('fails closed when serve/publication has no project root', () => {
+    const result = resolveDdcLayout({ buildCacheRoot: '/tmp/forgeax/cache' });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'ddc-project-root-required' },
+    });
+  });
+
+  it('has one canonical v2 child layout and cannot derive a root from asset inputs', () => {
+    const result = resolveDdcLayout({
+      buildCacheRoot: '/tmp/cache',
+      projectDdcRoot: '/tmp/game/.forgeax/ddc/v2',
+    });
+
+    if (!result.ok) throw result.error;
+    expect(result.value.build).toEqual({
+      objects: '/tmp/cache/objects',
+      staging: '/tmp/cache/staging',
+    });
+    expect(result.value.project).toEqual({
+      root: '/tmp/game/.forgeax/ddc/v2',
+      scope: '/tmp/game/.forgeax/ddc/v2/scope.json',
+      heads: '/tmp/game/.forgeax/ddc/v2/heads',
+      generations: '/tmp/game/.forgeax/ddc/v2/generations',
+      leases: '/tmp/game/.forgeax/ddc/v2/leases',
+      staging: '/tmp/game/.forgeax/ddc/v2/staging',
+    });
+  });
+});