toolroll 0.5.0

package/dist/retention-ui.js

@@ -0,0 +1,39 @@
+/**
+ * Settings → Retention (v105): how long each kind of data is kept, and what
+ * the next daily sweep would remove. An instance operator's page; changes
+ * take a step-up.
+ */
+import { bytesWords } from "./storage.js";
+import { PERIOD_CHOICES, RETENTION_KINDS, countWords, periodWords } from "./retention.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const RETENTION_CSS = `.retention{max-width:720px;min-width:0}.retention-next{margin:0 0 16px}` +
+    `.retention form{display:grid;gap:0}.retention .kind{display:grid;grid-template-columns:minmax(0,1fr) 11rem;gap:4px 16px;align-items:center;padding:12px 0;border-bottom:1px solid var(--border)}` +
+    `.retention .kind .name{font-weight:500;font-size:.875rem}.retention .kind .meta{grid-column:1;margin:0}.retention .kind select{grid-column:2;grid-row:1/span 2;width:100%;min-height:44px}` +
+    `.retention .step-up{display:grid;gap:4px;font-size:.8125rem;margin:16px 0 8px;max-width:20rem}.retention .step-up input{min-height:44px}.retention button{justify-self:start;min-height:44px}` +
+    `@media (max-width:560px){.retention .kind{grid-template-columns:minmax(0,1fr)}.retention .kind select{grid-column:1;grid-row:auto}}`;
+const listWords = (parts) => parts.length < 2 ? parts.join("") : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+/** The next sweep in a line: what goes and about how much space, or that nothing is due. */
+function nextWords(view) {
+    if (RETENTION_KINDS.every(({ kind }) => view.periods[kind] === null))
+        return "Everything is kept forever.";
+    const due = view.next.filter(one => one.count > 0);
+    if (due.length === 0)
+        return "Nothing is old enough to remove yet.";
+    const bytes = due.reduce((sum, one) => sum + one.bytes, 0);
+    return `The next daily sweep removes ${listWords(due.map(countWords))} (about ${bytesWords(bytes)}).`;
+}
+export function retentionHtml(view, notice) {
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const rows = RETENTION_KINDS.map(({ kind, label, detail }) => {
+        const current = view.periods[kind];
+        const choices = PERIOD_CHOICES.includes(current) ? PERIOD_CHOICES : [...PERIOD_CHOICES.slice(0, -1), current, null].sort((a, b) => (a ?? Infinity) - (b ?? Infinity));
+        const options = choices.map(days => `<option value="${days === null ? "forever" : days}"${days === current ? " selected" : ""}>${days === null ? "Forever" : `${periodWords(days)[0].toUpperCase()}${periodWords(days).slice(1)}`}</option>`).join("");
+        return `<div class="kind" data-kind="${kind}"><label class="name" for="keep-${kind}">${e(label)}</label><p class="meta">${e(detail)}</p><select id="keep-${kind}" name="${kind}">${options}</select></div>`;
+    }).join("");
+    const last = view.lastSweep === null ? "" : ` Last sweep ${e(view.lastSweep.slice(0, 10))}.`;
+    return `<article class="retention">${note}<p class="retention-next" data-retention-next>${e(nextWords(view))}${last}</p>` +
+        `<form method="post" action="/settings/retention"><input type="hidden" name="csrf" value="${e(view.csrf)}">${rows}` +
+        `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>` +
+        `<button type="submit">Save</button></form>` +
+        `<p class="meta">Never removed: the action ledger, and anything a task still needs (unfinished tasks, results not yet completed, anything on hold).</p></article>`;
+}

package/dist/retention.d.ts

