@forgeax/engine-ddc 0.1.2

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

@@ -0,0 +1,258 @@
+import { mkdtemp, 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 { DdcEntryStore, ddcOutputDigest } from '../entry-store.js';
+import { DdcStoreError } from '../errors.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);
+const KEY_C = 'c'.repeat(64);
+
+async function snapshotFiles(root: string): Promise<Record<string, string>> {
+  const files: Record<string, string> = {};
+  async function visit(directory: string): Promise<void> {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(path);
+      } else {
+        files[path.slice(root.length + 1)] = Buffer.from(await readFile(path)).toString('base64');
+      }
+    }
+  }
+  await visit(root);
+  return files;
+}
+
+async function expectHeadConflict(
+  operation: () => Promise<unknown>,
+  actual: 'syntax-invalid' | 'schema-invalid',
+): Promise<void> {
+  let error: unknown;
+  try {
+    await operation();
+  } catch (caught) {
+    error = caught;
+  }
+  expect(error).toBeInstanceOf(DdcStoreError);
+  expect(error).toMatchObject({
+    code: 'ddc-head-conflict',
+    expected: 'a valid DDC head record',
+    actual,
+    detail: expect.any(String),
+    hint: 'inspect the current head and retry with a fresh revision',
+    owner: 'engine-ddc',
+    rootKind: 'project-ddc',
+    recoveryActions: [
+      { kind: 'inspect', executable: true },
+      { kind: 'retry', executable: true },
+    ],
+  });
+  const structured = error as DdcStoreError;
+  expect(structured.detail.length).toBeLessThanOrEqual(96);
+  expect(JSON.stringify(structured)).not.toContain('/heads/');
+  expect(JSON.stringify(structured)).not.toContain('SyntaxError');
+}
+
+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 lifecycle head', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('moves missing to cooking and current only after validated commit', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({ state: 'missing' });
+    const lease = await lifecycle.begin(GUID, KEY_A);
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({ state: 'cooking' });
+    await writeEntry(root, KEY_A);
+    await expect(lifecycle.commit(lease, KEY_A)).resolves.toEqual({
+      result: 'current',
+      key: KEY_A,
+    });
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({
+      state: 'current',
+      currentKey: KEY_A,
+    });
+  });
+
+  it('retains last-known-good when recook fails', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const first = await lifecycle.begin(GUID, KEY_A);
+    await writeEntry(root, KEY_A);
+    await lifecycle.commit(first, KEY_A);
+    const second = await lifecycle.begin(GUID, KEY_B);
+    await lifecycle.fail(second, { code: 'producer-failed', detail: 'invalid source' });
+
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toMatchObject({
+      state: 'failed',
+      lastKnownGoodKey: KEY_A,
+      currentKey: KEY_A,
+      failure: { code: 'producer-failed' },
+    });
+  });
+
+  it('does not promote an old result after the desired key changes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const first = await lifecycle.begin(GUID, KEY_A);
+    await writeEntry(root, KEY_A);
+    await lifecycle.commit(first, KEY_A);
+    const second = await lifecycle.begin(GUID, KEY_B);
+
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toMatchObject({
+      state: 'cooking',
+      lastKnownGoodKey: KEY_A,
+    });
+    await expect(lifecycle.commit(second, KEY_A)).resolves.toEqual({
+      result: 'stale',
+      key: KEY_A,
+    });
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toMatchObject({
+      state: 'stale',
+      lastKnownGoodKey: KEY_A,
+      currentKey: KEY_A,
+    });
+  });
+
+  it('keeps a first cook failure failed without inventing a current or LKG', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const lease = await lifecycle.begin(GUID, KEY_A);
+    await lifecycle.fail(lease, { code: 'producer-failed', detail: 'missing input' });
+
+    await expect(lifecycle.inspect(GUID, KEY_A)).resolves.toMatchObject({
+      state: 'failed',
+      currentKey: undefined,
+      lastKnownGoodKey: undefined,
+    });
+  });
+
+  it('reports a corrupt current entry as failed with its identity preserved', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const store = new DdcEntryStore(root);
+    const firstLease = await lifecycle.begin(GUID, KEY_A);
+    await writeEntry(root, KEY_A);
+    await expect(lifecycle.commit(firstLease, KEY_A)).resolves.toEqual({
+      result: 'current',
+      key: KEY_A,
+    });
+    const lease = await lifecycle.begin(GUID, KEY_B);
+    await writeEntry(root, KEY_B);
+    await expect(lifecycle.commit(lease, KEY_B)).resolves.toEqual({
+      result: 'current',
+      key: KEY_B,
+    });
+
+    const receiptPath = join(root, 'entries', KEY_B, 'receipt.json');
+    const receipt = JSON.parse(await readFile(receiptPath, 'utf8')) as { outputDigest: string };
+    await writeFile(
+      receiptPath,
+      JSON.stringify({ ...receipt, outputDigest: `sha256:${'0'.repeat(64)}` }),
+    );
+
+    await expect(store.readChecked(KEY_B)).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'ddc-entry-invalid' },
+    });
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toMatchObject({
+      state: 'failed',
+      currentKey: KEY_B,
+      lastKnownGoodKey: KEY_A,
+      failure: { code: 'ddc-entry-invalid' },
+    });
+  });
+
+  it.each([
+    { label: 'syntax-invalid', bytes: Buffer.from('{'), actual: 'syntax-invalid' as const },
+    {
+      label: 'schema-invalid',
+      bytes: Buffer.from(JSON.stringify({ guid: GUID, desiredKey: KEY_B, revision: 'bad' })),
+      actual: 'schema-invalid' as const,
+    },
+  ])('refuses an existing $label head without mutation and recovers on same-lifecycle repair', async ({
+    bytes,
+    actual,
+  }) => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-lifecycle-'));
+    roots.push(root);
+    const lifecycle = new DdcLifecycle(root);
+    const store = new DdcEntryStore(root);
+    const firstLease = await lifecycle.begin(GUID, KEY_A);
+    await writeEntry(root, KEY_A);
+    await expect(lifecycle.commit(firstLease, KEY_A)).resolves.toMatchObject({
+      result: 'current',
+      key: KEY_A,
+    });
+    const secondLease = await lifecycle.begin(GUID, KEY_B);
+    await writeEntry(root, KEY_B);
+    await expect(lifecycle.commit(secondLease, KEY_B)).resolves.toMatchObject({
+      result: 'current',
+      key: KEY_B,
+    });
+
+    const headPath = join(root, 'heads', `${encodeURIComponent(GUID)}.json`);
+    const validHeadBytes = await readFile(headPath);
+    const prior = await lifecycle.inspect(GUID, KEY_B);
+    expect(prior).toMatchObject({
+      state: 'current',
+      currentKey: KEY_B,
+      lastKnownGoodKey: KEY_A,
+    });
+    const entryBytes = await snapshotFiles(join(root, 'entries'));
+    await writeFile(headPath, bytes);
+    const malformedFiles = await snapshotFiles(root);
+
+    await expectHeadConflict(() => lifecycle.inspect(GUID, KEY_B), actual);
+    await expect(snapshotFiles(root)).resolves.toEqual(malformedFiles);
+    await expect(store.read(KEY_A)).resolves.toMatchObject({ key: KEY_A, guid: GUID });
+    await expect(store.read(KEY_B)).resolves.toMatchObject({ key: KEY_B, guid: GUID });
+
+    await expectHeadConflict(() => lifecycle.begin(GUID, KEY_C), actual);
+    await expect(snapshotFiles(root)).resolves.toEqual(malformedFiles);
+    await expect(snapshotFiles(join(root, 'entries'))).resolves.toEqual(entryBytes);
+
+    await writeFile(headPath, validHeadBytes);
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toEqual(prior);
+    await expect(lifecycle.inspect(GUID, KEY_B)).resolves.toEqual(prior);
+
+    const nextLease = await lifecycle.begin(GUID, KEY_C);
+    expect(nextLease.expectedRevision).toBe(prior.revision);
+    expect(nextLease.generation).toBe((prior.generation ?? 0) + 1);
+    await lifecycle.close(nextLease);
+  });
+});

