@forgeax/engine-ddc 0.1.4 → 0.1.7

package/dist/lifecycle.d.ts

@@ -26,6 +26,32 @@ export interface DdcCommitResult {
     readonly result: 'current' | 'stale' | 'lease-lost' | 'invalid';
     readonly key: string;
     readonly revision?: number;
+    /** Internal CAS evidence retained for a later generation rollback. */
+    readonly restoreFence?: DdcRestoreFence;
+}
+export interface DdcRestoreFence {
+    readonly attempt: string;
+    readonly generation: number;
+    readonly revision: number;
+    readonly desiredKey: string;
+    readonly outcome: 'current' | 'invalid' | 'failed';
+    readonly key?: string;
+    readonly currentKey?: string;
+    readonly lastKnownGoodKey?: string;
+    readonly failure?: {
+        readonly code: string;
+        readonly detail: string;
+    };
+}
+export interface DdcRestoreResult {
+    readonly result: 'restored' | 'not-owner';
+    readonly revision: number;
+    readonly generation?: number;
+}
+export type DdcRollbackSnapshot = Omit<DdcHead, 'activeLease'>;
+export interface DdcBeginResult {
+    readonly lease: DdcLease;
+    readonly previousHead: DdcRollbackSnapshot;
 }
 /** Cross-process mkdir lock; a lock owned by a dead PID is reclaimable. */
 export declare function withDdcLock<T>(root: string, name: string, operation: () => Promise<T>): Promise<T>;
@@ -38,19 +64,28 @@ export declare class DdcLifecycle {
         readonly leaseTtlMs?: number;
     });
     inspect(guid: string, desiredKey: string): Promise<DdcHead>;
+    /** Begin a lease and capture the accepted rollback snapshot under one head lock. */
+    beginWithSnapshot(guid: string, desiredKey: string): Promise<DdcBeginResult>;
     begin(guid: string, desiredKey: string): Promise<DdcLease>;
     commit(lease: DdcLease, validatedKey: string): Promise<DdcCommitResult>;
     fail(lease: DdcLease, failure: {
         readonly code: string;
         readonly detail: string;
-    }): Promise<void>;
+    }): Promise<DdcRestoreFence | undefined>;
     heartbeat(lease: DdcLease): Promise<DdcLease>;
     close(lease: DdcLease): Promise<void>;
     discard(lease: DdcLease): Promise<void>;
-    /** Restore the last accepted head after a failed multi-owner generation commit. */
-    restore(head: DdcHead): Promise<void>;
+    /**
+     * Restore accepted content only when this lease still owns the mutable head.
+     * A newer active or terminal mutation makes rollback a deliberate no-op.
+     */
+    restore(head: DdcHead | DdcRollbackSnapshot, lease?: DdcLease, fence?: DdcRestoreFence): Promise<DdcRestoreResult>;
+    restoreIfCurrent(snapshot: DdcRollbackSnapshot, lease: DdcLease, fence?: DdcRestoreFence): Promise<DdcRestoreResult>;
     revoke(lease: DdcLease): Promise<void>;
     recover(guid: string, desiredKey: string): Promise<DdcHead>;
+    private rollbackSnapshot;
+    private matchesRestoreFence;
+    private projectHead;
     private allocateGeneration;
     private read;
     private write;

