faberun 0.3.0

package/src/contract/verification.mjs

@@ -0,0 +1,185 @@
+import { Buffer } from "node:buffer";
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { fail, isContained, tailText } from "../util.mjs";
+
+export const VERIFICATION_LIMITS = Object.freeze({
+  stdoutBytes: 16 * 1024,
+  stderrBytes: 16 * 1024,
+  maxCommands: 32,
+  maxRepeat: 8,
+  maxTimeoutSec: 600,
+  stateStdoutBytes: 2 * 1024,
+  stateCommands: 16,
+  stateAttempts: 4,
+  stateAttemptRecords: 16,
+  stateArgvBytes: 8 * 1024,
+  stateEnvBytes: 4 * 1024,
+  maxArgvBytes: 32 * 1024,
+  maxEnvBytes: 8 * 1024,
+  snapshotEntries: 4096,
+  snapshotPathBytes: 1024,
+});
+
+/** @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
+ */
+
+/**
+ * A single attempt of a verification command.
+ *
+ * @typedef {{attempt: number, invocationId: string, commandIndex: number, pid: number|null, processStartToken: string|null, processGroupId: number|null, startedAt: string, deadlineAt: string, status: VerificationAttemptStatus, completedAt?: string|null, result?: VerificationAttemptResult|null}} VerificationAttempt
+ */
+
+/**
+ * Bounded evidence captured for one attempt.
+ *
+ * @typedef {{passed: boolean, stdout: string, stderr: string, error: string|null, exitCode: number|null, signal: string|null, timedOut: boolean, durationMs: number|null}} VerificationAttemptResult
+ */
+
+/**
+ * A command with its repeated attempts.
+ *
+ * @typedef {VerificationCommand & {passed: boolean, attempts: VerificationAttemptResult[]}} VerificationCommandResult
+ */
+
+/**
+ * Aggregated verification result.
+ *
+ * @typedef {{passed: boolean, commands: VerificationCommandResult[]}} VerificationResult
+ */
+
+/**
+ * Callbacks and options for {@link runVerification}.
+ *
+ * @typedef {{signal?: AbortSignal, logDir?: string, writeFiles?: string[], onAttemptStart?: (attempt: VerificationAttempt) => void, onAttemptSpawn?: (attempt: VerificationAttempt) => void, onAttemptComplete?: (attempt: VerificationAttempt) => void}} VerificationOptions
+ */
+
+/**
+ * @param {unknown} cwd
+ * @param {string} label
+ */
+function validateRelativeCwd(cwd, label) {
+  if (typeof cwd !== "string" || isAbsolute(cwd) || /^[A-Za-z]:[\\/]/u.test(cwd) || /(?:^|[\\/])\.\.(?:[\\/]|$)/u.test(cwd)) {
+    throw fail("verification_cwd_invalid", `${label}.cwd must be a relative path without ..`);
+  }
+}
+
+/**
+ * @param {string} baseCwd
+ * @param {string} commandCwd
+ * @returns {string}
+ */
+export function resolveVerificationCwd(baseCwd, commandCwd = ".") {
+  validateRelativeCwd(commandCwd, "verification command");
+  const baseReal = realpathSync(baseCwd);
+  const candidate = resolve(baseReal, commandCwd);
+  const targetReal = realpathSync(candidate);
+  if (!isContained(baseReal, targetReal)) {
+    throw fail("verification_cwd_escape", `verification cwd escapes workspace: ${commandCwd}`);
+  }
+  if (!statSync(targetReal).isDirectory()) throw fail("verification_cwd_invalid", `verification cwd is not a directory: ${commandCwd}`);
+  return targetReal;
+}
+
+/**
+ * @param {unknown} commands
+ * @param {string} label
+ * @returns {VerificationCommand[]}
+ */
+export function validateVerificationCommands(commands, label = "verification") {
+  if (!Array.isArray(commands) || commands.length > VERIFICATION_LIMITS.maxCommands) {
+    throw new TypeError(`${label} must be an array of at most ${VERIFICATION_LIMITS.maxCommands} command objects`);
+  }
+  return commands.map((command, index) => validateVerificationCommand(command, `${label}[${index}]`));
+}
+
+/**
+ * @param {unknown} command
+ * @param {string} label
+ * @returns {VerificationCommand}
+ */
+function validateVerificationCommand(command, label = "verification command") {
+  if (!command || typeof command !== "object" || Array.isArray(command)) throw new TypeError(`${label} must be an argv command object`);
+  const record = /** @type {Record<string, unknown>} */ (command);
+  const allowed = new Set(["argv", "cwd", "timeoutSec", "repeat", "env", "mutation"]);
+  for (const key of Object.keys(record)) if (!allowed.has(key)) throw new TypeError(`${label} has unexpected field ${key}`);
+  if (!Array.isArray(record.argv) || record.argv.length === 0 || record.argv.length > 64 || record.argv.some((item) => typeof item !== "string" || !item.trim() || Buffer.byteLength(item, "utf8") > 8 * 1024)) {
+    throw new TypeError(`${label}.argv must be a non-empty array of strings`);
+  }
+  const argvBytes = record.argv.reduce((sum, item) => sum + Buffer.byteLength(/** @type {string} */ (item), "utf8"), 0);
+  if (argvBytes > VERIFICATION_LIMITS.maxArgvBytes) throw new TypeError(`${label}.argv exceeds aggregate byte limit`);
+  if (record.cwd !== undefined) validateRelativeCwd(record.cwd, label);
+  const timeoutSec = record.timeoutSec === undefined ? 120 : record.timeoutSec;
+  if (typeof timeoutSec !== "number" || !Number.isFinite(timeoutSec) || timeoutSec <= 0 || timeoutSec > VERIFICATION_LIMITS.maxTimeoutSec) throw new TypeError(`${label}.timeoutSec must be between 0 and ${VERIFICATION_LIMITS.maxTimeoutSec}`);
+  // Default single attempt: the worker already ran these commands inside its
+  // session and the controller run is the independent confirmation; repeating
+  // by default doubled suite cost for no extra signal.
+  const repeat = record.repeat === undefined ? 1 : record.repeat;
+  if (typeof repeat !== "number" || !Number.isInteger(repeat) || repeat <= 0 || repeat > VERIFICATION_LIMITS.maxRepeat) throw new TypeError(`${label}.repeat must be between 1 and ${VERIFICATION_LIMITS.maxRepeat}`);
+  const env = record.env ?? [];
+  if (!Array.isArray(env) || env.some((name) => typeof name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name))) throw new TypeError(`${label}.env must be an array of environment-variable names`);
+  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} */
+  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`);
+    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`);
+    }
+    mutation = { threshold: mutationRecord.threshold };
+  }
+  /** @type {VerificationCommand} */
+  const normalized = { argv: [.../** @type {string[]} */ (record.argv)], timeoutSec, repeat, env: [.../** @type {string[]} */ (env)] };
+  if (record.cwd !== undefined) normalized.cwd = /** @type {string} */ (record.cwd);
+  if (mutation !== undefined) normalized.mutation = mutation;
+  return normalized;
+}
+
+/**
+ * Bound a verification result for persisted node state.
+ *
+ * @param {VerificationResult|undefined} result
+ * @returns {VerificationResult}
+ */
+export function compactVerification(result) {
+  /** @type {VerificationCommandResult[]} */
+  const commands = [];
+  let argvBytes = 0;
+  let envBytes = 0;
+  for (const command of result?.commands ?? []) {
+    if (commands.length >= VERIFICATION_LIMITS.stateCommands) break;
+    const nextArgvBytes = argvBytes + command.argv.reduce((sum, item) => sum + Buffer.byteLength(String(item), "utf8"), 0);
+    const nextEnvBytes = envBytes + (command.env ?? []).reduce((sum, item) => sum + Buffer.byteLength(String(item), "utf8"), 0);
+    if (nextArgvBytes > VERIFICATION_LIMITS.stateArgvBytes || nextEnvBytes > VERIFICATION_LIMITS.stateEnvBytes) break;
+    argvBytes = nextArgvBytes;
+    envBytes = nextEnvBytes;
+    commands.push({
+      argv: command.argv,
+      cwd: command.cwd,
+      timeoutSec: command.timeoutSec,
+      repeat: command.repeat,
+      env: command.env,
+      passed: Boolean(command.passed),
+      attempts: (command.attempts ?? []).slice(0, VERIFICATION_LIMITS.stateAttempts).map((attempt) => ({
+        ...attempt,
+        stdout: tailText(attempt.stdout, VERIFICATION_LIMITS.stateStdoutBytes),
+        stderr: tailText(attempt.stderr, VERIFICATION_LIMITS.stateStdoutBytes),
+      })),
+    });
+  }
+  return { passed: Boolean(result?.passed), commands };
+}
+

