faberun 0.6.0 → 0.8.0

package/src/cli/spec.mjs

@@ -0,0 +1,119 @@
+/**
+ * `spec` argv: validate and scaffold a spec document. Both operations are
+ * deterministic — `src/plan/spec.mjs` invokes no model — so this file only
+ * owns the wire, the same split every other verb module in this directory
+ * uses.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs as parseFlags } from "node:util";
+import { validateSpec } from "../plan/spec.mjs";
+
+/** @typedef {import("../plan/spec.mjs").SpecValidation} SpecValidation */
+
+/** Flags are scoped to the operation that declares them; all others are rejected. */
+/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+const OPERATION_OPTIONS = {
+  validate: { "strict-traceability": { type: "boolean" }, json: { type: "boolean" } },
+  scaffold: { id: { type: "string" } },
+};
+
+const SCAFFOLD_TEMPLATE = `---
+id: <id>
+title: "<title>"
+version: 1.0.0
+status: draft
+date: <yyyy-mm-dd>
+owner: <owner>
+target: <org/repo>
+baseline: <git sha>
+---
+
+# <title>
+
+## Intent
+
+<Why this work, what problem, what it unblocks.>
+
+## Requirements
+
+### R1. <title>
+
+- **statement:** <the testable claim>
+- **proof:** \`command: <shell command>\`
+
+## Non-goals
+
+- <what this spec explicitly excludes>
+`;
+
+/**
+ * @param {string[]} args
+ * @returns {void}
+ */
+export function specCli(args) {
+  const operation = args[0];
+  if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const target = parsed.positionals[0];
+  if (!target || parsed.positionals.length > 1) return usage();
+  const values = /** @type {{"strict-traceability"?: boolean, json?: boolean, id?: string}} */ (parsed.values);
+  if (operation === "validate") {
+    validateSpecFile(resolve(target), { strict: values["strict-traceability"] === true, json: values.json === true });
+    return;
+  }
+  try {
+    scaffoldSpec(resolve(target), typeof values.id === "string" ? values.id : undefined);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Validate a spec file and print its class, its overall verdict, and one
+ * line per finding. Exits `1` when the verdict is not `ok`.
+ *
+ * @param {string} path
+ * @param {{strict: boolean, json: boolean}} options
+ * @returns {SpecValidation}
+ */
+export function validateSpecFile(path, { strict, json }) {
+  const result = validateSpec(readFileSync(path, "utf8"), { cwd: process.cwd(), strict });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else {
+    process.stdout.write(`${result.class} · ${result.class === "legacy" ? "accepted" : result.ok ? "ok" : "not ok"}\n`);
+    for (const finding of result.findings) process.stdout.write(`[${finding.severity}] ${finding.rule}: ${finding.message}\n`);
+  }
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+/**
+ * Write an empty document in the spec format at `path`. Refuses to overwrite
+ * an existing file.
+ *
+ * @param {string} path
+ * @param {string} [id]
+ * @returns {void}
+ */
+export function scaffoldSpec(path, id) {
+  if (existsSync(path)) throw new Error(`refusing to overwrite an existing file: ${path}`);
+  writeFileSync(path, id ? SCAFFOLD_TEMPLATE.replace("<id>", id) : SCAFFOLD_TEMPLATE);
+  process.stdout.write(`scaffolded ${path}\n`);
+}
+
+/** @returns {void} */
+function usage() {
+  process.stderr.write("usage: faberun spec <validate|scaffold> <path> [--strict-traceability] [--json] [--id <value>]\n");
+  process.exitCode = 2;
+}
+
+export default OPERATION_OPTIONS;

package/src/cli.mjs

@@ -31,6 +31,7 @@ import { setupCommand } from "./cli/setup.mjs";
 import { skillsCli } from "./cli/skills.mjs";
 import { updateCommand } from "./cli/update.mjs";
 import { contractCli, validateContractFile } from "./cli/contract.mjs";
+import { specCli } from "./cli/spec.mjs";
 import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics.mjs";
 import { runContract } from "./engine/scheduler.mjs";
 import { resumeRun } from "./engine/resume.mjs";
@@ -87,7 +88,7 @@ export function hasDetachedBootstrapNonce() {
 }
 
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
-const COMMAND_OPTIONS = {
+export const COMMAND_OPTIONS = {
   run: { detach: { type: "boolean" }, "base-ref": { type: "string" } },
   resume: { detach: { type: "boolean" }, node: { type: "string" }, reconcile: { type: "string" }, answer: { type: "string" } },
   supervise: { detach: { type: "boolean" }, interval: { type: "string" } },
@@ -209,6 +210,7 @@ async function main(argv) {
   if (argv[0] === "seat") { seatCli(argv.slice(1)); return; }
   if (argv[0] === "skills") { skillsCli(argv.slice(1)); return; }
   if (argv[0] === "contract") { contractCli(argv.slice(1)); return; }
+  if (argv[0] === "spec") { specCli(argv.slice(1)); return; }
   const parsed = parseCli(argv);
   if (!parsed) { usage(); return; }
   const { command, values } = parsed;

package/src/contract/index.mjs

@@ -79,7 +79,7 @@ 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}} NodeSnapshot */
+/** @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 {{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 */

package/src/contract/snapshot.mjs

@@ -129,7 +129,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
     "schemaVersion", "contractVersion", "id", "type", "sourceIdentity", "packetHash", "status", "phase",
     "attempt", "revisions", "judgeFailures", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
-    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead",
+    "scopeFindings", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
   ]), "node snapshot");
   validateMetadata(value, "node snapshot");
   requireId(value.id, "node snapshot.id");
@@ -166,6 +166,12 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   validateSnapshotError(value.error, "node snapshot.error");
   if (value.usage !== undefined) validateUsage(value.usage, "node snapshot.usage");
   if (value.costUsd !== undefined) nonNegativeNumber(value.costUsd, "node snapshot.costUsd");
+  // The summed byte size of the node's declared readFiles in the attempt
+  // worktree at dispatch time -- the one quantity the controller can measure
+  // about a packet's reference load, since the worker reads the files itself.
+  if (value.declaredReadBytes !== undefined && value.declaredReadBytes !== null) {
+    nonNegativeInteger(value.declaredReadBytes, "node snapshot.declaredReadBytes");
+  }
   if (value.routing !== undefined && value.routing !== null) validateRoutingState(value.routing, "node snapshot.routing");
   if (value.progress !== undefined && value.progress !== null) validateProgressState(value.progress, "node snapshot.progress");
   if (value.worktree !== undefined && value.worktree !== null) validateWorktreeState(value.worktree, "node snapshot.worktree");

package/src/engine/dispatch.mjs

@@ -32,7 +32,7 @@ import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
 import { hasOperationIntent, hasOperationSettlement, operationNeedsRecovery, operationNextState, persistInvocationIntent, providerReceipts, settleInvocation } from "../run/operations.mjs";
 import { invocationCost, invocationUsage } from "../run/usage.mjs";
 import { logPaths, readBoundedTail, startProcess } from "./process.mjs";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import { READ_LINE_LIMIT, normalizeProviderResult, providerCommand } from "../harnesses/index.mjs";
 import { readJson, writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
@@ -267,6 +267,30 @@ function phaseHandoffPrompt(contract, node, state, runDir, role) {
   ].join("\n\n");
   return boundedUtf8(handoff, 60 * 1024);
 }
+/**
+ * The declared weight of a node's readFiles at dispatch time: the sum of the
+ * byte sizes of the files that exist in the attempt workspace. This is the
+ * one quantity the controller can measure about a packet's reference load --
+ * the worker prompt lists readFiles and the worker reads them itself, so what
+ * it actually reads is the harness's business. A missing file counts 0 rather
+ * than throwing: a declared path can be produced by a dependency that has not
+ * run yet or removed by the tree since the packet was authored.
+ *
+ * @param {string[]} readFiles
+ * @param {string} workspace
+ * @returns {number}
+ */
+export function declaredReadBytes(readFiles, workspace) {
+  let total = 0;
+  for (const path of readFiles) {
+    try {
+      total += statSync(join(workspace, path)).size;
+    } catch {
+      // Missing or unreadable file: contributes no weight.
+    }
+  }
+  return total;
+}
 /**
  * The mechanical worker tool policy for the provider boundary: hook settings
  * on Claude-compatible commands. Only an adapter whose surface can prove
@@ -431,6 +455,7 @@ export function startWorker(contract, node, state, runDir, running, prompt, lock
   writeJsonAtomic(snapshotPath, baseline);
   state.phase = "worker";
   state.runtime = runtime;
+  state.declaredReadBytes = declaredReadBytes(node.taskPacket.readFiles ?? [], workspace);
   // A new worker attempt has no accepted result yet. The canonical result
   // file is cleared when the previous attempt was explicitly rejected (failed
   // gate verdict), when no valid canonical file exists, or when the stale file

package/src/plan/freeze.mjs

@@ -0,0 +1,97 @@
+/**
+ * Freezing a plan: the boundary between a session's draft and a contract the
+ * engine can execute. `freezePlan` writes the plan's nodes as a validated
+ * contract.json, plus a plan.json carrying that contract's digest and the
+ * full provenance of how it was produced — the two files travel together so
+ * a later launch and this record agree on exactly what was reviewed.
+ * `verifyFrozenPlan` is the one check that the pair still agree.
+ *
+ * Nothing here invokes a model or the engine; it only writes and hashes
+ * bytes, so freezing a plan can never be mistaken for starting a run.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, contractDigest, validateContract } from "../contract/index.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+
+/** @typedef {{runtimeId: string, model: string}} PlanParticipant */
+/** @typedef {{id: string, severity: "minor"|"major"|"critical", nodeId?: string, text: string}} PlanFinding */
+/** @typedef {{targetGitHead: string|null, planner: PlanParticipant, reviewer: PlanParticipant, sizing: unknown, findings: PlanFinding[]}} PlanProvenanceInput */
+/** @typedef {PlanProvenanceInput & {packageVersion: string, schemaVersion: number, contractVersion: string}} PlanProvenance */
+/** @typedef {{formatVersion: number, contractDigest: string, provenance: PlanProvenance}} FrozenPlan */
+/** @typedef {{ok: boolean, digest: string, expectedDigest: string}} FrozenPlanVerdict */
+
+const PLAN_FORMAT_VERSION = 1;
+
+/** @returns {string} the installed package's own version, read once per call so a freeze always names the toolchain that produced it */
+function packageVersion() {
+  const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}
+
+/**
+ * Validate `plan` as a contract and, only once it is valid, write it and a
+ * sibling plan.json naming its digest and provenance. `plan` supplies
+ * `schemaVersion`/`contractVersion` itself; when it does not, this fills in
+ * the runner's own current values.
+ *
+ * contract.json is written before validation runs, because a packet may
+ * declare `readFiles: ["contract.json"]` — an execution packet's own file,
+ * self-referenced the same way every fixture in this codebase already does.
+ * A validation failure removes that file again, so a caller never observes a
+ * contract.json that failed its own check.
+ *
+ * @param {JsonObject} plan
+ * @param {{outDir: string, provenance: PlanProvenanceInput}} options
+ * @returns {FrozenPlan}
+ */
+export function freezePlan(plan, { outDir, provenance }) {
+  mkdirSync(outDir, { recursive: true });
+  const contractPath = join(outDir, "contract.json");
+  const raw = /** @type {JsonObject} */ ({
+    schemaVersion: PROTOCOL_SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    ...plan,
+  });
+  writeFileSync(contractPath, `${JSON.stringify(raw, null, 2)}\n`);
+  try {
+    validateContract(raw, contractPath);
+  } catch (error) {
+    rmSync(contractPath, { force: true });
+    throw error;
+  }
+  const frozen = /** @type {FrozenPlan} */ ({
+    formatVersion: PLAN_FORMAT_VERSION,
+    contractDigest: contractDigest(raw),
+    provenance: {
+      packageVersion: packageVersion(),
+      schemaVersion: /** @type {number} */ (raw.schemaVersion),
+      contractVersion: /** @type {string} */ (raw.contractVersion),
+      targetGitHead: provenance.targetGitHead,
+      planner: provenance.planner,
+      reviewer: provenance.reviewer,
+      sizing: provenance.sizing,
+      findings: provenance.findings,
+    },
+  });
+  writeFileSync(join(outDir, "plan.json"), `${JSON.stringify(frozen, null, 2)}\n`);
+  return frozen;
+}
+
+/**
+ * Recompute contract.json's digest from the bytes on disk and compare it
+ * with the digest plan.json recorded at freeze time. A single byte changed
+ * in either file — the contract re-authored after review, or the plan
+ * record itself tampered with — is a mismatch.
+ *
+ * @param {string} outDir
+ * @returns {FrozenPlanVerdict}
+ */
+export function verifyFrozenPlan(outDir) {
+  const raw = JSON.parse(readFileSync(join(outDir, "contract.json"), "utf8"));
+  const plan = JSON.parse(readFileSync(join(outDir, "plan.json"), "utf8"));
+  const digest = contractDigest(raw);
+  return { ok: digest === plan.contractDigest, digest, expectedDigest: plan.contractDigest };
+}

package/src/plan/repo-facts.mjs

@@ -0,0 +1,148 @@
+/**
+ * Repo facts: a deterministic, bounded inventory of the target repository —
+ * tracked paths, declared scripts, timed verification candidates, and which
+ * test file covers which source module — collected without invoking a model.
+ * A planning stage's draft is authored against exactly this JSON instead of
+ * the session reading the repository by hand.
+ *
+ * Sorting and the absence of any clock in the output itself (only inside an
+ * injected measurer's own numbers) is what makes two calls at the same HEAD
+ * byte-identical.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { timeVerificationCommands } from "../host/preflight.mjs";
+import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
+
+/** @typedef {{argv: string[], measuredMs: number, eligible: boolean}} VerificationCandidate */
+/** @typedef {{path: string, covers: string|null}} TestFileEntry */
+/** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], testFiles: TestFileEntry[]}} RepoFacts */
+/** @typedef {{now?: () => number, run?: typeof import("node:child_process").spawnSync}} MeasureProbes */
+
+const FORMAT_VERSION = 1;
+const DEFAULT_MAX_PATHS = 2000;
+const ELIGIBLE_MS_CEILING = 600_000;
+const CANDIDATE_TIMEOUT_SEC = ELIGIBLE_MS_CEILING / 1_000;
+
+/**
+ * Every path git tracks at HEAD, sorted. The bounded spawn is the same
+ * pattern `src/repo/source-identity.mjs` uses for its own git reads: a
+ * `boundedGitSync` call, thrown on a non-zero exit or a killed process,
+ * never a raw `spawnSync`.
+ *
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function listTrackedPaths(cwd) {
+  const result = boundedGitSync(["-C", cwd, "ls-files"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) throw result.error ?? new Error(`git ls-files exited ${result.status}`);
+  return String(result.stdout).split("\n").filter(Boolean).sort();
+}
+
+/** @param {string} cwd @returns {Record<string, string>} */
+function readScripts(cwd) {
+  const packagePath = join(cwd, "package.json");
+  if (!existsSync(packagePath)) return {};
+  const parsed = JSON.parse(readFileSync(packagePath, "utf8"));
+  return parsed.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {};
+}
+
+/**
+ * The first-level directories under test/ that any tracked path is nested
+ * inside. `node --test <dir>` recurses through everything below it, so one
+ * candidate per directory is the whole layout, not one per file.
+ *
+ * @param {string[]} paths
+ * @returns {string[]}
+ */
+function testDirectories(paths) {
+  /** @type {Set<string>} */
+  const directories = new Set();
+  for (const path of paths) {
+    const match = /^test\/([^/]+)\//u.exec(path);
+    if (match) directories.add(`test/${match[1]}`);
+  }
+  return [...directories].sort();
+}
+
+/**
+ * @param {string[]} paths
+ * @param {Set<string>} pathSet
+ * @returns {TestFileEntry[]}
+ */
+function testFileEntries(paths, pathSet) {
+  return paths
+    .filter((path) => path.startsWith("test/") && path.endsWith(".test.mjs"))
+    .map((path) => {
+      const modulePath = `src/${path.slice("test/".length, -".test.mjs".length)}.mjs`;
+      return { path, covers: pathSet.has(modulePath) ? modulePath : null };
+    });
+}
+
+/**
+ * @param {Record<string, string>} scripts
+ * @param {string[]} paths
+ * @returns {{argv: string[]}[]}
+ */
+function candidateCommands(scripts, paths) {
+  const commands = testDirectories(paths).map((directory) => ({ argv: ["node", "--test", directory] }));
+  for (const name of ["check", "typecheck"]) {
+    if (typeof scripts[name] === "string") commands.push({ argv: ["npm", "run", name] });
+  }
+  return commands;
+}
+
+/**
+ * Time every candidate through `timeVerificationCommands`'s own probe —
+ * real `spawnSync` and `Date.now` by default, or the caller's fake — instead
+ * of re-implementing the spawn, ceiling and ENOENT handling it already owns.
+ * That function calls `now()` exactly twice per command, in order (start,
+ * then stop); wrapping it to record every mark it produces is how the real
+ * elapsed ms is recovered without parsing its human-readable report.
+ *
+ * @param {string} cwd
+ * @param {{argv: string[]}[]} commands
+ * @param {MeasureProbes} probes
+ * @returns {VerificationCandidate[]}
+ */
+function measureCandidates(cwd, commands, probes) {
+  if (commands.length === 0) return [];
+  const now = probes.now ?? (() => Date.now());
+  /** @type {number[]} */
+  const marks = [];
+  const contract = /** @type {import("../contract/index.mjs").ValidatedContract} */ (/** @type {any} */ ({
+    cwd,
+    nodes: commands.map((command, index) => ({
+      id: `repo-facts-${index}`,
+      taskPacket: { verification: [{ argv: command.argv, timeoutSec: CANDIDATE_TIMEOUT_SEC }] },
+    })),
+  }));
+  timeVerificationCommands(contract, { ...probes, now: () => { const mark = now(); marks.push(mark); return mark; } });
+  return commands.map((command, index) => {
+    const measuredMs = marks[index * 2 + 1] - marks[index * 2];
+    return { argv: command.argv, measuredMs, eligible: measuredMs <= ELIGIBLE_MS_CEILING };
+  });
+}
+
+/**
+ * @param {string} cwd
+ * @param {{measure?: MeasureProbes, maxPaths?: number}} [options]
+ * @returns {RepoFacts}
+ */
+export function collectRepoFacts(cwd, options = {}) {
+  const maxPaths = options.maxPaths ?? DEFAULT_MAX_PATHS;
+  const allPaths = listTrackedPaths(cwd);
+  const pathSet = new Set(allPaths);
+  const scripts = readScripts(cwd);
+  const commands = candidateCommands(scripts, allPaths);
+  const truncated = allPaths.length > maxPaths;
+  return {
+    formatVersion: FORMAT_VERSION,
+    gitHead: gitHead(cwd),
+    paths: truncated ? allPaths.slice(0, maxPaths) : allPaths,
+    truncated,
+    scripts,
+    verificationCandidates: measureCandidates(cwd, commands, options.measure ?? {}),
+    testFiles: testFileEntries(allPaths, pathSet),
+  };
+}

package/src/plan/routing.mjs

@@ -0,0 +1,200 @@
+/**
+ * Declarative runtime routing: cross a taskKind/riskTier table with live
+ * discovery availability to assign a worker and a judge runtime to each of a
+ * plan's draft nodes. Separate from runtime-discovery.mjs because that module
+ * resolves a *contract's* already-declared runtimes; a plan's draft node
+ * never names one (the constitution reserves model choice to runtimes,
+ * runtimeDefaults, or an explicit node override) — this module is what turns
+ * a taskKind/riskTier classification into one of those three.
+ */
+
+import { cheapest, strongest } from "../engine/runtime-discovery.mjs";
+
+/** @typedef {{available: boolean, exhaustedUntil: string|null, [key: string]: unknown}} RoutingAvailability */
+/** @typedef {{vendor: string, tier?: number|string, costRank?: number, fallback?: string, [key: string]: unknown}} RoutingRuntime */
+/** @typedef {{id: string, taskKind?: string, riskTier?: string}} RoutingNode */
+/** @typedef {{taskKind?: string, riskTier?: string}} RoutingWhen */
+/** @typedef {{name?: string, when: RoutingWhen, prefer: string[], role: "worker"|"judge"}} RoutingRule */
+/** @typedef {{worker?: string, judge?: string}} RoutingRoleMap */
+/** @typedef {{table?: RoutingRule[], runtimes: Record<string, RoutingRuntime>, availability?: Record<string, RoutingAvailability>, runtimeDefaults?: RoutingRoleMap, overrides?: Record<string, RoutingRoleMap>}} RoutingConfig */
+/** @typedef {{worker: string|null, judge: string|null, rule: {worker: string, judge: string}}} RoutingAssignment */
+/** @typedef {{nodeId: string, role: "worker"|"judge", rule: string}} RoutingUnmet */
+/** @typedef {{assignments: Record<string, RoutingAssignment>, unmet: RoutingUnmet[]}} RoutingResult */
+
+/**
+ * @param {RoutingNode[]} nodes
+ * @param {RoutingConfig} config
+ * @param {{partial?: boolean}} [options]
+ * @returns {RoutingResult}
+ */
+export function resolveRuntimes(nodes, config, options = {}) {
+  const table = config.table ?? [];
+  const runtimes = config.runtimes ?? {};
+  const availability = config.availability ?? {};
+  const runtimeDefaults = config.runtimeDefaults ?? {};
+  const overrides = config.overrides ?? {};
+
+  /** @type {Record<string, RoutingAssignment>} */
+  const assignments = {};
+  /** @type {RoutingUnmet[]} */
+  const unmet = [];
+
+  for (const node of nodes) {
+    const override = overrides[node.id] ?? {};
+    const worker = resolveRole(node, "worker", { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors: EMPTY_VENDORS });
+    if (worker.runtimeId === null) unmet.push({ nodeId: node.id, role: "worker", rule: worker.rule });
+    // The judge's forbidden vendors follow the worker runtime that was
+    // actually chosen, never the row that named it — a worker unmet leaves
+    // nothing to conflict with, so the judge resolves without restriction.
+    const forbiddenVendors = worker.runtimeId ? forbiddenJudgeVendors(worker.runtimeId, runtimes) : EMPTY_VENDORS;
+    const judge = resolveRole(node, "judge", { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors });
+    if (judge.runtimeId === null) unmet.push({ nodeId: node.id, role: "judge", rule: judge.rule });
+    assignments[node.id] = { worker: worker.runtimeId, judge: judge.runtimeId, rule: { worker: worker.rule, judge: judge.rule } };
+  }
+
+  if (unmet.length && options.partial !== true) {
+    const detail = unmet.map(({ nodeId, role, rule }) => `${nodeId}.${role} (rule: ${rule})`).join("; ");
+    throw new Error(`runtime_routing_unmet: ${detail}`);
+  }
+
+  return { assignments, unmet };
+}
+
+/** @type {ReadonlySet<string>} */
+const EMPTY_VENDORS = Object.freeze(new Set());
+
+/**
+ * Precedence for one role on one node: an explicit node override, then the
+ * operator's runtimeDefaults, then the first table row whose `when` matches
+ * this node's classification, then plain discovery. A row or default that
+ * names an unavailable or vendor-forbidden runtime is unmet by that rule —
+ * it does not fall through to a lower-precedence source, since falling
+ * through would silently discard an explicit declaration; only the
+ * candidates *within* a row's `prefer` list, and within discovery, are
+ * skipped for exhaustion or vendor conflict.
+ *
+ * @param {RoutingNode} node
+ * @param {"worker"|"judge"} role
+ * @param {{runtimes: Record<string, RoutingRuntime>, availability: Record<string, RoutingAvailability>, runtimeDefaults: RoutingRoleMap, table: RoutingRule[], override: RoutingRoleMap, forbiddenVendors: ReadonlySet<string>}} context
+ * @returns {{runtimeId: string|null, rule: string}}
+ */
+function resolveRole(node, role, context) {
+  const { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors } = context;
+
+  if (override[role] !== undefined) {
+    const id = override[role];
+    return { runtimeId: admits(id, runtimes, availability, forbiddenVendors) ? id : null, rule: "override" };
+  }
+
+  if (runtimeDefaults[role] !== undefined) {
+    const id = runtimeDefaults[role];
+    return { runtimeId: admits(id, runtimes, availability, forbiddenVendors) ? id : null, rule: "runtimeDefaults" };
+  }
+
+  const row = table.find((candidate) => candidate.role === role
+    && (candidate.when.taskKind === undefined || candidate.when.taskKind === node.taskKind)
+    && (candidate.when.riskTier === undefined || candidate.when.riskTier === node.riskTier));
+  if (row) {
+    const rule = ruleLabel(row);
+    const id = row.prefer.find((candidate) => admits(candidate, runtimes, availability, forbiddenVendors)) ?? null;
+    return { runtimeId: id, rule };
+  }
+
+  const discovered = role === "worker"
+    ? cheapestAvailable(runtimes, availability, forbiddenVendors)
+    : strongestAvailable(runtimes, availability, forbiddenVendors);
+  return { runtimeId: discovered, rule: "discovery" };
+}
+
+/**
+ * @param {string} id
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {boolean}
+ */
+function admits(id, runtimes, availability, forbiddenVendors) {
+  const runtime = runtimes[id];
+  if (!runtime) return false;
+  if (forbiddenVendors.has(runtime.vendor)) return false;
+  return isAvailable(availability[id]);
+}
+
+/** @param {RoutingAvailability|undefined} entry @returns {boolean} */
+function isAvailable(entry) {
+  if (!entry) return false;
+  if (entry.available === true) return !entry.exhaustedUntil || Date.parse(entry.exhaustedUntil) <= Date.now();
+  return Boolean(entry.exhaustedUntil && Date.parse(entry.exhaustedUntil) <= Date.now());
+}
+
+/**
+ * Every vendor a judge may not carry: the worker's own vendor, plus the
+ * vendor of each runtime reachable through the worker's declared `fallback`
+ * chain — the same independence the contract validator enforces statically
+ * once a worker is actually chosen dynamically here.
+ *
+ * @param {string} workerId
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @returns {Set<string>}
+ */
+function forbiddenJudgeVendors(workerId, runtimes) {
+  const vendors = new Set();
+  const seen = new Set();
+  /** @type {string|undefined} */
+  let id = workerId;
+  while (id !== undefined && runtimes[id] && !seen.has(id)) {
+    seen.add(id);
+    vendors.add(runtimes[id].vendor);
+    id = runtimes[id].fallback;
+  }
+  return vendors;
+}
+
+/** @param {RoutingRule} row @returns {string} */
+function ruleLabel(row) {
+  if (row.name) return row.name;
+  return `table:${row.role}:${row.when.taskKind ?? "*"}:${row.when.riskTier ?? "*"}`;
+}
+
+/**
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {{id: string, runtime: RoutingRuntime, order: number}[]}
+ */
+function candidateEntries(runtimes, availability, forbiddenVendors) {
+  return Object.entries(runtimes)
+    .map(([id, runtime], order) => ({ id, runtime, order }))
+    .filter(({ id, runtime }) => !forbiddenVendors.has(runtime.vendor) && isAvailable(availability[id]));
+}
+
+/**
+ * The plain discovery default for a worker: `runtime-discovery.mjs`'s own
+ * cheapest-first ranking, over candidates already filtered to what's
+ * available and vendor-permitted here. The ranking lives there, not here, so
+ * a contract's default and a plan's routed default never drift apart.
+ *
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {string|null}
+ */
+function cheapestAvailable(runtimes, availability, forbiddenVendors) {
+  return cheapest(candidateEntries(runtimes, availability, forbiddenVendors))?.id ?? null;
+}
+
+/**
+ * The plain discovery default for a judge: `runtime-discovery.mjs`'s own
+ * strongest-first ranking, over candidates already filtered to exclude the
+ * worker's vendor and fallback-chain vendors — `strongest`'s own single-vendor
+ * exclusion is passed the empty string, no runtime's actual vendor label, so
+ * it is a no-op on top of the filtering already done here.
+ *
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {string|null}
+ */
+function strongestAvailable(runtimes, availability, forbiddenVendors) {
+  return strongest(candidateEntries(runtimes, availability, forbiddenVendors), "")?.id ?? null;
+}