package/dist/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/publication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,EACP,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAED,MAAM,WAAW,8BAA+B,SAAQ,uBAAuB;IAC7E,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACxE;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,iCAAiC,CAAC;IAC/D,KAAK,CACH,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,4BAA4B,GACtC,MAAM,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;IAChD,MAAM,CACJ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,4BAA4B,EACvC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACtC,OAAO,CAAC,MAAM,CAAC,iCAAiC,EAAE,8BAA8B,CAAC,CAAC,CAAC;IACtF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACvE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,iCAAiC,GAAG,IAAI,CAAC;CAChF;AAkBD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,CAUhG;AAED,+EAA+E;AAC/E,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GAAG,MAAM,CAUT;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mCAAmC,GACzC,wBAAwB,CAmC1B;AAiPD,uEAAuE;AACvE,wBAAgB,8BAA8B,IAAI,wBAAwB,CAyDzE"}
+{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,EACP,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAED,MAAM,WAAW,8BAA+B,SAAQ,uBAAuB;IAC7E,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACxE;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,iCAAiC,CAAC;IAC/D,KAAK,CACH,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,4BAA4B,GACtC,MAAM,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;IAChD,MAAM,CACJ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,4BAA4B,EACvC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACtC,OAAO,CAAC,MAAM,CAAC,iCAAiC,EAAE,8BAA8B,CAAC,CAAC,CAAC;IACtF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACvE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,iCAAiC,GAAG,IAAI,CAAC;CAChF;AAkBD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,CAUhG;AAED,+EAA+E;AAC/E,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC,GAAG,MAAM,CAUT;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mCAAmC,GACzC,wBAAwB,CAmC1B;AAuPD,uEAAuE;AACvE,wBAAgB,8BAA8B,IAAI,wBAAwB,CAqDzE"}

package/dist/session.d.ts

@@ -1,5 +1,5 @@
 import type { DdcEntry, StagedDdcEntry } from './entry-store.js';
-import type { DdcCommitResult, DdcHead, DdcLease } from './lifecycle.js';
+import type { DdcCommitResult, DdcHead, DdcLease, DdcRestoreResult, DdcRollbackSnapshot } from './lifecycle.js';
 export interface DdcSessionOptions {
     readonly generation: number;
     readonly leaseTtlMs?: number;
@@ -7,7 +7,7 @@ export interface DdcSessionOptions {
 export interface DdcGenerationCandidate {
     readonly generation: number;
     readonly lease: DdcLease;
-    readonly previousHead: DdcHead;
+    readonly previousHead: DdcRollbackSnapshot;
 }
 export interface DdcGenerationEntryCandidate extends DdcGenerationCandidate {
     readonly staged: StagedDdcEntry;
@@ -23,6 +23,7 @@ export declare class DdcGenerationSession {
     private readonly lifecycle;
     private readonly entries;
     private readonly candidates;
+    private readonly restoreFences;
     private readonly heartbeatTimers;
     private readonly counters;
     private accepting;
@@ -34,7 +35,7 @@ export declare class DdcGenerationSession {
     commitEntry(candidate: DdcGenerationEntryCandidate, validatedKey: string): Promise<DdcCommitResult>;
     discardCandidate(candidate: DdcGenerationCandidate): Promise<void>;
     discardEntry(candidate: DdcGenerationEntryCandidate): Promise<void>;
-    restoreEntry(candidate: DdcGenerationEntryCandidate): Promise<void>;
+    restoreEntry(candidate: DdcGenerationEntryCandidate): Promise<DdcRestoreResult>;
     metrics(): DdcSessionMetrics;
     close(): Promise<void>;
     private assertOpen;

package/dist/session.d.ts.map

@@ -1 +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"}
+{"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,EACV,eAAe,EACf,OAAO,EACP,QAAQ,EAER,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAGxB,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,mBAAmB,CAAC;CAC5C;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,aAAa,CAA0D;IACxF,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;IAejF,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,2BAA2B,CAAC;IA0BjE,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;IAiBd,WAAW,CACtB,SAAS,EAAE,2BAA2B,EACtC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC;IAwBd,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,gBAAgB,CAAC;IA2BrF,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;CAOtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-ddc",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -85,13 +85,13 @@
     }
   },
   "dependencies": {
-    "@forgeax/engine-types": "0.1.4"
+    "@forgeax/engine-types": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "tsup": "^8.3.5",
     "typescript": "^5.8.3",
-    "vitest": "4.1.5"
+    "vitest": "4.0.18"
   },
   "scripts": {
     "build": "tsup",

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

@@ -3,21 +3,24 @@ 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(): DdcEntry {
+function entry(key = KEY): DdcEntry {
   const value = {
-    key: KEY,
+    key,
     guid: GUID,
-    payload: { kind: 'fixture' },
+    payload: { kind: 'fixture', key },
     refs: [],
     artifacts: {},
     receipt: {
       guid: GUID,
-      key: KEY,
+      key,
       producer: 'fixture',
       inputFingerprint: 'sha256:source',
       outputDigest: '',
@@ -71,4 +74,129 @@ describe('DDC generation session integration', () => {
       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__/multiprocess-lifecycle.integration.test.ts

@@ -9,15 +9,17 @@ 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 secondGuid = '019e3969-1d48-7c3b-ac24-6d68f457065e';
 const key = 'a'.repeat(64);
 
 function runWorker(
   root: string,
   source: string,
   args: readonly string[] = [],
+  workerGuid = guid,
 ): Promise<Record<string, unknown>> {
   return new Promise((resolveWorker, reject) => {
-    const child = spawnDdcWorker(source, [lifecycleModule, root, guid, key, ...args]);
+    const child = spawnDdcWorker(source, [lifecycleModule, root, workerGuid, key, ...args]);
     let output = '';
     let error = '';
     child.stdout.on('data', (chunk: Buffer) => (output += chunk.toString()));
@@ -78,6 +80,24 @@ describe('DDC multiprocess lifecycle', () => {
     expect(second.generation).toBeGreaterThan(first.generation as number);
   });
 
+  it('serializes generation allocation across independent asset heads', 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({ generation: lease.generation }));
+    `;
+
+    const [first, second] = await Promise.all([
+      runWorker(root, script, [], guid),
+      runWorker(root, script, [], secondGuid),
+    ]);
+    expect(first.generation).toEqual(expect.any(Number));
+    expect(second.generation).toEqual(expect.any(Number));
+    expect(first.generation).not.toBe(second.generation);
+  });
+
   it('rejects the stale writer instead of silently overwriting current', async () => {
     const root = await mkdtemp(join(tmpdir(), 'forgeax-ddc-multiprocess-head-'));
     roots.push(root);

package/src/index.ts

@@ -41,11 +41,15 @@ export {
   resolveDdcLayout,
 } from './layout.js';
 export {
+  type DdcBeginResult,
   type DdcCommitResult,
   type DdcHead,
   type DdcLease,
   DdcLifecycle,
   type DdcLifecycleState,
+  type DdcRestoreFence,
+  type DdcRestoreResult,
+  type DdcRollbackSnapshot,
 } from './lifecycle.js';
 export {
   type AcceptedPublicationCandidate,