@staix/agent-research 0.0.0-stage → 0.1.0

package/src/exp/investigate.ts

@@ -0,0 +1,182 @@
+import { readFinalSeeds, finalSeedsHash } from "./final.ts";
+import { foldIdeas } from "./ideas.ts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { assertWritable, commit, openStudy, plain, readLedger, readTextBounded, requireExperiment, sha256, type Actor, type LedgerEvent } from "../study.ts";
+import { listAttempts, type Attempt, type AttemptStatus } from "./attempts.ts";
+import { protocolHash, readProtocol } from "./protocol.ts";
+import { readSelection, selectionHash } from "./selection.ts";
+
+export const INVESTIGATE_BYTES = 1_048_576;
+export type NoWinner = "no-baseline" | "baseline-seeds" | "no-candidate" | "below-margin" | "tie";
+type Exclusion = "other-protocol" | "before-selection" | "missing-start-event" | "undeclared-seed" | "later-success" | "reserved-seed";
+export interface Sample { seed: number; attempt: string; value: number }
+export interface CommitResult {
+  commit: string; idea?: string; attempts: Record<AttemptStatus, string[]>; perSeed: Sample[];
+  pairedSeeds: number[]; pairs: { seed: number; attempt: string; baselineAttempt: string; value: number; baselineValue: number }[];
+  mean: number | null; baselineMean: number | null; delta: number | null; eligible: boolean; reason: string;
+}
+export interface InvestigateResult {
+  v: 1; run: string; ruleSha256: string; protocolHash: string; inputsSha256: string;
+  metric: { name: string; unit: string; direction: "max" | "min" };
+  baseline: CommitResult; candidates: CommitResult[];
+  totals: { attempts: number; byStatus: Record<AttemptStatus, number>; countedSuccesses: number; excluded: number };
+  excluded: { id: string; commit: string; seed: number; status: AttemptStatus; reasons: Exclusion[] }[];
+  winner: { commit: string; idea?: string; attempts: string[]; mean: number; delta: number } | null; reason?: NoWinner;
+}
+const recover = "; inspect ares attempt show and restore the last valid study inputs before ares investigate show";
+function bad(reason: string): never { throw new Error(`investigate: ${reason}${recover}`); }
+function canonical(raw: unknown): string {
+  if (Array.isArray(raw)) return `[${raw.map(canonical).join(",")}]`;
+  if (plain(raw)) return `{${Object.keys(raw).sort().map(k => `${JSON.stringify(k)}:${canonical(raw[k])}`).join(",")}}`;
+  return JSON.stringify(raw) ?? "null";
+}
+function mean(values: number[]): number | null {
+  if (!values.length) return null;
+  const total = values.reduce((sum, value) => sum + value, 0);
+  if (Number.isFinite(total)) return total / values.length;
+  const scale = Math.max(...values.map(Math.abs));
+  if (!scale) return 0;
+  // Normalize before summing so finite evaluator values never overflow their mean.
+  return Math.max(-1, Math.min(1, values.reduce((sum, v) => sum + v / scale / values.length, 0))) * scale;
+}
+export function metricValue(attempt: Attempt, metric: InvestigateResult["metric"]): number {
+  if (!Array.isArray(attempt.metrics)) bad(`attempt ${attempt.id}: primary metrics missing`);
+  const values = attempt.metrics.filter(m => m?.name === metric.name);
+  const value = values[0];
+  if (values.length !== 1 || !value || value.unit !== metric.unit || value.provenance !== "ares-observed" || typeof value.value !== "number" || !Number.isFinite(value.value)) bad(`attempt ${attempt.id}: primary metric missing, duplicate, non-finite or unvalidated`);
+  return value.value;
+}
+export interface PairedSamples {
+  pairedSeeds: number[]; pairs: { seed: number; attempt: string; referenceAttempt: string; value: number; referenceValue: number }[];
+  mean: number | null; referenceMean: number | null; delta: number | null;
+}
+/** Descriptive shared-seed comparison; callers decide eligibility and never infer significance. */
+export function pairSamples(samples: Sample[], reference: Sample[], direction: "max" | "min", commit: string): PairedSamples {
+  const pairs = [...samples].sort((a, b) => a.seed - b.seed).flatMap(sample => {
+    const base = reference.find(b => b.seed === sample.seed);
+    return base ? [{ seed: sample.seed, attempt: sample.attempt, referenceAttempt: base.attempt, value: sample.value, referenceValue: base.value }] : [];
+  });
+  const candidateMean = mean(pairs.map(p => p.value)), referenceMean = mean(pairs.map(p => p.referenceValue));
+  const delta = candidateMean === null || referenceMean === null ? null : direction === "max" ? candidateMean - referenceMean : referenceMean - candidateMean;
+  if (delta !== null && !Number.isFinite(delta)) bad(`commit ${commit}: primary metric delta overflows; rescale the metric's unit in a new protocol and rerun attempts`);
+  return { pairedSeeds: pairs.map(p => p.seed), pairs, mean: candidateMean, referenceMean, delta };
+}
+function empty(commit: string): CommitResult {
+  return { commit, attempts: { running: [], succeeded: [], failed: [], cancelled: [], unknown: [] }, perSeed: [], pairedSeeds: [], pairs: [], mean: null, baselineMean: null, delta: null, eligible: false, reason: "no-counted-success" };
+}
+function inputs(dirArg: string) {
+  const { dir, study } = openStudy(dirArg); requireExperiment(study);
+  const protocol = readProtocol(dir);
+  if (!protocol) throw new Error("investigate: protocol missing; run ares protocol before selecting an investigation rule");
+  const rule = readSelection(dir, protocol), ruleSha = selectionHash(dir, protocol);
+  if (!rule || !ruleSha) throw new Error("investigate: selection missing; run ares selection <dir> --file PATH before investigating");
+  const events = readLedger(dir), cutoff = events.findLastIndex(e => e.type === "selection.set");
+  if (cutoff < 0 || events[cutoff]!.data.sha256 !== ruleSha || events[cutoff]!.data.run !== rule.run) throw new Error("investigate: selection bytes have no current selection.set receipt; run ares selection <dir> --file PATH to record the rule before new attempts");
+  const hash = protocolHash(protocol), metric = protocol.metrics.find(m => m.name === rule.metric)!;
+  const attempts = listAttempts(dir, { run: rule.run }).attempts;
+  for (const attempt of attempts) {
+    if (attempt.studyId !== study.id || typeof attempt.commit !== "string" || !/^[a-f0-9]{40}$/.test(attempt.commit) || !Number.isSafeInteger(attempt.seed)) bad(`attempt ${attempt.id}: invalid study, commit or seed identity`);
+  }
+  const reserved = readFinalSeeds(dir, protocol)?.seeds ?? [], reservedSha = finalSeedsHash(dir, protocol);
+  return { dir, protocol, rule, ruleSha, events, cutoff, hash, metric, attempts, reserved, reservedSha };
+}
+function calculate(input: ReturnType<typeof inputs>): InvestigateResult {
+  const { rule, ruleSha, events, cutoff, hash, metric, attempts, protocol, reserved, reservedSha } = input;
+  const ideas = foldIdeas(events), owners = new Map<string, string>();
+  // The journal enforces exactly one idea owner for any associated commit.
+  for (const idea of ideas) for (const commit of idea.commits) owners.set(commit, idea.id);
+  const starts = new Map<string, { index: number; event: LedgerEvent }>();
+  events.forEach((event, index) => {
+    if (event.type !== "attempt.started" || typeof event.data.id !== "string") return;
+    if (starts.has(event.data.id)) bad(`attempt ${event.data.id}: duplicate attempt.started receipt`);
+    starts.set(event.data.id, { index, event });
+  });
+  const ordered = [...attempts].sort((a, b) => (starts.get(a.id)?.index ?? -1) - (starts.get(b.id)?.index ?? -1) || a.id.localeCompare(b.id));
+  const byStatus = { running: 0, succeeded: 0, failed: 0, cancelled: 0, unknown: 0 };
+  const rows = new Map<string, CommitResult>([[rule.baseline.commit, empty(rule.baseline.commit)]]);
+  const excluded: InvestigateResult["excluded"] = [];
+  for (const attempt of ordered) {
+    const row = rows.get(attempt.commit) ?? empty(attempt.commit); rows.set(row.commit, row);
+    byStatus[attempt.status]++; row.attempts[attempt.status].push(attempt.id);
+    const reasons: Exclusion[] = [], start = starts.get(attempt.id);
+    if (attempt.protocolHash !== hash) reasons.push("other-protocol");
+    if (!start) reasons.push("missing-start-event");
+    else {
+      if (start.event.data.run !== attempt.run || start.event.data.commit !== attempt.commit || start.event.data.seed !== attempt.seed) bad(`attempt ${attempt.id}: start receipt identity disagrees with its record`);
+      if (start.index <= cutoff) reasons.push("before-selection");
+    }
+    if (!protocol.seeds.includes(attempt.seed)) reasons.push("undeclared-seed");
+    if (reserved.includes(attempt.seed)) reasons.push("reserved-seed");
+    if (!reasons.length && attempt.status === "succeeded") {
+      if (row.perSeed.some(s => s.seed === attempt.seed)) reasons.push("later-success");
+      else row.perSeed.push({ seed: attempt.seed, attempt: attempt.id, value: metricValue(attempt, metric) });
+    }
+    if (reasons.length) excluded.push({ id: attempt.id, commit: attempt.commit, seed: attempt.seed, status: attempt.status, reasons });
+  }
+  for (const row of rows.values()) { const idea = owners.get(row.commit); if (idea !== undefined) row.idea = idea; }
+  const baseline = rows.get(rule.baseline.commit)!;
+  for (const row of rows.values()) row.perSeed.sort((a, b) => a.seed - b.seed);
+  baseline.mean = mean(baseline.perSeed.map(s => s.value)); baseline.baselineMean = baseline.mean;
+  baseline.pairedSeeds = baseline.perSeed.map(s => s.seed); baseline.delta = baseline.mean === null ? null : 0;
+  baseline.eligible = baseline.perSeed.length >= rule.minSeeds;
+  baseline.reason = !baseline.perSeed.length ? "no-baseline" : baseline.eligible ? "baseline" : "baseline-seeds";
+  const candidates = [...rows.values()].filter(row => row !== baseline).sort((a, b) => a.commit.localeCompare(b.commit));
+  for (const row of candidates) {
+    const paired = pairSamples(row.perSeed, baseline.perSeed, metric.direction, row.commit);
+    row.pairedSeeds = paired.pairedSeeds; row.mean = paired.mean; row.baselineMean = paired.referenceMean; row.delta = paired.delta;
+    row.pairs = paired.pairs.map(p => ({ seed: p.seed, attempt: p.attempt, baselineAttempt: p.referenceAttempt, value: p.value, baselineValue: p.referenceValue }));
+    row.reason = !baseline.perSeed.length ? "no-baseline" : !baseline.eligible ? "baseline-seeds" : !row.perSeed.length ? "no-counted-success" : row.pairs.length < rule.minSeeds ? "candidate-seeds" : row.delta! <= 0 || row.delta! < rule.minDelta ? "below-margin" : "eligible";
+    row.eligible = row.reason === "eligible";
+  }
+  const eligible = candidates.filter(row => row.eligible).sort((a, b) => b.delta! - a.delta!);
+  let winner: InvestigateResult["winner"] = null, reason: NoWinner | undefined;
+  if (!baseline.perSeed.length) reason = "no-baseline";
+  else if (!baseline.eligible) reason = "baseline-seeds";
+  else if (!candidates.some(row => row.pairedSeeds.length >= rule.minSeeds)) reason = "no-candidate";
+  else if (!eligible.length) reason = "below-margin";
+  else if (eligible.length > 1 && eligible[0]!.delta === eligible[1]!.delta) reason = "tie";
+  else { const row = eligible[0]!; winner = { commit: row.commit, ...(row.idea !== undefined ? { idea: row.idea } : {}), attempts: row.pairs.map(p => p.attempt), mean: row.mean!, delta: row.delta! }; }
+  const result: InvestigateResult = {
+    v: 1, run: rule.run, ruleSha256: ruleSha, protocolHash: hash,
+    inputsSha256: sha256(canonical({ ruleSha, protocolHash: hash, ...(reservedSha !== undefined ? { finalSeedsSha256: reservedSha } : {}), cutoff, ideas: sha256(canonical(ideas)), attempts: ordered.map(a => ({ record: sha256(canonical(a)), start: starts.get(a.id)?.index ?? null })) })),
+    metric, baseline, candidates, totals: { attempts: attempts.length, byStatus, countedSuccesses: [...rows.values()].reduce((n, r) => n + r.perSeed.length, 0), excluded: excluded.length }, excluded,
+    winner, ...(reason ? { reason } : {}),
+  };
+  assertWritable(JSON.stringify(result, null, 2) + "\n", INVESTIGATE_BYTES, "investigate result; archive this study and use a new bounded run");
+  return result;
+}
+export function investigateResultPath(dir: string, run: string): string { return join(dir, "runs", run, "investigate.json"); }
+function previousResult(file: string): string | undefined {
+  if (!existsSync(file)) return undefined;
+  let text: string;
+  try { text = readTextBounded(file, INVESTIGATE_BYTES); }
+  catch { throw new Error(`investigate result: unreadable, non-regular, invalid UTF-8 or larger than ${INVESTIGATE_BYTES} bytes; restore the last valid regular result within that bound before show or close`); }
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { throw new Error("investigate result: invalid JSON; restore the last valid investigate.json before show or close"); }
+  if (!plain(value) || value.v !== 1) throw new Error("investigate result: unsupported version; use an ares version that supports this result, keeping investigate.json unchanged");
+  return text;
+}
+export function showInvestigation(dirArg: string): InvestigateResult {
+  const input = inputs(dirArg); previousResult(investigateResultPath(input.dir, input.rule.run)); return calculate(input);
+}
+/** Caller holds the study lock; every refusal precedes the single file/event commit. */
+export function closeInvestigation(dirArg: string, actor: Actor): InvestigateResult {
+  const input = inputs(dirArg), file = investigateResultPath(input.dir, input.rule.run), previous = previousResult(file);
+  if (input.attempts.some(a => a.status === "running")) throw new Error("investigate close: an attempt in the selected run is running; run ares attempt reconcile before closing");
+  const result = calculate(input), text = JSON.stringify(result, null, 2) + "\n";
+  if (previous !== text) commit(input.dir, [[file, text, INVESTIGATE_BYTES]], [{ actor, type: "investigate.closed", data: { run: input.rule.run, sha256: sha256(text), ruleSha256: input.ruleSha, winner: result.winner?.commit ?? null } }]);
+  return result;
+}
+
+
+/** Read only a current, committed investigation result, never a hand-edited or stale winner. */
+export function readClosedInvestigation(dirArg: string): { result: InvestigateResult; sha256: string } {
+  const input = inputs(dirArg), text = previousResult(investigateResultPath(input.dir, input.rule.run));
+  if (text === undefined) throw new Error("investigate result: not closed; run ares investigate close before the next phase");
+  const hash = sha256(text), receipt = input.events.findLast(e => e.type === "investigate.closed" && e.data.run === input.rule.run);
+  if (!receipt || receipt.data.sha256 !== hash) throw new Error("investigate result: bytes do not match the latest close receipt; run ares investigate close to restore the committed result");
+  const result = calculate(input);
+  if (text !== JSON.stringify(result, null, 2) + "\n") throw new Error("investigate result: stale inputs; run ares investigate close again before the next phase");
+  return { result, sha256: hash };
+}