@@ -0,0 +1,72 @@
+import type { Store } from "./store.js";
+export declare const RETENTION_SCHEMA = "\nCREATE TABLE IF NOT EXISTS retention_setting (\n  kind       TEXT PRIMARY KEY CHECK (kind IN ('evidence', 'checkouts', 'chat', 'notifications')),\n  -- NULL is forever; a row only exists once someone chose.\n  days       INTEGER CHECK (days IS NULL OR (days >= 7 AND days <= 3650)),\n  updated_by TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n";
+export type RetentionKind = "evidence" | "checkouts" | "chat" | "notifications";
+export type RetentionPeriods = Record<RetentionKind, number | null>;
+export declare const RETENTION_KINDS: readonly {
+    kind: RetentionKind;
+    label: string;
+    detail: string;
+}[];
+/** The periods the page offers; the command line takes any number of days from 7 to 3650. */
+export declare const PERIOD_CHOICES: readonly (number | null)[];
+export declare const MIN_DAYS = 7;
+export declare const MAX_DAYS = 3650;
+/** A sweep is due once a day. */
+export declare const SWEEP_EVERY_MS = 86400000;
+/** At most this many runs, messages, notifications or records go per kind per sweep; the next sweep takes the rest. */
+export declare const SWEEP_BATCH = 2000;
+export declare const FOREVER: RetentionPeriods;
+export declare function isRetentionKind(value: string): value is RetentionKind;
+/** "forever", or a number of days ("90", "90d"), weeks ("12w") or years ("1y"); undefined when it's none of those or out of range. */
+export declare function parsePeriod(text: string): number | null | undefined;
+export declare function periodWords(days: number | null): string;
+export type RetentionCount = {
+    kind: RetentionKind;
+    days: number | null;
+    count: number;
+    bytes: number;
+    more: boolean;
+};
+export type RetentionPlan = {
+    at: string;
+    counts: RetentionCount[];
+    items: RetentionItems;
+};
+type RetentionItems = {
+    evidence: {
+        run: number;
+        bytes: number;
+    }[];
+    checkouts: {
+        path: string;
+        releasedAt: string;
+        bytes: number;
+    }[];
+    chat: {
+        id: number;
+        bytes: number;
+    }[];
+    notifications: {
+        id: number;
+        bytes: number;
+    }[];
+};
+/** What a sweep would delete now under `periods`, and how much space it would free. Reads only. */
+export declare function retentionPlan(store: Store, evidenceRoot: string, now: Date, periods?: RetentionPeriods): RetentionPlan;
+export type RetentionSweep = {
+    at: string;
+    counts: RetentionCount[];
+    freed: number;
+    ledgerId: number | null;
+};
+/** Delete what the plan names (checking each again first) and write one ledger entry. Nothing to do when every kind is forever. */
+export declare function sweepRetention(store: Store, evidenceRoot: string, now: Date, actor?: string): RetentionSweep;
+/** Whether a day has passed since the last sweep. */
+export declare function retentionDue(store: Store, now: Date): boolean;
+/** The daily sweep, when it's due: one worker takes it (the cursor moves in the same transaction). */
+export declare function dailyRetention(store: Store, evidenceRoot: string, now: Date): RetentionSweep | null;
+export declare function lastSweepAt(store: Store): string | null;
+export declare function countWords(one: Pick<RetentionCount, "kind" | "count">): string;
+/** "3 runs' evidence, 120 chat messages; about 41 MB freed", or "nothing was due". */
+export declare function sweepWords(counts: readonly RetentionCount[], freed: number): string;
+export {};

package/dist/retention.js

