@forgeax/engine-ddc 0.0.0-dev.8d955ade1c79

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__/generation-session.integration.test.ts

@@ -0,0 +1,202 @@
+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';
+import { DdcLifecycle } from '../lifecycle.js';
+import { DdcGenerationSession } from '../session.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const KEY = 'a'.repeat(64);
+const KEY_B = 'b'.repeat(64);
+const KEY_C = 'c'.repeat(64);
+
+function entry(key = KEY): DdcEntry {
+  const value = {
+    key,
+    guid: GUID,
+    payload: { kind: 'fixture', key },
+    refs: [],
+    artifacts: {},
+    receipt: {
+      guid: GUID,
+      key,
+      producer: 'fixture',
+      inputFingerprint: 'sha256:source',
+      outputDigest: '',
+    },
+  } satisfies DdcEntry;
+  return { ...value, receipt: { ...value.receipt, outputDigest: ddcOutputDigest(value) } };
+}
+
+describe('DDC generation session integration', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('accepts one validated candidate and keeps a later generation isolated', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry());
+
+    const first = new DdcGenerationSession(root, { generation: 1 });
+    const candidate = await first.beginCandidate(GUID, KEY);
+    await expect(first.commitCandidate(candidate, KEY)).resolves.toMatchObject({
+      result: 'current',
+    });
+    await expect(first.inspect(GUID, KEY)).resolves.toMatchObject({
+      state: 'current',
+      currentKey: KEY,
+    });
+    await first.close();
+
+    const second = new DdcGenerationSession(root, { generation: 2 });
+    expect(second.metrics().hitCount).toBe(0);
+    await expect(second.inspect(GUID, KEY)).resolves.toMatchObject({ state: 'current' });
+    expect(second.metrics().hitCount).toBe(1);
+    await second.close();
+  });
+
+  it('heartbeats staged candidates during a long generation before commit', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const session = new DdcGenerationSession(root, { generation: 1, leaseTtlMs: 100 });
+    try {
+      const candidate = await session.stageEntry(entry());
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      await expect(session.commitEntry(candidate, KEY)).resolves.toMatchObject({
+        result: 'current',
+      });
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('does not let a stale rollback restore over a newer active lease', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry());
+
+    const first = new DdcGenerationSession(root, { generation: 1 });
+    const firstCandidate = await first.stageEntry(entry());
+    const second = new DdcGenerationSession(root, { generation: 2 });
+    const secondCandidate = await second.stageEntry(entry());
+
+    await expect(first.commitEntry(firstCandidate, KEY)).resolves.toMatchObject({
+      result: 'stale',
+    });
+    await expect(first.restoreEntry(firstCandidate)).resolves.toMatchObject({
+      result: 'not-owner',
+    });
+
+    await expect(second.commitEntry(secondCandidate, KEY)).resolves.toMatchObject({
+      result: 'current',
+    });
+    await expect(first.restoreEntry(firstCandidate)).resolves.toMatchObject({
+      result: 'not-owner',
+    });
+    await expect(second.inspect(GUID, KEY)).resolves.toMatchObject({
+      state: 'current',
+      currentKey: KEY,
+    });
+    await first.close();
+    await second.close();
+  });
+
+  it('restores an own active candidate without regressing revision or generation', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const { lease, previousHead } = await lifecycle.beginWithSnapshot(GUID, KEY);
+
+    expect('activeLease' in previousHead).toBe(false);
+    await expect(lifecycle.restoreIfCurrent(previousHead, lease)).resolves.toMatchObject({
+      result: 'restored',
+      revision: 1,
+      generation: lease.generation,
+    });
+    await expect(lifecycle.inspect(GUID, KEY)).resolves.toMatchObject({
+      state: 'missing',
+      revision: 1,
+    });
+
+    const next = await lifecycle.begin(GUID, KEY);
+    expect(next.expectedRevision).toBe(1);
+    expect(next.generation).toBeGreaterThan(lease.generation);
+    await lifecycle.close(next);
+  });
+
+  it('restores an own terminal mutation while preserving the accepted head', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry(KEY));
+    const lifecycle = new DdcLifecycle(root);
+    const accepted = await lifecycle.begin(GUID, KEY);
+    await expect(lifecycle.commit(accepted, KEY)).resolves.toMatchObject({ result: 'current' });
+
+    const { lease, previousHead } = await lifecycle.beginWithSnapshot(GUID, KEY_B);
+    await store.write(entry(KEY_B));
+    const committed = await lifecycle.commit(lease, KEY_B);
+    expect(committed.restoreFence).toMatchObject({ outcome: 'current' });
+    await expect(
+      lifecycle.restoreIfCurrent(previousHead, lease, committed.restoreFence),
+    ).resolves.toMatchObject({ result: 'restored' });
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toMatchObject({
+      state: 'stale',
+      currentKey: KEY,
+      revision: (committed.revision ?? 0) + 1,
+      generation: lease.generation,
+    });
+  });
+
+  it('rolls back a newer cooking candidate without reviving its superseded writer', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const store = new DdcEntryStore(root);
+    await store.write(entry(KEY));
+    const lifecycle = new DdcLifecycle(root);
+    const accepted = await lifecycle.begin(GUID, KEY);
+    await lifecycle.commit(accepted, KEY);
+
+    const first = new DdcGenerationSession(root, { generation: 1 });
+    const firstCandidate = await first.stageEntry(entry(KEY_B));
+    const second = new DdcGenerationSession(root, { generation: 2 });
+    const secondCandidate = await second.stageEntry(entry(KEY_C));
+
+    await expect(second.restoreEntry(secondCandidate)).resolves.toMatchObject({
+      result: 'restored',
+    });
+    await expect(first.restoreEntry(firstCandidate)).resolves.toMatchObject({
+      result: 'not-owner',
+    });
+    await expect(second.inspect(GUID, KEY_C)).resolves.toMatchObject({
+      state: 'stale',
+      currentKey: KEY,
+    });
+    await first.close();
+    await second.close();
+  });
+
+  it('fences a failed terminal mutation before restoring accepted content', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const { lease, previousHead } = await lifecycle.beginWithSnapshot(GUID, KEY);
+    const failed = await lifecycle.fail(lease, { code: 'producer-failed', detail: 'fixture' });
+
+    expect(failed).toMatchObject({ outcome: 'failed', revision: 1 });
+    await expect(lifecycle.restoreIfCurrent(previousHead, lease, failed)).resolves.toMatchObject({
+      result: 'restored',
+      revision: 2,
+    });
+    await expect(lifecycle.inspect(GUID, KEY)).resolves.toMatchObject({
+      state: 'missing',
+      revision: 2,
+    });
+  });
+});

package/src/__tests__/generation-session.unit.test.ts

@@ -0,0 +1,35 @@
+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 { DdcGenerationSession } from '../session.js';
+
+describe('DDC generation session contract', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('fences candidates to one generation and exposes bounded session metrics', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-session-'));
+    roots.push(root);
+    const session = new DdcGenerationSession(root, { generation: 7 });
+
+    const candidate = await session.beginCandidate('asset-a', 'a'.repeat(64));
+    expect(candidate.generation).toBe(7);
+    expect(candidate.lease.guid).toBe('asset-a');
+    expect(session.metrics()).toEqual({
+      hitCount: 0,
+      missCount: 1,
+      corruptCount: 0,
+      writeFailureCount: 0,
+    });
+
+    await session.discardCandidate(candidate);
+    await session.close();
+    await expect(session.beginCandidate('asset-b', 'b'.repeat(64))).rejects.toThrow(
+      'DDC generation session is closed',
+    );
+  });
+});

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',
+    });
+  });
+});