package/src/exp/logs.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { openStudy, requireExperiment } from "../study.ts";
+import { showAttempt } from "./attempts.ts";
+import { runOnExecutor, shellQuote, spawnRunner, validateExecutor, type ProcessRunner, type Stage } from "./executor.ts";
+import { LOG_COPY_BYTES } from "./metrics.ts";
+
+export type LogStream = "stdout" | "stderr";
+export interface LogOptions { stage?: string; stream?: string; tailBytes?: number }
+export interface LogReadResult { id: string; logs: { stage: Stage; stream: LogStream; path: string; sha256: string; bytes: number; truncated: boolean; text: string; tailBytes: number }[] }
+export const DEFAULT_LOG_TAIL_BYTES = 16_384, MAX_LOG_TAIL_BYTES = 65_536;
+
+/** Explicit read-only log access. Nothing, including the returned text, is written to the study. */
+export async function readAttemptLogs(dir: string, wanted: string, options: LogOptions = {}, runner: ProcessRunner = spawnRunner): Promise<LogReadResult> {
+  const { study } = openStudy(dir); requireExperiment(study);
+  const attempt = showAttempt(dir, wanted), executor = validateExecutor(attempt.executor);
+  if (attempt.studyId !== study.id || !/^[A-Za-z0-9_-]{1,80}$/.test(attempt.studyId)) throw new Error("attempt logs: study identity differs from the record; restore the original attempt record before reading logs");
+  if (options.stage !== undefined && options.stage !== "candidate" && options.stage !== "evaluator") throw new Error("attempt logs: invalid stage; use --stage candidate or evaluator");
+  if (options.stream !== undefined && options.stream !== "stdout" && options.stream !== "stderr") throw new Error("attempt logs: invalid stream; use --stream stdout or stderr");
+  const count = options.tailBytes ?? DEFAULT_LOG_TAIL_BYTES;
+  if (!Number.isSafeInteger(count) || count < 0 || count > MAX_LOG_TAIL_BYTES) throw new Error(`attempt logs: invalid tail bound; use --tail 0..${MAX_LOG_TAIL_BYTES}`);
+  const root = posix.join(executor.workdir, attempt.studyId, attempt.id), logsDir = posix.join(root, "logs");
+  if (!attempt.paths || attempt.paths.snapshot !== posix.join(root, "snapshot")) throw new Error("attempt logs: workspace differs from recorded executor identity; restore the original record before reading logs");
+  const result: LogReadResult = { id: attempt.id, logs: [] };
+  const stages: Stage[] = options.stage ? [options.stage as Stage] : ["candidate", "evaluator"];
+  const streams: LogStream[] = options.stream ? [options.stream as LogStream] : ["stdout", "stderr"];
+  const requests: { stage: Stage; stream: LogStream; path: string; sha256: string; bytes: number; truncated: boolean }[] = [];
+  for (const stage of stages) for (const stream of streams) {
+    const metadata = attempt.stages[stage]?.evidence?.logs?.[stream];
+    if (!metadata) {
+      if (options.stage) throw new Error("attempt logs: the selected stage has no collected logs; reconcile after the stage finishes, then retry");
+      continue;
+    }
+    const expected = posix.join(logsDir, `${stage}.${stream}.log`);
+    if (metadata.path !== expected || typeof metadata.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(metadata.sha256) || !Number.isSafeInteger(metadata.bytes) || metadata.bytes < 0 || metadata.bytes > LOG_COPY_BYTES || typeof metadata.truncated !== "boolean") throw new Error("attempt logs: invalid log receipt or path; restore the original metadata before reading logs");
+    requests.push({ stage, stream, path: expected, sha256: metadata.sha256, bytes: metadata.bytes, truncated: metadata.truncated });
+  }
+  if (!requests.length) throw new Error("attempt logs: no collected logs yet; reconcile after a stage finishes, then retry");
+  for (const entry of requests) {
+    const controller = new AbortController(), hash = createHash("sha256");
+    let bytes = 0, tail: Buffer = Buffer.alloc(0);
+    const script = [
+      "set -eu", `root=${shellQuote(root)}; logs=${shellQuote(logsDir)}; file=${shellQuote(entry.path)}`,
+      'test -d "$root"; test ! -L "$root"; test -O "$root"; test "$(cd -P "$root" && pwd -P)" = "$root"',
+      'mode=$(stat -c %a "$root" 2>/dev/null || stat -f %Lp "$root"); test "$mode" = 700',
+      'test -d "$logs"; test ! -L "$logs"; test -O "$logs"; test -f "$file"; test ! -L "$file"; test -O "$file"',
+      `head -c ${LOG_COPY_BYTES + 1} "$file"`,
+    ].join("\n");
+    try {
+      const response = await runOnExecutor(executor, "sh", ["-c", script], runner, { signal: controller.signal, timeoutMs: 300_000, stdoutSink: chunk => {
+        if (bytes + chunk.byteLength > LOG_COPY_BYTES) { controller.abort(); throw new Error("log receipt read bound"); }
+        bytes += chunk.byteLength; hash.update(chunk);
+        if (count) tail = chunk.byteLength >= count ? Buffer.from(chunk.subarray(chunk.byteLength - count)) : Buffer.concat([tail.subarray(Math.max(0, tail.length + chunk.byteLength - count)), chunk]);
+      } });
+      if (response.exitCode !== 0 || response.timedOut || response.truncated) throw new Error("log read failed");
+    } catch {
+      controller.abort(); throw new Error(`executor ${executor.host ?? "local"}: log read failed; check the recorded private log file and retry ares attempt logs`);
+    }
+    if (bytes !== entry.bytes || hash.digest("hex") !== entry.sha256) throw new Error("attempt logs: host log differs from the recorded hash or size; inspect the executor copy before retrying");
+    result.logs.push({ ...entry, text: new TextDecoder().decode(tail), tailBytes: tail.byteLength });
+  }
+  return result;
+}

