@forgeax/engine-ddc 0.1.2 → 0.1.4

package/dist/session.d.ts

@@ -0,0 +1,45 @@
+import type { DdcEntry, StagedDdcEntry } from './entry-store.js';
+import type { DdcCommitResult, DdcHead, DdcLease } from './lifecycle.js';
+export interface DdcSessionOptions {
+    readonly generation: number;
+    readonly leaseTtlMs?: number;
+}
+export interface DdcGenerationCandidate {
+    readonly generation: number;
+    readonly lease: DdcLease;
+    readonly previousHead: DdcHead;
+}
+export interface DdcGenerationEntryCandidate extends DdcGenerationCandidate {
+    readonly staged: StagedDdcEntry;
+}
+export interface DdcSessionMetrics {
+    readonly hitCount: number;
+    readonly missCount: number;
+    readonly corruptCount: number;
+    readonly writeFailureCount: number;
+}
+export declare class DdcGenerationSession {
+    readonly generation: number;
+    private readonly lifecycle;
+    private readonly entries;
+    private readonly candidates;
+    private readonly heartbeatTimers;
+    private readonly counters;
+    private accepting;
+    constructor(root: string, options: DdcSessionOptions);
+    beginCandidate(guid: string, desiredKey: string): Promise<DdcGenerationCandidate>;
+    stageEntry(entry: DdcEntry): Promise<DdcGenerationEntryCandidate>;
+    inspect(guid: string, desiredKey: string): Promise<DdcHead>;
+    commitCandidate(candidate: DdcGenerationCandidate, validatedKey: string): Promise<DdcCommitResult>;
+    commitEntry(candidate: DdcGenerationEntryCandidate, validatedKey: string): Promise<DdcCommitResult>;
+    discardCandidate(candidate: DdcGenerationCandidate): Promise<void>;
+    discardEntry(candidate: DdcGenerationEntryCandidate): Promise<void>;
+    restoreEntry(candidate: DdcGenerationEntryCandidate): Promise<void>;
+    metrics(): DdcSessionMetrics;
+    close(): Promise<void>;
+    private assertOpen;
+    private assertCandidate;
+    private scheduleHeartbeat;
+    private stopHeartbeat;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAGzE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAmBD,qBAAa,oBAAoB;IAC/B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoD;IAC/E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAKvB;IACF,OAAO,CAAC,SAAS,CAAQ;gBAEN,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;IAY9C,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAajF,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAyBjE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3D,eAAe,CAC1B,SAAS,EAAE,sBAAsB,EACjC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC;IAed,WAAW,CACtB,SAAS,EAAE,2BAA2B,EACtC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC;IAqBd,gBAAgB,CAAC,SAAS,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAalE,YAAY,CAAC,SAAS,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,YAAY,CAAC,SAAS,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBzE,OAAO,IAAI,iBAAiB;IAItB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBnC,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,aAAa;CAMtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-ddc",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -84,6 +84,9 @@
       }
     }
   },
+  "dependencies": {
+    "@forgeax/engine-types": "0.1.4"
+  },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "tsup": "^8.3.5",

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

@@ -0,0 +1,74 @@
+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 { DdcGenerationSession } from '../session.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const KEY = 'a'.repeat(64);
+
+function entry(): DdcEntry {
+  const value = {
+    key: KEY,
+    guid: GUID,
+    payload: { kind: 'fixture' },
+    refs: [],
+    artifacts: {},
+    receipt: {
+      guid: GUID,
+      key: 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();
+    }
+  });
+});

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__/owner-chain.integration.test.ts

@@ -0,0 +1,45 @@
+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 { DdcGenerationSession } from '../session.js';
+
+const GUID = '019e3969-1d48-7c3b-ac24-6d68f457065f';
+const KEY = 'a'.repeat(64);
+
+describe('DDC owner chain', () => {
+  const roots: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+  });
+
+  it('accepts only the validated entry for the current candidate', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-owner-chain-'));
+    roots.push(root);
+    const value = {
+      key: KEY,
+      guid: GUID,
+      payload: { kind: 'texture' },
+      refs: [],
+      artifacts: {},
+      receipt: {
+        guid: GUID,
+        key: KEY,
+        producer: 'owner-chain',
+        inputFingerprint: 'sha256:source',
+        outputDigest: '',
+      },
+    } satisfies DdcEntry;
+    const entry = { ...value, receipt: { ...value.receipt, outputDigest: ddcOutputDigest(value) } };
+    await new DdcEntryStore(root).write(entry);
+    const session = new DdcGenerationSession(root, { generation: 3 });
+    const candidate = await session.beginCandidate(GUID, KEY);
+    await expect(session.commitCandidate(candidate, KEY)).resolves.toMatchObject({
+      result: 'current',
+    });
+    await expect(session.inspect(GUID, KEY)).resolves.toMatchObject({ state: 'current' });
+    await session.close();
+  });
+});