@@ -0,0 +1,288 @@
+/**
+ * Retention (v105): how long Toolroll keeps run evidence and logs,
+ * finished checkouts' records, chat messages and notifications. Each kind
+ * keeps everything ("forever") until an instance operator chooses a period;
+ * a daily sweep then deletes what is older than it and writes one action
+ * ledger entry saying what went and about how much space it freed.
+ *
+ * Never deleted, whatever the settings: the action ledger (it is append-only),
+ * and anything a task still needs. A task still needs its things until it is
+ * cancelled, or done with its result marked complete: an unfinished task
+ * (failed included: it can be requeued), a result not yet completed, a task
+ * on hold, one with a live run, a release candidate, and the source of an
+ * unfinished revision all keep theirs.
+ *
+ * Evidence goes as files: a run's evidence folder is emptied and a note left
+ * in it, so its pages say the files were removed by retention rather than
+ * damaged. Its database records (hashes, sizes, how each was captured) stay.
+ */
+import { existsSync, lstatSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { RETENTION_NOTE } from "./evidence.js";
+import { COMPLETION_ACTION } from "./result-completion.js";
+import { bytesWords, treeBytes } from "./storage.js";
+export const RETENTION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS retention_setting (
+  kind       TEXT PRIMARY KEY CHECK (kind IN ('evidence', 'checkouts', 'chat', 'notifications')),
+  -- NULL is forever; a row only exists once someone chose.
+  days       INTEGER CHECK (days IS NULL OR (days >= 7 AND days <= 3650)),
+  updated_by TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+export const RETENTION_KINDS = [
+    { kind: "evidence", label: "Run evidence and logs", detail: "Diffs, check logs, screenshots and reports saved for each run" },
+    { kind: "checkouts", label: "Finished checkout records", detail: "Records of build checkouts that were let go and are no longer on disk" },
+    { kind: "chat", label: "Chat messages", detail: "Messages in lead and team chats" },
+    { kind: "notifications", label: "Notifications", detail: "Delivered or dismissed notifications" },
+];
+/** The periods the page offers; the command line takes any number of days from 7 to 3650. */
+export const PERIOD_CHOICES = [30, 90, 180, 365, 730, null];
+export const MIN_DAYS = 7;
+export const MAX_DAYS = 3650;
+const DAY_MS = 86_400_000;
+/** A sweep is due once a day. */
+export const SWEEP_EVERY_MS = DAY_MS;
+/** At most this many runs, messages, notifications or records go per kind per sweep; the next sweep takes the rest. */
+export const SWEEP_BATCH = 2000;
+const SWEEP_CURSOR = "retention:last-sweep";
+export const FOREVER = { evidence: null, checkouts: null, chat: null, notifications: null };
+export function isRetentionKind(value) {
+    return RETENTION_KINDS.some(one => one.kind === value);
+}
+/** "forever", or a number of days ("90", "90d"), weeks ("12w") or years ("1y"); undefined when it's none of those or out of range. */
+export function parsePeriod(text) {
+    const value = text.trim().toLowerCase();
+    if (value === "forever" || value === "never")
+        return null;
+    const match = /^(\d{1,4})\s*(d|days?|w|weeks?|y|years?)?$/.exec(value);
+    if (match === null)
+        return undefined;
+    const unit = match[2]?.[0] ?? "d";
+    const days = Number(match[1]) * (unit === "y" ? 365 : unit === "w" ? 7 : 1);
+    return days >= MIN_DAYS && days <= MAX_DAYS ? days : undefined;
+}
+export function periodWords(days) {
+    if (days === null)
+        return "forever";
+    if (days % 365 === 0)
+        return days === 365 ? "1 year" : `${days / 365} years`;
+    return `${days} days`;
+}
+/** Tasks that no longer need anything kept: cancelled, or done with their result marked complete; not on hold, not
+ * running, not a release candidate, and no revision below it (at any depth) still unfinished — cancelled or completed,
+ * not merely Ready: a revision's review reads its ancestors' evidence. `r` is the task_ref alias. */
+function finishedTask(r) {
+    return `EXISTS (SELECT 1 FROM task t WHERE t.id = ${r}.external_id AND ${r}.backend = 'built-in' AND (t.state = 'cancelled' OR (t.state = 'done' AND EXISTS (
+      SELECT 1 FROM action_ledger a WHERE a.action = '${COMPLETION_ACTION}' AND (a.task_id = ${r}.external_id OR a.run_id IN (SELECT id FROM run WHERE task_ref = ${r}.id))))))
+    AND NOT EXISTS (SELECT 1 FROM hold h WHERE h.task_ref = ${r}.id)
+    AND NOT EXISTS (SELECT 1 FROM run live WHERE live.task_ref = ${r}.id AND live.finished_at IS NULL)
+    AND NOT EXISTS (SELECT 1 FROM task_scope s WHERE s.task_id = ${r}.external_id AND s.candidate IS NOT NULL)
+    AND NOT EXISTS (WITH RECURSIVE family(ext) AS (
+        SELECT rv.external_id FROM task_ref rv WHERE rv.revision_of = ${r}.external_id
+        UNION SELECT rv.external_id FROM task_ref rv JOIN family ON rv.revision_of = family.ext)
+      SELECT 1 FROM family JOIN task tv ON tv.id = family.ext
+      WHERE NOT (tv.state = 'cancelled' OR (tv.state = 'done' AND EXISTS (SELECT 1 FROM action_ledger a WHERE a.action = '${COMPLETION_ACTION}'
+        AND (a.task_id = family.ext OR a.run_id IN (SELECT run.id FROM run JOIN task_ref x ON x.id = run.task_ref WHERE x.external_id = family.ext))))))`;
+}
+function cutoff(now, days) {
+    return new Date(now.getTime() - days * DAY_MS).toISOString();
+}
+/** Whether a folder holds anything but the retention note. */
+function holdsFiles(dir) {
+    try {
+        return readdirSync(dir).some(name => name !== RETENTION_NOTE);
+    }
+    catch {
+        return false;
+    }
+}
+/** What a sweep would delete now under `periods`, and how much space it would free. Reads only. */
+export function retentionPlan(store, evidenceRoot, now, periods = store.retentionPeriods()) {
+    const db = store.handle;
+    const items = { evidence: [], checkouts: [], chat: [], notifications: [] };
+    const more = { evidence: false, checkouts: false, chat: false, notifications: false };
+    if (periods.evidence !== null) {
+        const rows = db.prepare(`SELECT run.id AS id FROM run JOIN task_ref r ON r.id = run.task_ref
+      WHERE run.finished_at IS NOT NULL AND run.finished_at < ? AND ${finishedTask("r")} ORDER BY run.id`).all(cutoff(now, periods.evidence));
+        for (const row of rows) {
+            const run = Number(row["id"]);
+            const dir = join(evidenceRoot, String(run));
+            if (!holdsFiles(dir))
+                continue;
+            if (items.evidence.length >= SWEEP_BATCH) {
+                more.evidence = true;
+                break;
+            }
+            items.evidence.push({ run, bytes: folderBytes(dir) });
+        }
+    }
+    if (periods.checkouts !== null) {
+        const rows = db.prepare(`SELECT w.path AS path, w.released_at AS released_at, length(w.path) + length(w.repo) + length(w.branch) + 64 AS bytes FROM worktree w
+      WHERE w.runner IS NULL AND w.released_at IS NOT NULL AND w.released_at < ?
+        AND (w.task_ref IS NULL OR EXISTS (SELECT 1 FROM task_ref r WHERE r.id = w.task_ref AND ${finishedTask("r")})) ORDER BY w.released_at`).all(cutoff(now, periods.checkouts));
+        for (const row of rows) {
+            const path = String(row["path"]);
+            // Only the record of a checkout that's gone from disk: the checkout itself is storage retention's (two days after it's let go).
+            if (existsSync(path))
+                continue;
+            if (items.checkouts.length >= SWEEP_BATCH) {
+                more.checkouts = true;
+                break;
+            }
+            items.checkouts.push({ path, releasedAt: String(row["released_at"]), bytes: Number(row["bytes"]) });
+        }
+    }
+    if (periods.chat !== null) {
+        const rows = db.prepare(`SELECT m.id AS id, length(m.text) + COALESCE(length(m.activity), 0) + 64 AS bytes FROM mate_message m JOIN mate_thread th ON th.id = m.thread
+      WHERE m.created_at < ?
+        AND NOT EXISTS (SELECT 1 FROM team_message tm WHERE tm.message = m.id AND tm.status IN ('queued', 'running', 'uncertain'))
+        AND NOT EXISTS (SELECT 1 FROM mate_turn turn WHERE turn.id = m.turn AND turn.state IN ('queued', 'running'))
+        AND NOT (th.scope_kind = 'task' AND NOT EXISTS (SELECT 1 FROM task_ref r WHERE r.external_id = th.scope_key AND ${finishedTask("r")}))
+      ORDER BY m.id LIMIT ?`).all(cutoff(now, periods.chat), SWEEP_BATCH + 1);
+        more.chat = rows.length > SWEEP_BATCH;
+        items.chat = rows.slice(0, SWEEP_BATCH).map(row => ({ id: Number(row["id"]), bytes: Number(row["bytes"]) }));
+    }
+    if (periods.notifications !== null) {
+        const rows = db.prepare(`SELECT n.id AS id, length(n.subject) + length(n.body) + COALESCE(length(n.receipt), 0) + COALESCE(length(n.last_error), 0) + 64 AS bytes FROM notification n
+      WHERE n.created_at < ? AND (n.resolved_at IS NOT NULL OR n.delivered_at IS NOT NULL)
+        AND NOT (n.claim_owner IS NOT NULL AND n.claim_expires_at > ?)
+        AND NOT EXISTS (SELECT 1 FROM notification_delivery d WHERE d.notification = n.id AND d.claim_owner IS NOT NULL AND d.claim_expires_at > ?)
+        AND NOT (n.resolved_at IS NULL AND n.task_ref IS NOT NULL AND NOT EXISTS (SELECT 1 FROM task_ref r WHERE r.id = n.task_ref AND ${finishedTask("r")}))
+      ORDER BY n.id LIMIT ?`).all(cutoff(now, periods.notifications), now.toISOString(), now.toISOString(), SWEEP_BATCH + 1);
+        more.notifications = rows.length > SWEEP_BATCH;
+        items.notifications = rows.slice(0, SWEEP_BATCH).map(row => ({ id: Number(row["id"]), bytes: Number(row["bytes"]) }));
+    }
+    const counts = RETENTION_KINDS.map(({ kind }) => ({
+        kind, days: periods[kind], count: items[kind].length,
+        bytes: items[kind].reduce((sum, one) => sum + one.bytes, 0), more: more[kind],
+    }));
+    return { at: now.toISOString(), counts, items };
+}
+/** Bytes a folder holds, the retention note aside. */
+function folderBytes(dir) {
+    let total = 0;
+    for (const name of readdirSync(dir))
+        if (name !== RETENTION_NOTE)
+            total += treeBytes(join(dir, name));
+    return total;
+}
+/** Delete what the plan names (checking each again first) and write one ledger entry. Nothing to do when every kind is forever. */
+export function sweepRetention(store, evidenceRoot, now, actor = "worker") {
+    const periods = store.retentionPeriods();
+    store.setServiceCursor(SWEEP_CURSOR, now.getTime(), now);
+    if (RETENTION_KINDS.every(({ kind }) => periods[kind] === null))
+        return { at: now.toISOString(), counts: [], freed: 0, ledgerId: null };
+    const plan = retentionPlan(store, evidenceRoot, now, periods);
+    const db = store.handle;
+    const done = { evidence: { count: 0, bytes: 0 }, checkouts: { count: 0, bytes: 0 }, chat: { count: 0, bytes: 0 }, notifications: { count: 0, bytes: 0 } };
+    // Evidence: each run's folder is emptied and a note left, so its pages say why the files are gone.
+    if (periods.evidence !== null) {
+        const still = db.prepare(`SELECT 1 FROM run JOIN task_ref r ON r.id = run.task_ref WHERE run.id = ? AND run.finished_at IS NOT NULL AND run.finished_at < ? AND ${finishedTask("r")}`);
+        const before = cutoff(now, periods.evidence);
+        for (const one of plan.items.evidence) {
+            if (still.get(one.run, before) === undefined)
+                continue;
+            const dir = join(evidenceRoot, String(one.run));
+            try {
+                if (!lstatSync(dir).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            let freed = 0;
+            for (const name of readdirSync(dir)) {
+                if (name === RETENTION_NOTE)
+                    continue;
+                const bytes = treeBytes(join(dir, name));
+                try {
+                    rmSync(join(dir, name), { recursive: true, force: true });
+                    freed += bytes;
+                }
+                catch { /* left for the next sweep */ }
+            }
+            try {
+                writeFileSync(join(dir, RETENTION_NOTE), `Removed by the retention setting on ${now.toISOString().slice(0, 10)}.\n`, { mode: 0o600 });
+            }
+            catch { /* the folder's emptiness says it */ }
+            done.evidence.count++;
+            done.evidence.bytes += freed;
+        }
+    }
+    store.transact(() => {
+        if (periods.checkouts !== null) {
+            const forget = db.prepare("DELETE FROM worktree WHERE path = ? AND runner IS NULL AND released_at = ?");
+            for (const one of plan.items.checkouts) {
+                if (existsSync(one.path))
+                    continue;
+                if (Number(forget.run(one.path, one.releasedAt).changes) === 1) {
+                    done.checkouts.count++;
+                    done.checkouts.bytes += one.bytes;
+                }
+            }
+        }
+        if (periods.chat !== null) {
+            const team = db.prepare("DELETE FROM team_message WHERE message = ? AND status NOT IN ('queued', 'running', 'uncertain')");
+            const message = db.prepare("DELETE FROM mate_message WHERE id = ? AND NOT EXISTS (SELECT 1 FROM team_message WHERE message = ?)");
+            for (const one of plan.items.chat) {
+                team.run(one.id);
+                if (Number(message.run(one.id, one.id).changes) === 1) {
+                    done.chat.count++;
+                    done.chat.bytes += one.bytes;
+                }
+            }
+        }
+        if (periods.notifications !== null) {
+            const deliveries = db.prepare("DELETE FROM notification_delivery WHERE notification = ?");
+            const outbound = db.prepare("DELETE FROM telegram_outbound_message WHERE notification = ?");
+            const pushes = db.prepare("DELETE FROM push_delivery WHERE notification = ?");
+            const notification = db.prepare("DELETE FROM notification WHERE id = ?");
+            for (const one of plan.items.notifications) {
+                deliveries.run(one.id);
+                outbound.run(one.id);
+                pushes.run(one.id);
+                if (Number(notification.run(one.id).changes) === 1) {
+                    done.notifications.count++;
+                    done.notifications.bytes += one.bytes;
+                }
+            }
+        }
+    });
+    const counts = plan.counts.map(one => ({ ...one, count: done[one.kind].count, bytes: done[one.kind].bytes }));
+    const freed = counts.reduce((sum, one) => sum + one.bytes, 0);
+    const ledgerId = store.recordAction({ at: now.toISOString(), actor, repo: null, taskId: null, runId: null, action: "retention sweep", outcome: freed > 0 || counts.some(one => one.count > 0) ? "removed" : "nothing due", source: "policy", detail: sweepWords(counts, freed) });
+    return { at: now.toISOString(), counts, freed, ledgerId };
+}
+/** Whether a day has passed since the last sweep. */
+export function retentionDue(store, now) {
+    return now.getTime() - store.serviceCursor(SWEEP_CURSOR) >= SWEEP_EVERY_MS;
+}
+/** The daily sweep, when it's due: one worker takes it (the cursor moves in the same transaction). */
+export function dailyRetention(store, evidenceRoot, now) {
+    const mine = store.transact(() => {
+        if (!retentionDue(store, now))
+            return false;
+        store.setServiceCursor(SWEEP_CURSOR, now.getTime(), now);
+        return true;
+    });
+    return mine ? sweepRetention(store, evidenceRoot, now) : null;
+}
+export function lastSweepAt(store) {
+    const at = store.serviceCursor(SWEEP_CURSOR);
+    return at === 0 ? null : new Date(at).toISOString();
+}
+const NOUNS = {
+    evidence: ["run's evidence", "runs' evidence"],
+    checkouts: ["checkout record", "checkout records"],
+    chat: ["chat message", "chat messages"],
+    notifications: ["notification", "notifications"],
+};
+export function countWords(one) {
+    return `${one.count} ${NOUNS[one.kind][one.count === 1 ? 0 : 1]}`;
+}
+/** "3 runs' evidence, 120 chat messages; about 41 MB freed", or "nothing was due". */
+export function sweepWords(counts, freed) {
+    const parts = counts.filter(one => one.count > 0).map(countWords);
+    return parts.length === 0 ? "nothing was due" : `${parts.join(", ")}; about ${bytesWords(freed)} freed`;
+}

package/dist/review-context.d.ts

@@ -0,0 +1,243 @@
+import { type ObservationEvidence } from "./observations.js";
+import type { ExecResult } from "./exec.js";
+import { type ApprovedCriterion, type CriterionJudgementWord } from "./proof.js";
+import type { Store } from "./store.js";
+/** Explicit bounds. Content bytes are UTF-8 of the stored (possibly
+ * redacted) text; the aggregate is the sum over every stored item. */
+export declare const LEGACY_REVIEW_CONTEXT_LIMITS: {
+    /** One complete file or partial patch chain. Larger files stay gaps. */
+    readonly itemBytes: number;
+    /** Every item's bytes together. Whatever would cross it is a named gap. */
+    readonly aggregateBytes: number;
+    /** Items stored, in deterministic relevance order. */
+    readonly items: 24;
+    /** Candidate paths considered from the source proof and diff-stat. */
+    readonly candidatePaths: 200;
+    /** Prior review rows carried as context. */
+    readonly priorReviews: 48;
+    readonly ancestors: 16;
+};
+/** Storage ceilings, independent of delivery. Ordinary large files remain whole.
+ * The encoded artifact allows worst-case JSON escaping plus metadata. */
+export declare const REVIEW_CONTEXT_LIMITS: {
+    /** Candidate paths considered from the source proof and diff-stat. */
+    readonly candidatePaths: 200;
+    /** Prior review rows carried as context. */
+    readonly priorReviews: 48;
+    readonly ancestors: 16;
+    readonly itemBytes: number;
+    readonly aggregateBytes: number;
+    readonly items: 200;
+};
+/** Only this compact projection enters prompts. Full bytes remain sealed in
+ * the artifact and are materialized under generated, flat scratch names. */
+export declare function reviewContextFileName(id: string): string;
+export declare function reviewContextManifest(inventory: ReviewContextInventory): string;
+export type ContextGapReason = "source-missing" | "source-unverified" | "source-proof-missing" | "source-scope-changed" | "criterion-changed" | "stale-ancestry" | "missing-at-head" | "not-a-file" | "binary" | "over-limit" | "aggregate-limit" | "item-cap" | "secret-redacted" | "capture-failed";
+export type ContextItemWhy = "source-criterion-evidence" | "source-changed-path" | "candidate-changed-path";
+export type ReviewContextItem = {
+    /** `ctx-<n>`: the provenance token a reviewer cites in its notes. */
+    id: string;
+    path: string;
+    /** The exact commit the blob was read at — this run's sealed head. */
+    commit: string;
+    /** The git blob id at that commit and path. */
+    blob: string;
+    /** SHA-256 of `content` exactly as stored (after any redaction). */
+    sha256: string;
+    bytes: number;
+    content: string;
+    /** The ancestor run whose verified artifacts made this path relevant. */
+    sourceRun: number;
+    /** Signed criterion ids this path is relevant to. */
+    criteria: string[];
+    why: ContextItemWhy[];
+    /** Whether the blob is byte-identical at the source run's head. null
+     * when ancestry could not be verified, so nothing is claimed. */
+    unchangedSinceSource: boolean | null;
+    redacted: boolean;
+    /** Schema 2/3 only. Content is concatenated exact artifact ranges, NEVER
+     * a complete file. Segments are ordered from oldest to newest. */
+    patch?: {
+        coverage: "partial";
+        segments: AncestorPatchSegment[];
+    };
+};
+type AncestorPatchSegment = {
+    run: number;
+    base: string;
+    head: string;
+    artifact: number;
+    sha256: string;
+    offset: number;
+    bytes: number;
+};
+export type ReviewContextIdentity = {
+    path: string;
+    commit: string;
+    blob: string;
+    mode: string;
+    bytes: number;
+    sourceRun: number;
+    sourceBlob: string | null;
+    sourceMode: string | null;
+    unchangedSinceSource: boolean | null;
+};
+export type ReviewContextGap = {
+    reason: ContextGapReason;
+    path: string | null;
+    criteria: string[];
+    detail: string;
+};
+export type PriorReviewSupport = {
+    criterionId: string;
+    sourceRun: number;
+    reviewerRun: number;
+    author: string;
+    judgement: CriterionJudgementWord;
+    note: string;
+    statementMatches: boolean;
+    ancestryVerified: boolean;
+    relevantPaths: string[];
+    relevantUnchanged: boolean;
+    bindingsVerified: boolean;
+    /** `eligible` = every proof above holds, so the reviewer may weigh it;
+     * `invalid` = at least one failed, and the reasons say which. Neither
+     * is a judgement on THIS run. */
+    support: "eligible" | "invalid";
+    reasons: string[];
+};
+export type CriterionContextCoverage = {
+    id: string;
+    /** `patch`: judged from this revision's own diff (a criterion new to this
+     * rubric, or one whose relevant code the patch touches). `context`:
+     * inherited, partly or wholly outside the patch, every relevant path sealed as an
+     * item. `gap`: inherited and some relevant context is
+     * missing — see `gaps`. */
+    state: "patch" | "context" | "gap";
+    /** Same id AND same statement as the source run's signed rubric. */
+    inherited: boolean;
+    paths: string[];
+    items: string[];
+    gaps: string[];
+    priorSupport: "eligible" | "invalid" | "none";
+};
+export type ReviewContextInventory = {
+    schema: 1 | 2 | 3;
+    /** Optional builder caveats, bound to the captured handoff, never evidence
+     * that a criterion passed. Older inventories remain byte-compatible. */
+    handoff?: {
+        artifact: number;
+        sha256: string;
+        content: string;
+    };
+    observations?: ObservationEvidence;
+    /** Tree identity is independent of whether content fits capture bounds. */
+    identities?: ReviewContextIdentity[];
+    bindings?: {
+        run: number;
+        sha256: string;
+        candidate?: true;
+    }[];
+    run: number;
+    head: string;
+    base: string | null;
+    source: {
+        task: string;
+        run: number;
+        head: string | null;
+        scopeDigest: string | null;
+        /** The source run's sealed proof AND diff-stat both verified. */
+        verified: boolean;
+        problems: string[];
+    };
+    ancestry: {
+        verified: boolean;
+        detail: string;
+    };
+    items: ReviewContextItem[];
+    gaps: ReviewContextGap[];
+    priorReview: PriorReviewSupport[];
+    coverage: CriterionContextCoverage[];
+    limits: {
+        itemBytes: number;
+        aggregateBytes: number;
+        items: number;
+    };
+};
+/** Fingerprint every input the ancestor review depended on, including
+ * absent inputs and later additions. No transcript or checkout is copied. */
+export declare function reviewContextBindingOf(store: Store, runId: number, candidate?: boolean): {
+    run: number;
+    sha256: string;
+    candidate?: true;
+};
+/** Re-prove sealed context before spending and inside final ingestion. */
+export declare function reviewContextCustodyProblem(store: Store, root: string, inventory: ReviewContextInventory): string | null;
+/** A candidate path the object reader will accept on argv: repository-
+ * relative, no `..` or `.` segments, no leading dash, no control bytes. */
+export declare function safeContextPath(path: string): boolean;
+export declare function serializeReviewContext(inventory: ReviewContextInventory): string;
+/**
+ * The strict reader every consumer uses (the reviewer pass, the surfaces,
+ * the tests): shape, bounds, unique ids, and every item's SHA-256
+ * recomputed from its content. What this refuses, nothing shows.
+ */
+export declare function parseReviewContext(raw: string): {
+    ok: true;
+    inventory: ReviewContextInventory;
+} | {
+    ok: false;
+    problem: string;
+};
+/** What the reviewer's parser needs from an inventory: the provenance
+ * tokens a note may cite, and the criteria whose judgement must cite one —
+ * every criterion NOT judged from the patch alone. */
+export declare function reviewContextRules(inventory: ReviewContextInventory): {
+    itemIds: ReadonlySet<string>;
+    provenanceRequired: ReadonlySet<string>;
+};
+/** Whether a reviewer's note cites supplied provenance: a `ctx-<n>` item
+ * id from the inventory, a path the patch names, or a sealed file name. */
+export declare function citesSuppliedProvenance(note: string, supplied: {
+    itemIds: ReadonlySet<string>;
+    patchPaths: ReadonlySet<string>;
+    sealedFiles: ReadonlySet<string>;
+}): boolean;
+type GitRunner = (file: string, args: readonly string[], options?: {
+    cwd?: string;
+    maxBuffer?: number;
+}) => Promise<ExecResult>;
+export type CaptureReviewContextArgs = {
+    runId: number;
+    taskRef: number;
+    /** This run's sealed head — the exact commit every item is read at. */
+    head: string;
+    base: string | null;
+    /** The signed rubric this run built against, in id order. */
+    rubric: readonly ApprovedCriterion[];
+    /** Paths this run's own sealed diff-stat names (empty when unknown). */
+    patchPaths: ReadonlySet<string>;
+    worktree: string;
+    root: string;
+    now: () => Date;
+};
+/**
+ * Capture complete criterion-relevant files for every rubric-bearing build.
+ * Ordinary builds bind their own candidate; revisions also bind their ancestry.
+ * Every capture stores a parseable inventory; problems become gaps in it, never a
+ * missing or truncated file.
+ */
+export declare function captureReviewContext(store: Store, git: GitRunner, args: CaptureReviewContextArgs): Promise<{
+    inventory: ReviewContextInventory;
+    artifactId: number;
+} | null>;
+/**
+ * The derivation, separated from storage so a test can hold the inventory
+ * against a real repository without an evidence root.
+ */
+export declare function deriveReviewContext(store: Store, git: GitRunner, args: CaptureReviewContextArgs, lineage: {
+    sourceTask: string;
+    sourceRun: number;
+}): Promise<ReviewContextInventory>;
+export {};