faberun 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/campaign/index.mjs

@@ -21,7 +21,9 @@ import { handoffFromState, materializeHandoff } from "./handoff.mjs";
 /** @typedef {{path: string, digest: string}} CampaignContract */
 /** @typedef {{runId: string, contractPath?: string, branch: string, sha: string, previousSha: string|null, at: string}} PromotionRecord */
 /** @typedef {{code: string, message: string, at: string, contractPath?: string, contractId?: string, runId?: string, node?: string|null, status?: string|null, resume?: string}} CampaignAttention */
-/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
+/** @typedef {{runId: string, node: string, passed: boolean|null, verdict: string|null}} RequirementNodeEvidence */
+/** @typedef {{requirementId: string, status: "covered"|"open", nodes: RequirementNodeEvidence[]}} RequirementClosure */
+/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
 /** @typedef {{type: string, eventId: string, at: string, sessionId?: string, text?: string, tool?: string, transcript?: string|null, transcriptUnavailable?: boolean, format?: string|null, cursor?: string|null, decisionId?: string, supersedes?: string, runId?: string, questionId?: string, campaignId?: string, nodeId?: string|null, phase?: string, checkpointsDone?: number, checkpointsTotal?: number, runtime?: string|null, state?: string, lastProgressAt?: string, attention?: string|null}} JournalEntry */
 /** @typedef {{updatedAt: string|null, decisions: Record<string, JournalEntry>, questions: Record<string, JournalEntry>, constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], sessions: JournalEntry[], next: JournalEntry|null, evicted: Record<string, number>}} Projection */
 /** @typedef {{cursor: number, byte: number, size: number, projection: Projection}} ProjectionRecord */
@@ -135,12 +137,82 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   }
   const repoRoot = campaignRepoRoot(campaignPath);
   const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
-  const closed = /** @type {Campaign} */ ({ ...campaign, status: "closed", closedAt: at, updatedAt: at });
+  // The closure travels on the record itself, computed in one deterministic
+  // pass over the linked runs' own files before the close is written.
+  const requirements = buildRequirementClosure(campaignPath, campaign);
+  /** @type {Campaign} */
+  const closed = { ...campaign, status: "closed", closedAt: at, updatedAt: at, requirements };
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
   appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
   return { path: campaignPath, campaign: closed, ledgerFiles };
 }
 