package/src/contract/worker-result.mjs

@@ -0,0 +1,138 @@
+import { Buffer } from "node:buffer";
+import { validateTaskPacket } from "./task-packet.mjs";
+import { requireText } from "./assert.mjs";
+
+const RESULT_LIMITS = Object.freeze({
+  bytes: 32 * 1024,
+  summaryBytes: 4 * 1024,
+  arrayItems: 32,
+  itemBytes: 2 * 1024,
+  artifactBytes: 16 * 1024,
+  missingContextItems: 16,
+});
+
+/**
+ * Worker-result fields the controller measures and derives itself, so the
+ * worker protocol has no owner for them. A result that declares one is
+ * rejected, never dropped: a field accepted after it lost its owner is how it
+ * comes back in the next prompt generation. The PRD's remaining derived fields
+ * -- commit, digest, worktreeIdentity, durationMs, exitCode -- enter this one
+ * list as their nodes land, so rejection stays a single edit.
+ */
+export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
+
+/** @typedef {"done"|"blocked_context"} WorkerResultStatus */
+
+/**
+ * The worker-result protocol: exactly one JSON object returned as the only
+ * content of the final worker message. `blocked_context` requires at least one
+ * missingContext entry; `done` requires none.
+ *
+ * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[]}} WorkerResult
+ */
+
+/**
+ * @param {string} value
+ * @returns {WorkerResult}
+ */
+export function parseWorkerResult(value) {
+  if (typeof value !== "string") throw new TypeError("worker result must be JSON text");
+  if (Buffer.byteLength(value, "utf8") > RESULT_LIMITS.bytes) {
+    throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new TypeError(`worker result is invalid JSON: ${(error instanceof Error ? error.message : String(error))}`);
+  }
+  return validateWorkerResult(parsed);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {WorkerResult}
+ */
+export function validateWorkerResult(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("worker result must be an object");
+  }
+  // Worker output is an external LLM boundary: models add fields beyond the
+  // protocol. Unknown provider extras are dropped (the normalized pick below
+  // keeps only canonical fields), but a field the controller derives is a
+  // protocol failure: silently dropping it is how the worker learns to keep
+  // sending it. Missing or invalid canonical fields stay fatal too.
+  const record = /** @type {Record<string, unknown>} */ (value);
+  for (const field of DERIVED_WORKER_RESULT_FIELDS) {
+    if (Object.hasOwn(record, field)) {
+      throw new TypeError(`worker result.${field} is derived by the controller and must not be declared`);
+    }
+  }
+  const expected = new Set(["status", "summary", "verification", "artifacts", "missingContext"]);
+  for (const key of expected) {
+    if (!Object.hasOwn(record, key)) throw new TypeError(`worker result.${key} is required`);
+  }
+  if (record.status !== "done" && record.status !== "blocked_context") {
+    throw new TypeError("worker result.status must be done or blocked_context");
+  }
+  requireText(record.summary, "worker result.summary", RESULT_LIMITS.summaryBytes);
+  requireList(record.verification, "worker result.verification", RESULT_LIMITS.arrayItems, RESULT_LIMITS.itemBytes);
+  requireList(record.artifacts, "worker result.artifacts", RESULT_LIMITS.arrayItems, RESULT_LIMITS.artifactBytes);
+  requireList(record.missingContext, "worker result.missingContext", RESULT_LIMITS.missingContextItems, RESULT_LIMITS.itemBytes);
+  const missingContext = /** @type {string[]} */ (record.missingContext);
+  if (record.status === "blocked_context" && missingContext.length === 0) {
+    throw new TypeError("worker result.missingContext must not be empty for blocked_context");
+  }
+  if (record.status === "done" && missingContext.length > 0) {
+    throw new TypeError("worker result.missingContext must be empty for done");
+  }
+  const normalized = {
+    status: /** @type {WorkerResultStatus} */ (record.status),
+    summary: /** @type {string} */ (record.summary),
+    verification: [.../** @type {string[]} */ (record.verification)],
+    artifacts: [.../** @type {string[]} */ (record.artifacts)],
+    missingContext: [...missingContext],
+  };
+  if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > RESULT_LIMITS.bytes) {
+    throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
+  }
+  return normalized;
+}
+
+/**
+ * @param {string|WorkerResult} value
+ * @param {string} cwd
+ * @returns {WorkerResult & {discoveryPacket: import("./task-packet.mjs").TaskPacket}}
+ */
+export function parseDiscoveryResult(value, cwd) {
+  const result = typeof value === "string" ? parseWorkerResult(value) : validateWorkerResult(value);
+  if (result.status !== "done") throw new TypeError("discovery result must have status done");
+  if (result.artifacts.length !== 1) throw new TypeError("discovery result must contain exactly one task packet artifact");
+  let packet;
+  try {
+    packet = JSON.parse(result.artifacts[0]);
+  } catch (error) {
+    throw new TypeError(`discovery task packet artifact is invalid JSON: ${(error instanceof Error ? error.message : String(error))}`);
+  }
+  validateTaskPacket(packet, 0, cwd);
+  if (packet.mode !== "execution") throw new TypeError("discovery task packet artifact must be execution mode");
+  const normalized = { ...result };
+  Object.defineProperty(normalized, "discoveryPacket", { value: packet, enumerable: false });
+  return /** @type {WorkerResult & {discoveryPacket: import("./task-packet.mjs").TaskPacket}} */ (
+    /** @type {unknown} */ (normalized)
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} maxItems
+ * @param {number} itemBytes
+ */
+function requireList(value, label, maxItems, itemBytes) {
+  if (!Array.isArray(value) || value.length > maxItems) throw new TypeError(`${label} must be an array with at most ${maxItems} items`);
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string") throw new TypeError(`${label}[${index}] must be a string`);
+    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new TypeError(`${label}[${index}] exceeds ${itemBytes} bytes`);
+  }
+}

