@forgeax/engine-ddc 0.1.6 → 0.1.7

package/src/lifecycle.ts

@@ -32,6 +32,33 @@ 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;
 }
 
 interface HeadRecord {
@@ -44,6 +71,7 @@ interface HeadRecord {
   readonly active?: DdcLease;
   readonly supersededAttempts?: readonly string[];
   readonly stale?: boolean;
+  readonly empty?: boolean;
   readonly failure?: {
     readonly desiredKey: string;
     readonly code: string;
@@ -71,9 +99,13 @@ function lockFile(root: string, name: string): string {
 function withRevision(
   result: Omit<DdcCommitResult, 'revision'>,
   revision: number,
+  restoreFence?: DdcRestoreFence,
 ): DdcCommitResult {
   const value = { ...result } as DdcCommitResult;
   Object.defineProperty(value, 'revision', { value: revision, enumerable: false });
+  if (restoreFence !== undefined) {
+    Object.defineProperty(value, 'restoreFence', { value: restoreFence, enumerable: false });
+  }
   return value;
 }
 
@@ -132,6 +164,7 @@ function isHeadRecord(value: unknown): value is HeadRecord {
     return false;
   }
   if (value.stale !== undefined && typeof value.stale !== 'boolean') return false;
+  if (value.empty !== undefined && typeof value.empty !== 'boolean') return false;
   if (value.failure !== undefined) {
     if (!isRecord(value.failure)) return false;
     if (
@@ -260,55 +293,15 @@ export class DdcLifecycle {
 
   public async inspect(guid: string, desiredKey: string): Promise<DdcHead> {
     const record = await this.read(guid);
-    if (record === null) {
-      return {
-        guid,
-        desiredKey,
-        state: 'missing',
-        currentKey: undefined,
-        lastKnownGoodKey: undefined,
-        revision: 0,
-      };
-    }
-    const recordedFailure =
-      record.failure?.desiredKey === desiredKey
-        ? { code: record.failure.code, detail: record.failure.detail }
-        : undefined;
-    const currentEntry =
-      record.currentKey === undefined ? null : await this.entries.readChecked(record.currentKey);
-    const entryFailure =
-      currentEntry !== null && !currentEntry.ok
-        ? { code: currentEntry.error.code, detail: currentEntry.error.detail }
-        : undefined;
-    const failure = recordedFailure ?? entryFailure;
-    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
-    const state: DdcLifecycleState =
-      failure !== undefined
-        ? 'failed'
-        : record.currentKey === desiredKey && currentValue?.guid === guid
-          ? 'current'
-          : record.stale === true
-            ? 'stale'
-            : record.active?.desiredKey === desiredKey
-              ? 'cooking'
-              : 'stale';
-    return {
-      guid,
-      desiredKey,
-      state,
-      currentKey: record.currentKey,
-      lastKnownGoodKey: record.lastKnownGoodKey,
-      revision: record.revision,
-      ...(record.generation === undefined ? {} : { generation: record.generation }),
-      ...(record.active === undefined ? {} : { activeLease: record.active }),
-      ...(failure === undefined ? {} : { failure }),
-    };
+    return this.projectHead(guid, desiredKey, record);
   }
 
-  public async begin(guid: string, desiredKey: string): Promise<DdcLease> {
+  /** Begin a lease and capture the accepted rollback snapshot under one head lock. */
+  public async beginWithSnapshot(guid: string, desiredKey: string): Promise<DdcBeginResult> {
     return withDdcLock(this.root, `head-${guid}`, async () => {
       const previous = await this.read(guid);
-      const generation = await this.allocateGeneration();
+      const previousHead = await this.projectHead(guid, desiredKey, previous, false);
+      const generation = await this.allocateGeneration(previous?.generation ?? 0);
       const lease: DdcLease = {
         guid,
         desiredKey,
@@ -336,10 +329,14 @@ export class DdcLifecycle {
         ...(supersededAttempts.length === 0 ? {} : { supersededAttempts }),
         ...(lastKnownGoodKey === undefined ? {} : { lastKnownGoodKey }),
       });
-      return lease;
+      return { lease, previousHead };
     });
   }
 
+  public async begin(guid: string, desiredKey: string): Promise<DdcLease> {
+    return (await this.beginWithSnapshot(guid, desiredKey)).lease;
+  }
+
   public async commit(lease: DdcLease, validatedKey: string): Promise<DdcCommitResult> {
     return withDdcLock(this.root, `head-${lease.guid}`, async () => {
       const current = await this.read(lease.guid);
@@ -373,21 +370,36 @@ export class DdcLifecycle {
       }
       const entry = await this.entries.read(validatedKey);
       if (entry === null || entry.guid !== lease.guid || entry.receipt.key !== validatedKey) {
+        const nextRevision = current.revision + 1;
+        const failure = {
+          desiredKey: lease.desiredKey,
+          code: 'entry-invalid',
+          detail: 'validated DDC key has no readable entry for this asset',
+        };
         await this.write({
           guid: lease.guid,
           desiredKey: lease.desiredKey,
-          revision: current.revision + 1,
+          revision: nextRevision,
           generation: lease.generation,
           ...(current.lastKnownGoodKey === undefined
             ? {}
             : { lastKnownGoodKey: current.lastKnownGoodKey }),
-          failure: {
-            desiredKey: lease.desiredKey,
-            code: 'entry-invalid',
-            detail: 'validated DDC key has no readable entry for this asset',
-          },
+          ...(current.supersededAttempts === undefined
+            ? {}
+            : { supersededAttempts: current.supersededAttempts }),
+          failure,
+        });
+        return withRevision({ result: 'invalid', key: validatedKey }, nextRevision, {
+          attempt: lease.attempt,
+          generation: lease.generation,
+          revision: nextRevision,
+          desiredKey: lease.desiredKey,
+          outcome: 'invalid',
+          ...(current.lastKnownGoodKey === undefined
+            ? {}
+            : { lastKnownGoodKey: current.lastKnownGoodKey }),
+          failure: { code: failure.code, detail: failure.detail },
         });
-        return withRevision({ result: 'invalid', key: validatedKey }, current.revision + 1);
       }
       const lastKnownGoodKey =
         current.currentKey !== undefined && current.currentKey !== validatedKey
@@ -406,28 +418,53 @@ export class DdcLifecycle {
           : { supersededAttempts: current.supersededAttempts }),
         ...(lastKnownGoodKey === undefined ? {} : { lastKnownGoodKey }),
       });
-      return withRevision({ result: 'current', key: validatedKey }, nextRevision);
+      return withRevision({ result: 'current', key: validatedKey }, nextRevision, {
+        attempt: lease.attempt,
+        generation: lease.generation,
+        revision: nextRevision,
+        desiredKey: lease.desiredKey,
+        outcome: 'current',
+        key: validatedKey,
+        currentKey: validatedKey,
+        ...(lastKnownGoodKey === undefined ? {} : { lastKnownGoodKey }),
+      });
     });
   }
 
   public async fail(
     lease: DdcLease,
     failure: { readonly code: string; readonly detail: string },
-  ): Promise<void> {
-    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+  ): Promise<DdcRestoreFence | undefined> {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
       const current = await this.read(lease.guid);
       if (current?.active?.attempt !== lease.attempt) return;
+      const nextRevision = current.revision + 1;
       await this.write({
         guid: lease.guid,
         desiredKey: lease.desiredKey,
-        revision: current.revision + 1,
+        revision: nextRevision,
         generation: lease.generation,
         ...(current.currentKey === undefined ? {} : { currentKey: current.currentKey }),
         ...(current.lastKnownGoodKey === undefined
           ? {}
           : { lastKnownGoodKey: current.lastKnownGoodKey }),
+        ...(current.supersededAttempts === undefined
+          ? {}
+          : { supersededAttempts: current.supersededAttempts }),
         failure: { desiredKey: lease.desiredKey, ...failure },
       });
+      return {
+        attempt: lease.attempt,
+        generation: lease.generation,
+        revision: nextRevision,
+        desiredKey: lease.desiredKey,
+        outcome: 'failed' as const,
+        ...(current.currentKey === undefined ? {} : { currentKey: current.currentKey }),
+        ...(current.lastKnownGoodKey === undefined
+          ? {}
+          : { lastKnownGoodKey: current.lastKnownGoodKey }),
+        failure,
+      };
     });
   }
 
@@ -478,27 +515,81 @@ export class DdcLifecycle {
     });
   }
 
-  /** 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,
+  /**
+   * Restore accepted content only when this lease still owns the mutable head.
+   * A newer active or terminal mutation makes rollback a deliberate no-op.
+   */
+  public async restore(
+    head: DdcHead | DdcRollbackSnapshot,
+    lease?: DdcLease,
+    fence?: DdcRestoreFence,
+  ): Promise<DdcRestoreResult> {
+    const inferredLease =
+      lease ??
+      ('activeLease' in head && head.activeLease !== undefined ? head.activeLease : undefined);
+    if (inferredLease === undefined) {
+      return {
+        result: 'not-owner',
         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
+      };
+    }
+    const snapshot = this.rollbackSnapshot(head);
+    return this.restoreIfCurrent(snapshot, inferredLease, fence);
+  }
+
+  public async restoreIfCurrent(
+    snapshot: DdcRollbackSnapshot,
+    lease: DdcLease,
+    fence?: DdcRestoreFence,
+  ): Promise<DdcRestoreResult> {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current === null || current.guid !== snapshot.guid) {
+        return {
+          result: 'not-owner',
+          revision: current?.revision ?? 0,
+          ...(current?.generation === undefined ? {} : { generation: current.generation }),
+        };
+      }
+      const ownsActive =
+        current.active?.attempt === lease.attempt &&
+        current.active.generation === lease.generation &&
+        current.active.desiredKey === lease.desiredKey;
+      const ownsTerminal = fence !== undefined && this.matchesRestoreFence(current, lease, fence);
+      if (!ownsActive && !ownsTerminal) {
+        return {
+          result: 'not-owner',
+          revision: current.revision,
+          ...(current.generation === undefined ? {} : { generation: current.generation }),
+        };
+      }
+
+      const nextRevision = current.revision + 1;
+      const generation = Math.max(
+        current.generation ?? 0,
+        lease.generation,
+        snapshot.generation ?? 0,
+      );
+      const supersededAttempts = current.supersededAttempts;
+      const restored: HeadRecord = {
+        guid: snapshot.guid,
+        desiredKey: snapshot.desiredKey,
+        revision: nextRevision,
+        generation,
+        ...(snapshot.currentKey === undefined ? {} : { currentKey: snapshot.currentKey }),
+        ...(snapshot.lastKnownGoodKey === undefined
           ? {}
-          : { failure: { desiredKey: head.desiredKey, ...head.failure } }),
-      });
+          : { lastKnownGoodKey: snapshot.lastKnownGoodKey }),
+        ...(supersededAttempts === undefined ? {} : { supersededAttempts }),
+        ...(snapshot.state === 'missing' ? { empty: true } : {}),
+        ...(snapshot.state === 'stale' ? { stale: true } : {}),
+        ...(snapshot.failure === undefined
+          ? {}
+          : { failure: { desiredKey: snapshot.desiredKey, ...snapshot.failure } }),
+      };
+      await this.write(restored);
+      return { result: 'restored', revision: nextRevision, generation };
     });
   }
 
