@forgeax/engine-ddc 0.1.6 → 0.1.19

package/dist/index.mjs

@@ -404,9 +404,12 @@ function headFile(heads, guid) {
 function lockFile(root, name) {
   return join(root, "locks", `${encodeURIComponent(name)}.lock`);
 }
-function withRevision(result, revision) {
+function withRevision(result, revision, restoreFence) {
   const value = { ...result };
   Object.defineProperty(value, "revision", { value: revision, enumerable: false });
+  if (restoreFence !== void 0) {
+    Object.defineProperty(value, "restoreFence", { value: restoreFence, enumerable: false });
+  }
   return value;
 }
 async function delay(ms) {
@@ -440,6 +443,7 @@ function isHeadRecord(value) {
     return false;
   }
   if (value.stale !== void 0 && typeof value.stale !== "boolean") return false;
+  if (value.empty !== void 0 && typeof value.empty !== "boolean") return false;
   if (value.failure !== void 0) {
     if (!isRecord(value.failure)) return false;
     if (!isString(value.failure.desiredKey) || !isString(value.failure.code) || !isString(value.failure.detail)) {
@@ -541,38 +545,14 @@ var DdcLifecycle = class {
   }
   async inspect(guid, desiredKey) {
     const record = await this.read(guid);
-    if (record === null) {
-      return {
-        guid,
-        desiredKey,
-        state: "missing",
-        currentKey: void 0,
-        lastKnownGoodKey: void 0,
-        revision: 0
-      };
-    }
-    const recordedFailure = record.failure?.desiredKey === desiredKey ? { code: record.failure.code, detail: record.failure.detail } : void 0;
-    const currentEntry = record.currentKey === void 0 ? null : await this.entries.readChecked(record.currentKey);
-    const entryFailure = currentEntry !== null && !currentEntry.ok ? { code: currentEntry.error.code, detail: currentEntry.error.detail } : void 0;
-    const failure2 = recordedFailure ?? entryFailure;
-    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
-    const state = failure2 !== void 0 ? "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 === void 0 ? {} : { generation: record.generation },
-      ...record.active === void 0 ? {} : { activeLease: record.active },
-      ...failure2 === void 0 ? {} : { failure: failure2 }
-    };
+    return this.projectHead(guid, desiredKey, record);
   }
-  async begin(guid, desiredKey) {
+  /** Begin a lease and capture the accepted rollback snapshot under one head lock. */
+  async beginWithSnapshot(guid, desiredKey) {
     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 = {
         guid,
         desiredKey,
@@ -597,9 +577,12 @@ var DdcLifecycle = class {
         ...supersededAttempts.length === 0 ? {} : { supersededAttempts },
         ...lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey }
       });
-      return lease;
+      return { lease, previousHead };
     });
   }
+  async begin(guid, desiredKey) {
+    return (await this.beginWithSnapshot(guid, desiredKey)).lease;
+  }
   async commit(lease, validatedKey) {
     return withDdcLock(this.root, `head-${lease.guid}`, async () => {
       const current = await this.read(lease.guid);
@@ -629,19 +612,30 @@ var DdcLifecycle = class {
       }
       const entry = await this.entries.read(validatedKey);
       if (entry === null || entry.guid !== lease.guid || entry.receipt.key !== validatedKey) {
+        const nextRevision2 = current.revision + 1;
+        const failure2 = {
+          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: nextRevision2,
           generation: lease.generation,
           ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
-          failure: {
-            desiredKey: lease.desiredKey,
-            code: "entry-invalid",
-            detail: "validated DDC key has no readable entry for this asset"
-          }
+          ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
+          failure: failure2
+        });
+        return withRevision({ result: "invalid", key: validatedKey }, nextRevision2, {
+          attempt: lease.attempt,
+          generation: lease.generation,
+          revision: nextRevision2,
+          desiredKey: lease.desiredKey,
+          outcome: "invalid",
+          ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+          failure: { code: failure2.code, detail: failure2.detail }
         });
-        return withRevision({ result: "invalid", key: validatedKey }, current.revision + 1);
       }
       const lastKnownGoodKey = current.currentKey !== void 0 && current.currentKey !== validatedKey ? current.currentKey : current.lastKnownGoodKey;
       const nextRevision = current.revision + 1;
@@ -655,22 +649,43 @@ var DdcLifecycle = class {
         ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
         ...lastKnownGoodKey === void 0 ? {} : { 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 === void 0 ? {} : { lastKnownGoodKey }
+      });
     });
   }
   async fail(lease, failure2) {
-    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+    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 === void 0 ? {} : { currentKey: current.currentKey },
         ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+        ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
         failure: { desiredKey: lease.desiredKey, ...failure2 }
       });