package/src/__tests__/multiprocess-gc.integration.test.ts

@@ -0,0 +1,36 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { collectDdcGarbage } from '../gc.js';
+import { createRuntimeScope } from '../runtime-scope.js';
+
+describe('DDC multiprocess GC and scope protection', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('keeps current, LKG and active lease objects reachable and scopes collision-free', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-multiprocess-gc-'));
+    roots.push(root);
+    await mkdir(join(root, 'entries', 'orphan'), { recursive: true });
+    await writeFile(join(root, 'entries', 'orphan', 'marker'), 'orphan');
+
+    const first = await createRuntimeScope(root, 'a/b');
+    const sibling = await createRuntimeScope(root, 'a_b');
+    const result = await collectDdcGarbage(root, {
+      currentKeys: ['current-key'],
+      lastKnownGoodKeys: ['lkg-key'],
+      activeLeaseKeys: ['lease-key'],
+      scopeIds: [first.scopeId, sibling.scopeId],
+    });
+
+    expect(first.scopeHash).not.toBe(sibling.scopeHash);
+    expect(result.deleted).not.toContain('current-key');
+    expect(result.deleted).not.toContain('lkg-key');
+    expect(result.deleted).not.toContain('lease-key');
+    expect(result.deleted).toContain('orphan');
+  });
+});

