@staix/agent-research 0.0.0-stage → 0.2.1

package/src/paper/check.ts

@@ -0,0 +1,181 @@
+import { CopilotAcceptError } from "../copilot.ts";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { openStudy, readTextBounded, sha256 } from "../study.ts";
+import { loadCandidates } from "../lit/candidates.ts";
+import { checkCitations, citationOccurrences } from "../lit/cite.ts";
+import { readProtocol } from "../exp/protocol.ts";
+import { readSelection } from "../exp/selection.ts";
+import { investigateResultPath, readClosedInvestigation } from "../exp/investigate.ts";
+import { finalResultPath } from "../exp/final.ts";
+import { MANUSCRIPT_BYTES, parsePlaceholders, resolvePlaceholders } from "./placeholders.ts";
+
+export const MAX_CODE_NUMBERS = 500;
+export interface PaperFinding { code: "bare-number" | "unresolved-ref" | "unaccepted-draft" | "bad-format" | "unknown-citation" | "unverified-citation" | "missing-negative-result"; start: number; end: number; line: number; column: number; message: string }
+function blank(text: string, mask: Uint8Array): string { return text.split("").map((char, index) => mask[index] && char !== "\n" && char !== "\r" ? " " : char).join(""); }
+function mark(mask: Uint8Array, start: number, end: number) { mask.fill(1, start, end); }
+function escaped(text: string, index: number): boolean { let slashes = 0; while (index > 0 && text[--index] === "\\") slashes++; return slashes % 2 === 1; }
+/** Masks syntax-only destinations and code while retaining original offsets. Visible link labels remain prose. */
+function markdownMask(text: string, knownHidden?: Uint8Array): { mask: Uint8Array; code: Uint8Array; hidden: Uint8Array } {
+  const mask = new Uint8Array(text.length), protectedText = new Uint8Array(text.length), tokens = parsePlaceholders(text);
+  for (const token of [...tokens.placeholders, ...tokens.findings]) mark(protectedText, token.start, token.end);
+  let fence: { char: string; length: number } | undefined, paragraph = false, indented = false;
+  const listIndents: number[] = [];
+  for (const match of text.matchAll(/[^\n]*(?:\n|$)/g)) {
+    const line = match[0], start = match.index;
+    if (!line) continue;
+    if (!line.trim()) { paragraph = false; continue; }
+    if (!fence && knownHidden?.[start + /^[ \t]*/.exec(line)![0].length]) { paragraph = false; continue; }
+    if (fence) {
+      mark(mask, start, start + line.length);
+      const close = /^ {0,3}(`+|~+)[ \t]*\r?\n?$/.exec(line);
+      if (close && close[1]![0] === fence.char && close[1]!.length >= fence.length) fence = undefined;
+      paragraph = false; indented = false;
+    } else if (!protectedText[start]) {
+      const open = /^ {0,3}(`{3,}|~{3,})([^\r\n]*)/.exec(line);
+      if (open && !(open[1]![0] === "`" && open[2]!.includes("`"))) { fence = { char: open[1]![0]!, length: open[1]!.length }; mark(mask, start, start + line.length); paragraph = false; indented = false; }
+      else {
+        const prefix = /^[ \t]*/.exec(line)![0];
+        let indent = 0; for (const char of prefix) indent += char === "\t" ? 4 - indent % 4 : 1;
+        const item = /^[ \t]*(?:[-+*]|[0-9]+[.)])[ \t]+/.exec(line);
+        let parent = listIndents.length; while (parent && listIndents[parent - 1]! > indent) parent--;
+        if (item && indent < (listIndents[parent - 1] ?? 0) + 4) {
+          listIndents.length = parent; listIndents.push(item[0].length); paragraph = true; indented = false;
+        }
+        else {
+          if (!paragraph) listIndents.length = parent;
+          if (indent >= (listIndents.at(-1) ?? 0) + 4 && (indented || !paragraph)) { mark(mask, start, start + line.length); indented = true; }
+          else { indented = false; paragraph = !/^ {0,3}(?:#{1,6}[ \t]|(?:---+|\*\*\*+|___+)[ \t]*$)/.test(line.trimEnd()); }
+        }
+      }
+    }
+  }
+  // Backtick runs must have an exactly matching closer; unmatched delimiters remain prose.
+  const runs = [...text.matchAll(/`+/g)].filter(hit => !mask[hit.index] && !protectedText[hit.index] && !knownHidden?.[hit.index]);
+  const regions: number[] = []; let region = 0, previous = 0;
+  for (const hit of runs) {
+    if (/\n[ \t]*\r?\n/.test(text.slice(previous, hit.index)) || mask.subarray(previous, hit.index).includes(1)) region++;
+    regions.push(region); previous = hit.index + hit[0].length;
+  }
+  const next = new Map<number, number>(), closers = new Map<string, number>();
+  for (let i = runs.length - 1; i >= 0; i--) {
+    const hit = runs[i]!, key = `${regions[i]}:${hit[0].length}`;
+    if (closers.has(key)) next.set(i, closers.get(key)!); closers.set(key, i);
+  }
+  for (let i = 0; i < runs.length; i++) {
+    if (escaped(text, runs[i]!.index)) continue;
+    const close = next.get(i);
+    if (close !== undefined) { mark(mask, runs[i]!.index, runs[close]!.index + runs[close]![0].length); i = close; }
+  }
+  const code = mask.slice();
+  const labels: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    if (mask[i] || protectedText[i] || knownHidden?.[i] || (text[i] !== "<" && text[i] !== "]" && text[i] !== "[") || escaped(text, i)) continue;
+    if (text[i] === "[") { labels.push(i); continue; }
+    if (text[i] === "<") {
+      const end = text.indexOf(">", i + 1), target = text.slice(i + 1, end < 0 ? i + 1 : end);
+      if (end >= 0 && /^(?:[A-Za-z][A-Za-z0-9+.-]{1,31}:[^\s<>]*|[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+)$/.test(target)) { mark(mask, i, end + 1); i = end; }
+    }
+    if (text[i] !== "]") continue;
+    const label = labels.pop();
+    if (label === undefined || text[i + 1] !== "(") continue;
+    let start = i + 2; while (/\s/.test(text[start] ?? "") && start < text.length) start++;
+    let end = start, depth = 0;
+    if (text[start] === "<") { end = text.indexOf(">", start + 1); if (end < 0) continue; end++; }
+    else {
+      while (end < text.length) {
+        const char = text[end]!;
+        if (char === "\\") { end += 2; continue; }
+        if (/\s/.test(char) || (char === ")" && depth === 0)) break;
+        if (char === "(") depth++;
+        if (char === ")") depth--;
+        end++;
+      }
+      if (depth) continue;
+    }
+    let tail = end; while (/\s/.test(text[tail] ?? "") && tail < text.length) tail++;
+    if (["\"", "'"].includes(text[tail] ?? "")) {
+      const quote = text[tail++]!; while (tail < text.length && (text[tail] !== quote || escaped(text, tail))) tail++;
+      if (tail >= text.length) continue; tail++; while (/\s/.test(text[tail] ?? "") && tail < text.length) tail++;
+    }
+    if (text[tail] === ")") mark(mask, start, end);
+  }
+  const hidden = new Uint8Array(text.length); let hasComment = false;
+  for (const comment of text.matchAll(/<!--[\s\S]*?(?:-->|$)/g)) {
+    if (!code[comment.index] && !protectedText[comment.index]) { mark(mask, comment.index, comment.index + comment[0].length); mark(hidden, comment.index, comment.index + comment[0].length); hasComment = true; }
+  }
+  // Reference definitions do not count as visible negative-result prose; labels/titles still get numeric checks.
+  for (const match of text.matchAll(/^ {0,3}\[[^\]\n]+\]:[ \t]*(<[^>\n]*>|[^\s]+)(?:[ \t]|$)/gm)) {
+    const target = match[1]!, start = match.index + match[0].lastIndexOf(target);
+    if (!mask[start] && !protectedText[start]) {
+      mark(mask, start, start + target.length);
+      const lineEnd = text.indexOf("\n", match.index); mark(hidden, match.index, lineEnd < 0 ? text.length : lineEnd);
+    }
+  }
+  // Reclassify once with non-code comments excluded, so a fence inside a comment cannot hide later prose.
+  if (!knownHidden && hasComment) return markdownMask(text, hidden);
+  return { mask, code, hidden };
+}
+export function manuscriptPath(dir: string): string { return join(dir, "paper", "manuscript.md"); }
+export function checkPaper(dirArg: string) {
+  const { dir, study } = openStudy(dirArg), file = manuscriptPath(dir);
+  let manuscript: string;
+  try { manuscript = readTextBounded(file, MANUSCRIPT_BYTES); }
+  catch { throw new Error("paper manuscript: missing, unreadable, invalid UTF-8, non-regular or larger than 2 MiB; restore paper/manuscript.md as a bounded UTF-8 regular file before paper check"); }
+  const masks = markdownMask(manuscript), prose = blank(manuscript, masks.mask), parsed = parsePlaceholders(prose), resolution = resolvePlaceholders(dir, prose);
+  const lines = [0]; for (let i = 0; i < manuscript.length; i++) if (manuscript[i] === "\n") lines.push(i + 1);
+  const location = (start: number) => {
+    let lo = 0, hi = lines.length; while (lo + 1 < hi) { const mid = (lo + hi) >>> 1; if (lines[mid]! <= start) lo = mid; else hi = mid; }
+    return { line: lo + 1, column: start - lines[lo]! + 1 };
+  };
+  const finding = (code: PaperFinding["code"], start: number, end: number, message: string): PaperFinding => ({ code, start, end, ...location(start), message });
+  const findings: PaperFinding[] = resolution.findings.map(f => finding(f.code, f.start, f.end, f.message));
+  const codeNumbers: { value: string; line: number; column: number }[] = [];
+  let codeNumberCount = 0;
+  const codeText = manuscript.split("").map((char, index) => masks.code[index] || char === "\n" || char === "\r" ? char : " ").join("");
+  for (const hit of codeText.matchAll(/\p{Nd}+(?:[.,]\p{Nd}+)*/gu)) {
+    codeNumberCount++;
+    if (codeNumbers.length < MAX_CODE_NUMBERS) codeNumbers.push({ value: hit[0], ...location(hit.index) });
+  }
+  const numberMask = masks.mask.slice(), citationMask = masks.mask.slice();
+  for (const placeholder of parsed.placeholders) {
+    mark(numberMask, placeholder.start, placeholder.end);
+    if (placeholder.kind === "number") mark(citationMask, placeholder.start, placeholder.end);
+  }
+  for (const problem of parsed.findings) { mark(numberMask, problem.start, problem.end); mark(citationMask, problem.start, problem.end); }
+  const citationText = blank(manuscript, citationMask), citations = checkCitations(citationText, loadCandidates(dir));
+  const groups = new Map<number, number>();
+  for (const hit of citationOccurrences(citationText)) {
+    mark(numberMask, hit.start, hit.end); groups.set(hit.groupStart, hit.groupEnd);
+    if (citations.unknown.includes(hit.key)) findings.push(finding("unknown-citation", hit.start, hit.end, `citation ${hit.key}: unknown key; add and verify the reference, then regenerate the bibliography`));
+    else if (citations.notVerified.includes(hit.key)) findings.push(finding("unverified-citation", hit.start, hit.end, `citation ${hit.key}: not included and identifier-verified; inspect ares lit list, verify the reference or exclude this citation`));
+  }
+  // Only locator-number syntax is exempt inside citation brackets; arbitrary prose numbers remain checked.
+  const locators = /(?:^|[^\p{L}\p{N}_])(p\.|pp\.|sec\.|§|ch\.|chap\.|fig\.|tbl\.|table|eq\.|l\.|ll\.|para\.)[ \t\r\n]*(\p{Nd}+(?:[ \t]*(?:--?|–|—)[ \t]*\p{Nd}+)?(?:[ \t]*,[ \t]*\p{Nd}+(?:[ \t]*(?:--?|–|—)[ \t]*\p{Nd}+)?)*)(?=$|[\s,;:\]\)]|\.(?!\p{Nd}))/giu;
+  for (const [start, end] of groups) {
+    const group = citationText.slice(start, end);
+    for (const hit of group.matchAll(locators)) {
+      const numbers = hit[2]!, offset = start + hit.index + hit[0].length - numbers.length;
+      mark(numberMask, offset, offset + numbers.length);
+    }
+  }
+  if (study.mode === "experiment") {
+    for (const match of manuscript.matchAll(/^ {0,3}[0-9]+[.)](?=[ \t])/gm)) mark(numberMask, match.index, match.index + match[0].length);
+    for (const match of blank(manuscript, numberMask).matchAll(/\p{Nd}+(?:[.,]\p{Nd}+)*/gu)) findings.push(finding("bare-number", match.index, match.index + match[0].length, "prose number has no evidence ref; use {{n:REF}} for a measured value or {{lit:TEXT}} for a reviewer-visible literal"));
+    const requireRef = (ref: string) => {
+      if (!parsed.placeholders.some(p => p.kind === "number" && p.ref === ref && p.format === undefined && !masks.hidden[p.start])) findings.push(finding("missing-negative-result", 0, 0, `paper omits ${ref}; include {{n:${ref}}} in prose so the result cannot be hidden`));
+    };
+    if (existsSync(finalResultPath(dir))) requireRef("final.status");
+    try {
+      const protocol = readProtocol(dir), rule = protocol ? readSelection(dir, protocol) : undefined;
+      if (rule && existsSync(investigateResultPath(dir, rule.run))) {
+        try { if (readClosedInvestigation(dir).result.winner === null) requireRef("investigate.reason"); }
+        catch (error) { findings.push(error instanceof CopilotAcceptError ? finding("unaccepted-draft", 0, 0, error.message) : finding("unresolved-ref", 0, 0, "investigate result is not current and closed; run ares investigate close before checking the paper")); }
+      }
+    } catch (error) { findings.push(error instanceof CopilotAcceptError ? finding("unaccepted-draft", 0, 0, error.message) : finding("unresolved-ref", 0, 0, "experiment design or selection is invalid; restore the current validated inputs before paper check")); }
+  }
+  let rendered = "", cursor = 0;
+  for (const entry of resolution.placeholders) { rendered += manuscript.slice(cursor, entry.placeholder.start) + entry.rendered; cursor = entry.placeholder.end; }
+  rendered += manuscript.slice(cursor);
+  return { ok: findings.length === 0, manuscriptSha256: sha256(manuscript), rendered, placeholders: resolution.placeholders, findings: findings.sort((a, b) => a.start - b.start || a.code.localeCompare(b.code)), literals: resolution.literals, codeNumbers, codeNumberCount, citations };
+}

package/src/paper/placeholders.ts

@@ -0,0 +1,118 @@
+import { CopilotAcceptError } from "../copilot.ts";
+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" | "unaccepted-draft"; 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 (error) { cache.set(key, error instanceof CopilotAcceptError ? error : 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 (error) {
+      if (error instanceof CopilotAcceptError) { findings.push({ ...placeholder, code: "unaccepted-draft", message: error.message }); continue; }
+      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,127 @@
+import { requireCopilotAccept, CopilotAcceptError } from "../copilot.ts";
+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);
+  requireCopilotAccept(dir, "paper");
+  const 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);
+  requireCopilotAccept(dir, "paper");
+  const 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 }[] = [];
+  for (const artifact of ["paper", "reviews"] as const) {
+    try { requireCopilotAccept(dir, artifact); }
+    catch (error) { unmet.push({ code: `accept:${artifact}`, message: error instanceof Error ? error.message : `copilot ${artifact} acceptance unavailable; inspect ares gate list` }); }
+  }
+  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" }); } }
+  for (const finding of check?.findings ?? []) if (finding.code === "unaccepted-draft" && !unmet.some(item => item.code === "accept-source" && item.message === finding.message)) unmet.unshift({ code: "accept-source", message: finding.message });
+  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), accept = report.unmet.find(item => item.code.startsWith("accept:") || item.code === "accept-source");
+  if (accept) throw new CopilotAcceptError(accept.message);
+  if (!report.ready) throw new Error(`gate review: ${report.unmet.map(item => `${item.code}: ${item.message}`).join("; ")}; inspect ares review show before approval`);
+}