@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/protocol-migration.js

@@ -1,9 +1,10 @@
 import { E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED } from "./error-codes.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
-import { detectLegacySingletonLayout, migrateLegacyLayout } from "./task-migration.js";
+import { detectLegacySingletonLayout } from "./task-migration.js";
+import { migrateLegacyTaskStorage } from "./task-storage-migration.js";
 import { getPackageRoot } from "./templates.js";
 
-function assertSupportedTarget(to) {
+export function assertSupportedProtocolMigrationTarget(to) {
   if (to === undefined || to === null || to === "") {
     const error = new Error("migrate-protocol requires --to <protocolVersion>");
     error.code = E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED;
@@ -26,9 +27,9 @@ function assertSupportedTarget(to) {
  */
 export async function migrateProtocol(
   target,
-  { to, dryRun = false, packageRoot = getPackageRoot() } = {},
+  { to, dryRun = false, packageRoot = getPackageRoot(), destination, writersQuiesced = false } = {},
 ) {
-  assertSupportedTarget(to);
+  assertSupportedProtocolMigrationTarget(to);
   const legacy = await detectLegacySingletonLayout(target);
 
   if (!legacy.hasLegacy) {
@@ -43,7 +44,7 @@ export async function migrateProtocol(
     };
   }
 
-  const result = await migrateLegacyLayout(target, { dryRun, packageRoot });
+  const result = await migrateLegacyTaskStorage(target, { dryRun, packageRoot, destination, writersQuiesced });
   return {
     ...result,
     fromProtocol: PROTOCOL_VERSION,
@@ -52,7 +53,7 @@ export async function migrateProtocol(
     actions: [{
       kind: "LEGACY_LAYOUT_MIGRATION",
       command: "task-migrate",
-      receipt: ".forgeloop/task-state/<taskKey>/migration-receipt.json",
+      receipt: result.migrationReceipt ?? "<destination>/publication/publication-journal.json",
       artifacts: legacy.legacyFiles.map((item) => item.path),
     }],
   };

package/src/core/protocol.js

@@ -30,6 +30,9 @@ export const FAILURE_CODES = Object.freeze([
   "E_GATE_REQUIRED",
   "E_GATE_UNVERIFIED",
   "E_GATE_STALE",
+  "E_GATE_NOT_REQUIRED",
+  "E_GATE_INVALID",
+  "E_PHASE_FREEZE",
   "E_PHASE_TRANSITION_INVALID",
   "E_PHASE_PREREQUISITE_MISSING",
   "E_PHASE_CHRONOLOGY_INVALID",
@@ -113,6 +116,23 @@ export const FAILURE_CODES = Object.freeze([
   "E_INTERVENTION_HYPOTHESIS_MISSING",
   "E_INTERVENTION_REFERENCE_INVALID",
   "E_STRATEGY_OSCILLATION",
+  "E_DECISION_ENGINE_UNAVAILABLE",
+  "E_DECISION_ENGINE_AUTH_REQUIRED",
+  "E_DECISION_ENGINE_AUTH_INVALID",
+  "E_DECISION_MODEL_UNSUPPORTED",
+  "E_DECISION_REQUEST_INVALID",
+  "E_DECISION_RESULT_INVALID",
+  "E_DECISION_TIMEOUT",
+  "E_DECISION_RATE_LIMITED",
+  "E_DECISION_STATE_UNSAFE",
+  "E_DECISION_STATE_LIMIT",
+  "E_DECISION_LOW_CONFIDENCE",
+  "E_DECISION_STALE",
+  "E_DECISION_POLICY_INVALID",
+  "E_DECISION_CACHE_INVALID",
+  "E_DECISION_QUESTION_SET_UNKNOWN",
+  "E_DECISION_QUESTION_SET_STALE",
+  "E_DECISION_REQUIRED",
   "E_DECISION_CRITERION_INVALID",
   "E_DECISION_NOT_UNRESOLVED",
 ]);

package/src/core/reconcile-closure.js

@@ -1,19 +1,81 @@
+import { withTaskTransaction } from "./transaction.js";
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateEventLedger } from "./events.js";
 import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebind.js";
 import { runCommandExecution } from "./execution.js";
 import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
+import { DIAGNOSTIC_SCHEMA_VERSION, diagnosticSemanticFingerprint } from "./diagnostic-model.js";
 import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 import { classifyRequirement } from "./evidence-readiness.js";
+import { assertDiagnosingToCorrectingTransition } from "./phase.js";
+import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
-const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
+/**
+ * Build the schema-valid rebound diagnostic case for a drifted DIAGNOSING task
+ * that entered the phase before its cycle recorded any diagnosis. The case
+ * binds every observation to the just-passed contract-bound evidence execution
+ * so the diagnosis carries explicit provenance instead of being manufactured
+ * by recovery: the hypothesis is the recovery statement, settled by the
+ * successful evidence, with the next safe action being the canonical advance.
+ */
+function reconcileReboundDiagnosticCase({
+  taskId,
+  verificationCycle,
+  checkId,
+  requirement,
+  command,
+  executionId,
+  repositoryHead,
+}) {
+  const statementLimit = 2000;
+  const observations = [{
+    id: "obs-reconcile-evidence",
+    kind: "CHECK_RESULT",
+    evidenceRef: checkId,
+    provenance: "FORGELOOP_EXECUTED",
+    statement: `Contract-bound evidence ${checkId} passed in the current repository (${repositoryHead}); execution ${executionId}: ${command}`.slice(0, statementLimit),
+  }];
+  const hypotheses = [{
+    id: "h-reconcile-rebind",
+    statement: `Repository moved after the task entered DIAGNOSING but before the cycle recorded any diagnosis; cycle ${verificationCycle} diagnosis is rebound from the passed contract-bound evidence requirement "${requirement}".`.slice(0, statementLimit),
+    contributorRefs: [],
+    evidenceRefs: [checkId],
+    settledBy: { type: "CHECK_STATUS", checkId, expectedStatus: "passed" },
+    status: "OPEN",
+  }];
+  const details = {
+    schemaVersion: DIAGNOSTIC_SCHEMA_VERSION,
+    verificationCycle,
+    diagnosticRevision: 1,
+    failureClass: "VERIFICATION_FAILURE",
+    observations,
+    contributors: [],
+    hypotheses,
+    nextSafeAction: {
+      statement: "Advance DIAGNOSING -> CORRECTING -> VERIFYING and continue the canonical verification pipeline in the reconciled repository.".slice(0, statementLimit),
+    },
+  };
+  details.diagnosticFingerprint = diagnosticSemanticFingerprint({
+    verificationCycle: details.verificationCycle,
+    failureClass: details.failureClass,
+    case_: details,
+  });
+  details.previousDiagnosticFingerprint = null;
+  return details;
+}
 
-const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
+// DIAGNOSING is reconcilable under the same diagnosis-boundary condition as
+// CORRECTING: the active cycle must already carry an append-only diagnosis.
+// Without it, drift entering DIAGNOSING before the cycle's first diagnosis is
+// unrecoverable (reconcile-closure, task-recover, handoff, and every mutation
+// all refuse), which stranded real drifted tasks on this exact edge.
+const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING"]);
 
 function reconcileError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -22,14 +84,171 @@ function reconcileError(code, message, artifacts = []) {
   return error;
 }
 
+function assertRepositoryOnlyFreshness(freshness, stateRel, contractRel) {
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    throw reconcileError(
+      "E_RECONCILE_NOT_STALE",
+      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
+      [stateRel, contractRel],
+    );
+  }
+  if (freshness.reasons.length === 1 && freshness.reasons[0] === "REPOSITORY_CHANGED") return;
+  throw reconcileError(
+    "E_RECONCILE_UNSUPPORTED_DRIFT",
+    `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${freshness.reasons.join(", ")}`,
+    [stateRel, contractRel],
+  );
+}
+
+async function assertFreshReviewingRecoveryIsAuthorized({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  eventsRel,
+  receiptRel,
+}) {
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) return;
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) return;
+  let receipt = null;
+  try {
+    receipt = (await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot)).value;
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  const recoveryAuth = validateCompletionRecoveryAuthorization({ state, receipt, events: ledger.events });
+  if (!recoveryAuth.authorized) {
+    const first = recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [eventsRel, receiptRel],
+    );
+  }
+}
+
+async function validateReconciliationCheckpoint({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  stateRel,
+  contractRel,
+  eventsRel,
+  receiptRel,
+  authorityContext,
+  runtimeContext,
+}) {
+  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    await assertFreshReviewingRecoveryIsAuthorized({
+      target,
+      packageRoot,
+      taskId,
+      state,
+      eventsRel,
+      receiptRel,
+    });
+  }
+  assertRepositoryOnlyFreshness(freshness, stateRel, contractRel);
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw reconcileError(
+      "E_RECONCILE_LEDGER_INVALID",
+      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
+      [eventsRel],
+    );
+  }
+
+  await assertReconciliationClaimOwnership(target, { taskId, packageRoot, state, stateRel, eventsRel });
+
+  const reboundOrState = await rebindReconciliationState(target, {
+    packageRoot,
+    taskId,
+    state,
+    ledger,
+    authorityContext,
+    runtimeContext,
+    stateRel,
+    receiptRel,
+  });
+  return reboundOrState;
+}
+
+/** Fail closed unless the task claim is valid, mutable, and ACTIVE in this checkout. */
+async function assertReconciliationClaimOwnership(target, { taskId, packageRoot, state, stateRel, eventsRel }) {
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed || ownership.claimState !== "ACTIVE") {
+    const first = ownership.ownershipErrors?.[0] ?? ownership.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+      `reconcile-closure requires active, valid task claim ownership: ${first.message ?? ownership.claimState}`,
+      [stateRel, eventsRel],
+    );
+  }
+}
+
+/** Handle the phase-bound diagnosis rebind gates for CORRECTING/DIAGNOSING and the REVIEWING recovery authorization.
+ * Returns the possibly-rebound state (or the original state when no rebind applies). */
+async function rebindReconciliationState(target, {
+  packageRoot,
+  taskId,
+  state,
+  ledger,
+  authorityContext,
+  runtimeContext,
+  stateRel,
+  receiptRel,
+}) {
+  if (state.phase === "CORRECTING" || state.phase === "DIAGNOSING") {
+    // The diagnosis boundary for CORRECTING stays absolute: recovery can never
+    // manufacture a diagnosis or authorize a retry the ordinary correction
+    // transition would refuse. A drifted DIAGNOSING task without a cycle
+    // diagnosis is the one legal exception: the drift struck between entering
+    // DIAGNOSING and recording the cycle's first diagnosis, and no other
+    // command can create either the diagnosis or the fresh checkpoint. Such a
+    // task reconciles only after contract-bound evidence passes, and the
+    // reconcile itself records the cycle diagnosis below (provenance bound to
+    // the passed evidence execution).
+    const cycleDiagnosis = resolveCurrentCycleDiagnostic(ledger.events, state.taskId, state.verificationCycle ?? 1);
+    if (state.phase === "DIAGNOSING" && !cycleDiagnosis) {
+      return { ...state, undiagnosedDiagnosingRebind: true };
+    }
+    assertDiagnosingToCorrectingTransition({
+      state,
+      events: ledger.events,
+      resolveDiagnosis: resolveCurrentCycleDiagnostic,
+    });
+  }
+
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) {
+    return state;
+  }
+
+  const recovery = await authorizeCompletionRecoveryOrRebind({ target, packageRoot, taskId, authorityContext, runtimeContext });
+  if (!recovery.recoveryAuth.authorized) {
+    const first = recovery.recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [stateRel, receiptRel],
+    );
+  }
+  return recovery.rebound ? recovery.state : state;
+}
+
 /**
- * Canonical recovery for an EXECUTING, VERIFYING, or REVIEWING task whose
+ * Canonical recovery for an EXECUTING, VERIFYING, CORRECTING, or REVIEWING task whose
  * objective is already satisfied in the current repository but whose
  * work-state checkpoint is stale because the repository fingerprint moved.
  *
  * The command refreshes the checkpoint repository fingerprint only after:
- *   - the task is EXECUTING, VERIFYING, or (with authorized completion
- *     recovery) REVIEWING,
+ *   - the task is EXECUTING, VERIFYING, CORRECTING, or REVIEWING (with either a
+ *     persisted completion rejection or the narrow repository-only bootstrap
+ *     path),
  *   - classification requires revalidation and the only drift is
  *     REPOSITORY_CHANGED,
  *   - the append-only event ledger is valid,
@@ -41,7 +260,14 @@ function reconcileError(code, message, artifacts = []) {
  * VERIFYING, prepare-completion, record-check, complete); claims are
  * released only by canonical COMPLETE.
  */