package/src/build-cache.ts

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { semanticDdcKey as ownerSemanticDdcKey } from './key.js';
+
+export interface BuildDdcInput {
+  readonly schemaVersion: string;
+  readonly importerVersion: string;
+  readonly codecVersion: string;
+  readonly sourceDependencies: readonly (
+    | string
+    | { readonly path: string; readonly digest: string }
+  )[];
+  readonly settings: unknown;
+  readonly declaredGuids: readonly string[];
+  readonly cookProfile: string;
+  readonly sourceOverrides?: unknown;
+  readonly publish?: unknown;
+}
+
+export function resolveDdcRoot(cwd: string): string {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, 'pnpm-workspace.yaml'))) {
+      return join(current, 'node_modules/.cache/forgeax-ddc');
+    }
+    const parent = dirname(current);
+    if (parent === current) return join(resolve(cwd), 'node_modules/.cache/forgeax-ddc');
+    current = parent;
+  }
+}
+
+/** Derive the build key while keeping publish URLs out of the semantic identity. */
+export function semanticBuildKey(input: BuildDdcInput): string {
+  const hasSourceOverrides =
+    input.sourceOverrides !== undefined &&
+    typeof input.sourceOverrides === 'object' &&
+    input.sourceOverrides !== null &&
+    !Array.isArray(input.sourceOverrides) &&
+    Object.keys(input.sourceOverrides).length > 0;
+  const settings = hasSourceOverrides
+    ? { settings: input.settings, sourceOverrides: input.sourceOverrides }
+    : input.settings;
+  return ownerSemanticDdcKey({
+    schemaVersion: input.schemaVersion,
+    importer: input.importerVersion,
+    codec: input.codecVersion,
+    settings,
+    sourceBytes: input.sourceDependencies
+      .map((dependency) =>
+        typeof dependency === 'string'
+          ? dependency.replaceAll('\\', '/').replace(/^.*\/(assets\/)/, '$1')
+          : dependency.digest,
+      )
+      .sort()
+      .map((digest) => new TextEncoder().encode(digest)),
+    declaredGuids: input.declaredGuids,
+    targetProfile: input.cookProfile,
+    producer: input.importerVersion,
+  });
+}

package/src/entry-store.ts

@@ -169,19 +169,24 @@ export class DdcEntryStore {
       throw new DdcStoreError('ddc-entry-invalid', 'receipt output digest does not match entry');
     }
     const path = join(this.staging, `${entry.key}-${randomUUID()}`);