package/src/engine/assignment.mjs

@@ -0,0 +1,63 @@
+/**
+ * Who runs a node, and what a failed dependency costs its dependants.
+ *
+ * `runtimeAssignments` composes the worker/judge pair only for the roles a
+ * contract left open, from the runtimes available right now -- which is why it
+ * is called on a fresh run *and* on a resume, and why it lives in neither.
+ * `blockDependents` walks the DAG forward from a terminal failure so a node
+ * whose dependency died never dispatches at all.
+ */
+import { PARKED } from "./prompts.mjs";
+import { composeAssignments, discoverRuntimes } from "./runtime-discovery.mjs";
+import { readUserConfig } from "../host/config.mjs";
+import { transition } from "./state.mjs";
+
+/** @typedef {import("../cli.mjs").LockHandle} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("./runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+
+/**
+ * Resolve role assignments once at run creation. Discovery is used only for
+ * omitted roles; the resulting pair is persisted so resume is deterministic.
+ *
+ * @param {ValidatedContract} contract
+ * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
+ */
+export async function runtimeAssignments(contract) {
+  const needsComposition = contract.nodes.some((node) =>
+    (node.runtime === undefined && contract.runtimeDefaults?.worker === undefined)
+    || (node.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined));
+  const availability = needsComposition ? await discoverRuntimes(contract.runtimes, { cwd: contract.cwd }) : {};
+  const config = readUserConfig(process.env);
+  const assignments = composeAssignments(contract, availability, { config });
+  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),
+      }];
+    })),
+    availability,
+  };
+}
+/**
+ * @param {ValidatedContract} contract
+ * @param {string} runDir
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {LockHandle} lock
+ */
+export function blockDependents(contract, runDir, states, lock) {
+  for (const node of contract.nodes) {
+    const state = states.get(node.id);
+    if (!state) continue;
+    if (state.status !== "pending") continue;
+    // Only a parent that has parked blocks its dependants. A parent whose
+    // automatic retry is still unspent is re-opened to `pending` before this
+    // runs, so the dependants stay `pending`/`phase: "waiting"` until it parks.
+    const blockedBy = node.dependsOn.filter((id) => PARKED.has(states.get(id)?.status ?? ""));
+    if (blockedBy.length) transition(runDir, state, "blocked", { phase: "dependency", blockedBy, error: { code: "dependency_failed", message: `blocked by ${blockedBy.join(", ")}` } }, lock);
+  }
+}