-export async function runReconcileClosure({
+export async function runReconcileClosure(options = {}) {
+  if (typeof options.taskId !== "string" || !options.taskId.trim()) return reconcileSelectedClosure(options);
+  return withTaskTransaction({ target: options.target, packageRoot: options.packageRoot,
+    taskId: options.taskId, operation: "reconcile-closure", recordCommitEvent: true },
+  () => reconcileSelectedClosure(options));
+}
+
+async function reconcileSelectedClosure({
   target,
   packageRoot,
   taskId,
@@ -52,18 +278,7 @@ export async function runReconcileClosure({
   authorityContext,
   runtimeContext,
 } = {}) {
-  if (typeof taskId !== "string" || !taskId.trim()) {
-    throw reconcileError("E_TASK_REQUIRED", "reconcile-closure requires --task", []);
-  }
-  if (typeof checkId !== "string" || !checkId.trim()) {
-    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --id", []);
-  }
-  if (typeof requirement !== "string" || !requirement.trim()) {
-    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --requirement", []);
-  }
-  if (!Array.isArray(argv) || argv.length === 0) {
-    throw reconcileError("E_RECONCILE_EVIDENCE_FAILED", "reconcile-closure requires -- followed by the evidence command argv", []);
-  }
+  requireReconcileInputs({ taskId, checkId, requirement, argv });
 
   const stateRel = taskArtifactPath(taskId, "state");
   const contractRel = taskArtifactPath(taskId, "contract");
@@ -77,57 +292,22 @@ export async function runReconcileClosure({
   if (!RECONCILABLE_PHASES.has(state.phase)) {
     throw reconcileError(
       "E_RECONCILE_PHASE_INVALID",
-      `reconcile-closure supports EXECUTING, VERIFYING, or REVIEWING tasks whose objective is already satisfied; found ${state.phase}`,
+      `reconcile-closure supports EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, or REVIEWING tasks whose objective is already satisfied; found ${state.phase}`,
       [stateRel],
     );
   }
-  if (state.phase === "REVIEWING") {
-    const recovery = await authorizeCompletionRecoveryOrRebind({
-      target,
-      packageRoot,
-      taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    if (!recovery.recoveryAuth.authorized) {
-      const first = recovery.recoveryAuth.errors?.[0] ?? {};
-      throw reconcileError(
-        first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
-        `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
-        [stateRel, receiptRel],
-      );
-    }
-    if (recovery.rebound) {
-      state = recovery.state;
-    }
-  }
-
-  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
-  if (freshness.status !== "REVALIDATION_REQUIRED" || !freshness.reasons.includes("REPOSITORY_CHANGED")) {
-    throw reconcileError(
-      "E_RECONCILE_NOT_STALE",
-      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
-      [stateRel, contractRel],
-    );
-  }
-  const unsupported = freshness.reasons.filter((reason) => !RECONCILABLE_DRIFT.has(reason));
-  if (unsupported.length > 0) {
-    throw reconcileError(
-      "E_RECONCILE_UNSUPPORTED_DRIFT",
-      `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${unsupported.join(", ")}`,
-      [stateRel, contractRel],
-    );
-  }
-
-  const ledger = await validateEventLedger(target, packageRoot, { taskId });
-  if (!ledger.valid) {
-    const first = ledger.errors[0];
-    throw reconcileError(
-      "E_RECONCILE_LEDGER_INVALID",
-      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
-      [eventsRel],
-    );
-  }
+  state = await validateReconciliationCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    stateRel,
+    contractRel,
+    eventsRel,
+    receiptRel,
+    authorityContext,
+    runtimeContext,
+  });
 
   const contract = await readContract(target, packageRoot, { taskId });
   const verificationItem = (contract.value.verification ?? []).find((item) => {
@@ -169,6 +349,24 @@ export async function runReconcileClosure({
   const repository = await currentRepositoryFingerprint(target);
   const previous = state.repositoryFingerprint;
 
+  const rebindDiagnosis = Boolean(state.undiagnosedDiagnosingRebind);
+  if (rebindDiagnosis) {
+    delete state.undiagnosedDiagnosingRebind;
+    await appendProtocolEvent(target, {
+      taskId,
+      event: "DIAGNOSTIC_CASE_RECORDED",
+      details: reconcileReboundDiagnosticCase({
+        taskId,
+        verificationCycle: state.verificationCycle ?? 1,
+        checkId,
+        requirement,
+        command: argv.join(" "),
+        executionId: execution.execution.executionId,
+        repositoryHead: repository.head,
+      }),
+    }, packageRoot, { taskId });
+  }
+
   await appendProtocolEvent(target, {
     taskId,
     event: RECONCILE_EVENT,
@@ -219,3 +417,19 @@ export async function runReconcileClosure({
     event: RECONCILE_EVENT,
   };
 }
+
+/** Validate the reconcile arguments exactly as before; shared by the phase-independent input gate. */
+function requireReconcileInputs({ taskId, checkId, requirement, argv } = {}) {
+  if (typeof taskId !== "string" || !taskId.trim()) {
+    throw reconcileError("E_TASK_REQUIRED", "reconcile-closure requires --task", []);
+  }
+  if (typeof checkId !== "string" || !checkId.trim()) {
+    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --id", []);
+  }
+  if (typeof requirement !== "string" || !requirement.trim()) {
+    throw reconcileError("E_RECONCILE_REQUIREMENT_UNKNOWN", "reconcile-closure requires --requirement", []);
+  }
+  if (!Array.isArray(argv) || argv.length === 0) {
+    throw reconcileError("E_RECONCILE_EVIDENCE_FAILED", "reconcile-closure requires -- followed by the evidence command argv", []);
+  }
+}

package/src/core/recovery-history.js

@@ -1,3 +1,5 @@
+import { ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { ledgerRelationSet } from "./ledger-relations.js";
 import {
   LEGACY_RECOVERY_MIGRATION_EVENT,
   isLegacyRecoveryEventShape,
@@ -6,6 +8,7 @@ import {
 const RECOVERY_EVENT_TYPES = new Set([
   "TASK_RECOVERY_RECORDED",
   "OPERATOR_RECOVERY_RECORDED",
+  "TASK_ABANDONED",
   LEGACY_RECOVERY_MIGRATION_EVENT,
 ]);
 
@@ -22,56 +25,65 @@ function recoveryIdOf(event) {
     : null;
 }
 
-export function classifyRecoveryHistory(events = []) {
+function recoveryCandidate(event, events, seenRecoveryIds, activeCycle, errors) {
+  // The known legacy defect signature is never an owning recovery cycle by
+  // itself. It remains non-owning historical evidence; ownership comes
+  // exclusively from its valid LEGACY_RECOVERY_MIGRATION_RECORDED event,
+  // which is validated (binding, uniqueness) by the ledger validator.
+  if (!event.details?.recoveryId && isLegacyRecoveryEventShape(event)) return null;
+  // A migration event only counts as a canonical recovery cycle when it
+  // binds an actual legacy event present earlier in this ledger.
+  if (event.event === LEGACY_RECOVERY_MIGRATION_EVENT
+    && !events.some((candidate) => candidate.seq === event.details?.legacyEventSeq
+      && isLegacyRecoveryEventShape(candidate))) {
+    errors.push(recoveryError(
+      `Legacy migration event at seq ${event?.seq ?? "unknown"} does not bind a legacy recovery event in this ledger`,
+    ));
+    return null;
+  }
+  const recoveryId = recoveryIdOf(event);
+  if (!recoveryId) {
+    errors.push(recoveryError(`Recovery event at seq ${event?.seq ?? "unknown"} has no recoveryId`));
+    return null;
+  }
+  if (seenRecoveryIds.has(recoveryId)) {
+    errors.push(recoveryError(`Recovery event at seq ${event.seq} reuses recovery id ${recoveryId}`));
+    return null;
+  }
+  if (activeCycle) {
+    errors.push(recoveryError(
+      `Recovery ${recoveryId} was recorded while recovery ${activeCycle.recoveryId} is unresolved`,
+    ));
+    return null;
+  }
+
+  return {
+    recoveryId,
+    recoveryEventSeq: event.seq,
+    resumedEventSeq: null,
+    active: true,
+    event,
+    resumedEvent: null,
+  };
+}
+
+function classifyHistory(events, { retainCycles = true, onRecovery = null } = {}) {
   const recoveries = [];
   const completedRecoveries = [];
   const errors = [];
-  const seenRecoveryIds = new Set();
+  const seenRecoveryIds = ledgerRelationSet();
   let activeCycle = null;
+  let completedRecoveryCount = 0;
 
-  for (const event of events) {
+  const relevant = Array.isArray(events) ? events : ledgerEventsOfTypes(events, [...RECOVERY_EVENT_TYPES, "TASK_RECOVERY_RESUMED"]);
+  for (const event of relevant) {
     if (RECOVERY_EVENT_TYPES.has(event?.event)) {
-      // The known legacy defect signature is never an owning recovery cycle by
-      // itself. It remains non-owning historical evidence; ownership comes
-      // exclusively from its valid LEGACY_RECOVERY_MIGRATION_RECORDED event,
-      // which is validated (binding, uniqueness) by the ledger validator.
-      if (!event.details?.recoveryId && isLegacyRecoveryEventShape(event)) continue;
-      // A migration event only counts as a canonical recovery cycle when it
-      // binds an actual legacy event present earlier in this ledger.
-      if (event.event === LEGACY_RECOVERY_MIGRATION_EVENT
-        && !events.some((candidate) => candidate.seq === event.details?.legacyEventSeq
-          && isLegacyRecoveryEventShape(candidate))) {
-        errors.push(recoveryError(
-          `Legacy migration event at seq ${event?.seq ?? "unknown"} does not bind a legacy recovery event in this ledger`,
-        ));
-        continue;
-      }
-      const recoveryId = recoveryIdOf(event);
-      if (!recoveryId) {
-        errors.push(recoveryError(`Recovery event at seq ${event?.seq ?? "unknown"} has no recoveryId`));
-        continue;
-      }
-      if (seenRecoveryIds.has(recoveryId)) {
-        errors.push(recoveryError(`Recovery event at seq ${event.seq} reuses recovery id ${recoveryId}`));
-        continue;
-      }
-      if (activeCycle) {
-        errors.push(recoveryError(
-          `Recovery ${recoveryId} was recorded while recovery ${activeCycle.recoveryId} is unresolved`,
-        ));
-        continue;
-      }
-
-      activeCycle = {
-        recoveryId,
-        recoveryEventSeq: event.seq,
-        resumedEventSeq: null,
-        active: true,
-        event,
-        resumedEvent: null,
-      };
-      seenRecoveryIds.add(recoveryId);
-      recoveries.push(activeCycle);
+      const candidate = recoveryCandidate(event, events, seenRecoveryIds, activeCycle, errors);
+      if (!candidate) continue;
+      activeCycle = candidate;
+      seenRecoveryIds.add(activeCycle.recoveryId);
+      if (retainCycles) recoveries.push(activeCycle);
+      if (onRecovery) onRecovery(activeCycle);
       continue;
     }
 
@@ -94,23 +106,31 @@ export function classifyRecoveryHistory(events = []) {
     activeCycle.resumedEventSeq = event.seq;
     activeCycle.resumedEvent = event;
     activeCycle.active = false;
-    completedRecoveries.push(activeCycle);
+    completedRecoveryCount += 1;
+    if (retainCycles) completedRecoveries.push(activeCycle);
     activeCycle = null;
   }
 
   const valid = errors.length === 0;
   return {
-    recoveries,
+    ...(retainCycles ? { recoveries } : {}),
     activeRecoveryId: valid ? activeCycle?.recoveryId ?? null : null,
     activeRecovery: valid && activeCycle
       ? { recoveryId: activeCycle.recoveryId, event: activeCycle.event }
       : null,
-    completedRecoveries,
+    ...(retainCycles ? { completedRecoveries } : { completedRecoveryCount }),
     valid,
     errors,
   };
 }
 
+/** Public evidence keeps its historical arrays. Internal classification can stream claims. */
+export function classifyRecoveryHistory(events = []) { return classifyHistory(events); }
+
+export function summarizeRecoveryHistory(events, onRecovery) {
+  return classifyHistory(events, { retainCycles: false, onRecovery });
+}
+
 export function resolveRecoveryHistory(events = []) {
   return classifyRecoveryHistory(events);
 }