package/src/exp/metrics.ts

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { posix } from "node:path";
+import { plain } from "../study.ts";
+import { runOnExecutor, shellQuote, type ProcessRunner, type Stage } from "./executor.ts";
+import { ARTIFACT_BYTES, ARTIFACT_FILES, ArtifactError, readArtifactArchive } from "./artifacts.ts";
+import type { Attempt, Evaluation } from "./attempts.ts";
+import type { Protocol } from "./protocol.ts";
+
+export const METRICS_BYTES = 65_536;
+export const OUTPUT_METADATA_BYTES = 256 * 1024;
+export const LOG_COPY_BYTES = 16 * 1024 * 1024;
+export interface LogEvidence { path: string; sha256: string; bytes: number; truncated: boolean }
+export interface StageEvidence { logs: { stdout: LogEvidence; stderr: LogEvidence }; outputs: Evaluation["outputs"] }
+export class EvidenceError extends Error {
+  constructor(readonly reason: string, message: string) { super(message); this.name = "EvidenceError"; }
+}
+export class MetricsError extends EvidenceError {
+  constructor(reason: string, cause: string) { super(reason, `evaluator metrics: ${cause}; write /result/metrics.json as an object of all declared metric names and finite numbers, then retry the attempt`); this.name = "MetricsError"; }
+}
+export function validateMetrics(raw: unknown, protocol: Protocol): Evaluation["metrics"] {
+  if (!plain(raw)) throw new MetricsError("malformed-metrics", "a metric-name to number object is required");
+  const declared = new Set(protocol.metrics.map(metric => metric.name));
+  if (Object.keys(raw).some(name => !declared.has(name))) throw new MetricsError("undeclared-metric", "an undeclared metric name is present");
+  if (protocol.metrics.some(metric => !Object.hasOwn(raw, metric.name))) throw new MetricsError("missing-metric", "a declared metric is missing");
+  return protocol.metrics.map(metric => {
+    const value = raw[metric.name];
+    if (typeof value !== "number") throw new MetricsError("invalid-metric-value", "a metric value is not a number");
+    if (!Number.isFinite(value)) throw new MetricsError("nonfinite-metric", "a metric value is not finite");
+    return { name: metric.name, unit: metric.unit, value, provenance: "ares-observed" };
+  });
+}
+export function parseMetrics(bytes: Uint8Array, protocol: Protocol): Evaluation["metrics"] {
+  if (bytes.byteLength > METRICS_BYTES) throw new MetricsError("metrics-limit", "metrics.json exceeds 65536 bytes");
+  let text: string, raw: unknown;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); raw = JSON.parse(text); }
+  catch { throw new MetricsError("malformed-metrics", "metrics.json is not valid UTF-8 JSON"); }
+  // After parsing, only a flat numeric object is valid; reject duplicate keys rather than silently use the last number.
+  const keys = new Set<string>();
+  for (const match of text.matchAll(/"((?:[^"\\]|\\.)*)"\s*:/g)) {
+    let key: string; try { key = JSON.parse(`"${match[1]}"`) as string; } catch { throw new MetricsError("malformed-metrics", "a metric name is malformed"); }
+    if (keys.has(key)) throw new MetricsError("duplicate-metric", "a metric name appears more than once"); keys.add(key);
+  }
+  return validateMetrics(raw, protocol);
+}
+function container(attempt: Attempt, stage: Stage): string {
+  const cid = attempt.stages[stage]?.containerId;
+  if (!cid || !/^[a-f0-9]{64}$/.test(cid)) throw new EvidenceError("missing-receipt", "stage evidence: verified container id is missing; run ares attempt reconcile before collecting evidence");
+  return cid;
+}
+export function outputBudget(outputs: Evaluation["outputs"]): Evaluation["outputs"] {
+  const unique = new Map<string, Evaluation["outputs"][number]>();
+  for (const output of outputs) {
+    const previous = unique.get(output.path);
+    if (previous && (previous.sha256 !== output.sha256 || previous.bytes !== output.bytes)) throw new EvidenceError("changed-output", "stage evidence: output changed after collection; inspect the executor workspace and retry with a fresh attempt");
+    unique.set(output.path, output);
+  }
+  const result = [...unique.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  if (result.length > ARTIFACT_FILES || result.reduce((total, item) => total + item.bytes, 0) > ARTIFACT_BYTES) throw new EvidenceError("artifact-limit", "stage evidence: output budget exceeded; reduce outputs to 500 files and 256 MiB before retrying");
+  if (Buffer.byteLength(JSON.stringify(result, null, 2)) > OUTPUT_METADATA_BYTES) throw new EvidenceError("artifact-limit", "stage evidence: output manifest is too large for the attempt record; shorten artifact paths or reduce their count before retrying");
+  return result;
+}
+function remaining(attempt: Attempt, extra: Evaluation["outputs"] = []) {
+  const outputs = outputBudget([...attempt.outputs, ...extra]);
+  return { maxFiles: ARTIFACT_FILES - outputs.length, maxBytes: ARTIFACT_BYTES - outputs.reduce((total, file) => total + file.bytes, 0) };
+}
+function archiveFailure(error: unknown, attempt: Attempt, step: string): EvidenceError {
+  const reason = error instanceof ArtifactError ? error.code : "artifact-read";
+  return new EvidenceError(reason, `executor ${attempt.executor.host ?? "local"}: ${step} failed; inspect the stage files for unsafe links, oversized output or malformed archives and retry the attempt`);
+}
+/** Only the evaluator's result mount supplies numbers. Candidate files and printed numbers are never parsed. */
+export async function collectEvaluation(attempt: Attempt, runner: ProcessRunner): Promise<Evaluation> {
+  let archive;
+  try { archive = await readArtifactArchive(attempt.executor, "docker", ["cp", `${container(attempt, "evaluator")}:/result/.`, "-"], runner, { capture: "metrics.json", captureBytes: METRICS_BYTES, ...remaining(attempt) }); }
+  catch (error) { throw archiveFailure(error, attempt, "evaluator result archive"); }
+  if (!archive.captured) throw new MetricsError("missing-metrics", "metrics.json is missing from the evaluator result directory");
+  const metrics = parseMetrics(archive.captured, attempt.protocol);
+  const outputs = archive.files.map(file => ({ path: posix.join(attempt.paths.result, file.path), sha256: file.sha256, bytes: file.bytes }));
+  outputBudget([...attempt.outputs, ...outputs]);
+  return { metrics, outputs };
+}
+
+/** Raw copies remain in the executor's private attempt directory; only metadata enters the study. */
+export async function collectStageEvidence(attempt: Attempt, stage: Stage, runner: ProcessRunner): Promise<StageEvidence> {
+  const cid = container(attempt, stage), root = posix.dirname(attempt.paths.snapshot), logs = posix.join(root, "logs");
+  const stdout = posix.join(logs, `${stage}.stdout.log`), stderr = posix.join(logs, `${stage}.stderr.log`), suffix = randomUUID();
+  const statePath = `logs/${stage}.state.json`, stateFile = posix.join(root, statePath);
+  const script = [
+    "set -eu", "umask 077", `logs=${shellQuote(logs)}`,
+    'if test ! -e "$logs"; then mkdir -m 700 "$logs"; fi', 'test -d "$logs"; test ! -L "$logs"; test -O "$logs"',
+    `out=${shellQuote(stdout)}; err=${shellQuote(stderr)}; state=${shellQuote(stateFile)}`,
+    'for file in "$out" "$err" "$state"; do if test -e "$file" || test -L "$file"; then test -f "$file"; test ! -L "$file"; fi; done',
+    `if test -f "$out" && test -f "$err" && test -f "$state" && test "$(wc -c < "$out")" -le ${LOG_COPY_BYTES} && test "$(wc -c < "$err")" -le ${LOG_COPY_BYTES}; then :; else`,
+    `outtmp=${shellQuote(`${stdout}.${suffix}.tmp`)}; errtmp=${shellQuote(`${stderr}.${suffix}.tmp`)}; statetmp=${shellQuote(`${stateFile}.${suffix}.tmp`)}`,
+    `outpipe=${shellQuote(posix.join(logs, `${stage}.${suffix}.stdout.pipe`))}; errpipe=${shellQuote(posix.join(logs, `${stage}.${suffix}.stderr.pipe`))}`,
+    'trap \'rm -f "$outtmp" "$errtmp" "$statetmp" "$outpipe" "$errpipe"\' 0',
+    'mkfifo "$outpipe" "$errpipe"',
+    `head -c ${LOG_COPY_BYTES} < "$outpipe" > "$outtmp" & outpid=$!`,
+    `head -c ${LOG_COPY_BYTES} < "$errpipe" > "$errtmp" & errpid=$!`,
+    `status=0; docker logs ${cid} > "$outpipe" 2> "$errpipe" || status=$?`,
+    'wait "$outpid"; wait "$errpid"', 'outbytes=$(wc -c < "$outtmp"); errbytes=$(wc -c < "$errtmp")',
+    'outcut=false; errcut=false',
+    `if test "$outbytes" -ge ${LOG_COPY_BYTES}; then outcut=true; fi; if test "$errbytes" -ge ${LOG_COPY_BYTES}; then errcut=true; fi`,
+    'if test "$status" -ne 0; then if test "$outcut" = true || test "$errcut" = true; then outcut=true; errcut=true; else exit "$status"; fi; fi',
+    'printf \'{"stdout":%s,"stderr":%s}\\n\' "$outcut" "$errcut" > "$statetmp"',
+    'mv "$outtmp" "$out"; mv "$errtmp" "$err"; mv "$statetmp" "$state"', 'fi',
+    // Archive content only: BSD tar otherwise emits binary xattr PAX and AppleDouble entries.
+    // ponytail: requires GNU tar >= 1.27 or bsdtar with --no-xattrs; unsupported tar
+    // (e.g. BusyBox) fails closed with the generic stage-log collection error, never a metadata fallback.
+    `COPYFILE_DISABLE=1 tar --no-xattrs -C ${shellQuote(root)} -cf - ${shellQuote(`logs/${stage}.stdout.log`)} ${shellQuote(`logs/${stage}.stderr.log`)} ${shellQuote(statePath)}`,
+  ].join("\n");
+  let logArchive;
+  try { logArchive = await readArtifactArchive(attempt.executor, "sh", ["-c", script], runner, { capture: statePath, captureBytes: 1024, maxFiles: 3, maxBytes: LOG_COPY_BYTES * 2 + 1024 }); }
+  catch (error) { throw archiveFailure(error, attempt, "stage log collection"); }
+  let truncated: unknown;
+  try { truncated = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(logArchive.captured)); } catch { /* validated below without copying metadata */ }
+  if (!plain(truncated) || Object.keys(truncated).length !== 2 || typeof truncated.stdout !== "boolean" || typeof truncated.stderr !== "boolean") throw new EvidenceError("invalid-log-state", "stage evidence: truncation metadata is missing or malformed; remove incomplete log copies on the executor host and retry collection");
+  const cuts = truncated as { stdout: boolean; stderr: boolean };
+  const log = (kind: "stdout" | "stderr"): LogEvidence => {
+    const file = logArchive.files.find(item => item.path === `logs/${stage}.${kind}.log`);
+    if (!file) throw new EvidenceError("missing-logs", "stage evidence: a stdout/stderr copy is missing; inspect the executor log directory and retry collection");
+    return { path: posix.join(root, file.path), sha256: file.sha256, bytes: file.bytes, truncated: cuts[kind] || file.bytes >= LOG_COPY_BYTES };
+  };
+  const outputs: Evaluation["outputs"] = [];
+  if (stage === "candidate") {
+    let archive;
+    try { archive = await readArtifactArchive(attempt.executor, "docker", ["cp", `${cid}:/out/.`, "-"], runner, { ...remaining(attempt, outputs) }); }
+    catch (error) { throw archiveFailure(error, attempt, "candidate output archive"); }
+    outputs.push(...archive.files.map(file => ({ path: posix.join(attempt.paths.output, file.path), sha256: file.sha256, bytes: file.bytes })));
+  }
+  outputBudget([...attempt.outputs, ...outputs]);
+  return { logs: { stdout: log("stdout"), stderr: log("stderr") }, outputs };
+}

