@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/gold.js

@@ -0,0 +1,463 @@
+// The outcome gold set: a random sample of prompts an operator judges blind, and a scorer that reads every signal against those
+// judgments. It answers one question agreement among the signals cannot: does a local proxy predict human-judged success within an operator?
+// Every arm stays separate: no composite, no per-person score. The file shows the request and the result; the signals and the agent's closing
+// claim go to a sidecar beside it.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { INTERRUPT_MARKER } from './derive.js';
+import { checkSession } from './exclusion.js';
+import { cut, EDITS, promptOpening, SHELL, shellTarget, shortName } from './extract.js';
+import { PROMPT_HEAD_CHARS } from './schema.js';
+import { SOURCES } from './sources.js';
+import { paths } from './store.js';
+export const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const texts = (value) => str(value) ?? '';
+// Capture's rules, kept in step by a test against `captureSession`, so a store `index` names the same turn here.
+const firstTextBlock = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    for (const block of content)
+        if (isObj(block) && block.type === 'text')
+            return texts(block.text);
+    return '';
+};
+const resultText = (block) => {
+    const { content } = block;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.filter((part) => isObj(part) && part.type === 'text').map((part) => texts(part.text)).join('\n');
+};
+const failedResult = (block, text) => {
+    if (block.is_error === true)
+        return true;
+    const exit = /^Exit code (\d+)/.exec(text.trim());
+    return exit !== null && exit[1] !== '0';
+};
+export const readTurns = (text) => {
+    const turns = [];
+    // A resumed session repeats earlier lines: the first copy of a call carries its result, and a repeat is not fresh work.
+    const calls = new Map();
+    const lines = text.split('\n');
+    for (const [position, raw] of lines.entries()) {
+        let line;
+        try {
+            line = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!isObj(line) || !isObj(line.message) || line.isSidechain === true)
+            continue;
+        const { content, role } = line.message;
+        const blocks = Array.isArray(content) ? content.filter(isObj) : [];
+        if (line.type === 'user' && role === 'user' && line.isMeta !== true) {
+            const written = firstTextBlock(content);
+            const opening = written === '' || blocks.some((block) => block.type === 'tool_result') ? undefined : promptOpening(written, lines, position);
+            if (opening !== undefined) {
+                turns.push({ index: turns.length, request: opening.request, calls: [], replies: [] });
+                continue;
+            }
+        }
+        const turn = turns.at(-1);
+        for (const block of blocks) {
+            if (block.type === 'tool_result') {
+                const answered = calls.get(texts(block.tool_use_id));
+                if (answered !== undefined && answered.ok === undefined) {
+                    answered.result = resultText(block);
+                    answered.ok = !failedResult(block, answered.result);
+                }
+            }
+            else if (turn === undefined || role !== 'assistant')
+                continue;
+            else if (block.type === 'text')
+                turn.replies.push(texts(block.text));
+            else if (block.type === 'tool_use') {
+                const id = texts(block.id);
+                if (id !== '' && calls.has(id))
+                    continue;
+                const call = { name: texts(block.name), input: isObj(block.input) ? block.input : {}, cwd: str(line.cwd) ?? null, ok: undefined, result: '' };
+                calls.set(id, call);
+                turn.calls.push(call);
+            }
+        }
+    }
+    return turns;
+};
+const REQUEST_CHARS = 2000;
+const SUBJECT_CHARS = 200;
+const EXCERPT_CHARS = 300;
+const ACTION_CHARS = 120;
+const ACTIONS_SHOWN = 12;
+const FILES_SHOWN = 12;
+const PROSE = /\.(?:md|mdx|txt|rst)$/i;
+const SUBAGENT_TOOLS = new Set(['Agent', 'Task']);
+// `commits` sees only a first-line `git commit` (10% recall), so every segment of the command is read here.
+const COMMIT_SEGMENT = /^(?:\S+=\S*\s+)*git(?:\s+-[cC]\s+(?:"[^"]*"|'[^']*'|\S+))*\s+commit\b/;
+const RESULT_SUBJECT = /^\[[^\]\n]*\s[0-9a-f]{7,40}\]\s*(.*)$/m;
+const RESULT_STAT = /^\s*(\d+ files? changed.*)$/m;
+const HEREDOC_SUBJECT = /(?:<<-?\s*['"]?\w+['"]?\)?|@['"])\s*\r?\n([^\n]*)/;
+const FLAG_SUBJECT = /\bcommit\b[^\n]*?\s-[a-zA-Z]*m\s+(?:"([^"\n]*)|'([^'\n]*))/;
+const commandOf = (call) => texts(call.input.command);
+const isCommitCall = (call) => SHELL.has(call.name) && call.ok === true && commandOf(call).split(/&&|\|\||;|\||\n/).some((segment) => COMMIT_SEGMENT.test(segment.trim()));
+const commitOf = (call, redact) => {
+    const command = commandOf(call);
+    const flag = FLAG_SUBJECT.exec(command);
+    const subject = RESULT_SUBJECT.exec(call.result)?.[1] ?? HEREDOC_SUBJECT.exec(command)?.[1] ?? flag?.[1] ?? flag?.[2] ?? null;
+    return { subject: subject === null ? null : cut(redact(subject), SUBJECT_CHARS), stat: RESULT_STAT.exec(call.result)?.[1]?.trim() ?? null };
+};
+const lineCount = (text) => (text === '' ? 0 : text.split('\n').length);
+/** Forward slashes, and relative to the call's folder when it sits inside it. */
+const shownPath = (path, cwd) => {
+    const plain = path.replace(/\\/g, '/');
+    const base = cwd?.replace(/\\/g, '/');
+    return base !== undefined && plain.startsWith(`${base}/`) ? plain.slice(base.length + 1) : plain;
+};
+const editChange = (call) => {
+    const { input } = call;
+    if (call.name === 'Write')
+        return { added: lineCount(texts(input.content)), removed: 0, last: texts(input.content) };
+    const pieces = call.name === 'MultiEdit' && Array.isArray(input.edits) ? input.edits.filter(isObj) : [input];
+    return {
+        added: pieces.reduce((sum, piece) => sum + lineCount(texts(piece.new_string)), 0),
+        removed: pieces.reduce((sum, piece) => sum + lineCount(texts(piece.old_string)), 0),
+        last: texts(pieces.at(-1)?.new_string),
+    };
+};
+const editsOf = (calls, redact) => {
+    const byFile = new Map();
+    for (const call of calls) {
+        // A failed edit wrote nothing; one with no result may have written, as `isEdit` in derive.ts has it.
+        if (!EDITS.has(call.name) || call.ok === false)
+            continue;
+        const file = redact(shownPath(texts(call.input.file_path), call.cwd));
+        const change = editChange(call);
+        const row = byFile.get(file) ?? { file, added: 0, removed: 0, calls: 0, excerpt: null };
+        row.added += change.added;
+        row.removed += change.removed;
+        row.calls += 1;
+        row.excerpt = PROSE.test(file) ? null : cut(redact(change.last), EXCERPT_CHARS);
+        byFile.set(file, row);
+    }
+    return [...byFile.values()];
+};
+const actionLabel = (call) => {
+    const { input, name } = call;
+    if (SHELL.has(name))
+        return `${name} ${shellTarget(commandOf(call))}`;
+    const aim = str(input.file_path) === undefined ? (str(input.pattern) ?? str(input.url) ?? (name === 'WebSearch' ? str(input.query) : undefined)) : shownPath(texts(input.file_path), call.cwd);
+    return aim === undefined ? shortName(name) : `${shortName(name)} ${aim}`;
+};
+const actionsOf = (calls, redact) => {
+    const runs = [];
+    for (const call of calls) {
+        const label = cut(redact(actionLabel(call)), ACTION_CHARS);
+        const last = runs.at(-1);
+        if (last?.label === label)
+            last.times += 1;
+        else
+            runs.push({ label, times: 1 });
+    }
+    const lines = runs.map((run) => (run.times === 1 ? run.label : `${run.label} x${String(run.times)}`));
+    return lines.length <= ACTIONS_SHOWN ? lines : [...lines.slice(0, ACTIONS_SHOWN), `and ${String(lines.length - ACTIONS_SHOWN)} more`];
+};
+export const viewOf = (turns, index, redact) => {
+    const calls = turns[index]?.calls ?? [];
+    const earlier = turns[index - 1]?.request;
+    const edits = editsOf(calls, redact);
+    return {
+        request: cut(redact(turns[index]?.request ?? ''), REQUEST_CHARS),
+        earlier: earlier === undefined ? null : cut(redact(earlier), PROMPT_HEAD_CHARS),
+        commits: calls.filter(isCommitCall).map((call) => commitOf(call, redact)),
+        edits,
+        // A shell call after an edit is the `verify` signal, so an edit prompt lists none; a prompt with no edit reads `na` and shows nothing by listing them.
+        actions: edits.length > 0 ? [] : actionsOf(calls, redact),
+        subagents: calls.filter((call) => SUBAGENT_TOOLS.has(call.name)).length,
+    };
+};
+/**
+ * The prompts that can be judged. A marker is not a request. A `no-tools` prompt has only its reply to show, and the reply is the closing claim the
+ * file must hide. A session from any other harness (every harness `SOURCES` names) has no Claude Code transcript to read. A prompt with no signals has nothing to score.
+ */
+export const frameOf = (prompts) => prompts.filter((prompt) => !prompt.head.startsWith(INTERRUPT_MARKER) && prompt.cls !== 'no-tools' && !SOURCES.some((source) => prompt.session.startsWith(`${source.name}-`)) && prompt.verify !== undefined && prompt.model !== '');
+const SESSION_CAP = 2;
+const hashOrder = (prompts, seed) => prompts
+    .map((prompt) => ({ prompt, key: createHash('sha256').update(`${seed}\n${prompt.session}\n${String(prompt.index)}`).digest('hex') }))
+    .sort((a, b) => (a.key < b.key ? -1 : 1))
+    .map((item) => item.prompt);
+/**
+ * A seeded draw across class and model. Each next prompt comes from the cell with the largest `sqrt(size) / (taken + 1)`: rarer classes and models
+ * get more than their share, so each one can be read, and a common cell still gets the most. A cell that runs dry drops out, and the others fill the
+ * sample. The base rate it yields is the sample's, not the store's.
+ */
+export const drawSample = async (frame, size, seed, accept) => {
+    const cells = new Map();
+    for (const prompt of hashOrder(frame, seed)) {
+        const key = `${prompt.cls}\n${prompt.model}`;
+        const cell = cells.get(key);
+        if (cell === undefined)
+            cells.set(key, [prompt]);
+        else
+            cell.push(prompt);
+    }
+    const open = [...cells.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, queue]) => ({ queue, weight: Math.sqrt(queue.length), taken: 0 }));
+    const perSession = new Map();
+    const picked = [];
+    while (picked.length < size && open.length > 0) {
+        const cell = open.reduce((best, item) => (item.weight / (item.taken + 1) > best.weight / (best.taken + 1) ? item : best));
+        const next = cell.queue.shift();
+        if (next === undefined) {
+            open.splice(open.indexOf(cell), 1);
+            continue;
+        }
+        // One long session must not fill a cell: its prompts are not independent reads.
+        if ((perSession.get(next.session) ?? 0) >= SESSION_CAP)
+            continue;
+        if (!(await accept(next)))
+            continue;
+        perSession.set(next.session, (perSession.get(next.session) ?? 0) + 1);
+        picked.push(next);
+        cell.taken += 1;
+    }
+    return hashOrder(picked, `${seed}\norder`);
+};
+const quoted = (text) => text.split(/\r?\n/).map((line) => `> ${line}`.trimEnd());
+const indented = (text) => text.split(/\r?\n/).map((line) => `    ${line}`.trimEnd());
+/** `1 edit`, `2 edits`: a count agrees with its noun in every line the commands print. */
+export const plural = (count, one) => `${String(count)} ${one}${count === 1 ? '' : 's'}`;
+/** The request and the result as lines, every one prefixed: no text from a transcript can begin a line the parser reads. */
+const shownLines = (view) => {
+    const result = [];
+    for (const commit of view.commits)
+        result.push(`- Commit: ${commit.subject ?? 'message not readable'}${commit.stat === null ? '' : ` (${commit.stat})`}`.replace(/\r?\n/g, ' '));
+    for (const edit of view.edits.slice(0, FILES_SHOWN)) {
+        result.push(`- ${edit.file}: +${String(edit.added)} -${String(edit.removed)} in ${plural(edit.calls, 'edit')}`.replace(/\r?\n/g, ' '));
+        if (edit.excerpt !== null && edit.excerpt !== '')
+            result.push(...indented(edit.excerpt));
+    }
+    if (view.edits.length > FILES_SHOWN)
+        result.push(`- and ${plural(view.edits.length - FILES_SHOWN, 'more file')}`);
+    for (const action of view.actions)
+        result.push(`- ${action}`.replace(/\r?\n/g, ' '));
+    if (view.subagents > 0)
+        result.push(`- ${plural(view.subagents, 'subagent call')} ran; their work is not shown`);
+    if (result.length === 0)
+        result.push('- No change or action in the main transcript.');
+    return [...(view.earlier === null ? [] : ['Earlier request:', ...quoted(view.earlier), '']), 'Request:', ...quoted(view.request), '', 'Result:', ...result];
+};
+/** What an evaluator is given, and only that: the same request and result the judge sees. */
+export const renderShown = (view) => shownLines(view).join('\n');
+const BLANK_JUDGMENT = 'yes|no';
+export const renderGold = (items, options) => {
+    const batches = Math.ceil(items.length / options.batch);
+    const lines = [
+        `# Outcome gold set, ${options.date}`,
+        '',
+        'Did the work do what was asked? Judge from what is shown, then replace `yes|no` with `yes` or `no`. Leave a line as it is when you cannot tell.',
+        'You can stop after any batch; the score reads whatever is filled in:',
+        '',
+        '    oars sessions gold score <this file>',
+        '',
+        "The agent's own closing words and every signal are kept out of this file. They are in the `.arms.json` file beside it: do not open that before judging.",
+        'Local only: never commit, never quote.',
+    ];
+    items.forEach((item, position) => {
+        if (position % options.batch === 0)
+            lines.push('', `## Batch ${String(position / options.batch + 1)} of ${String(batches)}`);
+        lines.push('', `### ${item.id}`, '', ...shownLines(item.view), '', `Judgment: ${BLANK_JUDGMENT}`);
+    });
+    return `${lines.join('\n')}\n`;
+};
+const ANSWERS = new Map([['yes', true], ['y', true], ['no', false], ['n', false]]);
+export const parseGold = (text) => {
+    const judged = new Map();
+    const unreadable = [];
+    let current;
+    for (const line of text.split(/\r?\n/)) {
+        const heading = /^### (G\d+)$/.exec(line);
+        if (heading !== null) {
+            current = heading[1];
+            continue;
+        }
+        const judgment = /^Judgment:(.*)$/.exec(line);
+        if (judgment === null || current === undefined)
+            continue;
+        const answer = (judgment[1] ?? '').trim().toLowerCase();
+        const value = ANSWERS.get(answer);
+        if (value !== undefined)
+            judged.set(current, value);
+        else if (answer !== '' && answer !== BLANK_JUDGMENT)
+            unreadable.push(current);
+    }
+    return { judged, unreadable };
+};
+const CONFIDENCE_LEVELS = new Map([['low', 0], ['medium', 1], ['moderate', 1], ['high', 2]]);
+const CONFIDENCE_VALUE = /^(low|medium|moderate|high)\b(?:[\s/-]+(?:to\s+)?(low|medium|moderate|high)\b)?/i;
+/** The words these lines use, in order, with a range read as its middle. Anything else, such as a percentage, has no reading. */
+export const confidenceLevel = (line) => {
+    const value = line?.slice(line.indexOf(':') + 1).replace(/^[\s*_]+/, '') ?? '';
+    const match = CONFIDENCE_VALUE.exec(value);
+    if (match === null)
+        return null;
+    const level = (word) => CONFIDENCE_LEVELS.get(word?.toLowerCase() ?? '');
+    const low = level(match[1]) ?? 0;
+    return ((low + (level(match[2]) ?? low)) / 2);
+};
+const answerRead = (answer) => (answer === 'yes' ? 1 : answer === 'no' ? 0 : null);
+const VERIFY_ORDER = new Map([['passed', 2], ['none', 1], ['failed', 0]]);
+/** The arms, in print order. Each is an observation read on its own, and none is a label. */
+export const ARMS = [
+    { arm: 'verify', read: (entry) => VERIFY_ORDER.get(entry.signals.verify) ?? null },
+    { arm: 'stopped', read: (entry) => (entry.signals.stopped === null ? 1 : 0) },
+    { arm: 'commits', read: (entry) => entry.signals.commits },
+    { arm: 'redo', read: (entry) => (entry.signals.redo ? 0 : 1) },
+    { arm: 'confidence', read: (entry) => confidenceLevel(entry.reads?.confidence) },
+    { arm: 'claim', read: (entry) => answerRead(entry.answers?.claim) },
+    { arm: 'evaluator', read: (entry) => answerRead(entry.answers?.evaluator) },
+    { arm: 'later', read: (entry) => answerRead(entry.answers?.later) },
+];
+const mean = (values) => values.reduce((sum, value) => sum + value, 0) / values.length;
+const sampleVariance = (values) => {
+    const center = mean(values);
+    return values.reduce((sum, value) => sum + (value - center) ** 2, 0) / (values.length - 1);
+};
+const Z_95 = 1.96;
+const NO_VARIANCE = 1e-12;
+/**
+ * AUROC with a DeLong 95% interval, which handles the heavy ties these signals have. A zero variance estimate (one value, perfect separation, or one
+ * row a side) gives no interval: it is a small sample, not certainty.
+ */
+export const auroc = (positives, negatives) => {
+    if (positives.length === 0 || negatives.length === 0)
+        return { auroc: null, low: null, high: null };
+    const beats = (positive, negative) => (positive > negative ? 1 : positive === negative ? 0.5 : 0);
+    const perPositive = positives.map((positive) => mean(negatives.map((negative) => beats(positive, negative))));
+    const perNegative = negatives.map((negative) => mean(positives.map((positive) => beats(positive, negative))));
+    const value = mean(perPositive);
+    if (positives.length < 2 || negatives.length < 2)
+        return { auroc: value, low: null, high: null };
+    const variance = sampleVariance(perPositive) / positives.length + sampleVariance(perNegative) / negatives.length;
+    if (variance < NO_VARIANCE)
+        return { auroc: value, low: null, high: null };
+    const half = Z_95 * Math.sqrt(variance);
+    return { auroc: value, low: Math.max(0, value - half), high: Math.min(1, value + half) };
+};
+const POOLED = 'all models';
+const modelRow = (model, entries, judged) => {
+    const yes = entries.filter((entry) => judged.get(entry.id) === true).length;
+    const arms = ARMS.map(({ arm, read }) => {
+        const positives = [];
+        const negatives = [];
+        for (const entry of entries) {
+            const value = read(entry);
+            if (value !== null)
+                (judged.get(entry.id) === true ? positives : negatives).push(value);
+        }
+        const covered = positives.length + negatives.length;
+        return { arm, covered, yes: positives.length, baseRate: covered === 0 ? null : positives.length / covered, ...auroc(positives, negatives) };
+    });
+    return { model, judged: entries.length, baseRate: yes / entries.length, arms };
+};
+export const scoreGold = (entries, judged) => {
+    const scored = entries.filter((entry) => judged.has(entry.id));
+    const models = [...new Set(scored.map((entry) => entry.model))].sort();
+    return {
+        total: entries.length,
+        judged: scored.length,
+        coverage: ARMS.map(({ arm, read }) => ({ arm, covered: entries.filter((entry) => read(entry) !== null).length })),
+        models: scored.length === 0 ? [] : [...models.map((model) => modelRow(model, scored.filter((entry) => entry.model === model), judged)), modelRow(POOLED, scored, judged)],
+    };
+};
+const percent = (value) => (value === null ? '-' : `${String(Math.round(value * 100))}%`);
+const decimal = (value) => (value === null ? '-' : value.toFixed(2));
+export const coverageLines = (score) => {
+    const width = Math.max(...score.coverage.map((row) => row.arm.length));
+    return ['Prompts each arm covers:', ...score.coverage.map((row) => `  ${row.arm.padEnd(width)}  ${String(row.covered)} of ${String(score.total)}`)];
+};
+export const formatScore = (score, unreadable) => {
+    const width = Math.max(...score.coverage.map((row) => row.arm.length));
+    const lines = [
+        `Judged ${String(score.judged)} of ${String(score.total)}. Each arm is an observation, not a label, and no arm is combined with another.`,
+        ...unreadable.map((id) => `Could not read the judgment of ${id}: write yes or no.`),
+        '',
+        ...coverageLines(score),
+    ];
+    for (const row of score.models) {
+        lines.push('', `${row.model}: ${String(row.judged)} judged, base rate ${percent(row.baseRate)}`, `  ${'arm'.padEnd(width)}  covered  yes  base  AUROC  95% interval`);
+        for (const arm of row.arms) {
+            const interval = arm.low === null || arm.high === null ? '-' : `${decimal(arm.low)} to ${decimal(arm.high)}`;
+            lines.push(`  ${arm.arm.padEnd(width)}  ${String(arm.covered).padStart(7)}  ${String(arm.yes).padStart(3)}  ${percent(arm.baseRate).padStart(4)}  ${decimal(arm.auroc).padStart(5)}  ${interval}`);
+        }
+    }
+    return lines.join('\n');
+};
+/** The sidecar beside a gold file. */
+export const armsPath = (goldFile) => `${goldFile.replace(/\.md$/, '')}.arms.json`;
+const readIfThere = (file) => readFile(file, 'utf8').catch(() => undefined);
+/** The first root that holds the session, so the draw and the text arms cannot come to read different files. Undefined when none does. */
+export const readTranscript = async (roots, project, session) => {
+    for (const root of roots) {
+        const text = await readIfThere(join(root, project, `${session}.jsonl`));
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+};
+export const sampleGold = async (runtime, store, redact, options) => {
+    const roots = [runtime.projectsRoot, paths(runtime.storeDir).raw];
+    const projectOf = new Map(store.sessions.map((session) => [session.session, session.project]));
+    const excluded = new Set();
+    const checked = new Set();
+    const built = new Map();
+    let unreadable = 0;
+    const accept = async (prompt) => {
+        const project = projectOf.get(prompt.session) ?? '';
+        if (excluded.has(prompt.session))
+            return false;
+        if (!checked.has(prompt.session)) {
+            checked.add(prompt.session);
+            // The one exclusion rule (A38): a session that holds a term, has no raw to scan, or could not be read is out, and so is every session when the term file is empty.
+            if ((await checkSession(runtime, options.termsFile, project, prompt.session, options.extraTerms)).excluded) {
+                excluded.add(prompt.session);
+                return false;
+            }
+        }
+        const text = await readTranscript(roots, project, prompt.session);
+        const turns = text === undefined ? [] : readTurns(text);
+        const turn = turns[prompt.index];
+        // The transcript grew or changed after the deposit if the head no longer matches, and the signals would then describe another turn.
+        if (turn === undefined || cut(redact(turn.request), PROMPT_HEAD_CHARS) !== prompt.head) {
+            unreadable += 1;
+            return false;
+        }
+        built.set(prompt, viewOf(turns, prompt.index, redact));
+        return true;
+    };
+    const frame = frameOf(store.prompts);
+    const picked = await drawSample(frame, options.size, options.seed, accept);
+    const width = Math.max(3, String(picked.length).length);
+    const views = [];
+    const entries = picked.map((prompt, position) => {
+        const id = `G${String(position + 1).padStart(width, '0')}`;
+        const view = built.get(prompt) ?? viewOf([], 0, redact);
+        views.push({ id, view });
+        return {
+            id,
+            session: prompt.session,
+            index: prompt.index,
+            project: projectOf.get(prompt.session) ?? '',
+            model: prompt.model,
+            cls: prompt.cls,
+            subagents: view.subagents,
+            signals: { verify: prompt.verify ?? 'na', stopped: prompt.stopped ?? null, commits: prompt.commits ?? 0, redo: prompt.redo ?? false },
+            shown: renderShown(view),
+        };
+    });
+    return { document: { date: options.date, seed: options.seed, batch: options.batch, frame: frame.length, excludedSessions: excluded.size, entries }, views, unreadable };
+};
+export const isGoldDocument = (value) => isObj(value) && Array.isArray(value.entries);

package/dist/sessions/graph.d.ts

@@ -0,0 +1,12 @@
+import type { StepObservation, ToolStatus } from './schema.js';
+/** One call's steps, with what the graph reads and does not keep. */
+export interface LinkedCall {
+    steps: StepObservation[];
+    /** One per step. Masked identities can match by accident, so a retry compares these; they are never stored. */
+    rawKeys: readonly string[];
+    /** The line of work: the prompt, and whether the call ran on a sidechain. */
+    line: string;
+    status: ToolStatus;
+}
+/** Writes `next`, `after-error`, and `retried` on every step, and `spawned` on the transcript's first when `spawnedAt` knows the call that started it. */
+export declare const linkSteps: (calls: readonly LinkedCall[], spawnedAt: number | null) => void;

package/dist/sessions/graph.js

@@ -0,0 +1,34 @@
+// The edges of the steps of one transcript (recall spec Section 2.3). Every edge is held on the step it points to, naming the step it came
+// from, so one transcript's capture writes all of its own edges and no earlier record is rewritten, including a subagent's first step, whose
+// edge comes from a call in another transcript.
+/** Writes `next`, `after-error`, and `retried` on every step, and `spawned` on the transcript's first when `spawnedAt` knows the call that started it. */
+export const linkSteps = (calls, spawnedAt) => {
+    const lines = new Map();
+    for (const { steps, rawKeys, line, status } of calls) {
+        const held = lines.get(line) ?? { last: undefined, lastFailed: false, failed: new Map() };
+        lines.set(line, held);
+        for (const [seg, step] of steps.entries()) {
+            const before = seg === 0 ? held.last : steps[seg - 1];
+            if (before !== undefined)
+                step.edges.push({ kind: 'next', n: before.n, seg: before.seg });
+            if (seg === 0 && before !== undefined && held.lastFailed)
+                step.edges.push({ kind: 'after-error', n: before.n, seg: before.seg });
+            const failure = held.failed.get(rawKeys[seg] ?? '');
+            if (failure !== undefined)
+                step.edges.push({ kind: 'retried', n: failure.n, seg: failure.seg });
+        }
+        // After the whole call: a command repeated inside one call is not a retry of itself.
+        for (const [seg, step] of steps.entries()) {
+            const key = rawKeys[seg] ?? '';
+            if (step.status === 'error')
+                held.failed.set(key, step);
+            else if (step.status === 'ok')
+                held.failed.delete(key);
+        }
+        held.last = steps.at(-1);
+        held.lastFailed = status === 'error';
+    }
+    const first = calls[0]?.steps[0];
+    if (first !== undefined && spawnedAt !== null)
+        first.edges.unshift({ kind: 'spawned', n: spawnedAt, seg: 0 });
+};

package/dist/sessions/grok.d.ts

@@ -0,0 +1,36 @@
+/** The Grok home for an environment; a test passes its own so it never reads the real one. */
+export declare const grokRoot: (env: {
+    [name: string]: string | undefined;
+}, home?: string) => string;
+type Obj = {
+    [key: string]: unknown;
+};
+/** A session found in the store, before its lines are read. */
+export interface GrokSession {
+    /** The session folder's name, which is the session id and names the skeleton. */
+    id: string;
+    /** `summary.json` `info.cwd`; null when it names none. */
+    folder: string | null;
+    /** The session's folder. */
+    dir: string;
+    size: number;
+    mtimeMs: number;
+}
+export interface GrokStore {
+    sessions: GrokSession[];
+    /** The session as transcript text for `captureSession`; throws when a file cannot be read or holds no parseable line. */
+    transcript: (session: GrokSession) => Promise<string>;
+    /** Folders skipped because their name is not a safe file name (it names a skeleton), counted so the skip is never silent. */
+    rejected: number;
+    /** Sessions that could not be inspected, reported once each and never fatal; the reason names no path. */
+    unreadable: {
+        file: string;
+        reason: string;
+    }[];
+}
+/** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
+export declare const grokBadLines: (text: string) => string[];
+/** One session as the lines `captureSession` reads. */
+export declare const grokLines: (text: string, fallbackId: string, summary: Obj, usage: Obj | undefined) => Obj[];
+export declare const openGrokStore: (root: string) => Promise<GrokStore | undefined>;
+export {};