-    await mkdir(join(path, 'artifacts'), { recursive: true });
-    await writeFile(join(path, 'payload.json'), canonicalDdcJson(entry.payload));
-    await writeFile(join(path, 'refs.json'), canonicalDdcJson(entry.refs));
-    await writeFile(join(path, 'receipt.json'), canonicalDdcJson(entry.receipt));
-    const artifacts: Record<string, { mediaType: string; file: string }> = {};
-    for (const [key, artifact] of sortedArtifacts(entry)) {
-      const file = artifactFile(key);
-      artifacts[key] = { mediaType: artifact.mediaType, file };
-      await writeFile(join(path, 'artifacts', `${file}.bin`), artifact.bytes);
+    try {
+      await mkdir(join(path, 'artifacts'), { recursive: true });
+      await writeFile(join(path, 'payload.json'), canonicalDdcJson(entry.payload));
+      await writeFile(join(path, 'refs.json'), canonicalDdcJson(entry.refs));
+      await writeFile(join(path, 'receipt.json'), canonicalDdcJson(entry.receipt));
+      const artifacts: Record<string, { mediaType: string; file: string }> = {};
+      for (const [key, artifact] of sortedArtifacts(entry)) {
+        const file = artifactFile(key);
+        artifacts[key] = { mediaType: artifact.mediaType, file };
+        await writeFile(join(path, 'artifacts', `${file}.bin`), artifact.bytes);
+      }
+      await writeFile(join(path, 'artifacts.json'), canonicalDdcJson(artifacts));
+      await writeFile(join(path, 'integrity.json'), canonicalDdcJson(integrityFor(entry)));
+      return { key: entry.key, path };
+    } catch (error) {
+      await rm(path, { recursive: true, force: true }).catch(() => {});
+      throw error;
     }
-    await writeFile(join(path, 'artifacts.json'), canonicalDdcJson(artifacts));
-    await writeFile(join(path, 'integrity.json'), canonicalDdcJson(integrityFor(entry)));
-    return { key: entry.key, path };
   }
 
   public async publish(staged: StagedDdcEntry): Promise<PublishDdcEntryResult> {
@@ -189,11 +194,14 @@ export class DdcEntryStore {
     const candidate = await this.readDirectory(staged.path, true);
     const target = join(this.entries, staged.key);
     await mkdir(this.entries, { recursive: true });
-    try {
-      await stat(target);
+    const useExisting = async (): Promise<PublishDdcEntryResult> => {
       const existing = await this.readDirectory(target, false);
       await rm(staged.path, { recursive: true, force: true });
       return existingResult(existing, candidate, staged.key);
+    };
+    try {
+      await stat(target);
+      return useExisting();
     } catch (error) {
       if (error instanceof DdcStoreError) throw error;
       if (errorCode(error) !== 'ENOENT') throw error;
@@ -203,12 +211,14 @@ export class DdcEntryStore {
       return { result: 'published', key: staged.key };
     } catch (error) {
       if (!['EEXIST', 'ENOTEMPTY', 'EISDIR'].includes(errorCode(error) ?? '')) throw error;
-      const existing = await this.readDirectory(target, false);
-      await rm(staged.path, { recursive: true, force: true });
-      return existingResult(existing, candidate, staged.key);
+      return useExisting();
     }
   }
 
+  public async discard(staged: StagedDdcEntry): Promise<void> {
+    await rm(staged.path, { recursive: true, force: true });
+  }
+
   public async write(entry: DdcEntry): Promise<PublishDdcEntryResult> {
     const staged = await this.stage(entry);
     return this.publish(staged);

package/src/index.ts

@@ -1,8 +1,14 @@
+export {
+  type BuildDdcInput,
+  resolveDdcRoot,
+  semanticBuildKey,
+} from './build-cache.js';
 export {
   type DdcArtifact,
   type DdcEntry,
   DdcEntryStore,
   type DdcReceipt,
+  DdcStoreError,
   ddcOutputDigest,
   type PublishDdcEntryResult,
   type StagedDdcEntry,
@@ -15,7 +21,6 @@ export {
   type DdcErrorCode,
   type DdcErrorRootKind,
   type DdcRecoveryAction as DdcErrorRecoveryAction,
-  DdcStoreError,
   type DdcStoreErrorInit,
 } from './errors.js';
 export { collectDdcGarbage, type DdcGcInput, type DdcGcResult } from './gc.js';
@@ -42,12 +47,30 @@ export {
   DdcLifecycle,
   type DdcLifecycleState,
 } from './lifecycle.js';
+export {
+  type AcceptedPublicationCandidate,
+  type AcceptedPublicationStore,
+  createAcceptedPublication,
+  createAcceptedPublicationStore,
+  type ScriptablePackPublicationBuildInput,
+  type ScriptablePackPublicationError,
+  type ScriptablePackPublicationSnapshot,
+  scriptablePackOutputSetDigest,
+  scriptablePackPublicationGeneration,
+} from './publication.js';
 export {
   assertRuntimeScope,
   createRuntimeScope,
   type DdcRuntimeScope,
   runtimeScopeHash,
 } from './runtime-scope.js';
+export {
+  type DdcGenerationCandidate,
+  type DdcGenerationEntryCandidate,
+  DdcGenerationSession,
+  type DdcSessionMetrics,
+  type DdcSessionOptions,
+} from './session.js';
 export {
   type BrowserDdcRecoveryAction,
   type BrowserDdcStatus,

package/src/lifecycle.ts

@@ -464,6 +464,44 @@ export class DdcLifecycle {
     });
   }
 
+  public async discard(lease: DdcLease): Promise<void> {
+    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) return;
+      const { active: _active, ...withoutActive } = current;
+      await this.write({
+        ...withoutActive,
+        revision: current.revision + 1,
+        generation: lease.generation,
+        stale: current.currentKey === undefined,
+      });
+    });
+  }
+
+  /** Restore the last accepted head after a failed multi-owner generation commit. */
+  public async restore(head: DdcHead): Promise<void> {
+    await withDdcLock(this.root, `head-${head.guid}`, async () => {
+      const path = headFile(this.heads, head.guid);
+      if (head.state === 'missing') {
+        await rm(path, { force: true });
+        return;
+      }
+      await this.write({
+        guid: head.guid,
+        desiredKey: head.desiredKey,
+        revision: head.revision ?? 0,
+        ...(head.currentKey === undefined ? {} : { currentKey: head.currentKey }),
+        ...(head.lastKnownGoodKey === undefined ? {} : { lastKnownGoodKey: head.lastKnownGoodKey }),
+        ...(head.generation === undefined ? {} : { generation: head.generation }),
+        ...(head.activeLease === undefined ? {} : { active: head.activeLease }),
+        ...(head.state === 'stale' ? { stale: true } : {}),
+        ...(head.failure === undefined
+          ? {}
+          : { failure: { desiredKey: head.desiredKey, ...head.failure } }),
+      });
+    });
+  }
+
   public async revoke(lease: DdcLease): Promise<void> {
     await this.fail(lease, {
       code: 'lease-lost',