package/src/exp/protocol.ts

@@ -0,0 +1,145 @@
+import { finalSeedsHash } from "./final.ts";
+import { selectionHash } from "./selection.ts";
+import { existsSync, lstatSync, opendirSync } from "node:fs";
+import { join } from "node:path";
+import { commit, openStudy, plain, readBytesBounded, readJsonFile, readTextBounded, requireExperiment, sha256, type Actor } from "../study.ts";
+
+export interface Limits { cpus: number; memoryMb: number; pidsLimit: number; wallSeconds: number; gpus: number }
+export interface Protocol {
+  v: 1; method: string;
+  candidate: { image: string; command: string[]; env?: Record<string, string> };
+  evaluator: { image: string; command: string[] };
+  metrics: { name: string; unit: string; direction: "max" | "min" }[];
+  seeds: number[]; limits: Limits; network: "none";
+  budget: { maxAttempts: number; maxWallHours: number; maxGpuHours: number };
+}
+export const PROTOCOL_BYTES = 65_536, TASK_FILES = 500, TASK_BYTES = 64 * 1024 * 1024;
+export const LIMIT_BOUNDS = { cpus: [0.1, 256], memoryMb: [16, 1_048_576], pidsLimit: [1, 65_536], wallSeconds: [1, 604_800], gpus: [0, 64] } as const;
+function object(raw: unknown, keys: string[], what: string): Record<string, unknown> {
+  if (!plain(raw)) throw new Error(`${what}: object required; set ${what} to a JSON object`);
+  const extra = Object.keys(raw).find(key => !keys.includes(key));
+  if (extra !== undefined) throw new Error(`${what}: unknown field ${extra}; remove it and use only ${keys.join(", ")}`);
+  return raw;
+}
+function number(raw: unknown, what: string, min: number, max: number, integer = true): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw) || (integer && !Number.isSafeInteger(raw)) || raw < min || raw > max) throw new Error(`${what}: invalid number; set ${what} to a finite ${integer ? "integer" : "number"} in ${min}..${max}`);
+  return raw;
+}
+function array(raw: unknown, what: string, max: number): unknown[] {
+  if (!Array.isArray(raw) || raw.length < 1 || raw.length > max) throw new Error(`${what}: invalid array; set ${what} to a JSON array of 1..${max} items`);
+  return raw;
+}
+// Preserve argv and environment bytes; trimming these would change execution.
+function literal(raw: unknown, what: string, max: number, empty = false): string {
+  if (typeof raw !== "string" || raw.includes("\0") || raw.length > max || (!empty && !raw.trim())) throw new Error(`${what}: invalid text; set ${what} to a ${empty ? "possibly empty" : "nonblank"} string of at most ${max} characters without NUL`);
+  return raw;
+}
+function stage(raw: unknown, what: string, envAllowed: boolean): Protocol["candidate"] {
+  const value = object(raw, envAllowed ? ["image", "command", "env"] : ["image", "command"], what);
+  const image = literal(value.image, `${what}.image`, 512);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/:\-]*@sha256:[a-f0-9]{64}$/.test(image)) throw new Error(`${what}.image: digest-pinned image required; set ${what}.image to name@sha256:<64 lowercase hex digits>`);
+  const command = array(value.command, `${what}.command`, 128).map((v, i) => literal(v, `${what}.command[${i}]`, 4096, true));
+  if (!command[0]?.trim()) throw new Error(`${what}.command[0]: executable missing; set the first argv item to a nonblank executable`);
+  if (value.env === undefined) return { image, command };
+  const rawEnv = object(value.env, Object.keys(plain(value.env) ? value.env : {}), `${what}.env`);
+  if (Object.keys(rawEnv).length > 64) throw new Error(`${what}.env: too many keys; reduce ${what}.env to at most 64 keys`);
+  const entries: [string, string][] = [];
+  for (const [key, val] of Object.entries(rawEnv)) {
+    if (key === "ARES_SEED") throw new Error(`${what}.env: key ARES_SEED is reserved for the selected attempt seed; remove it from candidate.env and select a declared seed with ares attempt run --seed N`);
+    if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error(`${what}.env: key ${key} is reserved for object internals; remove or rename that env entry before setting the protocol`);
+    if (/KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i.test(key)) throw new Error(`${what}.env: key ${key} looks like a secret; pass secrets through the image, not the protocol`);
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${what}.env: key ${key} is invalid; use 1..128 letters, digits or underscores, starting with a letter or underscore`);
+    entries.push([key, literal(val, `${what}.env.${key}`, 4096, true)]);
+  }
+  return { image, command, env: Object.fromEntries(entries) };
+}
+export function validateProtocol(raw: unknown): Protocol {
+  const p = object(raw, ["v", "method", "candidate", "evaluator", "metrics", "seeds", "limits", "network", "budget"], "protocol");
+  if (p.v !== 1) throw new Error("protocol.v: unsupported version; set protocol.v to 1");
+  if (p.network !== "none") throw new Error('protocol.network: network access is unsupported; set protocol.network to "none"');
+  const limitsRaw = object(p.limits, Object.keys(LIMIT_BOUNDS), "protocol.limits");
+  const limits = Object.fromEntries(Object.entries(LIMIT_BOUNDS).map(([key, [min, max]]) => [key, number(limitsRaw[key], `protocol.limits.${key}`, min, max, key !== "cpus")])) as unknown as Limits;
+  const budget = object(p.budget, ["maxAttempts", "maxWallHours", "maxGpuHours"], "protocol.budget");
+  const metrics = array(p.metrics, "protocol.metrics", 100).map((rawMetric): Protocol["metrics"][number] => {
+    const m = object(rawMetric, ["name", "unit", "direction"], "metric");
+    if (m.direction !== "max" && m.direction !== "min") throw new Error("metric.direction: unknown direction; set metric.direction to max or min");
+    return { name: literal(m.name, "metric.name", 128).trim(), unit: literal(m.unit, "metric.unit", 64).trim(), direction: m.direction };
+  });
+  if (new Set(metrics.map(m => m.name)).size !== metrics.length) throw new Error("metrics: duplicate name; give each metric a unique name");
+  const seeds = array(p.seeds, "protocol.seeds", 1000).map(v => number(v, "protocol.seed", -2_147_483_648, 2_147_483_647));
+  if (new Set(seeds).size !== seeds.length) throw new Error("seeds: duplicate seed; remove repeated seeds from protocol.seeds");
+  const protocol: Protocol = { v: 1, method: literal(p.method, "protocol.method", 4000).trim(), candidate: stage(p.candidate, "candidate", true), evaluator: stage(p.evaluator, "evaluator", false), metrics, seeds, limits, network: "none", budget: {
+    maxAttempts: number(budget.maxAttempts, "budget.maxAttempts", 1, 1_000_000),
+    maxWallHours: number(budget.maxWallHours, "budget.maxWallHours", 0.000001, 1_000_000, false),
+    maxGpuHours: number(budget.maxGpuHours, "budget.maxGpuHours", 0, 64_000_000, false),
+  } };
+  if (Buffer.byteLength(JSON.stringify(protocol, null, 2) + "\n") > PROTOCOL_BYTES) throw new Error(`protocol: too large; reduce the formatted protocol to at most ${PROTOCOL_BYTES} bytes`);
+  return protocol;
+}
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (plain(value)) return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+export function protocolHash(protocol: Protocol): string {
+  const { budget: _budget, ...comparable } = validateProtocol(protocol);
+  return sha256(canonical(comparable));
+}
+export function readProtocol(dir: string): Protocol | undefined {
+  const file = join(dir, "design", "protocol.json");
+  return existsSync(file) ? validateProtocol(readJsonFile(file, PROTOCOL_BYTES)) : undefined;
+}
+/** Hash unambiguous sorted [relative path, file hash] pairs; directory entries are never followed. */
+export function taskTreeHash(dir: string): string {
+  const root = join(dir, "task"), entries: [string, string][] = [];
+  let bytes = 0, directories = 0;
+  function walk(relative: string, depth: number): void {
+    const path = relative ? join(root, relative) : root, label = relative ? `task/${relative}` : "task/";
+    let stat;
+    try { stat = lstatSync(path); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`${label}: missing; write task/task.md and task/evaluator/ before ares protocol`);
+      throw new Error(`${label}: metadata could not be read; check its permissions and restore a readable task tree`);
+    }
+    if (stat.isSymbolicLink()) throw new Error(`${label}: symlink refused; replace it with a regular file or directory inside task/`);
+    if (!relative && !stat.isDirectory()) throw new Error("task/: directory required; replace task with a directory containing task.md and evaluator/");
+    if (stat.isDirectory()) {
+      if (depth > 64 || ++directories > 1000) throw new Error(`${label}: too many directories or nesting too deep; reduce task/ to at most 1000 directories and 64 levels`);
+      const directory = opendirSync(path);
+      try {
+        for (let entry = directory.readSync(); entry; entry = directory.readSync()) walk(relative ? `${relative}/${entry.name}` : entry.name, depth + 1);
+      } finally { directory.closeSync(); }
+    } else {
+      if (!stat.isFile()) throw new Error(`${label}: regular files only; replace this special file with a regular file or remove it`);
+      if (entries.length >= TASK_FILES) throw new Error(`task/: more than ${TASK_FILES} files; remove files until task/ contains at most ${TASK_FILES}`);
+      if (stat.size > TASK_BYTES - bytes) throw new Error(`task/: larger than ${TASK_BYTES} bytes; reduce total task/ file bytes to at most ${TASK_BYTES}`);
+      const content = readBytesBounded(path, TASK_BYTES - bytes);
+      bytes += content.length; entries.push([relative, sha256(content)]);
+    }
+  }
+  walk("", 0);
+  return sha256(JSON.stringify(entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+}
+export function designBinding(dir: string): string | undefined {
+  return readDesign(dir)?.binding;
+}
+/** Capture the validated protocol and its raw-byte seal together for a frozen attempt. */
+export function readDesign(dir: string): { protocol: Protocol; treeHash: string; binding: string } | undefined {
+  const file = join(dir, "design", "protocol.json");
+  if (!existsSync(file)) return undefined;
+  const text = readTextBounded(file, PROTOCOL_BYTES);
+  let raw: unknown; try { raw = JSON.parse(text); } catch { throw new Error("protocol: invalid JSON; restore design/protocol.json with a valid ares protocol input"); }
+  const protocol = validateProtocol(raw), treeHash = taskTreeHash(dir);
+  const selected = selectionHash(dir, protocol), reserved = finalSeedsHash(dir, protocol);
+  return { protocol, treeHash, binding: sha256(JSON.stringify([sha256(text), treeHash, ...(selected !== undefined ? [selected] : []), ...(reserved !== undefined ? [reserved] : [])])) };
+}
+/** Caller holds the study lock, as with setScope. Validate everything before any write. */
+export function setProtocol(dir: string, raw: unknown, actor: Actor): Protocol {
+  requireExperiment(openStudy(dir).study);
+  const protocol = validateProtocol(raw), treeHash = taskTreeHash(dir), text = JSON.stringify(protocol, null, 2) + "\n";
+  // Never commit a protocol that makes its existing selection unreadable.
+  selectionHash(dir, protocol);
+  finalSeedsHash(dir, protocol);
+  commit(dir, [[join(dir, "design", "protocol.json"), text, PROTOCOL_BYTES]], [{ actor, type: "protocol.set", data: { sha256: sha256(text), protocolHash: protocolHash(protocol), treeHash } }]);
+  return protocol;
+}

package/src/exp/selection.ts

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { boundedText, commit, onlyKeys, openStudy, plain, readTextBounded, requireExperiment, sha256, type Actor } from "../study.ts";
+import type { Protocol } from "./protocol.ts";
+
+export interface Selection { v: 1; run: string; metric: string; baseline: { commit: string }; minSeeds: number; minDelta: number }
+export const SELECTION_BYTES = 65_536;
+const compatible = "use an ares version that supports this selection, keeping design/selection.json unchanged";
+export function selectionPath(dir: string): string { return join(dir, "design", "selection.json"); }
+export function validateSelection(raw: unknown, protocol: Protocol): Selection {
+  try {
+    if (!plain(raw)) throw new Error("selection: JSON object required");
+    if (raw.v !== 1) throw new Error(`selection.v: unsupported version; ${compatible}`);
+    onlyKeys(raw, ["v", "run", "metric", "baseline", "minSeeds", "minDelta"], "selection");
+    if (typeof raw.run !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(raw.run)) throw new Error("selection.run: use 1..64 letters, digits, underscores or hyphens, starting with a letter or digit");
+    if (["ablate", "final", "posthoc"].includes(raw.run)) throw new Error(`selection.run: ${raw.run} is a reserved phase run; choose another run such as investigate`);
+    const metric = boundedText(raw.metric, "selection.metric", 128);
+    if (!protocol.metrics.some(m => m.name === metric)) throw new Error("selection.metric: undeclared; choose a metric from design/protocol.json");
+    if (!plain(raw.baseline)) throw new Error("selection.baseline: object with commit required");
+    onlyKeys(raw.baseline, ["commit"], "selection.baseline");
+    if (typeof raw.baseline.commit !== "string" || !/^[a-fA-F0-9]{40}$/.test(raw.baseline.commit)) throw new Error("selection.baseline.commit: full 40-hex commit required");
+    if (!Number.isSafeInteger(raw.minSeeds) || (raw.minSeeds as number) < 1 || (raw.minSeeds as number) > protocol.seeds.length) throw new Error(`selection.minSeeds: integer in 1..${protocol.seeds.length} required (declared protocol seed count)`);
+    if (typeof raw.minDelta !== "number" || !Number.isFinite(raw.minDelta) || raw.minDelta < 0) throw new Error("selection.minDelta: finite number >= 0 required in the metric's unit");
+    return { v: 1, run: raw.run, metric, baseline: { commit: raw.baseline.commit.toLowerCase() }, minSeeds: raw.minSeeds as number, minDelta: raw.minDelta };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "selection: invalid rule";
+    throw new Error(message.includes(compatible) ? message : `${message}; correct the rule and run ares selection <dir> --file PATH again`);
+  }
+}
+function record(dir: string, protocol: Protocol): { selection: Selection; text: string } | undefined {
+  const file = selectionPath(dir);
+  if (!existsSync(file)) return undefined;
+  let text: string;
+  try { text = readTextBounded(file, SELECTION_BYTES); }
+  catch { throw new Error(`design/selection.json: unreadable, non-regular, invalid UTF-8 or larger than ${SELECTION_BYTES} bytes; restore a readable regular UTF-8 rule within that limit before ares selection`); }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new Error("design/selection.json: invalid JSON; restore its last valid rule before running ares selection"); }
+  return { selection: validateSelection(raw, protocol), text };
+}
+export function readSelection(dir: string, protocol: Protocol): Selection | undefined { return record(dir, protocol)?.selection; }
+/** The design seal binds original file bytes, including formatting, just like the protocol. */
+export function selectionHash(dir: string, protocol: Protocol): string | undefined {
+  const value = record(dir, protocol);
+  return value === undefined ? undefined : sha256(value.text);
+}
+/** Caller holds the study lock. Identical bytes do not move the investigation cutoff. */
+export function setSelection(dir: string, raw: unknown, protocol: Protocol, actor: Actor) {
+  requireExperiment(openStudy(dir).study);
+  const selection = validateSelection(raw, protocol), previous = record(dir, protocol);
+  const text = JSON.stringify(selection, null, 2) + "\n", hash = sha256(text), changed = previous?.text !== text;
+  if (changed) commit(dir, [[selectionPath(dir), text, SELECTION_BYTES]], [{ actor, type: "selection.set", data: { sha256: hash, run: selection.run, metric: selection.metric } }]);
+  return { selection, sha256: hash, changed };
+}