package/src/__tests__/multiprocess-lifecycle.integration.test.ts

@@ -0,0 +1,109 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { spawnDdcWorker } from './multiprocess-worker.js';
+
+const sourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entryModule = join(sourceRoot, 'entry-store.ts');
+const lifecycleModule = join(sourceRoot, 'lifecycle.ts');
+const guid = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const key = 'a'.repeat(64);
+
+function runWorker(
+  root: string,
+  source: string,
+  args: readonly string[] = [],
+): Promise<Record<string, unknown>> {
+  return new Promise((resolveWorker, reject) => {
+    const child = spawnDdcWorker(source, [lifecycleModule, root, guid, key, ...args]);
+    let output = '';
+    let error = '';
+    child.stdout.on('data', (chunk: Buffer) => (output += chunk.toString()));
+    child.stderr.on('data', (chunk: Buffer) => (error += chunk.toString()));
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`worker timed out: ${error}`));
+    }, 5000);
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`worker failed (${code}): ${error}`));
+        return;
+      }
+      try {
+        resolveWorker(JSON.parse(output) as Record<string, unknown>);
+      } catch (parseError) {
+        reject(new Error(`worker output was not JSON: ${output}; ${String(parseError)}`));
+      }
+    });
+  });
+}
+
+describe('DDC multiprocess lifecycle', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('allocates unique persistent generations across two independent processes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-multiprocess-generation-'));
+    roots.push(root);
+    const script = `
+      const { DdcLifecycle } = await load(process.argv[1]);
+      const lease = await new DdcLifecycle(process.argv[2]).begin(process.argv[3], process.argv[4]);
+      console.log(JSON.stringify({ attempt: lease.attempt, generation: lease.generation }));
+    `;
+
+    const [first, second] = await Promise.all([runWorker(root, script), runWorker(root, script)]);
+    expect(first.generation).toEqual(expect.any(Number));
+    expect(second.generation).toEqual(expect.any(Number));
+    expect(first.generation).not.toBe(second.generation);
+  });
+
+  it('does not reuse a generation after a process restart', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-multiprocess-restart-'));
+    roots.push(root);
+    const script = `
+      const { DdcLifecycle } = await load(process.argv[1]);
+      const lease = await new DdcLifecycle(process.argv[2]).begin(process.argv[3], process.argv[4]);
+      console.log(JSON.stringify({ generation: lease.generation }));
+    `;
+    const first = await runWorker(root, script);
+    const second = await runWorker(root, script);
+
+    expect(second.generation).toBeGreaterThan(first.generation as number);
+  });
+
+  it('rejects the stale writer instead of silently overwriting current', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-multiprocess-head-'));
+    roots.push(root);
+    const script = `
+      const { DdcEntryStore, ddcOutputDigest } = await load(process.argv[5]);
+      const { DdcLifecycle } = await load(process.argv[1]);
+      const root = process.argv[2];
+      const guid = process.argv[3];
+      const key = process.argv[4];
+      const payload = process.argv[6];
+      const entry = { key, guid, payload: { payload }, refs: [], artifacts: {}, receipt: { guid, key, producer: 'worker', inputFingerprint: payload, outputDigest: '' } };
+      const store = new DdcEntryStore(root);
+      const lifecycle = new DdcLifecycle(root);
+      const lease = await lifecycle.begin(guid, key);
+      await new Promise((resolve) => setTimeout(resolve, 250));
+      await store.write({ ...entry, receipt: { ...entry.receipt, outputDigest: ddcOutputDigest(entry) } });
+      const committed = await lifecycle.commit(lease, key);
+      console.log(JSON.stringify({ result: committed.result, revision: committed.revision, generation: lease.generation }));
+    `;
+    const [first, second] = await Promise.all([
+      runWorker(root, script, [entryModule, 'first']),
+      runWorker(root, script, [entryModule, 'second']),
+    ]);
+
+    expect([first.result, second.result].filter((value) => value === 'current')).toHaveLength(1);
+    expect([first.result, second.result]).toContain('stale');
+    expect(first.revision ?? second.revision).toEqual(expect.any(Number));
+  });
+});

