@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/events.js

@@ -14,7 +14,25 @@ import { taskArtifactPath } from "./task-paths.js";
 import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 import { assertDiagnosisDetails } from "./diagnosis-model.js";
+import {
+  assertActionEventDetails,
+  assertApprovalEventDetails,
+  isActionEventName,
+  isApprovalEventName,
+} from "./action-model.js";
+import {
+  assertDiagnosticCaseDetails,
+  assertInterventionDetails,
+  assertHypothesisDispositionDetails,
+} from "./diagnostic-model.js";
 import { assertDecisionCriterionDetails } from "./settlement-model.js";
+import {
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+  assertLegacyMigrationDetails,
+  isLegacyRecoveryDetailsShape,
+  isLegacyRecoveryEventShape,
+  legacyRecoveryMigrationId,
+} from "./task-recovery-migration.js";
 
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
@@ -39,6 +57,7 @@ const REPEATABLE_MILESTONES = new Set([
   "VERIFICATION_RECORDED",
   "REVIEW_STARTED",
   "TERMINAL_RESULT_RECORDED",
+  "PREFLIGHT_READY",
 ]);
 
 function eventIndexPath(eventsPath) {
@@ -91,17 +110,93 @@ export function validateKnownEventDetails(event) {
     case "DIAGNOSIS_RECORDED":
       assertDiagnosisDetails(event.details);
       return;
+    case "DIAGNOSTIC_CASE_RECORDED":
+      assertDiagnosticCaseDetails(event.details);
+      return;
+    case "INTERVENTION_RECORDED":
+      assertInterventionDetails(event.details);
+      return;
+    case "HYPOTHESIS_DISPOSITION_RECORDED":
+      assertHypothesisDispositionDetails(event.details);
+      return;
     case "DECISION_CRITERION_RECORDED":
       assertDecisionCriterionDetails(event.details);
       return;
     case "CHECKPOINT_RECONCILED":
       assertReconcileClosureDetails(event.details);
       return;
+    case "TASK_RECOVERY_RECORDED":
+      assertRecoveryRecordedDetails(event.details);
+      return;
+    case "OPERATOR_RECOVERY_RECORDED":
+      // The exact known legacy defect signature is tolerated here so the
+      // ledger can be parsed and classified. It only becomes valid through an
+      // official migration event (enforced by validateEventLedger).
+      if (!event.details?.recoveryId && isLegacyRecoveryDetailsShape(event.details)) return;
+      assertRecoveryRecordedDetails(event.details);
+      return;
+    case "LEGACY_RECOVERY_MIGRATION_RECORDED":
+      assertLegacyMigrationDetails(event.details);
+      return;
+    case "TASK_RECOVERY_RESUMED":
+      assertRecoveryResumedDetails(event.details);
+      return;
+    case "TRAJECTORY_EVALUATED":
+      if (!event.details || !/^eval-[A-Za-z0-9_-]+$/.test(event.details.evaluationId ?? "")
+        || typeof event.details.scenarioId !== "string" || !/^[a-f0-9]{64}$/.test(event.details.evaluationFingerprint ?? "")
+        || event.fingerprint !== event.details.evaluationFingerprint) {
+        throw protocolError("E_EVENT_INVALID", "TRAJECTORY_EVALUATED requires a bound evaluationId, scenarioId, and fingerprint");
+      }
+      return;
     default:
+      if (isActionEventName(event.event)) {
+        assertActionEventDetails(event);
+        return;
+      }
+      if (isApprovalEventName(event.event)) {
+        assertApprovalEventDetails(event);
+        return;
+      }
       return;
   }
 }
 