+      return {
+        attempt: lease.attempt,
+        generation: lease.generation,
+        revision: nextRevision,
+        desiredKey: lease.desiredKey,
+        outcome: "failed",
+        ...current.currentKey === void 0 ? {} : { currentKey: current.currentKey },
+        ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+        failure: failure2
+      };
     });
   }
   async heartbeat(lease) {
@@ -717,25 +732,62 @@ var DdcLifecycle = class {
       });
     });
   }
-  /** Restore the last accepted head after a failed multi-owner generation commit. */
-  async restore(head) {
-    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.
+   */
+  async restore(head, lease, fence) {
+    const inferredLease = lease ?? ("activeLease" in head && head.activeLease !== void 0 ? head.activeLease : void 0);
+    if (inferredLease === void 0) {
+      return {
+        result: "not-owner",
         revision: head.revision ?? 0,
-        ...head.currentKey === void 0 ? {} : { currentKey: head.currentKey },
-        ...head.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: head.lastKnownGoodKey },
-        ...head.generation === void 0 ? {} : { generation: head.generation },
-        ...head.activeLease === void 0 ? {} : { active: head.activeLease },
-        ...head.state === "stale" ? { stale: true } : {},
-        ...head.failure === void 0 ? {} : { failure: { desiredKey: head.desiredKey, ...head.failure } }
-      });
+        ...head.generation === void 0 ? {} : { generation: head.generation }
+      };
+    }
+    const snapshot = this.rollbackSnapshot(head);
+    return this.restoreIfCurrent(snapshot, inferredLease, fence);
+  }
+  async restoreIfCurrent(snapshot, lease, fence) {
+    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 === void 0 ? {} : { generation: current.generation }
+        };
+      }
+      const ownsActive = current.active?.attempt === lease.attempt && current.active.generation === lease.generation && current.active.desiredKey === lease.desiredKey;
+      const ownsTerminal = fence !== void 0 && this.matchesRestoreFence(current, lease, fence);
+      if (!ownsActive && !ownsTerminal) {
+        return {
+          result: "not-owner",
+          revision: current.revision,
+          ...current.generation === void 0 ? {} : { 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 = {
+        guid: snapshot.guid,
+        desiredKey: snapshot.desiredKey,
+        revision: nextRevision,
+        generation,
+        ...snapshot.currentKey === void 0 ? {} : { currentKey: snapshot.currentKey },
+        ...snapshot.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: snapshot.lastKnownGoodKey },
+        ...supersededAttempts === void 0 ? {} : { supersededAttempts },
+        ...snapshot.state === "missing" ? { empty: true } : {},
+        ...snapshot.state === "stale" ? { stale: true } : {},
+        ...snapshot.failure === void 0 ? {} : { failure: { desiredKey: snapshot.desiredKey, ...snapshot.failure } }
+      };
+      await this.write(restored);
+      return { result: "restored", revision: nextRevision, generation };
     });
   }
   async revoke(lease) {
@@ -752,6 +804,8 @@ var DdcLifecycle = class {
           guid,
           desiredKey,
           revision: current.revision + 1,
+          ...current.generation === void 0 ? {} : { generation: current.generation },
+          ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
           ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
           failure: {
             desiredKey,
@@ -763,23 +817,75 @@ var DdcLifecycle = class {
       return this.inspect(guid, desiredKey);
     });
   }
-  async allocateGeneration() {
-    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"));
-      if (record.schemaVersion === "forgeax-ddc-generation/v2" && Number.isInteger(record.next))
-        next = Math.max(1, record.next);
-    } catch {
+  rollbackSnapshot(head) {
+    const { activeLease: _activeLease, ...snapshot } = head;
+    if (snapshot.state !== "cooking") return snapshot;
+    return {
+      ...snapshot,
+      state: snapshot.currentKey === void 0 ? "missing" : "stale"
+    };
+  }
+  matchesRestoreFence(current, lease, fence) {
+    if (fence.attempt !== lease.attempt || fence.generation !== lease.generation || current.active !== void 0 || 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 !== void 0 && current.currentKey === fence.key && current.failure === void 0 && current.stale !== true;
+    }
+    if (fence.failure === void 0 || current.failure === void 0 || 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 === void 0 : true;
+  }
+  async projectHead(guid, desiredKey, record, includeActive = true) {
+    if (record === null) {
+      return {
+        guid,
+        desiredKey,
+        state: "missing",
+        currentKey: void 0,
+        lastKnownGoodKey: void 0,
+        revision: 0
+      };
+    }
+    const recordedFailure = record.failure?.desiredKey === desiredKey ? { code: record.failure.code, detail: record.failure.detail } : void 0;
+    const currentEntry = record.currentKey === void 0 ? null : await this.entries.readChecked(record.currentKey);
+    const entryFailure = currentEntry !== null && !currentEntry.ok ? { code: currentEntry.error.code, detail: currentEntry.error.detail } : void 0;
+    const failure2 = recordedFailure ?? entryFailure;
+    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
+    const state = failure2 !== void 0 ? "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 === void 0 ? {} : { generation: record.generation },
+      ...includeActive && record.active === void 0 ? {} : includeActive && record.active !== void 0 ? { activeLease: record.active } : {},
+      ...failure2 === void 0 ? {} : { failure: failure2 }
+    };
+  }
+  async allocateGeneration(minimumExclusive = 0) {
+    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"));
+        if (record.schemaVersion === "forgeax-ddc-generation/v2" && Number.isSafeInteger(record.next) && record.next >= 1)
+          next = Math.max(1, record.next);
+      } catch {
+      }
+      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;
+    });
   }
   async read(guid) {
     const path = headFile(this.heads, guid);
@@ -1129,13 +1235,10 @@ function createAcceptedPublicationStore() {
   function stateFor(sourcePath) {
     const existing = states.get(sourcePath);
     if (existing !== void 0) return existing;
-    const created = { snapshot: {}, staged: /* @__PURE__ */ new Map() };
+    const created = { snapshot: {}, staged: /* @__PURE__ */ new Set() };
     states.set(sourcePath, created);
     return created;
   }
-  function candidateKey(candidate) {
-    return `${candidate.generation}\0${candidate.digest}\0${candidate.outputSetDigest}`;
-  }
   return {
     observe(sourcePath) {
       return stateFor(sourcePath).snapshot;
@@ -1147,13 +1250,12 @@ function createAcceptedPublicationStore() {
         "publication request was cancelled before DDC commit"
       );
       if (invalid !== void 0) return err(invalid);
-      stateFor(sourcePath).staged.set(candidateKey(candidate.envelope), candidate.envelope);
+      stateFor(sourcePath).staged.add(candidate.envelope);
       return ok(void 0);
     },
     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(
@@ -1169,11 +1271,11 @@ function createAcceptedPublicationStore() {
         );
       }
       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);
@@ -1248,6 +1350,7 @@ var DdcGenerationSession = class {
   lifecycle;
   entries;
   candidates = /* @__PURE__ */ new Map();
+  restoreFences = /* @__PURE__ */ new WeakMap();
   heartbeatTimers = /* @__PURE__ */ new Map();
   counters = {
     hitCount: 0,
@@ -1268,12 +1371,14 @@ var DdcGenerationSession = class {
     this.entries = new DdcEntryStore(root);
   }
   async beginCandidate(guid, desiredKey) {
-    const head = await this.inspect(guid, desiredKey);
-    const lease = await this.lifecycle.begin(guid, desiredKey);
+    this.assertOpen();
+    const { lease, previousHead } = await this.lifecycle.beginWithSnapshot(guid, desiredKey);
+    if (previousHead.state === "current") this.counters.hitCount += 1;
+    else this.counters.missCount += 1;
     const candidate = {
       generation: this.generation,
       lease,
-      previousHead: head
+      previousHead
     };
     this.candidates.set(lease.attempt, candidate);
     this.scheduleHeartbeat(candidate);
@@ -1293,10 +1398,11 @@ var DdcGenerationSession = class {
       this.candidates.set(candidate.lease.attempt, entryCandidate);
       return entryCandidate;
     } catch (error) {
-      await this.lifecycle.fail(candidate.lease, {
+      const fence = await this.lifecycle.fail(candidate.lease, {
         code: "ddc-entry-stage-failed",
         detail: error instanceof Error ? error.message : String(error)
       });
+      if (fence !== void 0) this.restoreFences.set(candidate, fence);
       this.stopHeartbeat(candidate);
       this.candidates.delete(candidate.lease.attempt);
       this.counters.writeFailureCount += 1;
@@ -1314,6 +1420,8 @@ var DdcGenerationSession = class {
     const registered = this.assertCandidate(candidate);
     try {
       const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      if (result.restoreFence !== void 0)
+        this.restoreFences.set(registered, result.restoreFence);
       if (result.result === "invalid") this.counters.corruptCount += 1;
       this.stopHeartbeat(registered);
       this.candidates.delete(registered.lease.attempt);
@@ -1329,15 +1437,18 @@ var DdcGenerationSession = class {
     try {
       await this.entries.publish(candidate.staged);
       const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      if (result.restoreFence !== void 0)
+        this.restoreFences.set(registered, result.restoreFence);
       this.stopHeartbeat(registered);
       this.candidates.delete(registered.lease.attempt);
       return result;
     } catch (error) {
       this.stopHeartbeat(registered);
-      await this.lifecycle.fail(registered.lease, {
+      const fence = await this.lifecycle.fail(registered.lease, {
         code: "ddc-entry-publish-failed",
         detail: error instanceof Error ? error.message : String(error)
       });
+      if (fence !== void 0) this.restoreFences.set(registered, fence);
       await this.entries.discard(candidate.staged).catch(() => {
       });
       this.candidates.delete(registered.lease.attempt);
@@ -1362,20 +1473,28 @@ var DdcGenerationSession = class {
   }
   async restoreEntry(candidate) {
     const registered = this.candidates.get(candidate.lease.attempt);
+    const ownerLease = registered?.lease ?? candidate.lease;
+    const fence = this.restoreFences.get(candidate);
+    this.stopHeartbeat(ownerLease);
+    let result = {
+      result: "not-owner",
+      revision: candidate.previousHead.revision ?? 0,
+      ...candidate.previousHead.generation === void 0 ? {} : { generation: candidate.previousHead.generation }
+    };
     let restoreError;
     try {
-      await this.lifecycle.restore(candidate.previousHead);
+      result = await this.lifecycle.restoreIfCurrent(candidate.previousHead, ownerLease, fence);
     } catch (error) {
       restoreError = error;
     } finally {
       await this.entries.discard(candidate.staged).catch(() => {
       });
       if (registered !== void 0) {
-        this.stopHeartbeat(registered);
         this.candidates.delete(registered.lease.attempt);
       }
     }
     if (restoreError !== void 0) throw restoreError;
+    return result;
   }
   metrics() {
     return { ...this.counters };
@@ -1425,10 +1544,11 @@ var DdcGenerationSession = class {
     this.heartbeatTimers.set(attempt, timer);
   }
   stopHeartbeat(candidate) {
-    const timer = this.heartbeatTimers.get(candidate.lease.attempt);
+    const attempt = "lease" in candidate ? candidate.lease.attempt : candidate.attempt;
+    const timer = this.heartbeatTimers.get(attempt);
     if (timer === void 0) return;
     clearTimeout(timer);
-    this.heartbeatTimers.delete(candidate.lease.attempt);
+    this.heartbeatTimers.delete(attempt);
   }
 };