@@ -517,6 +608,10 @@ export class DdcLifecycle {
           guid,
           desiredKey,
           revision: current.revision + 1,
+          ...(current.generation === undefined ? {} : { generation: current.generation }),
+          ...(current.supersededAttempts === undefined
+            ? {}
+            : { supersededAttempts: current.supersededAttempts }),
           ...(current.lastKnownGoodKey === undefined
             ? {}
             : { lastKnownGoodKey: current.lastKnownGoodKey }),
@@ -531,24 +626,134 @@ export class DdcLifecycle {
     });
   }
 
-  private async allocateGeneration(): Promise<number> {
-    const path = join(this.root, 'generations', 'counter.json');
-    await mkdir(join(this.root, 'generations'), { recursive: true });
-    let next = 1;
-    try {
-      const record = JSON.parse(await readFile(path, 'utf8')) as GenerationRecord;
-      if (record.schemaVersion === 'forgeax-ddc-generation/v2' && Number.isInteger(record.next))
-        next = Math.max(1, record.next);
-    } catch {
-      // A missing counter is the first allocation, not an implicit legacy fallback.
+  private rollbackSnapshot(head: DdcHead | DdcRollbackSnapshot): DdcRollbackSnapshot {
+    const { activeLease: _activeLease, ...snapshot } = head as DdcHead;
+    if (snapshot.state !== 'cooking') return snapshot;
+    return {
+      ...snapshot,
+      state: snapshot.currentKey === undefined ? 'missing' : 'stale',
+    };
+  }
+
+  private matchesRestoreFence(
+    current: HeadRecord,
+    lease: DdcLease,
+    fence: DdcRestoreFence,
+  ): boolean {
+    if (
+      fence.attempt !== lease.attempt ||
+      fence.generation !== lease.generation ||
+      current.active !== undefined ||
+      current.revision !== fence.revision ||
+      current.generation !== fence.generation ||
+      current.desiredKey !== fence.desiredKey ||
+      current.currentKey !== fence.currentKey ||
+      current.lastKnownGoodKey !== fence.lastKnownGoodKey
+    ) {
+      return false;
     }
-    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    await writeFile(
-      temporary,
-      JSON.stringify({ schemaVersion: 'forgeax-ddc-generation/v2', next: next + 1 }),
-    );
-    await rename(temporary, path);
-    return next;
+    if (fence.outcome === 'current') {
+      return (
+        fence.key !== undefined &&
+        current.currentKey === fence.key &&
+        current.failure === undefined &&
+        current.stale !== true
+      );
+    }
+    if (
+      fence.failure === undefined ||
+      current.failure === undefined ||
+      current.failure.desiredKey !== fence.desiredKey ||
+      current.failure.code !== fence.failure.code ||
+      current.failure.detail !== fence.failure.detail
+    ) {
+      return false;
+    }
+    return fence.outcome === 'invalid' ? fence.currentKey === undefined : true;
+  }
+
+  private async projectHead(
+    guid: string,
+    desiredKey: string,
+    record: HeadRecord | null,
+    includeActive = true,
+  ): Promise<DdcHead> {
+    if (record === null) {
+      return {
+        guid,
+        desiredKey,
+        state: 'missing',
+        currentKey: undefined,
+        lastKnownGoodKey: undefined,
+        revision: 0,
+      };
+    }
+    const recordedFailure =
+      record.failure?.desiredKey === desiredKey
+        ? { code: record.failure.code, detail: record.failure.detail }
+        : undefined;
+    const currentEntry =
+      record.currentKey === undefined ? null : await this.entries.readChecked(record.currentKey);
+    const entryFailure =
+      currentEntry !== null && !currentEntry.ok
+        ? { code: currentEntry.error.code, detail: currentEntry.error.detail }
+        : undefined;
+    const failure = recordedFailure ?? entryFailure;
+    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
+    const state: DdcLifecycleState =
+      failure !== undefined
+        ? 'failed'
+        : record.currentKey === desiredKey && currentValue?.guid === guid
+          ? 'current'
+          : record.stale === true
+            ? 'stale'
+            : includeActive && record.active?.desiredKey === desiredKey
+              ? 'cooking'
+              : record.empty === true
+                ? 'missing'
+                : 'stale';
+    return {
+      guid,
+      desiredKey,
+      state,
+      currentKey: record.currentKey,
+      lastKnownGoodKey: record.lastKnownGoodKey,
+      revision: record.revision,
+      ...(record.generation === undefined ? {} : { generation: record.generation }),
+      ...(includeActive && record.active === undefined
+        ? {}
+        : includeActive && record.active !== undefined
+          ? { activeLease: record.active }
+          : {}),
+      ...(failure === undefined ? {} : { failure }),
+    };
+  }
+
+  private async allocateGeneration(minimumExclusive = 0): Promise<number> {
+    return withDdcLock(this.root, 'generation-counter', async () => {
+      const path = join(this.root, 'generations', 'counter.json');
+      await mkdir(join(this.root, 'generations'), { recursive: true });
+      let next = 1;
+      try {
+        const record = JSON.parse(await readFile(path, 'utf8')) as GenerationRecord;
+        if (
+          record.schemaVersion === 'forgeax-ddc-generation/v2' &&
+          Number.isSafeInteger(record.next) &&
+          record.next >= 1
+        )
+          next = Math.max(1, record.next);
+      } catch {
+        // A missing counter is the first allocation, not an implicit legacy fallback.
+      }
+      const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+      next = Math.max(next, minimumExclusive + 1);
+      await writeFile(
+        temporary,
+        JSON.stringify({ schemaVersion: 'forgeax-ddc-generation/v2', next: next + 1 }),
+      );
+      await rename(temporary, path);
+      return next;
+    });
   }
 
   private async read(guid: string): Promise<HeadRecord | null> {

package/src/publication.ts

@@ -315,7 +315,13 @@ function validateEnvelope(
 
 interface PublicationState {
   snapshot: ScriptablePackPublicationSnapshot;
-  readonly staged: Map<string, AssetPublicationEnvelope>;
+  /**
+   * Staged candidates are owned by their envelope object, not by the
+   * publication tuple. Two overlapping generations can legitimately produce
+   * the same deterministic tuple; a stale owner's discard must not remove the
+   * current owner's candidate before commit.
+   */
+  readonly staged: Set<AssetPublicationEnvelope>;
 }
 
 function validateCandidate(
@@ -389,13 +395,10 @@ export function createAcceptedPublicationStore(): AcceptedPublicationStore {
   function stateFor(sourcePath: string): PublicationState {
     const existing = states.get(sourcePath);
     if (existing !== undefined) return existing;
-    const created: PublicationState = { snapshot: {}, staged: new Map() };
+    const created: PublicationState = { snapshot: {}, staged: new Set() };
     states.set(sourcePath, created);
     return created;
   }
-  function candidateKey(candidate: AssetPublicationEnvelope): string {
-    return `${candidate.generation}\0${candidate.digest}\0${candidate.outputSetDigest}`;
-  }
   return {
     observe(sourcePath) {
       return stateFor(sourcePath).snapshot;
@@ -407,13 +410,12 @@ export function createAcceptedPublicationStore(): AcceptedPublicationStore {
         'publication request was cancelled before DDC commit',
       );
       if (invalid !== undefined) return err(invalid);
-      stateFor(sourcePath).staged.set(candidateKey(candidate.envelope), candidate.envelope);
+      stateFor(sourcePath).staged.add(candidate.envelope);
       return ok(undefined);
     },
     async commit(sourcePath, candidate, commitRoute) {
-      const key = candidateKey(candidate.envelope);
       const state = stateFor(sourcePath);
-      if (!state.staged.has(key)) {
+      if (!state.staged.has(candidate.envelope)) {
         const current = state.snapshot.current;
         const lastKnownGood = state.snapshot.lastKnownGood ?? current;
         return err(
@@ -429,11 +431,11 @@ export function createAcceptedPublicationStore(): AcceptedPublicationStore {
         );
       }
       const result = await publishCandidate(state, candidate, commitRoute);
-      state.staged.delete(key);
+      state.staged.delete(candidate.envelope);
       return result;
     },
     discard(sourcePath, candidate) {
-      stateFor(sourcePath).staged.delete(candidateKey(candidate));
+      stateFor(sourcePath).staged.delete(candidate);
     },
     restore(sourcePath, snapshot) {
       const state = stateFor(sourcePath);