package/src/__tests__/multiprocess-worker.ts

@@ -0,0 +1,41 @@
+import { execFileSync, spawn } from 'node:child_process';
+
+const bunWorkerArgvSentinel = '__forgeax_ddc_worker__';
+const bunBootstrap = `
+  // Bun 1.2 exposes its virtual -e entry as process.argv[1].
+  if (process.argv[1]?.endsWith('[eval]')) {
+    process.argv.splice(1, 1);
+  }
+  if (process.argv[1] === '${bunWorkerArgvSentinel}') {
+    process.argv.splice(1, 1);
+  }
+  const load = (specifier) => import(specifier);
+`;
+const nodeBootstrap = `
+  import jitiPackage from 'jiti';
+  const createJiti = jitiPackage.createJiti ?? jitiPackage.default ?? jitiPackage;
+  const jiti = createJiti(import.meta.url, { interopDefault: false });
+  const load = (specifier) => jiti.import(specifier);
+`;
+
+function resolveBunExecutable(): string | undefined {
+  const configuredRuntime = process.env.FORGEAX_DDC_WORKER_RUNTIME;
+  if (configuredRuntime === 'node') return undefined;
+  if (configuredRuntime && configuredRuntime !== 'bun') return configuredRuntime;
+  try {
+    execFileSync('bun', ['--version'], { stdio: 'ignore' });
+    return 'bun';
+  } catch {
+    return undefined;
+  }
+}
+
+export function spawnDdcWorker(source: string, args: string[]) {
+  const bunExecutable = resolveBunExecutable();
+  const runtime = bunExecutable ? bunBootstrap : nodeBootstrap;
+  const command = bunExecutable ?? process.execPath;
+  const commandArgs = bunExecutable
+    ? ['-e', `${runtime}\n${source}`, bunWorkerArgvSentinel, ...args]
+    : ['--input-type=module', '-e', `${runtime}\n${source}`, ...args];
+  return spawn(command, commandArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
+}

package/src/__tests__/status-root-kind-owner.test-d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { DdcErrorRootKind } from '../errors.js';
+import type { BrowserDdcStatusLayer, DdcStatusLayer, DdcStatusRootKind } from '../index.js';
+
+type ExpectedRootKinds = 'build-cache' | 'project-ddc' | 'runtime';
+type LayerRootKind = DdcStatusLayer['rootKind'];
+type BrowserLayerRootKind = BrowserDdcStatusLayer['rootKind'];
+
+const statusSource = readFileSync(new URL('../status.ts', import.meta.url), 'utf8');
+
+describe('DDC status root kind owner', () => {
+  it('keeps the exact root membership and derives status from the error owner', () => {
+    expectTypeOf<DdcErrorRootKind>().toEqualTypeOf<ExpectedRootKinds>();
+    expectTypeOf<ExpectedRootKinds>().toEqualTypeOf<DdcErrorRootKind>();
+    expectTypeOf<DdcStatusRootKind>().toEqualTypeOf<DdcErrorRootKind>();
+    expectTypeOf<DdcErrorRootKind>().toEqualTypeOf<DdcStatusRootKind>();
+
+    const acceptsRootKind = (kind: DdcStatusRootKind): DdcStatusRootKind => kind;
+    acceptsRootKind('build-cache');
+    acceptsRootKind('project-ddc');
+    acceptsRootKind('runtime');
+    // @ts-expect-error unknown root kinds remain outside the closed owner union.
+    acceptsRootKind('root-kind-not-real');
+  });
+
+  it('preserves the layer/root distinction and browser projection', () => {
+    expectTypeOf<DdcStatusLayer['kind']>().toEqualTypeOf<'build' | 'project' | 'runtime'>();
+    expectTypeOf<LayerRootKind>().toEqualTypeOf<DdcErrorRootKind>();
+    expectTypeOf<BrowserLayerRootKind>().toEqualTypeOf<DdcErrorRootKind>();
+  });
+
+  it('keeps the owner declaration as the single status root vocabulary', () => {
+    expect(statusSource).toContain("import type { DdcErrorRootKind } from './errors.js';");
+    expect(statusSource).toContain('export type DdcStatusRootKind = DdcErrorRootKind;');
+    expect(statusSource).not.toContain(
+      "export type DdcStatusRootKind = 'build-cache' | 'project-ddc' | 'runtime';",
+    );
+  });
+});

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DDC_STATUS_SCHEMA,
+  type DdcStatus,
+  projectDdcStatusForBrowser,
+  serializeDdcStatus,
+} from '../status.js';
+
+describe('DDC versioned status envelope', () => {
+  const status: DdcStatus = {
+    schemaVersion: DDC_STATUS_SCHEMA,
+    health: 'blocked',
+    gameDir: '/Users/test/game',
+    projectDdcRoot: '/Users/test/game/.forgeax/ddc/v2',
+    layers: [
+      {
+        kind: 'project',
+        owner: 'engine-ddc',
+        rootKind: 'project-ddc',
+        scopeId: 'editor/main',
+        current: 7,
+        lastKnownGood: 6,
+        protection: ['current', 'lease:editor-a'],
+        actions: [
+          {
+            kind: 'prune',
+            executable: true,
+            exactTarget: '/Users/test/game/.forgeax/ddc/v2/generations/4',
+          },
+        ],
+      },
+    ],
+  };
+
+  it('serializes the public schema with layer, owner, current, LKG, protection and actions', () => {
+    const serialized = JSON.parse(serializeDdcStatus(status)) as DdcStatus;
+
+    expect(serialized).toEqual(status);
+    expect(serialized.schemaVersion).toBe('forgeax-ddc-status/v2');
+  });
+
+  it('redacts every host path from browser projection while preserving recovery data', () => {
+    const browser = projectDdcStatusForBrowser(status);
+    const text = JSON.stringify(browser);
+
+    expect(browser).not.toHaveProperty('gameDir');
+    expect(browser).not.toHaveProperty('projectDdcRoot');
+    expect(text).not.toContain('/Users/test');
+    expect(browser.layers[0]).toMatchObject({
+      current: 7,
+      lastKnownGood: 6,
+      protection: ['current', 'lease:editor-a'],
+      actions: [{ kind: 'prune', executable: true }],
+    });
+  });
+});