chainlesschain 0.166.21 → 0.166.24

package/src/lib/evolution/governed-wiki-pruning.js

@@ -1,4 +1,12 @@
 import { createHash } from "node:crypto";
+import { captureWikiPruningJournalStore } from "./governed-wiki-pruning-ledger-adapter.js";
+import {
+  GOVERNED_WIKI_PRUNING_PLAN_SCHEMA,
+  GOVERNED_WIKI_PRUNING_POLICY_SCHEMA,
+  buildWikiPruningJournal,
+  pruningOperationCalls,
+  verifyPruningJournalPlan,
+} from "./governed-wiki-pruning-journal.js";
 
 import {
   WIKI_PATTERN_STATUS,
@@ -6,8 +14,7 @@ import {
   digestWikiState,
 } from "./evidence-backed-wiki-maintainer.js";
 
-export const GOVERNED_WIKI_PRUNING_PLAN_SCHEMA =
-  "chainlesschain.governed-wiki-pruning-plan/v1";
+export { GOVERNED_WIKI_PRUNING_PLAN_SCHEMA } from "./governed-wiki-pruning-journal.js";
 export const GOVERNED_WIKI_PRUNING_CONTROL_SCHEMA =
   "chainlesschain.governed-wiki-pruning-control/v1";
 export const GOVERNED_ONLINE_ADAPTATION_AUTHORIZATION_SCHEMA =
@@ -112,17 +119,7 @@ function verifiedAt(pattern) {
 }
 
 function assertPlan(plan, tenantId) {
-  if (
-    plan?.schema !== GOVERNED_WIKI_PRUNING_PLAN_SCHEMA ||
-    plan.tenantId !== tenantId ||
-    !DIGEST.test(plan?.planDigest ?? "")
-  )
-    throw new TypeError("Wiki pruning plan is invalid");
-  const core = clone(plan);
-  delete core.planDigest;
-  if (hash(GOVERNED_WIKI_PRUNING_PLAN_SCHEMA, core) !== plan.planDigest)
-    throw new Error("Wiki pruning plan digest is invalid");
-  return freeze(clone(plan));
+  return verifyPruningJournalPlan(plan, tenantId);
 }
 
 function operationRequest(plan, operation, payload) {
@@ -153,9 +150,156 @@ function requireDurableAck(result, requestDigest, label) {
   return result.receiptDigest;
 }
 
+export function createWikiPruningPlanner({ descriptor: input, ports } = {}) {
+  const descriptor = normalizeDescriptor(input);
+  const captured = {};
+  for (const name of ["loadWikiState", "resolveDeletionReceipt"]) {
+    if (typeof ports?.[name] !== "function")
+      throw new TypeError(`Wiki pruning planner port ${name} is required`);
+    captured[name] = ports[name].bind(ports);
+  }
+  Object.freeze(captured);
+  return Object.freeze({
+    descriptor,
+    plan: (input) => buildPruningPlan(descriptor, captured, input),
+  });
+}
+
+async function buildPruningPlan(
+  descriptor,
+  ports,
+  { expectedStateDigest, effectiveAt, deletionReceiptDigests = [] },
+) {
+  digest(expectedStateDigest, "expectedStateDigest");
+  time(effectiveAt, "effectiveAt");
+  const receiptDigests = boundedUniqueStrings(
+    deletionReceiptDigests,
+    "deletionReceiptDigests",
+    descriptor.maxActions,
+  );
+  receiptDigests.forEach((value) => digest(value, "deletionReceiptDigest"));
+  const state = verifyStateEnvelope(
+    await ports.loadWikiState({ tenantId: descriptor.tenantId }),
+    descriptor.tenantId,
+    expectedStateDigest,
+  );
+  const cutoff =
+    Date.parse(effectiveAt) - descriptor.staleGraceDays * 86_400_000;
+  const patternActions = [];
+  const retrievalRemovals = [];
+  for (const pattern of Object.values(state.patterns).sort((a, b) =>
+    a.patternId.localeCompare(b.patternId),
+  )) {
+    if (
+      pattern.status === WIKI_PATTERN_STATUS.STALE &&
+      Number.isFinite(Date.parse(verifiedAt(pattern))) &&
+      Date.parse(verifiedAt(pattern)) <= cutoff
+    )
+      patternActions.push({
+        type: "tombstone",
+        patternId: pattern.patternId,
+        reason: "stale-grace-elapsed",
+      });
+    if (
+      pattern.status === WIKI_PATTERN_STATUS.STALE ||
+      TERMINAL_PATTERN_STATUSES.has(pattern.status)
+    )
+      retrievalRemovals.push(pattern.patternId);
+  }
+
+  const deletions = [];
+  const dependencyDispositions = [];
+  for (const receiptDigest of receiptDigests) {
+    const receipt = await ports.resolveDeletionReceipt({
+      tenantId: descriptor.tenantId,
+      receiptDigest,
+    });
+    const evidence = state.evidence?.[receipt?.evidenceRef];
+    if (
+      receipt?.authenticated !== true ||
+      receipt.tenantId !== descriptor.tenantId ||
+      receipt.decision !== "delete" ||
+      receipt.receiptDigest !== receiptDigest ||
+      evidence == null ||
+      receipt.sourceDigest !== evidence.sourceDigest ||
+      receipt.artifactRef !== evidence.artifactRef ||
+      typeof receipt.rawArtifactRef !== "string" ||
+      !receipt.rawArtifactRef.startsWith(
+        `artifact://${descriptor.tenantId}/raw/`,
+      ) ||
+      !DIGEST.test(receipt.rawCipherDigest ?? "") ||
+      typeof receipt.keyRef !== "string" ||
+      !receipt.keyRef.startsWith(`kms://${descriptor.tenantId}/`)
+    )
+      throw new Error("privacy deletion receipt is not exactly bound");
+    const dependentPatternIds = [
+      ...new Set(state.evidenceDependents?.[receipt.evidenceRef] ?? []),
+    ].sort();
+    for (const patternId of dependentPatternIds) {
+      const pattern = state.patterns[patternId];
+      if (!pattern) throw new Error("Wiki evidence dependency is corrupt");
+      dependencyDispositions.push({
+        evidenceRef: receipt.evidenceRef,
+        patternId,
+        action: pattern.skillNames?.length > 0 ? "rollback" : "tombstone",
+        skillNames: [...(pattern.skillNames ?? [])].sort(),
+      });
+      retrievalRemovals.push(patternId);
+    }
+    deletions.push({
+      evidenceRef: receipt.evidenceRef,
+      sourceDigest: evidence.sourceDigest,
+      artifactRef: evidence.artifactRef,
+      rawArtifactRef: receipt.rawArtifactRef,
+      rawCipherDigest: receipt.rawCipherDigest,
+      keyRef: receipt.keyRef,
+      receiptDigest,
+    });
+  }
+  const actionCount =
+    patternActions.length + deletions.length + dependencyDispositions.length;
+  if (actionCount > descriptor.maxActions)
+    throw new Error("Wiki pruning plan exceeds its action budget");
+  const core = {
+    schema: GOVERNED_WIKI_PRUNING_PLAN_SCHEMA,
+    tenantId: descriptor.tenantId,
+    wikiStateDigest: expectedStateDigest,
+    policyDigest: hash(GOVERNED_WIKI_PRUNING_POLICY_SCHEMA, descriptor),
+    effectiveAt,
+    patternActions,
+    retrievalRemovals: [...new Set(retrievalRemovals)].sort(),
+    dependencyDispositions,
+    deletions,
+    auditPolicy: {
+      retainWikiRevisions: true,
+      retainEvolutionLog: true,
+      retainDeletionReceipts: true,
+      removeDeletedEvidenceFromRetrieval: true,
+    },
+  };
+  return freeze({
+    ...core,
+    planDigest: hash(GOVERNED_WIKI_PRUNING_PLAN_SCHEMA, core),
+  });
+}
+
 export class GovernedWikiPruning {
-  constructor({ descriptor, ports } = {}) {
+  #ports;
+  #journal;
+  #planner;
+
+  constructor({ descriptor, ports, journalStore = null } = {}) {
     this.descriptor = normalizeDescriptor(descriptor);
+    this.#journal =
+      journalStore === null
+        ? null
+        : captureWikiPruningJournalStore(journalStore);
+    if (
+      this.#journal &&
+      this.#journal.descriptor.tenantId !== this.descriptor.tenantId
+    )
+      throw new TypeError("Wiki pruning journal belongs to another tenant");
+    const captured = {};
     for (const name of [
       "loadWikiState",
       "resolveDeletionReceipt",
@@ -166,138 +310,68 @@ export class GovernedWikiPruning {
       "publishRetrievalProjection",
       "verifyOfflineClosure",
     ]) {
+      if (name === "commitControl" && this.#journal) continue;
       if (typeof ports?.[name] !== "function")
         throw new TypeError(`Wiki pruning port ${name} is required`);
-      this[`_${name}`] = ports[name].bind(ports);
+      captured[name] = ports[name].bind(ports);
     }
+    this.#ports = Object.freeze(captured);
+    this.#planner = createWikiPruningPlanner({
+      descriptor: this.descriptor,
+      ports: this.#ports,
+    });
+    Object.freeze(this);
   }
 
-  async plan({
-    expectedStateDigest,
-    effectiveAt,
-    deletionReceiptDigests = [],
-  }) {
-    digest(expectedStateDigest, "expectedStateDigest");
-    time(effectiveAt, "effectiveAt");
-    const receiptDigests = boundedUniqueStrings(
-      deletionReceiptDigests,
-      "deletionReceiptDigests",
-      this.descriptor.maxActions,
-    );
-    receiptDigests.forEach((value) => digest(value, "deletionReceiptDigest"));
-    const state = verifyStateEnvelope(
-      await this._loadWikiState({ tenantId: this.descriptor.tenantId }),
-      this.descriptor.tenantId,
-      expectedStateDigest,
-    );
-    const cutoff =
-      Date.parse(effectiveAt) - this.descriptor.staleGraceDays * 86_400_000;
-    const patternActions = [];
-    const retrievalRemovals = [];
-    for (const pattern of Object.values(state.patterns).sort((a, b) =>
-      a.patternId.localeCompare(b.patternId),
-    )) {
-      if (
-        pattern.status === WIKI_PATTERN_STATUS.STALE &&
-        Number.isFinite(Date.parse(verifiedAt(pattern))) &&
-        Date.parse(verifiedAt(pattern)) <= cutoff
-      )
-        patternActions.push({
-          type: "tombstone",
-          patternId: pattern.patternId,
-          reason: "stale-grace-elapsed",
-        });
-      if (
-        pattern.status === WIKI_PATTERN_STATUS.STALE ||
-        TERMINAL_PATTERN_STATUSES.has(pattern.status)
-      )
-        retrievalRemovals.push(pattern.patternId);
-    }
-
-    const deletions = [];
-    const dependencyDispositions = [];
-    for (const receiptDigest of receiptDigests) {
-      const receipt = await this._resolveDeletionReceipt({
-        tenantId: this.descriptor.tenantId,
-        receiptDigest,
-      });
-      const evidence = state.evidence?.[receipt?.evidenceRef];
-      if (
-        receipt?.authenticated !== true ||
-        receipt.tenantId !== this.descriptor.tenantId ||
-        receipt.decision !== "delete" ||
-        receipt.receiptDigest !== receiptDigest ||
-        evidence == null ||
-        receipt.sourceDigest !== evidence.sourceDigest ||
-        receipt.artifactRef !== evidence.artifactRef ||
-        typeof receipt.rawArtifactRef !== "string" ||
-        !receipt.rawArtifactRef.startsWith(
-          `artifact://${this.descriptor.tenantId}/raw/`,
-        ) ||
-        !DIGEST.test(receipt.rawCipherDigest ?? "") ||
-        typeof receipt.keyRef !== "string" ||
-        !receipt.keyRef.startsWith(`kms://${this.descriptor.tenantId}/`)
-      )
-        throw new Error("privacy deletion receipt is not exactly bound");
-      const dependentPatternIds = [
-        ...new Set(state.evidenceDependents?.[receipt.evidenceRef] ?? []),
-      ].sort();
-      for (const patternId of dependentPatternIds) {
-        const pattern = state.patterns[patternId];
-        if (!pattern) throw new Error("Wiki evidence dependency is corrupt");
-        dependencyDispositions.push({
-          evidenceRef: receipt.evidenceRef,
-          patternId,
-          action: pattern.skillNames?.length > 0 ? "rollback" : "tombstone",
-          skillNames: [...(pattern.skillNames ?? [])].sort(),
-        });
-        retrievalRemovals.push(patternId);
-      }
-      deletions.push({
-        evidenceRef: receipt.evidenceRef,
-        sourceDigest: evidence.sourceDigest,
-        artifactRef: evidence.artifactRef,
-        rawArtifactRef: receipt.rawArtifactRef,
-        rawCipherDigest: receipt.rawCipherDigest,
-        keyRef: receipt.keyRef,
-        receiptDigest,
-      });
-    }
-    const actionCount =
-      patternActions.length + deletions.length + dependencyDispositions.length;
-    if (actionCount > this.descriptor.maxActions)
-      throw new Error("Wiki pruning plan exceeds its action budget");
-    const core = {
-      schema: GOVERNED_WIKI_PRUNING_PLAN_SCHEMA,
-      tenantId: this.descriptor.tenantId,
-      wikiStateDigest: expectedStateDigest,
-      effectiveAt,
-      patternActions,
-      retrievalRemovals: [...new Set(retrievalRemovals)].sort(),
-      dependencyDispositions,
-      deletions,
-      auditPolicy: {
-        retainWikiRevisions: true,
-        retainEvolutionLog: true,
-        retainDeletionReceipts: true,
-        removeDeletedEvidenceFromRetrieval: true,
-      },
-    };
-    return freeze({
-      ...core,
-      planDigest: hash(GOVERNED_WIKI_PRUNING_PLAN_SCHEMA, core),
-    });
+  async plan(input) {
+    return this.#buildPlan(input);
   }
 
-  async execute({ plan: input, expectedControlDigest = null }) {
+  async #buildPlan(input) {
+    return this.#planner.plan(input);
+  }
+  async execute({
+    plan: input,
+    expectedControlDigest = null,
+    expectedJournalDigest,
+  }) {
     const plan = assertPlan(input, this.descriptor.tenantId);
+    if (
+      plan.policyDigest !==
+      hash(GOVERNED_WIKI_PRUNING_POLICY_SCHEMA, this.descriptor)
+    )
+      throw new Error(
+        "Wiki pruning plan does not match current trusted policy",
+      );
+    if (this.#journal) {
+      if (expectedControlDigest !== null)
+        throw new TypeError(
+          "durable pruning uses expectedJournalDigest, not legacy control digests",
+        );
+      return this.#executeJournal(plan, expectedJournalDigest);
+    }
+    if (expectedJournalDigest !== undefined)
+      throw new TypeError(
+        "a durable journal is required for expectedJournalDigest",
+      );
     if (expectedControlDigest != null)
       digest(expectedControlDigest, "expectedControlDigest");
-    verifyStateEnvelope(
-      await this._loadWikiState({ tenantId: this.descriptor.tenantId }),
-      this.descriptor.tenantId,
-      plan.wikiStateDigest,
-    );
+    if (!Array.isArray(plan.deletions))
+      throw new TypeError("Wiki pruning plan deletions are invalid");
+    // A self-consistent digest is not authorization. Rebuild all derived
+    // actions using the current trusted Wiki, captured policy, and freshly
+    // authenticated deletion receipts before preparing any side effects.
+    const authorizedPlan = await this.#buildPlan({
+      expectedStateDigest: plan.wikiStateDigest,
+      effectiveAt: plan.effectiveAt,
+      deletionReceiptDigests: plan.deletions.map(
+        (entry) => entry.receiptDigest,
+      ),
+    });
+    if (canonical(plan) !== canonical(authorizedPlan))
+      throw new Error(
+        "Wiki pruning plan does not match current trusted policy",
+      );
     const preparedCore = {
       schema: GOVERNED_WIKI_PRUNING_CONTROL_SCHEMA,
       tenantId: this.descriptor.tenantId,
@@ -310,7 +384,7 @@ export class GovernedWikiPruning {
       ...preparedCore,
       controlDigest: hash(GOVERNED_WIKI_PRUNING_CONTROL_SCHEMA, preparedCore),
     });
-    const preparation = await this._commitControl({
+    const preparation = await this.#ports.commitControl({
       state: prepared,
       expectedControlDigest,
     });
@@ -326,9 +400,9 @@ export class GovernedWikiPruning {
       [
         "dependency-dispositions",
         plan.dependencyDispositions,
-        this._applyDependencyDispositions,
+        this.#ports.applyDependencyDispositions,
       ],
-      ["wiki-revision", plan.patternActions, this._applyWikiRevision],
+      ["wiki-revision", plan.patternActions, this.#ports.applyWikiRevision],
     ]) {
       const call = operationRequest(plan, operation, payload);
       receipts.push(
@@ -343,7 +417,7 @@ export class GovernedWikiPruning {
       const call = operationRequest(plan, "crypto-shred", deletion);
       receipts.push(
         requireDurableAck(
-          await this._cryptoShred(call),
+          await this.#ports.cryptoShred(call),
           call.requestDigest,
           "Wiki privacy deletion",
         ),
@@ -354,7 +428,7 @@ export class GovernedWikiPruning {
     });
     receipts.push(
       requireDurableAck(
-        await this._publishRetrievalProjection(projection),
+        await this.#ports.publishRetrievalProjection(projection),
         projection.requestDigest,
         "Wiki retrieval projection",
       ),
@@ -368,7 +442,7 @@ export class GovernedWikiPruning {
       ...finalCore,
       controlDigest: hash(GOVERNED_WIKI_PRUNING_CONTROL_SCHEMA, finalCore),
     });
-    const completion = await this._commitControl({
+    const completion = await this.#ports.commitControl({
       state: finalized,
       expectedControlDigest: prepared.controlDigest,
     });
@@ -381,6 +455,111 @@ export class GovernedWikiPruning {
     return finalized;
   }
 
+  async resume({ expectedJournalDigest } = {}) {
+    if (!this.#journal)
+      throw new TypeError("a durable journal is required for pruning recovery");
+    const latest = await this.#journal.load({
+      tenantId: this.descriptor.tenantId,
+    });
+    if (!latest.state) return null;
+    const plan = assertPlan(latest.state.plan, this.descriptor.tenantId);
+    if (
+      plan.policyDigest !==
+      hash(GOVERNED_WIKI_PRUNING_POLICY_SCHEMA, this.descriptor)
+    )
+      throw new Error(
+        "Wiki pruning plan does not match current trusted policy",
+      );
+    return this.#executeJournal(plan, expectedJournalDigest, latest);
+  }
+
+  async #executeJournal(plan, expectedJournalDigest, restoredLatest = null) {
+    if (expectedJournalDigest !== undefined && expectedJournalDigest !== null)
+      digest(expectedJournalDigest, "expectedJournalDigest");
+    const scope = { tenantId: this.descriptor.tenantId };
+    // The usual case is the current plan. One fully authenticated load proves
+    // both its identity and that it is latest; no duplicate restore is needed.
+    // An explicitly requested older plan still gets its separate historical
+    // lookup. Providers and commits independently authorize their own effects.
+    const latest = restoredLatest ?? (await this.#journal.load(scope));
+    const known =
+      !latest.state || latest.state.plan.planDigest === plan.planDigest
+        ? latest
+        : await this.#journal.load({ ...scope, planDigest: plan.planDigest });
+    let state = known.state;
+    if (state && canonical(state.plan) !== canonical(plan))
+      throw new Error("restored pruning journal plan was substituted");
+    if (state?.phase === "finalized") return state;
+    if (
+      expectedJournalDigest !== undefined &&
+      expectedJournalDigest !== (latest.state?.journalDigest ?? null)
+    )
+      throw new Error("pruning journal changed before execution");
+    if (state && latest.state?.journalDigest !== state.journalDigest)
+      throw new Error("pruning journal is no longer the current execution");
+    if (!state) {
+      if (latest.state && latest.state.phase !== "finalized")
+        throw new Error("another pruning plan is unfinished");
+      const authorized = await this.#buildPlan({
+        expectedStateDigest: plan.wikiStateDigest,
+        effectiveAt: plan.effectiveAt,
+        deletionReceiptDigests: plan.deletions.map(
+          (entry) => entry.receiptDigest,
+        ),
+      });
+      if (canonical(plan) !== canonical(authorized))
+        throw new Error(
+          "Wiki pruning plan does not match current trusted policy",
+        );
+      state = buildWikiPruningJournal({ plan, previous: latest.state });
+      await this.#journal.commit({
+        state,
+        expectedJournalDigest: latest.state?.journalDigest ?? null,
+      });
+    }
+    // Restore is authenticated by the branded journal's current plan and
+    // operation verifiers, including the historical source Wiki binding. Do
+    // not require the original Wiki to remain current after our own revision.
+    // Effect providers MUST reconcile the same requestDigest after a response
+    // loss or a crash between their durable effect and this checkpoint.
+    const handlers = {
+      "dependency-dispositions": this.#ports.applyDependencyDispositions,
+      "wiki-revision": this.#ports.applyWikiRevision,
+      "crypto-shred": this.#ports.cryptoShred,
+      "retrieval-projection": this.#ports.publishRetrievalProjection,
+    };
+    const calls = pruningOperationCalls(plan);
+    for (
+      let index = state.operationReceipts.length;
+      index < calls.length;
+      index++
+    ) {
+      const call = calls[index];
+      const receipt = await handlers[call.request.operation](call);
+      requireDurableAck(
+        receipt,
+        call.requestDigest,
+        `Wiki pruning ${call.request.operation}`,
+      );
+      const next = buildWikiPruningJournal({ plan, previous: state, receipt });
+      await this.#journal.commit({
+        state: next,
+        expectedJournalDigest: state.journalDigest,
+      });
+      state = next;
+    }
+    const finalized = buildWikiPruningJournal({
+      plan,
+      previous: state,
+      finalize: true,
+    });
+    await this.#journal.commit({
+      state: finalized,
+      expectedJournalDigest: state.journalDigest,
+    });
+    return finalized;
+  }
+
   async authorizeOnlineAdaptation(input = {}) {
     const requested = boundedUniqueStrings(
       input.requestedCapabilities ?? [],
@@ -400,7 +579,7 @@ export class GovernedWikiPruning {
       requested.some((capability) => !baseline.includes(capability))
     )
       throw new Error("online adaptation cannot expand authority");
-    const closure = await this._verifyOfflineClosure({
+    const closure = await this.#ports.verifyOfflineClosure({
       tenantId: this.descriptor.tenantId,
       receiptDigest: digest(
         input.offlineClosureReceiptDigest,