@staix/agent-research 0.0.0-stage → 0.1.0

package/src/paper/placeholders.ts

@@ -0,0 +1,116 @@
+import { join, relative } from "node:path";
+import { openStudy, plain, readLedger, readTextBounded, sha256 } from "../study.ts";
+import { ATTEMPT_BYTES, listAttempts, type Attempt, type AttemptStatus } from "../exp/attempts.ts";
+import { protocolHash, readProtocol } from "../exp/protocol.ts";
+import { INVESTIGATE_BYTES, investigateResultPath, metricValue, readClosedInvestigation } from "../exp/investigate.ts";
+import { ABLATE_BYTES, ablateResultPath, readClosedAblate } from "../exp/ablate.ts";
+import { FINAL_RESULT_BYTES, finalResultPath, readClosedFinal, requirePosthocClosed } from "../exp/final.ts";
+
+export const MANUSCRIPT_BYTES = 2 * 1024 * 1024, MAX_PLACEHOLDERS = 5000;
+interface Position { start: number; end: number; line: number; column: number; raw: string }
+export type Placeholder = Position & ({ kind: "number"; ref: string; format?: number } | { kind: "literal"; text: string });
+export interface PlaceholderFinding extends Position { code: "bad-format" | "unresolved-ref"; message: string }
+export interface ResolvedPlaceholder { placeholder: Placeholder; value: number | string; rendered: string; source?: { file: string; sha256: string } }
+/** Offsets are UTF-16 string indices; line and column are 1-based, as used by the Markdown checker. */
+export function parsePlaceholders(text: string): { placeholders: Placeholder[]; findings: PlaceholderFinding[] } {
+  if (Buffer.byteLength(text) > MANUSCRIPT_BYTES) throw new Error("paper manuscript: larger than 2 MiB; shorten paper/manuscript.md before checking or building");
+  const placeholders: Placeholder[] = [], findings: PlaceholderFinding[] = [];
+  const opening = /{{(?:n|lit):/g;
+  let match: RegExpExecArray | null, count = 0, scanned = 0, line = 1, column = 1;
+  while ((match = opening.exec(text))) {
+    const start = match.index, closing = text.indexOf("}}", opening.lastIndex), end = closing < 0 ? text.length : closing + 2;
+    while (scanned < start) { if (text[scanned++] === "\n") { line++; column = 1; } else column++; }
+    const at: Position = { start, end, line, column, raw: text.slice(start, end) };
+    if (++count > MAX_PLACEHOLDERS) { findings.push({ ...at, code: "bad-format", message: "paper placeholders: more than 5000; reduce the number of n/lit placeholders before building" }); break; }
+    const body = text.slice(opening.lastIndex, closing < 0 ? text.length : closing);
+    if (closing < 0 || body.includes("{{") || body.includes("}}")) {
+      findings.push({ ...at, code: "bad-format", message: "placeholder: missing closing braces or nested placeholder; use {{n:REF[|.Nf]}} or {{lit:TEXT}}" });
+      opening.lastIndex = end; continue;
+    }
+    opening.lastIndex = end;
+    if (match[0] === "{{lit:") {
+      if (!body.length) findings.push({ ...at, code: "bad-format", message: "literal placeholder: empty TEXT; supply the literal text for reviewer inspection" });
+      else placeholders.push({ ...at, kind: "literal", text: body });
+      continue;
+    }
+    // ponytail: metric names containing | or } cannot be represented by this grammar; rename them in a new protocol.
+    const parsed = /^([^{}|]+)(?:\|\.([0-6])f)?$/.exec(body);
+    if (!parsed || (/\s/.test(parsed[1]!) && !/^(attempt|posthoc):[a-f0-9]{16}\..+$/s.test(parsed[1]!))) findings.push({ ...at, code: "bad-format", message: "number placeholder: invalid ref or format; use {{n:REF}} or {{n:REF|.Nf}} with N from 0 to 6" });
+    else placeholders.push({ ...at, kind: "number", ref: parsed[1]!, ...(parsed[2] === undefined ? {} : { format: Number(parsed[2]) }) });
+  }
+  return { placeholders, findings };
+}
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (plain(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+interface Source<T> { value: T; source: { file: string; sha256: string } }
+function source<T>(dir: string, file: string, bound: number, value: T, expected?: string): Source<T> {
+  const text = readTextBounded(file, bound), hash = sha256(text);
+  if (expected === undefined && canonical(JSON.parse(text)) !== canonical(value)) throw new Error("source value changed during resolution");
+  if (expected !== undefined && hash !== expected) throw new Error("source bytes changed during resolution");
+  return { value, source: { file: relative(dir, file), sha256: hash } };
+}
+const statuses: readonly string[] = ["running", "succeeded", "failed", "cancelled", "unknown"];
+function validValue(value: unknown): value is string | number { return typeof value === "string" ? value.length > 0 : typeof value === "number" && Number.isFinite(value); }
+/** A per-call cache keeps repeated placeholders tied to the same checked source bytes. No writes, network or process execution. */
+export function resolvePlaceholders(dirArg: string, text: string) {
+  const { dir, study } = openStudy(dirArg), parsed = parsePlaceholders(text), findings = [...parsed.findings], resolved: ResolvedPlaceholder[] = [], literals: Placeholder[] = [];
+  const cache = new Map<string, Source<unknown> | Error>();
+  const cached = <T>(key: string, read: () => Source<T>): Source<T> => {
+    if (!cache.has(key)) { try { cache.set(key, read()); } catch { cache.set(key, new Error("absent, unclosed, stale or invalid source")); } }
+    const value = cache.get(key)!; if (value instanceof Error) throw value; return value as Source<T>;
+  };
+  const investigate = () => cached("investigate", () => { const closed = readClosedInvestigation(dir); return source(dir, investigateResultPath(dir, closed.result.run), INVESTIGATE_BYTES, closed.result, closed.sha256); });
+  const ablate = () => cached("ablate", () => { const closed = readClosedAblate(dir); return source(dir, ablateResultPath(dir), ABLATE_BYTES, closed.result, closed.sha256); });
+  const final = () => cached("final", () => { const closed = readClosedFinal(dir); return source(dir, finalResultPath(dir), FINAL_RESULT_BYTES, closed.result, closed.sha256); });
+  let attemptIndex: Map<string, Attempt[]> | undefined;
+  const attempt = (id: string, posthoc: boolean): Source<Attempt> => cached(`attempt:${id}:${posthoc}`, () => {
+    if (!attemptIndex) {
+      attemptIndex = new Map();
+      for (const record of listAttempts(dir).attempts) { const same = attemptIndex.get(record.id) ?? []; same.push(record); attemptIndex.set(record.id, same); }
+    }
+    const found = attemptIndex.get(id) ?? [];
+    if (found.length !== 1) throw new Error("attempt missing or ambiguous");
+    const a = found[0]!, protocol = readProtocol(dir);
+    if (posthoc) requirePosthocClosed(dir);
+    if (a.studyId !== study.id || a.status !== "succeeded" || !protocol || a.protocolHash !== protocolHash(protocol) || a.protocolHash !== protocolHash(a.protocol) || (a.run === "posthoc") !== posthoc) throw new Error("attempt is not a current completed metric source");
+    if (!readLedger(dir).some(e => e.type === "attempt.started" && e.data.id === a.id && e.data.run === a.run && e.data.commit === a.commit && e.data.seed === a.seed)) throw new Error("attempt start receipt missing");
+    return source(dir, join(dir, "runs", a.run, "attempts", `${a.id}.json`), ATTEMPT_BYTES, a);
+  });
+  for (const placeholder of parsed.placeholders) {
+    if (placeholder.kind === "literal") { literals.push(placeholder); resolved.push({ placeholder, value: placeholder.text, rendered: placeholder.text }); continue; }
+    const ref = placeholder.ref;
+    try {
+      if (study.mode !== "experiment") throw new Error("experiment refs unavailable in survey");
+      let value: unknown, provenance: Source<unknown>, exploratory = false;
+      let match: RegExpExecArray | null;
+      if ((match = /^final\.(status|reason|delta|mean|baselineMean)$/.exec(ref))) { const read = final(); provenance = read; value = read.value[match[1] as "status"]; }
+      else if ((match = /^final\.attempts\.([a-z]+)$/.exec(ref)) && statuses.includes(match[1]!)) { const read = final(); provenance = read; value = read.value.attempts.filter(a => a.status === match![1]).length; }
+      else if ((match = /^investigate\.(winner|reason)$/.exec(ref))) { const read = investigate(); provenance = read; value = match[1] === "winner" ? read.value.winner?.commit.slice(0, 12) : read.value.reason; }
+      else if ((match = /^investigate\.winner\.(delta|mean)$/.exec(ref))) { const read = investigate(); provenance = read; value = read.value.winner?.[match[1] as "delta"]; }
+      else if (ref === "investigate.baseline.mean") { const read = investigate(); provenance = read; value = read.value.baseline.mean; }
+      else if ((match = /^(investigate|ablate)\.totals\.([a-z]+)$/.exec(ref)) && statuses.includes(match[2]!)) { const read = match[1] === "investigate" ? investigate() : ablate(); provenance = read; value = read.value.totals.byStatus[match[2] as AttemptStatus]; }
+      else if ((match = /^ablate:([A-Za-z0-9][A-Za-z0-9_-]{0,63})\.(delta|mean|referenceMean)$/.exec(ref))) { const read = ablate(); provenance = read; value = read.value.ablations.find(a => a.id === match![1])?.paired[match[2] as "delta"]; }
+      else if ((match = /^(attempt|posthoc):([a-f0-9]{16})\.(.+)$/.exec(ref))) {
+        exploratory = match[1] === "posthoc"; const read = attempt(match[2]!, exploratory); provenance = read;
+        const metric = read.value.protocol.metrics?.find(m => m.name === match![3]);
+        if (!metric) throw new Error("metric undeclared"); value = metricValue(read.value, metric);
+      } else throw new Error("unknown reference");
+      if (!validValue(value)) throw new Error("value unavailable or non-finite");
+      if (typeof value === "string" && placeholder.format !== undefined) {
+        findings.push({ ...placeholder, code: "bad-format", message: `placeholder ${ref}: text refs take no numeric format; remove |.Nf` }); continue;
+      }
+      const rendered = (typeof value === "number" && placeholder.format !== undefined ? value.toFixed(placeholder.format) : String(value)) + (exploratory ? " (exploratory)" : "");
+      resolved.push({ placeholder, value, rendered, source: provenance.source });
+    } catch {
+      findings.push({ ...placeholder, code: "unresolved-ref", message: `placeholder ${ref}: unknown ref or absent, unclosed, stale or invalid source; inspect the attempt and close the current phase results before retrying` });
+    }
+  }
+  const replacements = new Map(resolved.map(entry => [entry.placeholder.start, entry]));
+  let rendered = "", cursor = 0;
+  for (const placeholder of parsed.placeholders) { rendered += text.slice(cursor, placeholder.start) + (replacements.get(placeholder.start)?.rendered ?? placeholder.raw); cursor = placeholder.end; }
+  rendered += text.slice(cursor);
+  return { rendered, placeholders: resolved, findings: findings.sort((a, b) => a.start - b.start), literals };
+}

package/src/paper/review.ts

@@ -0,0 +1,115 @@
+import { boundedText, commit, onlyKeys, openStudy, plain, readLedger, sha256, type Actor, type LedgerEvent } from "../study.ts";
+import { readCurrentBuild } from "./build.ts";
+import { checkPaper } from "./check.ts";
+export const REVIEW_KINDS = ["contradiction", "unsupported-claim", "number", "citation", "method", "clarity", "other"] as const;
+export interface ReviewReport {
+  v: 1; reviewer: { id: string; modelFamily: string }; buildSha256: string;
+  checklist: { negativeResults: boolean; denominators: boolean; limitations: boolean; reproducibility: boolean };
+  findings: { id: string; kind: typeof REVIEW_KINDS[number]; location: string; text: string; blocking: boolean }[];
+}
+interface Resolution { reason: string; actor: Actor; at: string }
+interface ReviewRecord { id: string; report: ReviewReport; actor: Actor; at: string; resolutions: Record<string, Resolution> }
+function bad(message: string): never { throw new Error(`review: ${message}; inspect ares review show, correct the report or target, and retry`); }
+function text(raw: unknown, field: string, max = 4000): string {
+  let value: string;
+  try { value = boundedText(raw, `review ${field}`, max); } catch { bad(`${field} must be nonblank text of at most ${max} bytes`); }
+  if (Buffer.byteLength(value) > max) bad(`${field} exceeds ${max} bytes`);
+  return value;
+}
+function identifier(raw: unknown, field: string): string { const value = text(raw, field, 128); if (value.includes("/")) bad(`${field} contains /; choose an id without slashes`); return value; }
+function object(raw: unknown, keys: string[], field: string, strict: boolean): Record<string, unknown> {
+  if (!plain(raw)) bad(`${field} must be an object`);
+  if (strict) onlyKeys(raw, keys, `review ${field}`);
+  return raw;
+}
+export function validateReview(raw: unknown, strict = true): ReviewReport {
+  try {
+    const value = object(raw, ["v", "reviewer", "buildSha256", "checklist", "findings"], "report", strict);
+    if (value.v !== 1) throw new Error("review: unsupported report version; use an ares version that supports this report, keeping the original bytes unchanged");
+    const reviewer = object(value.reviewer, ["id", "modelFamily"], "reviewer", strict), checklist = object(value.checklist, ["negativeResults", "denominators", "limitations", "reproducibility"], "checklist", strict);
+    const buildSha256 = text(value.buildSha256, "buildSha256", 64);
+    if (!/^[a-f0-9]{64}$/.test(buildSha256)) bad("buildSha256 must be the 64-hex current evidence hash; run ares paper build");
+    for (const name of ["negativeResults", "denominators", "limitations", "reproducibility"]) if (typeof checklist[name] !== "boolean") bad(`checklist.${name} must be a boolean`);
+    if (!Array.isArray(value.findings) || value.findings.length > 200) bad("findings must be an array of at most 200 entries");
+    const ids = new Set<string>();
+    const findings = value.findings.map((raw, index) => {
+      const finding = object(raw, ["id", "kind", "location", "text", "blocking"], `finding[${index}]`, strict), id = identifier(finding.id, `finding[${index}].id`);
+      if (ids.has(id)) bad(`duplicate finding id ${id}`); ids.add(id);
+      if (!REVIEW_KINDS.includes(finding.kind as typeof REVIEW_KINDS[number])) bad(`finding ${id} has unknown kind; use ${REVIEW_KINDS.join(", ")}`);
+      if (typeof finding.blocking !== "boolean") bad(`finding ${id}.blocking must be a boolean`);
+      return { id, kind: finding.kind as typeof REVIEW_KINDS[number], location: text(finding.location, `finding ${id}.location`), text: text(finding.text, `finding ${id}.text`), blocking: finding.kind === "contradiction" || finding.blocking };
+    });
+    return { v: 1, reviewer: { id: text(reviewer.id, "reviewer.id", 128), modelFamily: text(reviewer.modelFamily, "reviewer.modelFamily", 128).trim().toLowerCase() }, buildSha256, checklist: { negativeResults: checklist.negativeResults as boolean, denominators: checklist.denominators as boolean, limitations: checklist.limitations as boolean, reproducibility: checklist.reproducibility as boolean }, findings };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "invalid report";
+    if (message.includes("; inspect ares review show") || message.includes("supports this report")) throw error;
+    bad(`${message}; correct the input before ares review add --file PATH`);
+  }
+}
+export function foldReviews(events: LedgerEvent[]): ReviewRecord[] {
+  const rows: ReviewRecord[] = [], counts = new Map<string, number>();
+  for (const event of events) {
+    if (event.type === "review.added") {
+      const id = identifier(event.data.id, "stored review id"), report = validateReview(event.data.review, false), count = (counts.get(report.buildSha256) ?? 0) + 1;
+      if (count > 100 || rows.some(row => row.id === id)) bad("review journal has duplicate ids or more than 100 reviews for one build; restore its last valid version");
+      counts.set(report.buildSha256, count); rows.push({ id, report, actor: event.actor, at: event.at, resolutions: Object.create(null) as Record<string, Resolution> });
+    } else if (event.type === "review.resolved") {
+      const row = rows.find(row => row.id === event.data.reviewId), finding = row?.report.findings.find(f => f.id === event.data.findingId);
+      if (!row || !finding || event.data.buildSha256 !== row.report.buildSha256 || row.resolutions[finding.id]) bad("resolution journal references a missing or already resolved finding; restore its last valid version");
+      row.resolutions[finding.id] = { reason: text(event.data.reason, "stored resolution reason"), actor: event.actor, at: event.at };
+    }
+  }
+  return rows;
+}
+/** Caller holds the study lock; report ids are generated, findings never disappear by vote. */
+export function addReview(dirArg: string, raw: unknown, actor: Actor) {
+  const { dir } = openStudy(dirArg), report = validateReview(raw), current = readCurrentBuild(dir), events = readLedger(dir), rows = foldReviews(events);
+  if (report.buildSha256 !== current.evidenceSha256) bad("stale buildSha256; use the evidenceSha256 from the current ares paper build output");
+  if (rows.filter(row => row.report.buildSha256 === report.buildSha256).length >= 100) bad("100 reviews already recorded for this build; resolve existing findings or build a revised manuscript");
+  const id = sha256(JSON.stringify([report, events.length])).slice(0, 16);
+  if (rows.some(row => row.id === id)) bad("review id collision; inspect the journal before retrying");
+  // ponytail: the ledger's existing 64 KiB event limit is stricter than individual text/count limits combined.
+  if (Buffer.byteLength(JSON.stringify(report)) > 60 * 1024) bad("combined report exceeds the 60 KiB review payload ceiling; shorten texts or submit fewer findings per report");
+  commit(dir, [], [{ actor, type: "review.added", data: { id, review: report } }]); return { id, ...report };
+}
+export function resolveReview(dirArg: string, target: string, reason: string, actor: Actor) {
+  const { dir } = openStudy(dirArg), parts = target.split("/");
+  if (parts.length !== 2) bad("resolution target must be <review-id>/<finding-id>; use ids from ares review show");
+  const reviewId = identifier(parts[0], "review id"), findingId = identifier(parts[1], "finding id"), why = text(reason, "resolution reason"), row = foldReviews(readLedger(dir)).find(row => row.id === reviewId);
+  if (!row) bad(`unknown review ${reviewId}`);
+  if (!row.report.findings.some(f => f.id === findingId)) bad(`unknown finding ${reviewId}/${findingId}`);
+  if (row.resolutions[findingId]) bad(`finding ${reviewId}/${findingId} is already resolved`);
+  commit(dir, [], [{ actor, type: "review.resolved", data: { reviewId, findingId, buildSha256: row.report.buildSha256, reason: why } }]);
+  return { reviewId, findingId, reason: why, actor };
+}
+function canonical(raw: unknown): string {
+  if (Array.isArray(raw)) return `[${raw.map(canonical).join(",")}]`;
+  if (plain(raw)) return `{${Object.keys(raw).sort().map(key => `${JSON.stringify(key)}:${canonical(raw[key])}`).join(",")}}`;
+  return JSON.stringify(raw) ?? "null";
+}
+function binding(current: { manuscriptSha256: string; evidenceSha256: string }, events: LedgerEvent[], rows: ReviewRecord[]): string {
+  const selected = rows.filter(row => row.report.buildSha256 === current.evidenceSha256), ids = new Set(selected.map(row => row.id));
+  const added = events.filter(e => e.type === "review.added" && ids.has(e.data.id as string)).map(e => sha256(canonical(e))).sort();
+  const resolutions = events.filter(e => e.type === "review.resolved" && ids.has(e.data.reviewId as string)).map(e => sha256(canonical(e))).sort();
+  return sha256(JSON.stringify([current.manuscriptSha256, current.evidenceSha256, added, resolutions]));
+}
+export function reviewBinding(dirArg: string): string | undefined {
+  try { const { dir } = openStudy(dirArg), current = readCurrentBuild(dir), events = readLedger(dir); return binding(current, events, foldReviews(events)); } catch { return undefined; }
+}
+export function reviewReadiness(dirArg: string) {
+  const { dir } = openStudy(dirArg), events = readLedger(dir), unmet: { code: string; message: string }[] = [];
+  let current: ReturnType<typeof readCurrentBuild> | undefined, check: ReturnType<typeof checkPaper> | undefined;
+  try { current = readCurrentBuild(dir); check = current.check; } catch (error) { unmet.push({ code: "build", message: error instanceof Error ? error.message : "current build unavailable; run ares paper build" }); }
+  if (!check) { try { check = checkPaper(dir); } catch (error) { unmet.push({ code: "paper-check", message: error instanceof Error ? error.message : "paper check unavailable; restore paper/manuscript.md" }); } }
+  if (check && !check.ok) unmet.push({ code: "paper-check", message: `paper check has ${check.findings.length} finding(s); run ares paper check --json and fix every finding` });
+  let rows: ReviewRecord[] = [];
+  try { rows = foldReviews(events); } catch (error) { unmet.push({ code: "review-journal", message: error instanceof Error ? error.message : "review journal invalid; restore its valid events" }); }
+  const buildSha256 = current?.evidenceSha256, reviews = rows.filter(row => row.report.buildSha256 === buildSha256), families = [...new Set(reviews.map(row => row.report.reviewer.modelFamily))].sort();
+  if (families.length < 2) unmet.push({ code: "model-families", message: "fewer than two distinct model families reviewed the current evidence hash; add current-build reviews from two families" });
+  const openBlocking = reviews.flatMap(row => row.report.findings.filter(f => f.blocking && !row.resolutions[f.id]).map(f => ({ reviewId: row.id, findingId: f.id, kind: f.kind, location: f.location, text: f.text })));
+  if (openBlocking.length) unmet.push({ code: "blocking-findings", message: `open blocking findings: ${openBlocking.map(f => `${f.reviewId}/${f.findingId} (${f.kind})`).join(", ")}; resolve each with a reason using ares review resolve` });
+  return { ready: unmet.length === 0, buildSha256: buildSha256 ?? null, ...(current ? { manuscriptSha256: current.manuscriptSha256 } : {}), check: check ?? null, reviews, families, openBlocking, checklists: reviews.map(row => ({ reviewId: row.id, ...row.report.checklist })), claims: "unavailable (STAIxBWLB/agent-hub#931)", unmet };
+}
+export function requireReviewReady(dir: string): void {
+  const report = reviewReadiness(dir); if (!report.ready) throw new Error(`gate review: ${report.unmet.map(item => `${item.code}: ${item.message}`).join("; ")}; inspect ares review show before approval`);
+}

package/src/plan/controller.ts

@@ -0,0 +1,192 @@
+import { boundHubTask, type HubClient, type HubObservation } from "./hub.ts";
+import { assertPlanOwner, commit, openStudy, readLedger, requireGate, withLock, withPlanLock, StudyLockBusyError, type Actor, type PendingEvent, type PlanOwner } from "../study.ts";
+import { canonical, nextDispatchId, planGateBinding, readPlanState, type NodeState, type PlanState } from "./state.ts";
+import type { PlanNode } from "./definition.ts";
+
+export type StepNode = Extract<PlanNode, { kind: "step" }>;
+export type HubNode = Extract<PlanNode, { kind: "hub" }>;
+export interface Observation { status: "dispatched" | "done" | "failed" | "cancelled" | "uncertain"; output?: unknown; reason?: string; progress?: string; taskId?: number; hubProject?: string }
+export interface ControllerRuntime {
+  actor: Actor;
+  hub?: HubClient;
+  signal?: AbortSignal;
+  sleep?: (ms: number) => Promise<void>;
+  clock?: () => number;
+  prepare: (node: StepNode, state: NodeState) => Promise<{ attemptId?: string }>;
+  execute: (node: StepNode, state: NodeState) => Promise<Observation>;
+  reconcile: (node: StepNode, state: NodeState) => Promise<Observation>;
+}
+export interface ControllerOptions { parallel?: number }
+const delay = (ms: number, signal?: AbortSignal): Promise<void> => new Promise(resolve => {
+  if (signal?.aborted) { resolve(); return; }
+  const finish = () => { clearTimeout(timer); signal?.removeEventListener("abort", finish); resolve(); };
+  const timer = setTimeout(finish, ms); signal?.addEventListener("abort", finish, { once: true });
+});
+async function tryTransaction<T>(dir: string, fn: () => T): Promise<{ value: T } | undefined> {
+  try { return { value: await withLock(dir, fn) }; }
+  catch (error) { if (error instanceof StudyLockBusyError) return undefined; throw error; }
+}
+async function transaction<T>(dir: string, fn: () => T): Promise<T> {
+  let wait = 50;
+  for (;;) {
+    const result = await tryTransaction(dir, fn);
+    if (result) return result.value;
+    await delay(wait); wait = Math.min(wait * 2, 1000);
+  }
+}
+/** One controller, short transactional study locks, and no replay of unobserved actions. */
+export async function runPlan(dirArg: string, options: ControllerOptions, runtime: ControllerRuntime): Promise<PlanState> {
+  const { dir, study } = openStudy(dirArg), parallel = options.parallel ?? 1;
+  if (!Number.isSafeInteger(parallel) || parallel < 1 || parallel > 8) throw new Error("run --parallel: integer in 1..8 required; run ares run <dir> --parallel 1..8");
+  return withPlanLock(dir, async owner => {
+    const state = () => readPlanState(dir, readLedger(dir));
+    const clock = runtime.clock ?? (() => performance.now());
+    const sleep = (ms: number) => runtime.sleep ? runtime.sleep(ms) : delay(ms, runtime.signal);
+    const polls = new Map<string, { at: number; wait: number; signature: string }>();
+    const schedule = (node: NodeState, observation: Observation) => {
+      if (!node.dispatchId) return;
+      if (observation.status !== "dispatched") { polls.delete(node.dispatchId); return; }
+      const previous = polls.get(node.dispatchId), signature = canonical(observation);
+      const wait = previous?.signature === signature ? Math.min(previous.wait * 2, 30_000) : 1000;
+      polls.set(node.dispatchId, { at: clock() + wait, wait, signature });
+    };
+    const locked = <T>(fn: () => T) => transaction(dir, () => { assertPlanOwner(dir, owner); return fn(); });
+    const observe = async (node: NodeState, observation: Observation) => {
+      const target = state().nodes.find(n => n.id === node.id);
+      if (!target || target.dispatchId !== node.dispatchId || !["dispatched", "uncertain"].includes(target.status)) return;
+      if (observation.status === "dispatched" && target.lastObserved?.dispatchId === node.dispatchId && target.reason === observation.reason && (observation.taskId === undefined || target.taskId === observation.taskId) && (observation.hubProject === undefined || target.hubProject === observation.hubProject)) return;
+      return locked(() => {
+      const current = state(), target = current.nodes.find(n => n.id === node.id);
+      if (!target || target.dispatchId !== node.dispatchId || !["dispatched", "uncertain"].includes(target.status)) return;
+      if (observation.status === "dispatched" && target.status === "dispatched" && target.lastObserved && target.lastObserved.dispatchId === node.dispatchId && target.lastObserved.status === "dispatched" && target.reason === observation.reason && (observation.taskId === undefined || target.taskId === observation.taskId) && (observation.hubProject === undefined || target.hubProject === observation.hubProject)) return;
+      commit(dir, [], [{ actor: runtime.actor, type: "node.observed", data: { revision: current.revision, node: node.id, dispatchId: node.dispatchId, status: observation.status, ...(observation.output !== undefined ? { output: observation.output } : {}), ...(observation.reason !== undefined ? { reason: observation.reason } : {}), ...(observation.taskId !== undefined ? { taskId: observation.taskId } : {}), ...(observation.hubProject !== undefined ? { hubProject: observation.hubProject } : {}) } }]);
+      });
+    };
+    const reconcile = async (node: NodeState): Promise<void> => {
+      const definition = state().definition.nodes.find(n => n.id === node.id);
+      if (!definition || (definition.kind === "hub" && !runtime.hub)) return;
+      let observation: Observation;
+      if (definition.kind === "hub") {
+        try { observation = await runtime.hub!.observe(definition.campaign, definition.unit, node.taskId ?? boundHubTask(readLedger(dir), state().revision, node.id)); }
+        catch { observation = { status: "dispatched", reason: "hub read unavailable; check ahub study show and restore hub access" }; }
+      } else if (definition.kind !== "step" || definition.command !== "attempt.run") observation = { status: "uncertain", reason: "step result unavailable after interruption; explicitly retry or skip this node" };
+      else {
+        try { observation = await runtime.reconcile(definition, node); }
+        catch (error) { if (error instanceof StudyLockBusyError) { schedule(node, { status: "dispatched", reason: node.reason }); return; } observation = { status: "dispatched", reason: "attempt observation unavailable; check the executor and run ares attempt reconcile" }; }
+      }
+      await observe(node, observation); schedule(node, observation);
+    };
+    await locked(() => {
+      const current = state();
+      if (current.state === "running") commit(dir, [], [{ actor: runtime.actor, type: "plan.paused", data: { revision: current.revision, reason: "controller startup restores paused" } }]);
+    });
+    for (const node of state().nodes.filter(n => n.status === "dispatched")) await reconcile(node);
+    const active = new Map<string, Promise<void>>();
+    const launch = (definition: StepNode, node: NodeState) => {
+      const work = (async () => {
+        let observation: Observation;
+        let wait = 1000;
+        for (;;) {
+          const current = state().nodes.find(n => n.id === node.id);
+          if (runtime.signal?.aborted || !current || current.dispatchId !== node.dispatchId || current.status !== "dispatched") return;
+          assertPlanOwner(dir, owner);
+          try { observation = await runtime.execute(definition, node); break; }
+          catch (error) {
+            if (error instanceof StudyLockBusyError) { await sleep(wait); wait = Math.min(wait * 2, 30_000); continue; }
+            if (definition.command === "attempt.run") { await reconcile(node); return; }
+            observation = { status: "uncertain", reason: "step execution interrupted or failed without an observable result; inspect inputs, then retry or skip this node" }; break;
+          }
+        }
+        await observe(node, observation); schedule(node, observation);
+      })();
+      active.set(node.id, work);
+      // The main loop awaits every task; failures are consumed immediately to prevent unhandled rejection.
+      void work.catch(() => {});
+    };
+    let failure: unknown, wait = 500, fingerprint = canonical(state());
+    try {
+      while (!runtime.signal?.aborted) {
+        let current = state();
+        if (current.state === "done") break;
+        if (current.state === "running") {
+          // Pending auto gates are approved only inside a successful controller transaction.
+          if (study.autonomy === "auto" && current.nodes.some(n => n.kind === "gate" && n.status === "pending" && n.gate?.state === "pending")) await tryTransaction(dir, () => {
+            assertPlanOwner(dir, owner);
+            const events = readLedger(dir), value = readPlanState(dir, events), approvals: PendingEvent[] = [];
+            if (value.state !== "running") return;
+            for (const gate of value.nodes.filter(n => n.kind === "gate" && n.status === "pending" && n.gate?.state === "pending")) {
+              if (study.autonomy === "auto") approvals.push(...requireGate(dir, study, `plan:${gate.id}`, name => planGateBinding(value, name)));
+            }
+            if (approvals.length) commit(dir, [], [...approvals, { actor: runtime.actor, type: "plan.gates", data: { revision: value.revision } }]);
+          });
+          current = state();
+          for (const node of current.nodes) {
+            if (runtime.signal?.aborted || current.state !== "running") break;
+            const definition = current.definition.nodes.find(n => n.id === node.id)!;
+            if (node.status !== "ready" || active.has(node.id)) continue;
+            if (definition.kind === "hub" && runtime.hub) {
+              const binding = boundHubTask(readLedger(dir), current.revision, node.id);
+              let result: HubObservation;
+              try { result = await runtime.hub.observe(definition.campaign, definition.unit, binding); }
+              catch { result = { status: "dispatched", reason: "hub read unavailable; check ahub study show and restore hub access" }; }
+              const intent = await admit(dir, owner, runtime.actor, current, node, definition, { ...(result.taskId !== undefined ? { taskId: result.taskId } : {}), ...(result.hubProject !== undefined ? { hubProject: result.hubProject } : {}) }, parallel);
+              if (intent) { await observe(intent, result); schedule(intent, result); }
+              current = state(); continue;
+            }
+            if (definition.kind !== "step") continue;
+            const slots = stepSlots(current);
+            if (slots >= parallel) continue;
+            // A2 permits one active experiment attempt per study.
+            if (definition.command === "attempt.run" && current.nodes.some(n => n.status === "dispatched" && current.definition.nodes.find(d => d.id === n.id)?.kind === "step" && (current.definition.nodes.find(d => d.id === n.id) as StepNode).command === "attempt.run")) continue;
+            let prepared: { attemptId?: string };
+            try { prepared = await runtime.prepare(definition, node); }
+            catch { // Preparation is read-only; still record a correlated failed dispatch for visibility.
+              prepared = {};
+              const intent = await admit(dir, owner, runtime.actor, current, node, definition, prepared, parallel);
+              if (intent) await observe(intent, { status: "failed", reason: "step preparation failed; check command inputs and retry this node" });
+              current = state(); continue;
+            }
+            const intent = await admit(dir, owner, runtime.actor, current, node, definition, prepared, parallel);
+            if (intent) launch(definition, intent);
+            current = state();
+          }
+        }
+        // Detached attempts are observed while paused too, without admitting new work.
+        for (const node of state().nodes.filter(n => n.status === "dispatched" && !active.has(n.id))) {
+          if (clock() >= (polls.get(node.dispatchId!)?.at ?? 0)) await reconcile(node);
+        }
+        if (state().state === "done") break;
+        const next = canonical(state());
+        wait = next === fingerprint ? Math.min(wait * 2, 30_000) : 1000; fingerprint = next;
+        const live = new Set(state().nodes.filter(n => n.status === "dispatched").map(n => n.dispatchId));
+        for (const id of polls.keys()) if (!live.has(id)) polls.delete(id);
+        const due = [...polls.values()].map(p => Math.max(1, p.at - clock()));
+        const interval = Math.min(wait, ...(due.length ? due : [30_000]));
+        if (active.size) {
+          const settled = await Promise.race([...active].map(async ([id, work]) => { await work; return id; }).concat([sleep(interval).then(() => "")]));
+          if (settled) { await active.get(settled); active.delete(settled); }
+        } else await sleep(interval);
+      }
+    } catch (error) { failure = error; }
+    // Pause stops admission, drains this process's command calls, and leaves detached attempts alive.
+    await Promise.allSettled(active.values());
+    await locked(() => { const current = state(); if (current.state === "running") commit(dir, [], [{ actor: runtime.actor, type: "plan.paused", data: { revision: current.revision, reason: "controller stopped" } }]); });
+    if (failure) throw failure;
+    return state();
+  });
+}
+async function admit(dir: string, owner: PlanOwner, actor: Actor, snapshot: PlanState, node: NodeState, definition: StepNode | HubNode, prepared: { attemptId?: string; taskId?: number; hubProject?: string }, parallel: number): Promise<NodeState | undefined> {
+  const result = await tryTransaction(dir, () => {
+    assertPlanOwner(dir, owner);
+    const current = readPlanState(dir, readLedger(dir)), target = current.nodes.find(n => n.id === node.id);
+    if (current.state !== "running" || current.revision !== snapshot.revision || target?.status !== "ready" || canonical(current.definition.nodes.find(n => n.id === node.id)) !== canonical(definition) || (definition.kind === "step" && stepSlots(current) >= parallel)) return undefined;
+    const dispatchId = nextDispatchId(current, node.id);
+    commit(dir, [], [{ actor, type: "node.intent", data: { revision: current.revision, node: node.id, dispatchId, ...prepared } }]);
+    return readPlanState(dir, readLedger(dir)).nodes.find(n => n.id === node.id)!;
+  });
+  return result?.value;
+}
+
+function stepSlots(state: PlanState): number {
+  return state.nodes.filter(n => n.kind === "step" && n.status === "dispatched").length;
+}

package/src/plan/definition.ts

@@ -0,0 +1,156 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { COMMANDS } from "../commands-table.ts";
+import { boundedText, commit, onlyKeys, plain, readJsonFile, sha256, type Actor } from "../study.ts";
+
+export const PLAN_BYTES = 65_536, PLAN_ID_BYTES = 128;
+export const STEP_COMMANDS = ["lit.search", "lit.verify", "lit.bib", "cite.check", "attempt.run", "investigate.close", "ablate.close", "final.close", "paper.build", "watch.run"] as const;
+export type StepCommand = typeof STEP_COMMANDS[number];
+export type StepArgs = Record<string, string | number | boolean | string[]>;
+type BaseNode = { id: string; needs: string[] };
+export type PlanNode = BaseNode & (
+  { kind: "step"; command: StepCommand; args: StepArgs } |
+  { kind: "hub"; campaign: string; unit: string } |
+  { kind: "gate"; binds: string[] }
+);
+export interface PlanDefinition { v: 1; revision: number; nodes: PlanNode[]; edges: [string, string][] }
+const retry = "correct the definition and run ares plan set again";
+const compatible = "use an ares version that supports this plan, keeping plan.json unchanged";
+function nodeId(raw: unknown, what = "plan node id"): string {
+  const id = boundedText(raw, what, PLAN_ID_BYTES);
+  if (Buffer.byteLength(id) > PLAN_ID_BYTES) throw new Error(`${what}: at most ${PLAN_ID_BYTES} bytes`);
+  return id;
+}
+function references(raw: unknown, name: string): string[] {
+  if (!Array.isArray(raw) || raw.length > 128) throw new Error(`${name}: at most 128 node ids required`);
+  return raw.map((id, i) => nodeId(id, `${name}[${i}]`));
+}
+function stepArgs(raw: unknown, command: StepCommand, id: string): StepArgs {
+  const where = `plan step ${id} (${command})`;
+  if (!plain(raw)) throw new Error(`${where}.args: object required`);
+  const spec = COMMANDS.find(c => c.name === command.replace(".", " "))!;
+  const args: StepArgs = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const field = `${where}.args.${key}`;
+    if (key === "json" || (command === "attempt.run" && key === "detach")) throw new Error(`${field}: controller-owned option; remove ${key} and run ares plan set again`);
+    if (command === "lit.search" && key === "query") {
+      const query = boundedText(value, field, 1000);
+      if (Buffer.byteLength(query) > 1000) throw new Error(`${field}: at most 1000 bytes`);
+      args[key] = query; continue;
+    }
+    if (command === "cite.check" && key === "draft") {
+      args[key] = boundedText(value, field, 4096); continue;
+    }
+    if (command === "lit.verify" && key === "ids") {
+      if (!Array.isArray(value) || value.length > 500) throw new Error(`${field}: array of at most 500 candidate ids required`);
+      args[key] = value.map((item, i) => boundedText(item, `${field}[${i}]`, 300)); continue;
+    }
+    const option = Object.hasOwn(spec.options, `--${key}`) ? spec.options[`--${key}`] : undefined;
+    if (!option) throw new Error(`${field}: unknown option ${key}`);
+    if (option === "flag" ? typeof value !== "boolean" : !["string", "number"].includes(typeof value)) throw new Error(`${field}: ${option === "flag" ? "boolean flag" : "string or number value"} required`);
+    if (typeof value === "number" && !Number.isFinite(value)) throw new Error(`${field}: finite value required`);
+    if (typeof value === "string") boundedText(value, field, 4096);
+    args[key] = value as string | number | boolean;
+  }
+  const required = command === "attempt.run" ? ["repo", "commit"] : command === "lit.search" ? ["query"] : command === "cite.check" ? ["draft"] : [];
+  for (const key of required) if (!Object.hasOwn(args, key)) throw new Error(`${where}: required option ${key}; add args.${key} and run ares plan set again`);
+  return args;
+}
+export function validatePlan(raw: unknown): PlanDefinition {
+  try { return validateDefinition(raw); }
+  catch (error) {
+    const message = error instanceof Error ? error.message : "plan: invalid definition";
+    throw new Error(message.includes(compatible) || message.includes("run ares plan set again") ? message : `${message}; ${retry}`);
+  }
+}
+function validateDefinition(raw: unknown): PlanDefinition {
+  if (!plain(raw)) throw new Error("plan: object required");
+  if (raw.v !== 1) throw new Error(`plan: unsupported v ${String(raw.v)} (expected 1); ${compatible}`);
+  onlyKeys(raw, ["v", "revision", "nodes", "edges"], "plan");
+  const revision = raw.revision ?? 1;
+  if (!Number.isSafeInteger(revision) || (revision as number) < 1) throw new Error("plan: revision must be a positive safe integer");
+  if (!Array.isArray(raw.nodes) || raw.nodes.length > 128) throw new Error("plan: at most 128 nodes required");
+  if (!Array.isArray(raw.edges) || raw.edges.length > 512) throw new Error("plan: at most 512 edges required");
+  const nodes: PlanNode[] = raw.nodes.map((n: unknown, index: number) => {
+    if (!plain(n)) throw new Error(`plan node[${index}]: object required`);
+    const id = nodeId(n.id, `plan node[${index}].id`), needs = n.needs === undefined ? [] : references(n.needs, `plan node ${String(n.id)}.needs`);
+    const base = { id, needs };
+    switch (n.kind) {
+      case "step": {
+        onlyKeys(n, ["id", "kind", "needs", "command", "args"], `plan step ${id}`);
+        if (!STEP_COMMANDS.includes(n.command as StepCommand)) throw new Error(`plan step ${id}: unknown command ${String(n.command)} (allowed: ${STEP_COMMANDS.join(", ")})`);
+        const command = n.command as StepCommand;
+        return { ...base, kind: "step", command, args: stepArgs(n.args ?? {}, command, id) };
+      }
+      case "hub": {
+        onlyKeys(n, ["id", "kind", "needs", "campaign", "unit"], `plan hub ${id}`);
+        return { ...base, kind: "hub", campaign: nodeId(n.campaign, `plan hub ${id}.campaign`), unit: nodeId(n.unit, `plan hub ${id}.unit`) };
+      }
+      case "gate":
+        onlyKeys(n, ["id", "kind", "needs", "binds"], `plan gate ${id}`);
+        return { ...base, kind: "gate", binds: references(n.binds, `plan gate ${id}.binds`) };
+      default: throw new Error(`plan node ${id}: unknown node kind ${String(n.kind)}; ${compatible}`);
+    }
+  });
+  const ids = new Set(nodes.map(n => n.id));
+  const seen = new Set<string>();
+  for (const n of nodes) {
+    if (seen.has(n.id)) throw new Error(`plan: duplicate node id ${n.id}; rename the duplicate node and update its references`);
+    seen.add(n.id);
+  }
+  const edges: [string, string][] = raw.edges.map((e: unknown, index: number) => {
+    if (!Array.isArray(e) || e.length !== 2) throw new Error(`plan edge[${index}]: pair required`);
+    return [nodeId(e[0], `plan edge[${index}].from`), nodeId(e[1], `plan edge[${index}].to`)];
+  });
+  const parents = new Map(nodes.map(n => [n.id, new Set(n.needs)]));
+  for (const [from, to] of edges) {
+    if (!ids.has(from) || !ids.has(to)) throw new Error(`plan edge [${from}, ${to}]: missing endpoint, no node ${!ids.has(from) ? from : to}; add that node or remove this edge`);
+    parents.get(to)!.add(from);
+  }
+  for (const n of nodes) for (const p of n.needs) if (!ids.has(p)) throw new Error(`plan node ${n.id}.needs: missing endpoint, no node ${p}; add that node or remove this dependency`);
+  const visiting = new Set<string>(), visited = new Set<string>();
+  const stack: string[] = [];
+  function visit(id: string): void {
+    if (visiting.has(id)) throw new Error(`plan: cycle through ${[...stack.slice(stack.indexOf(id)), id].reverse().join(" -> ")}; remove one dependency and run ares plan set again`);
+    if (visited.has(id)) return;
+    visiting.add(id); stack.push(id);
+    for (const parent of parents.get(id)!) visit(parent);
+    stack.pop(); visiting.delete(id); visited.add(id);
+  }
+  for (const n of nodes) visit(n.id);
+  const ancestorCache = new Map<string, Set<string>>();
+  function ancestors(id: string): Set<string> {
+    const cached = ancestorCache.get(id);
+    if (cached) return cached;
+    const result = new Set<string>();
+    for (const parent of parents.get(id)!) {
+      result.add(parent);
+      for (const ancestor of ancestors(parent)) result.add(ancestor);
+    }
+    ancestorCache.set(id, result);
+    return result;
+  }
+  for (const n of nodes) if (n.kind === "gate") for (const bound of n.binds) {
+    if (!ids.has(bound) || !ancestors(n.id).has(bound)) throw new Error(`plan gate ${n.id} binds ${bound}, which is not upstream; add an upstream dependency or remove this binding`);
+  }
+  const result: PlanDefinition = { v: 1, revision: revision as number, nodes, edges };
+  if (Buffer.byteLength(JSON.stringify(result, null, 2) + "\n") > PLAN_BYTES) throw new Error(`plan: exceeds ${PLAN_BYTES} bytes`);
+  return result;
+}
+export function readPlan(dir: string): PlanDefinition | undefined {
+  const file = join(dir, "plan.json");
+  if (!existsSync(file)) return undefined;
+  const raw: unknown = readJsonFile(file, PLAN_BYTES);
+  const definition = validatePlan(raw);
+  if (!plain(raw) || raw.revision === undefined) throw new Error(`plan.json: stored revision required; restore a revisioned definition before running ares plan set again`);
+  return definition;
+}
+/** Caller holds the study lock; definition and initial state share one transaction. */
+export function setPlan(dir: string, raw: unknown, actor: Actor) {
+  const definition = validatePlan(raw), previous = readPlan(dir);
+  definition.revision = (previous?.revision ?? 0) + 1;
+  if (!Number.isSafeInteger(definition.revision)) throw new Error("plan.revision: exhausted; create a new study before setting another plan");
+  const text = JSON.stringify(definition, null, 2) + "\n";
+  commit(dir, [[join(dir, "plan.json"), text, PLAN_BYTES]], [{ actor, type: "plan.set", data: { revision: definition.revision, definition, state: "paused", sha256: sha256(text) } }]);
+  return { definition, state: "paused" as const };
+}