@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/core/preflight.js

@@ -1,4 +1,5 @@
 import { ARTIFACT_PATHS, writeJsonArtifact } from "./artifacts.js";
+import { withTaskTransaction } from "./transaction.js";
 import { readContract } from "./contract.js";
 import { assertRouteInvariants } from "./router.js";
 import { validateProfileSources } from "./profile.js";
@@ -35,13 +36,17 @@ const PREVIEW_DECISION_MAX_LENGTH = 240;
 
 export { validatePersistedPreflight } from "./preflight-model.js";
 
-export async function evaluatePreflight({ target, packageRoot, strict = false, taskId = null, contractPath = null, routePath = null, statePath = null } = {}) {
+function preflightArtifactPath(explicitPath, taskId, kind) {
+  return explicitPath ?? (taskId ? taskArtifactPath(taskId, kind) : ARTIFACT_PATHS[kind]);
+}
+
+export async function evaluatePreflight({ target, packageRoot, strict = false, taskId = null, contractPath = null, routePath = null, statePath = null, readers = null } = {}) {
   const errors = [];
   const profile = await readProfile(target);
   const profileProvenance = await validateProfileSources(target, packageRoot);
   errors.push(...(profileProvenance.errors ?? []));
-  const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath });
-  const route = await loadRoute(target, packageRoot, errors, { taskId, routePath });
+  const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath, readers });
+  const route = await loadRoute(target, packageRoot, errors, { taskId, routePath, readers });
   const config = await optionalConfig(target, packageRoot, errors);
   if (config.structuralQuality !== undefined) {
     try {
@@ -59,9 +64,9 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
     errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", [PROFILE_PATH]));
   }
 
-  const contractRelPath = contractPath ?? (taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRelPath = routePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
-  const stateRelPath = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const contractRelPath = preflightArtifactPath(contractPath, taskId, "contract");
+  const routeRelPath = preflightArtifactPath(routePath, taskId, "route");
+  const stateRelPath = preflightArtifactPath(statePath, taskId, "state");
 
   const unresolvedDecisions = contract?.value?.unresolvedDecisions ?? [];
   if (unresolvedDecisions.length > 0) {
@@ -88,11 +93,11 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
   }
 
   const sources = await loadSources(target, contract, packageRoot, errors);
-  const gates = await inspectGates(target, contract, route, packageRoot, errors, config, { taskId });
+  const gates = await inspectGates(target, contract, route, packageRoot, errors, config, { taskId, readers });
 
   let state = null;
   try {
-    state = await readWorkState(target, { packageRoot, taskId, statePath });
+    state = await (readers?.readState ?? readWorkState)(target, { packageRoot, taskId, statePath });
   } catch (error) {
     errors.push(issue("E_STATE_INVALID", error.message, [stateRelPath]));
   }
@@ -135,7 +140,7 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
     reasonCodes: [],
     next: config.structuralQuality?.mode === "gate" ? "CAPTURE_STRUCTURAL_QUALITY_BASELINE" : null,
   };
-  if (effectiveTaskId !== "unknown") {
+  if (effectiveTaskId !== "unknown" && (!readers || structuralQuality.mode !== "off")) {
     try {
       const { projectStructuralQualityStatus } = await import("./structural-quality/service.js");
       structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId: effectiveTaskId });
@@ -183,7 +188,19 @@ export async function validateReadyProtocolConsistency(options = {}) {
   });
 }
 