+/**
+ * The requirement closure a close records: one entry per requirement id the
+ * linked runs' contracts declared, correlated only by the identifiers the runs
+ * carried -- the contract node's declaration and the id the done node snapshot
+ * itself carries, stamped there by the engine -- never by requirement text. A
+ * requirement no done node carries is recorded as open rather than omitted.
+ * Deterministic and free of external calls: runs are visited in sorted id
+ * order, nodes in contract order, requirement ids sorted, and the only inputs
+ * are files already on disk. A run that never launched (or was pruned)
+ * contributes nothing.
+ *
+ * @param {string} campaignPath
+ * @param {Campaign} campaign
+ * @returns {RequirementClosure[]}
+ */
+function buildRequirementClosure(campaignPath, campaign) {
+  const runsDir = resolve(campaignPath, "..", "..");
+  /** @type {Map<string, RequirementNodeEvidence[]>} */
+  const covered = new Map();
+  /** @type {Set<string>} */
+  const declared = new Set();
+  for (const runId of [...campaign.linkedRunIds].sort()) {
+    const contract = readRunJson(join(runsDir, runId, "contract.json"));
+    const nodes = contract !== null && Array.isArray(contract.nodes) ? /** @type {JsonObject[]} */ (contract.nodes) : [];
+    for (const node of nodes) {
+      const nodeId = typeof node.id === "string" ? node.id : "";
+      const requirementIds = Array.isArray(node.requirementIds) ? node.requirementIds : [];
+      if (!nodeId || requirementIds.length === 0) continue;
+      const snapshot = readRunJson(join(runsDir, runId, "nodes", `${nodeId}.json`));
+      const done = snapshot !== null && snapshot.status === "done";
+      const carried = snapshot !== null && Array.isArray(snapshot.requirementIds) ? /** @type {unknown[]} */ (snapshot.requirementIds) : [];
+      const verification = snapshot !== null ? /** @type {JsonObject|null|undefined} */ (snapshot.verification) : undefined;
+      const gate = snapshot !== null ? /** @type {JsonObject|null|undefined} */ (snapshot.gate) : undefined;
+      const passed = verification && typeof verification.passed === "boolean" ? verification.passed : null;
+      const verdict = gate && typeof gate.verdict === "string" ? gate.verdict : null;
+      for (const requirementId of requirementIds) {
+        if (typeof requirementId !== "string") continue;
+        declared.add(requirementId);
+        if (!done || !carried.includes(requirementId)) continue;
+        const evidence = covered.get(requirementId) ?? [];
+        evidence.push({ runId, node: nodeId, passed, verdict });
+        covered.set(requirementId, evidence);
+      }
+    }
+  }
+  return [...declared].sort().map((requirementId) => {
+    const nodes = covered.get(requirementId) ?? [];
+    return { requirementId, status: nodes.length > 0 ? "covered" : "open", nodes };
+  });
+}
+
+/**
+ * @param {string} path
+ * @returns {JsonObject|null} null when the file is absent or not JSON: a run
+ * that never launched contributes nothing to the closure rather than failing
+ * the close, the same discipline `preserveCampaignLedger` applies to a run
+ * without a usage ledger.
+ */
+function readRunJson(path) {
+  try {
+    return /** @type {JsonObject} */ (JSON.parse(readFileSync(path, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The repository a campaign's ledger is preserved into. Under the home layout
  * the campaign path carries the project id at the resolver's fixed position,

package/src/campaign/record.mjs

@@ -99,4 +99,32 @@ function validateCampaign(campaign) {
       if (promotion.contractPath !== undefined) requireString(promotion.contractPath, `campaign.promotions[${index}].contractPath`);
     }
   }
+  // The requirement closure a close records: one entry per requirement id the
+  // linked runs' contracts declared, correlated by the identifiers the runs
+  // carried, with every uncovered requirement kept as open. Optional on read
+  // so a campaign closed before the field existed stays readable.
+  if (record.requirements !== undefined) {
+    if (!Array.isArray(record.requirements)) throw new TypeError("campaign.requirements must be an array");
+    for (const [index, entry] of record.requirements.entries()) {
+      assertObject(entry, `campaign.requirements[${index}]`);
+      const closure = /** @type {JsonObject} */ (entry);
+      requireId(closure.requirementId, `campaign.requirements[${index}].requirementId`);
+      if (closure.status !== "covered" && closure.status !== "open") {
+        throw new TypeError(`campaign.requirements[${index}].status must be covered or open`);
+      }
+      if (!Array.isArray(closure.nodes)) throw new TypeError(`campaign.requirements[${index}].nodes must be an array`);
+      for (const [position, evidence] of closure.nodes.entries()) {
+        assertObject(evidence, `campaign.requirements[${index}].nodes[${position}]`);
+        const node = /** @type {JsonObject} */ (evidence);
+        requireId(node.runId, `campaign.requirements[${index}].nodes[${position}].runId`);
+        requireId(node.node, `campaign.requirements[${index}].nodes[${position}].node`);
+        if (node.passed !== null && typeof node.passed !== "boolean") {
+          throw new TypeError(`campaign.requirements[${index}].nodes[${position}].passed must be a boolean or null`);
+        }
+        if (node.verdict !== null && typeof node.verdict !== "string") {
+          throw new TypeError(`campaign.requirements[${index}].nodes[${position}].verdict must be a string or null`);
+        }
+      }
+    }
+  }
 }

package/src/cli/plan.mjs

@@ -11,6 +11,8 @@ import { classifyRunProgress } from "../campaign/chain.mjs";
 import { runProgress } from "../engine/supervise.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
 import { validateRuntime } from "../contract/runtime.mjs";
+import { validateFinalVerification, validateSharedVerification } from "../contract/final-verification.mjs";
+import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
 import { runDirectory } from "../run/paths.mjs";
@@ -79,9 +81,40 @@ export function loadRuntimesCatalogue(path) {
   return runtimes;
 }
 
+/**
+ * A `--verification <path>` catalogue: a JSON object carrying either or both
+ * of the contract's own suite keys, `sharedVerification` and
+ * `finalVerification`, each validated with the same validator
+ * `validateContract` applies. A key that is not a contract suite is refused
+ * rather than ignored: a typo'd key would freeze a contract that looks
+ * ratcheted and is not, which is the failure mode this flag exists to close.
+ *
+ * @param {string} path
+ * @returns {{sharedVerification?: import("../contract/index.mjs").VerificationCommand[], finalVerification?: import("../contract/index.mjs").VerificationCommand[]}}
+ */
+export function loadVerificationSuites(path) {
+  const resolved = resolve(path);
+  /** @type {unknown} */
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(resolved, "utf8"));
+  } catch (error) {
+    throw new Error(`--verification ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`--verification ${path} must be a JSON object`);
+  const record = /** @type {Record<string, unknown>} */ (raw);
+  for (const key of Object.keys(record)) {
+    if (key !== "sharedVerification" && key !== "finalVerification") throw new Error(`--verification ${path} must carry only sharedVerification and finalVerification: ${key}`);
+  }
+  return {
+    ...(record.sharedVerification === undefined ? {} : { sharedVerification: validateSharedVerification(record.sharedVerification, "contract.sharedVerification") }),
+    ...(record.finalVerification === undefined ? {} : { finalVerification: validateFinalVerification(record.finalVerification, "contract.finalVerification") }),
+  };
+}
+
 /**
  * @param {string} target
- * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, detach?: boolean, json?: boolean}} values
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, detach?: boolean, json?: boolean}} values
  * @returns {Promise<void>}
  */
 export async function planCli(target, values) {
@@ -95,12 +128,16 @@ export async function planCli(target, values) {
   const runtimes = typeof values.runtimes === "string" && values.runtimes
     ? loadRuntimesCatalogue(values.runtimes)
     : DISCOVERY_RUNTIME_DEFINITIONS;
+  const verification = typeof values.verification === "string" && values.verification
+    ? loadVerificationSuites(values.verification)
+    : {};
 
   if (values.detach === true) {
     const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
     if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);
     if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
     if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
+    if (typeof values.verification === "string" && values.verification) argv.push("--verification", resolve(values.verification));
     const child = detachArgv(argv);
     if (child.pid === undefined) throw new Error("detached plan has no pid");
     process.stdout.write(`[plan] detached · pid ${child.pid} · ${specPath}\n`);
@@ -115,6 +152,7 @@ export async function planCli(target, values) {
     approveBelow,
     runtimeDefaults,
     runtimes,
+    verification,
     launch: async (contractPath, contract) => {
       const child = detachSelf("run", contractPath);
       if (child.pid === undefined) throw new Error("detached planning run has no pid");
@@ -139,5 +177,6 @@ export async function planCli(target, values) {
     process.exitCode = 1;
     return;
   }
+  for (const warning of result.warnings) process.stdout.write(`${statusToken("warn", colorLevel(process.env, process.stdout.isTTY))} ${warning}\n`);
   process.stdout.write(`[plan] ${campaignId} phase ${phase} frozen · approved ${result.approved} · ${result.contractPath}\n`);
 }

package/src/cli.mjs

@@ -122,6 +122,7 @@ export const COMMAND_OPTIONS = {
     "approve-below": { type: "string" },
     "runtime-defaults": { type: "string" },
     runtimes: { type: "string" },
+    verification: { type: "string" },
     detach: { type: "boolean" },
     json: { type: "boolean" },
   },

package/src/contract/index.mjs

@@ -37,7 +37,7 @@ const CONTRACT_FIELDS = new Set([
 ]);
 const DEFAULTS_FIELDS = new Set(["worker", "judge"]);
 const NODE_FIELDS = new Set([
-  "id", "type", "phase", "runtime", "dependsOn", "taskPacket", "taskPacketFile", "prompt", "promptFile",
+  "id", "type", "phase", "requirementIds", "runtime", "dependsOn", "taskPacket", "taskPacketFile", "prompt", "promptFile",
   "definitionOfDone", "gate", "timeoutSec", "maxTurns",
   "requiredCapabilities", "packetHash", "sourceIdentity", "replayPolicy",
 ]);
@@ -68,7 +68,7 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
 /** @typedef {{enabled: boolean, review?: ("none"|"advisory"|"blocking"), runtime?: string, failOn?: ("minor"|"major"|"critical")[], maxRevisions?: number, requiredCapabilities?: CapabilityRequirements, skipWhen?: {verificationGreen: true, maxChangedPaths: number}}} ValidatedGate */
 
-/** @typedef {{id: string, type: string, phase: string, runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, maxTurns?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
+/** @typedef {{id: string, type: string, phase: string, requirementIds?: string[], runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, maxTurns?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
 
 /** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, maxTurns: number, phaseSessionReuse: boolean, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
 /** @typedef {{costUsd?: number, durationSec?: number}} NodeAdvisoryPolicy */
@@ -98,11 +98,11 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 /** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number}} RoutingState */
 /** @typedef {{revision?: number, heartbeatCount: number, dryHeartbeatCount: number, progressSignature?: string|null, lastHeartbeatAt: string|null, lastProgressAt: string|null, nextCheckAt?: string|null}} ProgressState */
 /** @typedef {{status: "unassigned"|"provisioning"|"ready"|"failed"|"removed", path: string|null, branch: string|null, commit: string|null, baseSha?: string|null, sealedSha?: string|null, sealError?: string|null, previousAttempt?: number|null}} WorktreeState */
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, requirementIds?: string[], status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
 /** @typedef {{path: string, sha: string}} ControllerIdentity */
 /** @typedef {{schemaVersion: number, contractVersion: string, pid: number, processStartToken: string|null, startedAt: string, sourceIdentity: SourceIdentity, controllerIdentity?: ControllerIdentity, integrationRef?: string, identityWarnings?: string[], relaunchCount?: number, lastRelaunchProgressAt?: string|null, attention?: {code: string, message: string, at: string}|null, contractDigest?: string, scopeDecision?: ScopeDecision, autoRetries?: Record<string, {code: string, at: string}>}} RunMetadata */
 /** @typedef {{at: string, base: string|null, dirtyTreeFingerprint: string|null}} ScopeDecision */
-/** @typedef {{schemaVersion: number, contractVersion: string, at: string, node: string, from?: string, to: string, type?: string, phase?: string, attempt?: number, role?: "worker"|"judge", status?: NodeStatus, runtime?: string, currentRuntime?: string, errorCode?: string, error?: SnapshotError, verdict?: string, summary?: string, revisions?: number, sourceIdentity: SourceIdentity, packetHash: string, override?: unknown, recovery?: unknown, invocationId?: string, unexpectedPaths?: string[], unexpectedPathCount?: number}} EventRecord */
+/** @typedef {{schemaVersion: number, contractVersion: string, at: string, node: string, from?: string, to: string, type?: string, phase?: string, attempt?: number, role?: "worker"|"judge", status?: NodeStatus, runtime?: string, currentRuntime?: string, errorCode?: string, error?: SnapshotError, verdict?: string, summary?: string, revisions?: number, requirementIds?: string[], sourceIdentity: SourceIdentity, packetHash: string, override?: unknown, recovery?: unknown, invocationId?: string, unexpectedPaths?: string[], unexpectedPathCount?: number}} EventRecord */
 
 /**
  * Validate and canonicalize the versioned contract. Runtime JSON remains
@@ -179,6 +179,17 @@ export function validateContract(raw, contractPath, options = {}) {
     ids.add(node.id);
     requireString(node.type, `nodes[${index}].type`);
     boundedString(node.phase, `nodes[${index}].phase`, 128);
+    // A node's requirementIds are inherited from its phase at freeze time
+    // (src/plan/freeze.mjs stamps them) and are optional on read: a contract
+    // without the field loads unchanged, which is what keeps CONTRACT_VERSION
+    // at 0.3.0 while requirement ids reach the node.
+    const requirementIds = node.requirementIds;
+    if (requirementIds !== undefined) {
+      if (!Array.isArray(requirementIds) || requirementIds.length > 64) {
+        throw new TypeError(`nodes[${index}].requirementIds must be an array of at most 64 requirement ids`);
+      }
+      requirementIds.forEach((id, position) => boundedString(id, `nodes[${index}].requirementIds[${position}]`, 128));
+    }
     if (node.runtime !== undefined) requireRuntime(runtimes, node.runtime, `nodes[${index}].runtime`);
     const dependsOn = node.dependsOn ?? [];
     if (!Array.isArray(dependsOn) || dependsOn.some((id) => typeof id !== "string")) {

package/src/contract/runtime.mjs

@@ -1,13 +1,15 @@
 /**
  * A declared runtime: its fields, the harness names it may name, whether its
- * permission mode can execute a command, and how a role resolves to one.
+ * permission mode can execute a command, and how a role resolves to one -- the
+ * latter including the strategies a routing rule may name, which are authored
+ * protocol surface a reader can reject by name just like a harness name.
  *
  * Split out because both the contract validator and the snapshot validator need
  * it -- a persisted `runtime` on a node snapshot is the shape the contract
  * declared -- and the snapshot validator should not import the contract
  * validator to reach it.
  */
-import { assertObject, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString, requireStringArray } from "./assert.mjs";
+import { assertObject, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString, requireStringArray, requireTimestamp } from "./assert.mjs";
 import { composeAssignments } from "../engine/runtime-discovery.mjs";
 import { harnessCapabilities, resolvePermissionExecution, resolveVendor, validateCapabilityRequirements } from "../harnesses/index.mjs";
 import { stableJson } from "../util.mjs";
@@ -26,6 +28,19 @@ const RUNTIME_FIELDS = new Set([
 ]);
 const RUNTIME_HARNESSES = new Set(["claude", "codex", "agy", "dsh", "zcode", "exec-jsonl", "replay"]);
 
+/**
+ * The strategies a routing rule may name: how a rule consumes its `prefer`
+ * list. `priority` takes the first admissible candidate; `cost` the lowest
+ * declared `costRank`; `reset-proximity` the least observed `remaining`
+ * allowance -- the window nearest its reset is spent first; `attempt-affinity`
+ * the previous attempt's runtime for the same node. A strategy whose datum a
+ * given runtime does not expose is inert for that runtime -- never a failure.
+ * An assignment records `declared` instead of any of these when an operator's
+ * runtime instruction prevailed over the table and every strategy.
+ * @typedef {"priority" | "cost" | "reset-proximity" | "attempt-affinity"} RoutingStrategy
+ */
+export const ROUTING_STRATEGIES = Object.freeze(new Set(["priority", "cost", "reset-proximity", "attempt-affinity"]));
+
 /**
  * Harness-specific stall thresholds where the contract's single default is
  * wrong for every turn the harness runs. `zcode` has no streaming flag: its
@@ -54,6 +69,14 @@ const CAPABILITY_FIELDS = new Set([
  */
 export function routeRuntime(contract, node, role = "worker", event = {}) {
   if (role !== "worker" && role !== "judge") throw new TypeError("route role must be worker or judge");
+  // Catalogue records entering a routing decision are validated here, the one
+  // boundary every runtime-routing reader shares; the copies persisted on node
+  // snapshots are validated where they are written.
+  if (event.availability) {
+    for (const [id, availability] of Object.entries(event.availability)) {
+      validateRuntimeAvailability(availability, `routing availability ${id}`);
+    }
+  }
   const initialRuntimeId = role === "judge"
     ? node.gate.runtime ?? contract.runtimeDefaults?.judge
     : node.runtime ?? contract.runtimeDefaults?.worker;
@@ -149,6 +172,31 @@ function validatePricing(value, label) {
     if (rate < 0) throw new TypeError(`${label}.${key} must not be negative`);
   }
 }
+/** The fields of one runtime-catalogue record (`RuntimeAvailability`). */
+const AVAILABILITY_FIELDS = new Set(["available", "exhaustedUntil", "reason", "observedAt", "window", "remaining"]);
+
+/**
+ * One runtime-catalogue record: what the harness de facto reported, and when.
+ * The three classified fields are required; the observables may be absent (a
+ * record that predates the field) or null (the harness exposes nothing -- never
+ * zero and never full allowance), but a present one must be typed: a record is
+ * persisted or read into a routing decision only through validators that can
+ * say what each datum means.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+export function validateRuntimeAvailability(value, label) {
+  assertObject(value, label);
+  rejectUnknown(value, AVAILABILITY_FIELDS, label);
+  if (typeof value.available !== "boolean") throw new TypeError(`${label}.available must be boolean`);
+  if (value.exhaustedUntil !== undefined && value.exhaustedUntil !== null) requireTimestamp(value.exhaustedUntil, `${label}.exhaustedUntil`);
+  requireString(value.reason, `${label}.reason`);
+  if (value.observedAt !== undefined && value.observedAt !== null) requireTimestamp(value.observedAt, `${label}.observedAt`);
+  if (value.window !== undefined && value.window !== null) requireString(value.window, `${label}.window`);
+  if (value.remaining !== undefined && value.remaining !== null) nonNegativeNumber(value.remaining, `${label}.remaining`);
+}
+
 /**
  * @param {Record<string, ValidatedRuntime>} runtimes
  * @param {string} runtimeId

package/src/contract/snapshot.mjs

@@ -127,7 +127,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   assertObject(value, "node snapshot");
   rejectUnknown(value, new Set([
     "schemaVersion", "contractVersion", "id", "type", "sourceIdentity", "packetHash", "status", "phase",
-    "attempt", "revisions", "judgeFailures", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
+    "attempt", "revisions", "judgeFailures", "requirementIds", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
     "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
   ]), "node snapshot");
@@ -139,6 +139,10 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   nonNegativeInteger(value.attempt, "node snapshot.attempt");
   nonNegativeInteger(value.revisions, "node snapshot.revisions");
   if (value.judgeFailures !== undefined) nonNegativeInteger(value.judgeFailures, "node snapshot.judgeFailures");
+  // The phase requirement ids the engine stamped onto the node when its result
+  // was accepted; optional on read so snapshots written before the stamp load
+  // unchanged.
+  if (value.requirementIds !== undefined) validateRequirementIdList(value.requirementIds, "node snapshot.requirementIds");
   // The review mode that governed the attempt's gate, recorded so a status
   // surface can tell an advisory finding from a below-threshold blocking one.
   if (value.review !== undefined && !REVIEW_MODES.has(/** @type {string} */ (value.review))) {
@@ -206,7 +210,7 @@ export function validateEvent(value) {
   assertObject(value, "event");
   rejectUnknown(value, new Set([
     "schemaVersion", "contractVersion", "at", "node", "from", "to", "type", "phase", "attempt", "runtime",
-    "role", "status", "currentRuntime", "errorCode", "error", "verdict", "summary", "revisions", "sourceIdentity", "packetHash", "override", "recovery", "invocationId", "unexpectedPaths", "unexpectedPathCount",
+    "role", "status", "currentRuntime", "errorCode", "error", "verdict", "summary", "revisions", "requirementIds", "sourceIdentity", "packetHash", "override", "recovery", "invocationId", "unexpectedPaths", "unexpectedPathCount",
   ]), "event");
   validateMetadata(value, "event");
   requireString(value.at, "event.at");
@@ -230,8 +234,23 @@ export function validateEvent(value) {
     }
   }
   if (value.unexpectedPathCount !== undefined) nonNegativeInteger(value.unexpectedPathCount, "event.unexpectedPathCount");
+  if (value.requirementIds !== undefined) validateRequirementIdList(value.requirementIds, "event.requirementIds");
   return /** @type {EventRecord} */ (value);
 }
+/**
+ * The requirement ids a node inherited from its phase, stamped by the engine
+ * and carried beside the result on both the snapshot and the transition event.
+ * Bounded like every persisted list: at most 64 ids of at most 128 bytes.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateRequirementIdList(value, label) {
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new TypeError(`${label} must be an array of at most 64 requirement ids`);
+  }
+  for (const [index, id] of value.entries()) boundedString(id, `${label}[${index}]`, 128);
+}
 /**
  * @param {unknown} value
  * @param {string} label

package/src/contract/verification.mjs

@@ -21,12 +21,28 @@ export const VERIFICATION_LIMITS = Object.freeze({
   snapshotPathBytes: 1024,
 });
 
+/**
+ * The declared risk tiers and the fraction of sampled mutants a suite must kill
+ * for a `mutation` verification entry to pass. The tier is what the entry
+ * declares; the fraction is not re-picked per entry, so two nodes at the same
+ * tier sit the same bar. The wall-clock budget that bounds how many mutants run
+ * at all is a measurement, not policy, and lives with the runner that enforces
+ * it (`MUTATION_TIME_BUDGET_MS`, `src/engine/mutation.mjs`).
+ */
+export const MUTATION_TIERS = Object.freeze({
+  high: 1,
+  medium: 0.75,
+  low: 0.5,
+});
+
+/** @typedef {keyof typeof MUTATION_TIERS} MutationTier */
+
 /** @typedef {"active"|"closed"|"failed"|"crashed"|"canceled"} VerificationAttemptStatus */
 
 /**
  * One declared deterministic check: an argv command run by the controller.
  *
- * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {threshold: number}}} VerificationCommand
+ * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {tier: MutationTier}}} VerificationCommand
  */
 
 /**
@@ -126,20 +142,20 @@ function validateVerificationCommand(command, label = "verification command") {
   const envBytes = env.reduce((sum, name) => sum + Buffer.byteLength(/** @type {string} */ (name), "utf8"), 0);
   if (envBytes > VERIFICATION_LIMITS.maxEnvBytes) throw new TypeError(`${label}.env exceeds aggregate byte limit`);
   // Mutation testing is opt-in per entry: it re-runs the same argv against
-  // deliberately broken copies of the node's written files. `threshold` is the
-  // fraction of mutants the suite must kill, so 0 accepts any suite and 1
-  // demands every sampled mutant fail it.
-  /** @type {{threshold: number}|undefined} */
+  // deliberately broken copies of the node's written files. The entry declares
+  // its risk tier; `MUTATION_TIERS` fixes the kill fraction each tier demands,
+  // so the bar is a property of the tier, not of the author's caution.
+  /** @type {{tier: MutationTier}|undefined} */
   let mutation;
   if (record.mutation !== undefined) {
     const rawMutation = record.mutation;
-    if (!rawMutation || typeof rawMutation !== "object" || Array.isArray(rawMutation)) throw new TypeError(`${label}.mutation must be an object with a threshold between 0 and 1`);
+    if (!rawMutation || typeof rawMutation !== "object" || Array.isArray(rawMutation)) throw new TypeError(`${label}.mutation must be an object with a declared risk tier`);
     const mutationRecord = /** @type {Record<string, unknown>} */ (rawMutation);
-    for (const key of Object.keys(mutationRecord)) if (key !== "threshold") throw new TypeError(`${label}.mutation has unexpected field ${key}`);
-    if (typeof mutationRecord.threshold !== "number" || !Number.isFinite(mutationRecord.threshold) || mutationRecord.threshold < 0 || mutationRecord.threshold > 1) {
-      throw new TypeError(`${label}.mutation.threshold must be a number between 0 and 1`);
+    for (const key of Object.keys(mutationRecord)) if (key !== "tier") throw new TypeError(`${label}.mutation has unexpected field ${key}`);
+    if (typeof mutationRecord.tier !== "string" || !Object.hasOwn(MUTATION_TIERS, mutationRecord.tier)) {
+      throw new TypeError(`${label}.mutation.tier must be one of ${Object.keys(MUTATION_TIERS).join(", ")}`);
     }
-    mutation = { threshold: mutationRecord.threshold };
+    mutation = { tier: /** @type {MutationTier} */ (mutationRecord.tier) };
   }
   /** @type {VerificationCommand} */
   const normalized = { argv: [.../** @type {string[]} */ (record.argv)], timeoutSec, repeat, env: [.../** @type {string[]} */ (env)] };

package/src/engine/assignment.mjs

@@ -20,9 +20,17 @@ import { transition } from "./state.mjs";
 /**
  * Resolve role assignments once at run creation. Discovery is used only for
  * omitted roles; the resulting pair is persisted so resume is deterministic.
+ * Alongside it, `decisions` records, for every assignment, the strategy that
+ * was applied and the reason for the choice: `declared` with the declaring
+ * field when the contract named the runtime -- an operator instruction
+ * prevails over every strategy -- or the discovery ranking that composed an
+ * omitted role. The record lives at this boundary, not on the persisted
+ * assignment entries, because the snapshot's routing.allowlist still carries
+ * the classified fields only (the same declared lag as the catalogue
+ * observables); it widens when a reader needs the record durably.
  *
  * @param {ValidatedContract} contract
- * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
+ * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, decisions: Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
  */
 export async function runtimeAssignments(contract) {
   const needsComposition = contract.nodes.some((node) =>
@@ -31,15 +39,34 @@ export async function runtimeAssignments(contract) {
   const availability = needsComposition ? await discoverRuntimes(contract.runtimes, { cwd: contract.cwd }) : {};
   const config = readUserConfig(process.env);
   const assignments = composeAssignments(contract, availability, { config });
+  /** @type {Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>} */
+  const decisions = {};
   return {
     assignments: Object.fromEntries(Object.entries(assignments).map(([nodeId, assignment]) => {
       const node = contract.nodes.find((candidate) => candidate.id === nodeId);
-      return [nodeId, {
-        ...assignment,
-        composedWorker: node?.runtime === undefined && contract.runtimeDefaults?.worker === undefined,
-        composedJudge: Boolean(node?.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined),
-      }];
+      const composedWorker = node?.runtime === undefined && contract.runtimeDefaults?.worker === undefined;
+      const composedJudge = Boolean(node?.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined);
+      // A judge the gate never asks for is no choice at all: no strategy
+      // decided it, so none is recorded.
+      const judgeSource = node?.gate.enabled && node.gate.runtime !== undefined
+        ? "gate runtime"
+        : contract.runtimeDefaults?.judge !== undefined ? "runtimeDefaults.judge" : null;
+      const workerSource = node?.runtime !== undefined
+        ? "node runtime"
+        : contract.runtimeDefaults?.worker !== undefined ? "runtimeDefaults.worker" : null;
+      decisions[nodeId] = {
+        worker: {
+          strategy: composedWorker ? "cost" : workerSource !== null ? "declared" : null,
+          reason: composedWorker ? "discovery: cheapest available runtime" : /** @type {string} */ (workerSource),
+        },
+        judge: {
+          strategy: composedJudge ? "priority" : judgeSource !== null ? "declared" : null,
+          reason: composedJudge ? "discovery: strongest available runtime" : /** @type {string} */ (judgeSource ?? "no judge required"),
+        },
+      };
+      return [nodeId, { ...assignment, composedWorker, composedJudge }];
     })),
+    decisions,
     availability,
   };
 }

package/src/engine/backoff.mjs

@@ -476,6 +476,12 @@ const MAX_ROUTING_HISTORY = 64;
 /**
  * The override reason recorded on the node, in the operator's words.
  *
+ * The reason also names the attempt-affinity outcome, because the override is
+ * the role's working assignment and the record of why it names the runtime it
+ * names: a reset holds affinity (the previous attempt's runtime stays warm
+ * for the retry), an edge yields it (the previous runtime is the one that
+ * just failed, and the reason quotes its code).
+ *
  * @param {Transition} schedule
  * @param {"worker"|"judge"} role
  * @param {string} current
@@ -484,10 +490,10 @@ const MAX_ROUTING_HISTORY = 64;
  */
 function routeReason(schedule, role, current, error) {
   if (schedule.kind === "reset" && schedule.reason === "quota_reset") {
-    return `${role} provider ${current} quota resets at ${schedule.at}: ${error.message}`;
+    return `${role} provider ${current} quota resets at ${schedule.at}: ${error.message}; attempt-affinity held: ${current} keeps the node's context for the retry`;
   }
-  if (schedule.kind === "reset") return `${role} provider ${current} hit a transient network failure, retrying at ${schedule.at}: ${error.message}`;
-  if (schedule.reason === "network_backoff") return `${role} provider ${current} kept failing on the network: ${error.message}`;
-  if (schedule.reason === "protocol_failure") return `${role} provider ${current} could not hold the result protocol: ${error.message}`;
-  return `${role} provider ${current} exhausted: ${error.message}`;
+  if (schedule.kind === "reset") return `${role} provider ${current} hit a transient network failure, retrying at ${schedule.at}: ${error.message}; attempt-affinity held: ${current} keeps the node's context for the retry`;
+  if (schedule.reason === "network_backoff") return `${role} provider ${current} kept failing on the network: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
+  if (schedule.reason === "protocol_failure") return `${role} provider ${current} could not hold the result protocol: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
+  return `${role} provider ${current} exhausted: ${error.message}; attempt-affinity yielded: ${current} reported ${error.code}`;
 }