+function assertStringList(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+    throw protocolError("E_EVENT_INVALID", `${label} must be an array of non-empty strings`);
+  }
+}
+
+function assertRecoveryRecordedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event requires structured details");
+  }
+  for (const key of ["recoveryId", "classification", "previousPhase", "authorityKind"]) {
+    if (typeof details[key] !== "string" || !details[key]) {
+      throw protocolError("E_EVENT_INVALID", `recovery event details.${key} must be a non-empty string`);
+    }
+  }
+  if (!Number.isInteger(details.previousRevision) || details.previousRevision < 0) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.previousRevision must be a non-negative integer");
+  }
+  if (!["STALE", "ABANDONED"].includes(details.classification)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.classification must be STALE or ABANDONED");
+  }
+  if (!["CALLER_ACKNOWLEDGED", "HOST_ATTESTED"].includes(details.authorityKind)) {
+    throw protocolError("E_EVENT_INVALID", "recovery event details.authorityKind is invalid");
+  }
+  assertStringList(details.reasonCodes, "recovery event details.reasonCodes");
+  assertStringList(details.releasedClaims, "recovery event details.releasedClaims");
+}
+
+function assertRecoveryResumedDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)
+    || typeof details.recoveryId !== "string" || !details.recoveryId) {
+    throw protocolError("E_EVENT_INVALID", "TASK_RECOVERY_RESUMED requires details.recoveryId");
+  }
+  assertStringList(details.reacquiredClaims, "TASK_RECOVERY_RESUMED details.reacquiredClaims");
+}
+
 function assertReconcileClosureDetails(details) {
   if (!details || typeof details !== "object" || Array.isArray(details)) {
     throw protocolError("E_EVENT_INVALID", "CHECKPOINT_RECONCILED requires structured details");
@@ -121,7 +216,7 @@ function assertReconcileClosureDetails(details) {
   }
 }
 
-function eventHash(event) {
+export function eventHash(event) {
   const { hash, ...body } = event;
   return canonicalFingerprint(body);
 }
@@ -242,6 +337,73 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
   return event;
 }
 
+/**
+ * Validates the append-only pairing between unmigrated legacy recovery events
+ * and their official migration events. Strict by default; the official repair
+ * command validates intermediate state with `allowUnmigratedLegacyRecoveryEvents`
+ * before appending the migration events.
+ */
+function validateLegacyRecoveryMigrations(events, errors, { allowUnmigratedLegacyRecoveryEvents = false } = {}) {
+  const migrationBySeq = new Map();
+  for (const event of events) {
+    if (event.event !== LEGACY_RECOVERY_MIGRATION_EVENT) continue;
+    try {
+      assertLegacyMigrationDetails(event.details);
+    } catch (err) {
+      errors.push({ code: err.code ?? "E_EVENT_INVALID", message: `event ${event.seq} (${event.event}): ${err.message}` });
+      continue;
+    }
+    if (migrationBySeq.has(event.details.legacyEventSeq)) {
+      errors.push({
+        code: "E_EVENT_INVALID",
+        message: `event ${event.seq} (${event.event}): duplicate migration for legacy recovery event seq ${event.details.legacyEventSeq}`,
+      });
+      continue;
+    }
+    migrationBySeq.set(event.details.legacyEventSeq, event);
+  }
+  for (const event of events) {
+    if (!isLegacyRecoveryEventShape(event)) continue;
+    const migration = migrationBySeq.get(event.seq);
+    if (!migration) {
+      if (!allowUnmigratedLegacyRecoveryEvents) {
+        errors.push({
+          code: "E_EVENT_INVALID",
+          message: `legacy recovery event ${event.seq} is not officially migrated (run forgeloop task-repair-legacy-recovery)`,
+        });
+      }
+      continue;
+    }
+    migrationBySeq.delete(event.seq);
+    const expectedRecoveryId = legacyRecoveryMigrationId({ taskId: event.taskId, seq: event.seq, hash: event.hash });
+    // Tail-binding: the migration event is appended at the ledger tail and may
+    // sit anywhere after its historical source. It binds by reference only.
+    if (migration.seq <= event.seq) {
+      errors.push({
+        code: "E_EVENT_INVALID",
+        message: `migration event ${migration.seq} must follow legacy recovery event ${event.seq}`,
+      });
+    }
+    if (migration.taskId !== event.taskId
+      || migration.details.legacyTaskId !== event.taskId
+      || migration.details.recoveryId !== expectedRecoveryId
+      || migration.details.legacyEventHash !== event.hash
+      || migration.details.legacyEventAt !== event.at
+      || migration.details.legacyEventType !== event.event) {
+      errors.push({
+        code: "E_LEDGER_HASH_INVALID",
+        message: `migration event ${migration.seq} does not bind legacy recovery event ${event.seq}`,
+      });
+    }
+  }
+  for (const [legacySeq, migration] of migrationBySeq) {
+    errors.push({
+      code: "E_EVENT_INVALID",
+      message: `migration event ${migration.seq} references unknown legacy recovery event seq ${legacySeq}`,
+    });
+  }
+}
+
 export async function validateEventLedger(target, packageRoot, options = {}) {
   const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   let events;
@@ -284,7 +446,11 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
           code: "E_PHASE_CHRONOLOGY_INVALID",
           message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}`,
         });
-      } else if (milestoneIndex < lastMilestone && event.event !== "VERIFICATION_STARTED") {
+      } else if (milestoneIndex < lastMilestone && event.event !== "VERIFICATION_STARTED"
+        && event.event !== "PREFLIGHT_READY") {
+        // VERIFICATION_STARTED re-enters per verification cycle; PREFLIGHT_READY
+        // may be refreshed mid-lifecycle (policy/contract evolution) after its
+        // prerequisites were already satisfied by the earlier occurrence.
         errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
       } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event)) {
         errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
@@ -323,6 +489,9 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion rejected before verification started" });
     }
   }
+  validateLegacyRecoveryMigrations(events, errors, {
+    allowUnmigratedLegacyRecoveryEvents: options?.allowUnmigratedLegacyRecoveryEvents === true,
+  });
   return { valid: errors.length === 0, events, errors };
 }
 

package/src/core/execution-prerequisites.js

@@ -102,7 +102,10 @@ function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
       ));
     }
   }
-  const preflightEvent = currentEvents.find((event) => event.event === "PREFLIGHT_READY");
+  // Bind to the latest PREFLIGHT_READY: an append-only lifecycle may contain an
+  // older READY event superseded by a BLOCKED outcome and a fresh READY with
+  // current details (see preflight-reactivation recovery).
+  const preflightEvent = currentEvents.findLast((event) => event.event === "PREFLIGHT_READY");
   if (preflightEvent && (!sameStringSet(preflightEvent.details?.requiredGates, preflight.requiredGates)
     || !sameStringSet(preflightEvent.details?.satisfiedGates, preflight.satisfiedGates))) {
     errors.push(issue(

package/src/core/execution.js

@@ -1,5 +1,3 @@
-import { createHash, randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { ensureWithin, fileExists } from "./filesystem.js";
@@ -7,17 +5,19 @@ import {
   ARTIFACT_PATHS,
   executionArtifactPath,
   readJsonArtifact,
-  writeJsonArtifact,
 } from "./artifacts.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
-import {
-  resolveExecutionResolution,
-  validateVerificationAuthority,
-  E_COMMAND_RESOLUTION_AMBIGUOUS,
-} from "./verification-capability.js";
 
-export { E_COMMAND_RESOLUTION_AMBIGUOUS };
-export const EXECUTION_KIND = "COMMAND_EXECUTION";
+export { E_COMMAND_RESOLUTION_AMBIGUOUS } from "./verification-capability.js";
+import {
+  prepareCommandExecution,
+  runPreparedCommandExecution,
+} from "./prepared-execution.js";
+export {
+  prepareCommandExecution,
+  runPreparedCommandExecution,
+  TERMINATION_GRACE_MS_PREPARED as TERMINATION_GRACE_MS,
+} from "./prepared-execution.js";
 
 function executionError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -26,111 +26,6 @@ function executionError(code, message, artifacts = []) {
   return error;
 }
 
-function normalizeArgv(argv) {
-  if (!Array.isArray(argv) || argv.length === 0 || argv.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw executionError("E_EXECUTION_INVALID", "Execution argv must contain at least one non-empty string");
-  }
-  return [...argv];
-}
-
-function validateAuthorityBeforeLaunch({ target, taskId, argv, resolution, details, authorityContext, runtimeContext }) {
-  if (!resolution.mayInstall) return;
-  const check = {
-    kind: "command",
-    source: argv[0],
-    details: {
-      ...(details ?? {}),
-      execution: { resolution },
-    },
-  };
-  const authority = validateVerificationAuthority(check, {
-    target,
-    taskId,
-    authorityContext,
-    runtimeContext,
-  });
-  if (!authority.valid) {
-    throw executionError(authority.error.code ?? "E_INSTALLATION_AUTHORITY_REQUIRED", authority.error.message);
-  }
-}
-
-const MAX_CAPTURED_OUTPUT_BYTES = 64 * 1024;
-export const TERMINATION_GRACE_MS = 1_000;
-
-function digest(bytes) {
-  return createHash("sha256").update(bytes).digest("hex");
-}
-
-function executeProcess(argv, cwd, { timeoutMs = null } = {}) {
-  return new Promise((resolve) => {
-    let spawnError = null;
-    let timedOut = false;
-    let settled = false;
-    let timeout = null;
-    let forceTermination = null;
-    const stdout = [];
-    const stderr = [];
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
-    let outputTruncated = false;
-    const capture = (chunks, chunk, total) => {
-      const available = MAX_CAPTURED_OUTPUT_BYTES - total;
-      if (available <= 0) {
-        outputTruncated = true;
-        return total;
-      }
-      if (chunk.length > available) {
-        chunks.push(chunk.subarray(0, available));
-        outputTruncated = true;
-        return total + available;
-      }
-      chunks.push(chunk);
-      return total + chunk.length;
-    };
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      if (forceTermination) clearTimeout(forceTermination);
-      resolve({
-        ...result,
-        timedOut,
-        stdout: Buffer.concat(stdout),
-        stderr: Buffer.concat(stderr),
-        stdoutBytes,
-        stderrBytes,
-        outputTruncated,
-      });
-    };
-    try {
-      const child = spawn(argv[0], argv.slice(1), {
-        cwd,
-        shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      child.stdout?.on("data", (chunk) => { stdoutBytes = capture(stdout, chunk, stdoutBytes); });
-      child.stderr?.on("data", (chunk) => { stderrBytes = capture(stderr, chunk, stderrBytes); });
-      child.once("error", (error) => {
-        spawnError = error;
-      });
-      child.once("close", (exitCode, signal) => {
-        finish({ exitCode, signal, spawnError });
-      });
-      if (Number.isInteger(timeoutMs) && timeoutMs > 0) {
-        timeout = setTimeout(() => {
-          timedOut = true;
-          child.kill("SIGTERM");
-          forceTermination = setTimeout(() => {
-            child.kill("SIGKILL");
-          }, TERMINATION_GRACE_MS);
-        }, timeoutMs);
-      }
-    } catch (error) {
-      finish({ exitCode: null, signal: null, spawnError: error });
-    }
-  });
-}
-
 /**
  * Resolves where a new execution artifact should be written. Task-scoped
  * execution artifacts require a real modern task namespace (a task.json
@@ -148,6 +43,12 @@ export async function resolveExecutionArtifactPath(target, taskId, executionId)
   return executionArtifactPath(executionId);
 }
 
+/**
+ * Deterministic pre-launch preparation followed by an exact-argv launch.
+ * Kept as the canonical single-command entrypoint for non-durable callers
+ * (run-check); durable actions use the two phases separately so that
+ * ACTION_STARTED lands exactly on the launch boundary (INV-EXEC-01).
+ */
 export async function runCommandExecution({
   target,
   packageRoot,
@@ -162,87 +63,24 @@ export async function runCommandExecution({
   executionPath,
   timeoutMs = null,
 } = {}) {
-  const commandArgv = normalizeArgv(argv);
-  const resolution = await resolveExecutionResolution({
-    argv: commandArgv,
-    cwd: target,
-  });
-
-  if (
-    resolution.resolutionMode === "UNKNOWN"
-    && resolution.mayInstall === true
-    && (
-      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
-      || resolution.reason === "NPM_SUBCOMMAND_AMBIGUOUS"
-      || resolution.reason === "NPM_COMMAND_UNCLASSIFIED"
-      || resolution.reason === "NPM_OPTION_VALUE_AMBIGUOUS"
-    )
-  ) {
-    const error = new Error(
-      resolution.reason === "NPM_WORKSPACE_SCRIPT_UNRESOLVED"
-        ? "npm workspace script execution cannot be proven from the current target. Run ForgeLoop against the selected workspace directory."
-        : "Command execution context could not be proven safe before launch."
-    );
-    error.code = E_COMMAND_RESOLUTION_AMBIGUOUS;
-    error.resolution = resolution;
-    throw error;
-  }
-
-  validateAuthorityBeforeLaunch({
+  const prepared = await prepareCommandExecution({
     target,
-    taskId,
-    argv: commandArgv,
-    resolution,
+    argv,
     details,
     authorityContext,
     runtimeContext,
   });
-
-  const executionId = `exec-${randomUUID()}`;
-  const startedAt = new Date().toISOString();
-  const processResult = await executeProcess(commandArgv, target, { timeoutMs });
-  const finishedAt = new Date().toISOString();
-  const execution = {
-    schemaVersion: 1,
-    protocolVersion: 1,
-    executionId,
+  return runPreparedCommandExecution({
+    target,
+    packageRoot,
     taskId,
     checkId,
     requirement,
     verificationCycle,
-    kind: EXECUTION_KIND,
-    argv: commandArgv,
-    cwd: target,
-    resolution: {
-      resolutionMode: resolution.resolutionMode,
-      mayInstall: resolution.mayInstall,
-      installer: resolution.installer,
-      tool: resolution.tool,
-    },
-    ...(resolution.dispatch ? { dispatch: resolution.dispatch } : {}),
-    startedAt,
-    finishedAt,
-    status: processResult.exitCode === 0 && !processResult.spawnError && !processResult.timedOut ? "passed" : "failed",
-    exitCode: processResult.exitCode,
-    durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
-    termination: processResult.spawnError ? "spawn-error" : processResult.timedOut ? "timeout" : processResult.signal ? "signal" : "exit",
-    signal: processResult.signal ?? null,
-    stdoutSha256: digest(processResult.stdout),
-    stderrSha256: digest(processResult.stderr),
-    stdoutBytes: processResult.stdoutBytes,
-    stderrBytes: processResult.stderrBytes,
-    outputTruncated: processResult.outputTruncated,
-    ...(Number.isInteger(timeoutMs) && timeoutMs > 0 ? { timeoutMs, terminationGraceMs: TERMINATION_GRACE_MS } : {}),
-  };
-  const execPath = executionPath ?? await resolveExecutionArtifactPath(target, taskId, executionId);
-  const written = await writeJsonArtifact(target, execPath, execution, "execution", packageRoot);
-  return {
-    path: written.path,
-    execution: written.value,
-    result: processResult.spawnError
-      ? "process failed to start"
-      : `process exited with code ${processResult.exitCode}`,
-  };
+    prepared,
+    timeoutMs,
+    executionPath,
+  });
 }
 
 export async function readExecutionArtifact({ target, executionRef, packageRoot, taskId } = {}) {
@@ -287,7 +125,7 @@ export async function readExecutionArtifact({ target, executionRef, packageRoot,
 }
 
 export function validateExecutionBinding({ execution, taskId, checkId, requirement, verificationCycle = 1 } = {}) {
-  if (!execution || execution.kind !== EXECUTION_KIND
+  if (!execution || execution.kind !== "COMMAND_EXECUTION"
     || execution.taskId !== taskId
     || execution.checkId !== checkId
     || execution.requirement !== requirement

package/src/core/failure-signature.js

@@ -0,0 +1,70 @@
+import { canonicalFingerprint } from "./artifacts.js";
+
+export function computeFailureSignature({ requirement, checkKind = null, status, exitCode = null, failureToken = null }) {
+  if (!requirement || typeof requirement !== "string") {
+    const error = new Error("failure signature requires a requirement");
+    error.code = "E_FAILURE_SIGNATURE_INVALID";
+    throw error;
+  }
+  if (!status || typeof status !== "string") {
+    const error = new Error("failure signature requires a status");
+    error.code = "E_FAILURE_SIGNATURE_INVALID";
+    throw error;
+  }
+  return canonicalFingerprint({
+    requirement,
+    ...(checkKind ? { checkKind } : {}),
+    status,
+    ...(Number.isInteger(exitCode) ? { exitCode } : {}),
+    ...(failureToken ? { failureToken: String(failureToken) } : {}),
+  });
+}
+
+function failureTokenOf(details) {
+  if (typeof details?.failureToken === "string" && details.failureToken) return details.failureToken;
+  if (typeof details?.details?.failureToken === "string" && details.details.failureToken) return details.details.failureToken;
+  return null;
+}
+
+export function projectFailureSignatures({ state = null, events = [] } = {}) {
+  const byCycle = new Map();
+  const record = (cycle, details) => {
+    if (details.status !== "failed" && details.status !== "blocked") return;
+    const requirement = details.requirement ?? details.id ?? details.checkId;
+    if (!requirement) return;
+    const signature = computeFailureSignature({
+      requirement,
+      status: details.status,
+      exitCode: Number.isInteger(details.exitCode) ? details.exitCode : null,
+      failureToken: failureTokenOf(details),
+    });
+    if (!byCycle.has(cycle)) byCycle.set(cycle, new Map());
+    const cycleMap = byCycle.get(cycle);
+    if (!cycleMap.has(signature)) cycleMap.set(signature, { signature, requirements: new Set(), cycles: new Set() });
+    cycleMap.get(signature).requirements.add(requirement);
+    cycleMap.get(signature).cycles.add(cycle);
+  };
+
+  for (const event of events) {
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    record(event.details?.verificationCycle ?? 1, event.details ?? {});
+  }
+  for (const check of state?.checks ?? []) {
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check);
+  }
+
+  const signaturesByIdentity = new Map();
+  for (const [, cycleMap] of [...byCycle.entries()].sort(([a], [b]) => a - b)) {
+    for (const [signature, entry] of cycleMap) {
+      if (!signaturesByIdentity.has(signature)) signaturesByIdentity.set(signature, { signature, cycles: [], requirements: new Set() });
+      const aggregated = signaturesByIdentity.get(signature);
+      aggregated.cycles.push(...entry.cycles);
+      for (const requirement of entry.requirements) aggregated.requirements.add(requirement);
+    }
+  }
+
+  return [...signaturesByIdentity.values()]
+    .map((entry) => ({ ...entry, cycles: [...new Set(entry.cycles)].sort((a, b) => a - b), requirements: [...entry.requirements].sort() }))
+    .sort((a, b) => a.signature.localeCompare(b.signature));
+}

package/src/core/failure-surface.js

@@ -0,0 +1,57 @@
+export function projectFailureSurfaces({ state = null, events = [] } = {}) {
+  const failedRequirementsByCycle = new Map();
+  // Track every canonically verified cycle so a successful verification
+  // appears explicitly as surface: [] instead of silently disappearing.
+  const knownCycles = new Set();
+  const record = (cycle, requirement) => {
+    if (!Number.isInteger(cycle)) cycle = Number(cycle) || 1;
+    knownCycles.add(cycle);
+    if (!failedRequirementsByCycle.has(cycle)) failedRequirementsByCycle.set(cycle, new Set());
+    if (!requirement) return;
+    failedRequirementsByCycle.get(cycle).add(requirement);
+  };
+  const knowCycle = (cycle) => {
+    if (Number.isInteger(cycle)) knownCycles.add(cycle);
+  };
+
+  for (const event of events) {
+    if (event.event === "VERIFICATION_STARTED") {
+      knowCycle(event.details?.verificationCycle);
+    }
+    if (event.event !== "VERIFICATION_RECORDED") continue;
+    const d = event.details ?? {};
+    if (d.status === "failed" || d.status === "blocked") {
+      record(d.verificationCycle ?? 1, d.requirement ?? d.id ?? d.checkId);
+    } else {
+      knowCycle(d.verificationCycle);
+    }
+  }
+
+  for (const check of state?.checks ?? []) {
+    knowCycle(check.details?.verificationCycle ?? state?.verificationCycle ?? 1);
+    if (check.status !== "failed" && check.status !== "blocked") continue;
+    record(check.details?.verificationCycle ?? state?.verificationCycle ?? 1, check.requirement ?? check.id ?? check.checkId);
+  }
+  for (const cycle of knownCycles) {
+    if (!failedRequirementsByCycle.has(cycle)) failedRequirementsByCycle.set(cycle, new Set());
+  }
+
+  return [...failedRequirementsByCycle.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([verificationCycle, requirements]) => ({
+      verificationCycle,
+      surface: [...requirements].sort(),
+      size: requirements.size,
+    }));
+}
+
+export function compareFailureSurface(previous, current) {
+  if (!previous || !current) return { changed: false, direction: "UNCHANGED" };
+  const previousSet = new Set(previous);
+  const currentSet = new Set(current);
+  const removed = [...previousSet].filter((item) => !currentSet.has(item));
+  const added = [...currentSet].filter((item) => !previousSet.has(item));
+  if (added.length > 0) return { changed: true, direction: "EXPANDED", added, removed };
+  if (removed.length > 0) return { changed: true, direction: "REDUCED", added, removed };
+  return { changed: false, direction: "UNCHANGED", added, removed };
+}