-export async function runPreflight({
+export async function runPreflight(options = {}) {
+  if (options.persist === false) return runPreflightInTransaction(options);
+  let taskId = options.taskId;
+  if (!taskId) {
+    const { target, packageRoot, strict, contractPath, routePath, statePath } = options;
+    const result = await evaluatePreflight({ target, packageRoot, strict, contractPath, routePath, statePath });
+    if (result.taskId !== "unknown") taskId = result.taskId;
+  }
+  if (!taskId) return runPreflightInTransaction(options);
+  return withTaskTransaction({ target: options.target, taskId, packageRoot: options.packageRoot, operation: "preflight" }, () => runPreflightInTransaction({ ...options, taskId }));
+}
+
+async function runPreflightInTransaction({
   target,
   packageRoot,
   strict = false,
@@ -198,7 +215,7 @@ export async function runPreflight({
   let result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
   if (!persist) return result;
 
-  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
+  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, contractPath, routePath, statePath, eventsPath });
   assertPreflightResultPersistenceSafety(result);
   assertExistingReadyLifecycleCompatibility(ledger, result);
 
@@ -224,7 +241,7 @@ export async function runPreflight({
       result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
       assertPreflightResultPersistenceSafety(result);
       assertExistingReadyLifecycleCompatibility(ledger, result);
-      ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
+      ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, contractPath, routePath, statePath, eventsPath });
     }
   }
 

package/src/core/progress.js

@@ -1,8 +1,8 @@
-import { diagnosisEventsForTask } from "./diagnosis-model.js";
+import { isLedgerEventCollection, ledgerEventsOfTypes } from "./ledger-event-collection.js";
+import { latestDiagnosisForTask } from "./diagnosis-model.js";
 import { resolveCurrentCycleDiagnostic } from "./diagnostic-projection.js";
 import {
-  buildInformationGainProjection,
-  evaluateStructuredDiagnosticStall,
+  summarizeInformationGain,
 } from "./information-gain-projection.js";
 
 export const PROGRESS_STATUS = Object.freeze({
@@ -27,6 +27,17 @@ export function diagnosisRequirements(diagnosis, checksById) {
   )].sort();
 }
 
+function progressTaskEvents(events, taskId) {
+  if (Array.isArray(events)) return events.filter(event => !taskId || event.taskId === taskId);
+  return isLedgerEventCollection(events) ? events : [];
+}
+
+function* progressVerificationEvents(events, taskId) {
+  for (const event of ledgerEventsOfTypes(events, ["VERIFICATION_RECORDED"])) {
+    if (!taskId || event.taskId === taskId) yield event;
+  }
+}
+
 export function evaluateProgress({ state, events = [] } = {}) {
   const signals = [];
   let status = PROGRESS_STATUS.ADVANCING;
@@ -35,10 +46,10 @@ export function evaluateProgress({ state, events = [] } = {}) {
     return { status, signals };
   }
 
-  const taskEvents = Array.isArray(events) ? events.filter((e) => !state.taskId || e.taskId === state.taskId) : [];
-  const diagEvents = diagnosisEventsForTask(taskEvents, state.taskId);
+  const taskEvents = progressTaskEvents(events, state.taskId);
+  const latestLegacy = latestDiagnosisForTask(taskEvents, state.taskId);
   const resolvedDiagnostic = resolveCurrentCycleDiagnostic(taskEvents, state.taskId, state.verificationCycle ?? null);
-  const latestDiag = resolvedDiagnostic?.details ?? diagEvents.at(-1)?.details ?? null;
+  const latestDiag = resolvedDiagnostic?.details ?? latestLegacy?.details ?? null;
 
   let latestGainClassification = latestDiag?.informationGain ?? null;
   let structuredStall = null;
@@ -49,8 +60,8 @@ export function evaluateProgress({ state, events = [] } = {}) {
       )];
     }
     // Canonical structured-stall truth; compatibility classification is presentation only.
-    structuredStall = evaluateStructuredDiagnosticStall(
-      buildInformationGainProjection(taskEvents, state.taskId),
+    structuredStall = summarizeInformationGain(
+      taskEvents, state.taskId,
       { verificationCycle: state.verificationCycle ?? null },
     );
     latestDiag.effectiveInformationGain = !(structuredStall.stalled);
@@ -63,7 +74,7 @@ export function evaluateProgress({ state, events = [] } = {}) {
     if (check.id) checksById.set(check.id, check);
     if (check.checkId) checksById.set(check.checkId, check);
   }
-  for (const event of taskEvents) {
+  for (const event of progressVerificationEvents(taskEvents, state.taskId)) {
     if (event.event === "VERIFICATION_RECORDED" && event.details) {
       if (event.details.id) checksById.set(event.details.id, event.details);
       if (event.details.checkId) checksById.set(event.details.checkId, event.details);
@@ -108,7 +119,7 @@ export function evaluateProgress({ state, events = [] } = {}) {
   }
 
   // Also extract from VERIFICATION_RECORDED events
-  for (const event of taskEvents) {
+  for (const event of progressVerificationEvents(taskEvents, state.taskId)) {
     if (event.event === "VERIFICATION_RECORDED") {
       const details = event.details ?? {};
       if (details.status === "failed" || details.status === "blocked") {

package/src/core/protocol-info.js

@@ -7,6 +7,8 @@ import { VERIFICATION_ISOLATION_MODES } from "./verification-execution.js";
 import { PROVIDER_KINDS } from "../providers/capabilities.js";
 import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./decision/constants.js";
 
+import { getStorageCapabilities } from "../storage/capabilities.js";
+
 export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
   protocolVersion: PROTOCOL_VERSION,
   schemaVersion: 1,
@@ -38,6 +40,7 @@ export function protocolInfo({ packageVersion = null } = {}) {
     writesSchemaVersions: schemaVersions,
     compatibility: SCHEMA_COMPATIBILITY_POLICY,
     features: {
+      operationalStorage: getStorageCapabilities(),
       semanticDecisionPlane: {
         version: 1,
         supported: true,

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/reconcile-closure.js

@@ -1,3 +1,4 @@
+import { withTaskTransaction } from "./transaction.js";
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateEventLedger } from "./events.js";
@@ -7,12 +8,74 @@ 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_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
+/**
+ * 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;
+}
+
+// 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);
@@ -100,6 +163,23 @@ async function validateReconciliationCheckpoint({
     );
   }
 
+  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] ?? {};
@@ -109,18 +189,46 @@ async function validateReconciliationCheckpoint({
       [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,
-  });
+  const recovery = await authorizeCompletionRecoveryOrRebind({ target, packageRoot, taskId, authorityContext, runtimeContext });
   if (!recovery.recoveryAuth.authorized) {
     const first = recovery.recoveryAuth.errors?.[0] ?? {};
     throw reconcileError(
@@ -133,12 +241,12 @@ async function validateReconciliationCheckpoint({
 }
 
 /**
- * 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 REVIEWING (with either a
+ *   - 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
@@ -152,7 +260,14 @@ async function validateReconciliationCheckpoint({
  * 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,
@@ -163,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");
@@ -188,7 +292,7 @@ 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],
     );
   }
@@ -245,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,
@@ -295,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,
@@ -23,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;
     }
 
@@ -95,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);
 }