@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/refine/evidence.js

@@ -0,0 +1,330 @@
+// The evidence folder an improver reads. Evidence is served as files and the prompt is a short
+// pointer, so nothing is truncated to fit a prompt:
+//
+//   context/task.md                  the task as the agent received it
+//   context/source/                  the material it was done from
+//   context/rollouts/<label>.md      full trajectories
+//   context/deliverables/<label>/    what each rollout produced
+//   context/harness/<rel>            the harness being edited
+//   context/library/INDEX.md         earlier tasks in this area and their full harnesses
+//   context/pool/<label>/            candidate harnesses, their diffs and rollouts
+//   context/decisions/<label>.md     earlier edit and composition notes
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/context.py`).
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, sep } from 'node:path';
+import { PI_SURFACE } from "../variant/surface.js";
+import { readVariant } from "../variant/variant.js";
+/** Strings that only a grader's own output contains. A tripwire, not the defence itself. */
+export const GRADER_VERDICT_MARKERS = [
+    'deterministic_eval_summary',
+    'deterministic_eval_result',
+    'judge_scope_and_deterministic_status',
+    'Judge findings on the rendered result',
+    '"passed_count"',
+    '"pass_rate"',
+    '"test_pass_rate"',
+    'review_verdict',
+    '"reviewVerdict"'
+];
+const SCANNED = new Set(['.md', '.txt', '.json', '.csv', '.tsv', '.yaml', '.yml', '.html', '.htm', '.log', '.py', '.js', '.mjs', '.ts', '.sh', '.xml', '.ini', '.toml', '.patch', '.diff', '']);
+/** Minimum per-observation truncation; lower values fabricate defects. */
+export const MIN_OBS_TRUNC = 10_000;
+function files(dir) {
+    const out = [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of names.sort()) {
+        const path = join(dir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(path).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            out.push(...files(path));
+        else
+            out.push(path);
+    }
+    return out;
+}
+function rel(root, path) {
+    return relative(root, path).split(sep).join('/');
+}
+function globToRegExp(glob) {
+    const pattern = glob.replace(/\\/g, '/').replace(/^\.\//, '');
+    let out = '';
+    for (const ch of pattern) {
+        if (ch === '*')
+            out += '[^]*';
+        else if (ch === '?')
+            out += '.';
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^(?:[^]*/)?${out}$`);
+}
+/** Refuses a folder holding a path the task marks as an answer key. */
+export function assertNoLeakPaths(root, globs = []) {
+    if (!globs.length || !existsSync(root))
+        return;
+    const rx = globs.map(globToRegExp);
+    const hits = files(root).map((path) => rel(root, path)).filter((path) => rx.some((r) => r.test(path)));
+    if (hits.length)
+        throw new Error(`answer-key path(s) would enter model context: ${hits.sort().slice(0, 8).join(', ')}`);
+}
+/** Refuses a folder containing a grader's output, by file name and by content. */
+export function assertNoGraderVerdicts(root, markers = GRADER_VERDICT_MARKERS) {
+    if (!existsSync(root))
+        return;
+    for (const path of files(root)) {
+        const name = rel(root, path);
+        for (const marker of markers) {
+            if (name.includes(marker))
+                throw new Error(`grader verdict would enter model context: '${name}' matched marker '${marker}' in its NAME. Find the read path that produced it.`);
+        }
+        if (!SCANNED.has(extname(path).toLowerCase()))
+            continue;
+        let body;
+        try {
+            body = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const marker of markers) {
+            const at = body.indexOf(marker);
+            if (at >= 0)
+                throw new Error(`grader verdict would enter model context: '${name}' contains marker '${marker}' at offset ${at}. Find the read path that produced it.`);
+        }
+    }
+}
+/** The same tripwire on a variant, before it is rolled or stored. */
+export function assertVariantHasNoGraderVerdicts(variant, markers = GRADER_VERDICT_MARKERS) {
+    for (const [name, body] of Object.entries(variant).sort()) {
+        for (const marker of markers) {
+            if (name.includes(marker))
+                throw new Error(`harness file '${name}' has grader-verdict marker '${marker}' in its NAME; rename it`);
+            if (SCANNED.has(extname(name).toLowerCase()) && body.includes(marker))
+                throw new Error(`harness file '${name}' contains grader-verdict marker '${marker}'; remove that string -- files carrying it cannot be served as evidence to later tasks`);
+        }
+    }
+}
+function copyFolder(src, dst) {
+    let n = 0;
+    for (const path of files(src)) {
+        if (path.includes(`${sep}__pycache__${sep}`) || path.endsWith('.pyc'))
+            continue;
+        const target = join(dst, relative(src, path));
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(path, target);
+        n++;
+    }
+    return n;
+}
+/** Copies the task's source material under `root/source`, minus answer-key paths. */
+export function copySource(task, root) {
+    const src = task.sourceDir;
+    if (!src || !existsSync(src))
+        return 0;
+    const leak = (task.leakGlobs ?? []).map(globToRegExp);
+    let n = 0;
+    for (const path of files(src)) {
+        const name = rel(src, path);
+        if (name.split('/').includes('__pycache__') || leak.some((r) => r.test(name)))
+            continue;
+        const target = join(root, 'source', name);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(path, target);
+        n++;
+    }
+    if (n)
+        assertNoLeakPaths(join(root, 'source'), task.leakGlobs);
+    return n;
+}
+/** A line-based unified diff, enough for a reader to see what changed. */
+export function unifiedDiff(before, after, fromLabel, toLabel) {
+    const out = [];
+    for (const name of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+        const a = before[name] ?? '';
+        const b = after[name] ?? '';
+        if (a === b)
+            continue;
+        out.push(`--- ${fromLabel}/${name}`, `+++ ${toLabel}/${name}`);
+        const x = a ? a.split('\n') : [];
+        const y = b ? b.split('\n') : [];
+        // A longest-common-subsequence walk; variants are small enough for the quadratic table.
+        const dp = Array.from({ length: x.length + 1 }, () => new Array(y.length + 1).fill(0));
+        for (let i = x.length - 1; i >= 0; i--)
+            for (let j = y.length - 1; j >= 0; j--)
+                dp[i][j] = x[i] === y[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        let i = 0;
+        let j = 0;
+        while (i < x.length || j < y.length) {
+            if (i < x.length && j < y.length && x[i] === y[j]) {
+                out.push(` ${x[i]}`);
+                i++;
+                j++;
+            }
+            else if (j < y.length && (i >= x.length || dp[i][j + 1] >= dp[i + 1][j])) {
+                out.push(`+${y[j]}`);
+                j++;
+            }
+            else {
+                out.push(`-${x[i]}`);
+                i++;
+            }
+        }
+    }
+    return out.length ? `${out.join('\n')}\n` : '';
+}
+/** The evidence-layout listing that goes in a mission; it mentions only what exists. */
+export function layout(evidence) {
+    const lines = ['context/task.md                  the task as the agent received it'];
+    if (evidence.sourceFiles)
+        lines.push('context/source/                 task source materials');
+    if (evidence.decisions)
+        lines.push('context/decisions/              earlier edits and composition decisions');
+    if (evidence.rollouts.length) {
+        const names = evidence.rollouts.slice(0, 6).map((label) => `${label}.md`).join(', ');
+        const more = evidence.rollouts.length > 6 ? ` (+${evidence.rollouts.length - 6} more)` : '';
+        lines.push(`context/rollouts/               FULL trajectories: ${names}${more}`);
+    }
+    if (evidence.deliverables.length)
+        lines.push('context/deliverables/<label>/    the files each rollout produced, one per artifact (browse INDEX.md for the set)');
+    if (evidence.harnessFiles)
+        lines.push(`context/harness/                the harness you are editing (${evidence.harnessFiles} files)`);
+    if (evidence.pool.length)
+        lines.push(`context/pool/                   ${evidence.pool.length} candidates, each with its harness and its rollout`);
+    if (evidence.library)
+        lines.push('context/library/                earlier tasks in this area -- browse INDEX.md first, then open what looks relevant');
+    return lines.join('\n');
+}
+function writeRollout(dest, rollout, executor, obsTrunc) {
+    let failure = '';
+    mkdirSync(join(dest, 'rollouts'), { recursive: true });
+    try {
+        writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), executor.trajectory(rollout, { obsTrunc }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), `(trajectory unavailable: ${message})`);
+        failure = `${rollout.label}: ${message}`;
+    }
+    const dir = join(dest, 'deliverables', rollout.label);
+    mkdirSync(dir, { recursive: true });
+    let produced = {};
+    try {
+        produced = executor.deliverableFiles(rollout);
+    }
+    catch (error) {
+        produced = { 'unavailable.md': `(deliverable unavailable: ${error instanceof Error ? error.message : String(error)})` };
+    }
+    const names = Object.keys(produced).sort();
+    for (const name of names) {
+        const target = join(dir, name);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, produced[name]);
+    }
+    writeFileSync(join(dir, 'INDEX.md'), names.length ? `# ${rollout.label} produced ${names.length} file(s)\n\n${names.map((name) => `- \`${name}\``).join('\n')}\n` : `# ${rollout.label} produced nothing\n`);
+    return failure;
+}
+function renderDeliverable(executor, rollout) {
+    const produced = executor.deliverableFiles(rollout);
+    const names = Object.keys(produced).sort();
+    if (!names.length)
+        return '';
+    if (names.length === 1)
+        return produced[names[0]];
+    return names.map((name) => `## ${name}\n\n${produced[name]}`).join('\n\n');
+}
+export { renderDeliverable };
+/**
+ * Writes the evidence folder and returns what landed, so a mission describes only that. A
+ * trajectory is written in full; `obsTrunc` applies per observation.
+ */
+export function build(dest, input) {
+    const { task, executor } = input;
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    const obsTrunc = Math.max(input.obsTrunc ?? 50_000, MIN_OBS_TRUNC);
+    writeFileSync(join(dest, 'task.md'), task.prompt);
+    const sourceFiles = copySource(task, dest);
+    for (const [label, notes] of Object.entries(input.decisions ?? {})) {
+        mkdirSync(join(dest, 'decisions'), { recursive: true });
+        writeFileSync(join(dest, 'decisions', `${label}.md`), notes || 'No decision notes returned.');
+    }
+    const rollouts = [];
+    const deliverables = [];
+    const failed = [];
+    for (const rollout of input.rollouts ?? []) {
+        const failure = writeRollout(dest, rollout, executor, obsTrunc);
+        if (failure)
+            failed.push(failure);
+        else
+            rollouts.push(rollout.label);
+        deliverables.push(rollout.label);
+    }
+    let harnessFiles = 0;
+    if (input.variantDir && existsSync(input.variantDir)) {
+        assertNoLeakPaths(input.variantDir, task.leakGlobs);
+        harnessFiles = copyFolder(input.variantDir, join(dest, 'harness'));
+    }
+    const pool = [];
+    for (const entry of input.pool ?? []) {
+        const dir = join(dest, 'pool', entry.label);
+        mkdirSync(dir, { recursive: true });
+        if (entry.variantDir && existsSync(entry.variantDir)) {
+            assertNoLeakPaths(entry.variantDir, task.leakGlobs);
+            copyFolder(entry.variantDir, join(dir, 'harness'));
+            const reference = readVariant(PI_SURFACE, join(dest, 'harness'));
+            const candidate = readVariant(PI_SURFACE, entry.variantDir);
+            writeFileSync(join(dir, 'harness.diff'), unifiedDiff(reference, candidate, 'current', entry.label));
+        }
+        if (entry.rollout) {
+            try {
+                writeFileSync(join(dir, 'rollout.md'), executor.trajectory(entry.rollout, { obsTrunc }));
+                writeFileSync(join(dir, 'produced.md'), renderDeliverable(executor, entry.rollout) || '(nothing produced)');
+            }
+            catch (error) {
+                writeFileSync(join(dir, 'rollout.md'), `(unavailable: ${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+        pool.push(entry.label);
+    }
+    let library = false;
+    if (input.libraryDir && existsSync(input.libraryDir) && readdirSync(input.libraryDir).length) {
+        assertNoLeakPaths(input.libraryDir, task.leakGlobs);
+        cpSync(input.libraryDir, join(dest, 'library'), { recursive: true });
+        library = true;
+    }
+    assertNoLeakPaths(dest, task.leakGlobs);
+    assertNoGraderVerdicts(dest);
+    if ((input.rollouts ?? []).length && !rollouts.length) {
+        throw new Error(`no trajectory could be rendered for ANY rollout -- the improver would be adapting on nothing: ${failed.slice(0, 4).join('; ')}`);
+    }
+    return { root: dest, taskId: task.id, rollouts, deliverables, harnessFiles, library, pool, failed, sourceFiles, decisions: Object.keys(input.decisions ?? {}).length };
+}
+/** The short pointer to the evidence on disk: the job, where the evidence is, and the instruction to open it. */
+export function mission(evidence, job) {
+    return [
+        job.trim(),
+        '',
+        '# YOUR EVIDENCE',
+        '',
+        'It is on disk, in `context/`. Read it -- do not answer from this message alone.',
+        '',
+        layout(evidence),
+        '',
+        'Every trajectory EVENT is present: the trajectory was not clipped to fit this mission. An individual observation may contain an explicit renderer-truncation marker; that marker is ours, not behavior by the solver. Do not diagnose it as a solver failure.',
+        '',
+        'Read `task.md` and the current harness first. Inventory every available rollout or candidate and inspect each at least once before deciding. For a candidate, compare what changed from its editing baseline, what behavior changed in its rollout, what improved, and what regressed or remained unresolved. Then deep-read the evidence relevant to any edit. Cite the specific trajectory moment behind every change; one you cannot trace to a moment is speculation.'
+    ].join('\n');
+}

package/dist/sdk/refine/host.d.ts

@@ -0,0 +1,59 @@
+import type { CallerContext } from "../core/caller.js";
+import type { Launch } from "../prompt/compile.js";
+import type { Effort } from "../sessions/runner.js";
+import type { GitSnapshotWorkspace, RefineTask } from "./types.js";
+/** How one execution of a task runs: who it works as and with what. */
+export interface RolloutSession {
+    caller: CallerContext;
+    tools: {
+        allow: string[];
+        gated?: string[];
+    };
+    launch?: Launch;
+    model?: string | null;
+    effort?: Effort | null;
+    accountId?: string | null;
+    poolId?: string | null;
+    connections?: boolean | {
+        readOnly?: boolean;
+    };
+    providers?: boolean;
+}
+export interface RolloutWorkspace {
+    /** The folder the execution works in. It must not be a folder a person is working in. */
+    cwd: string;
+    /** Called after what the execution produced has been read. */
+    cleanup?: () => Promise<void>;
+}
+export interface RefineHost {
+    /** A fresh, isolated folder for one execution. */
+    prepareWorkspace(input: {
+        refineId: string;
+        label: string;
+        task: RefineTask;
+    }): Promise<RolloutWorkspace>;
+    /** The session settings an execution runs with. */
+    session(input: {
+        refineId: string;
+        label: string;
+        task: RefineTask;
+    }): Promise<RolloutSession>;
+    /** What one execution produced, filename → readable text. Defaults to its reply and the files it changed. */
+    deliverable?(input: {
+        cwd: string;
+        reply: string;
+        task: RefineTask;
+    }): Promise<Record<string, string>>;
+}
+/** The reply, and every text file the execution added or changed relative to the task's source. */
+export declare function defaultDeliverable(cwd: string, reply: string, sourceDir: string | null | undefined): Record<string, string>;
+/** For a host that supplies nothing: a temporary copy of the task's source, the caller as the scope, and Pi's file and shell tools. */
+/**
+ * A throwaway checkout of a turn snapshot. It is a `--shared` clone, so the person's repository
+ * gains no worktree, ref or file: the clone only reads its object store. HEAD is the commit the
+ * turn started on and the working tree holds the snapshot, so tracked edits show as changes and new
+ * files as untracked, as they were. Ignored files named by `.worktreeinclude` are copied from the
+ * repository as it is now.
+ */
+export declare function prepareSnapshotWorkspace(snapshot: GitSnapshotWorkspace): Promise<RolloutWorkspace>;
+export declare const DEFAULT_REFINE_HOST: RefineHost;

package/dist/sdk/refine/host.js

@@ -0,0 +1,105 @@
+// The application's part in refinement (the seventh extension point). The harness runs the
+// method; the application says where an execution may work, as whom, with which tools, and what
+// it produced. Nothing here names an application concept.
+import { cpSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { copyFiles, includedFiles } from "../worktrees/copy.js";
+import { git } from "../worktrees/git.js";
+const TEXT_LIMIT = 200_000;
+const FILES_LIMIT = 40;
+function files(dir, into = [], base = dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return into;
+    }
+    for (const name of names.sort()) {
+        if (name === '.git' || name === 'node_modules' || name.startsWith('.'))
+            continue;
+        const path = join(dir, name);
+        try {
+            if (statSync(path).isDirectory())
+                files(path, into, base);
+            else
+                into.push(relative(base, path).split(sep).join('/'));
+        }
+        catch {
+            // Skip what cannot be read.
+        }
+        if (into.length > 2_000)
+            break;
+    }
+    return into;
+}
+function readable(path) {
+    try {
+        const buffer = readFileSync(path);
+        if (buffer.length > TEXT_LIMIT || buffer.includes(0))
+            return null;
+        return buffer.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** The reply, and every text file the execution added or changed relative to the task's source. */
+export function defaultDeliverable(cwd, reply, sourceDir) {
+    const out = {};
+    if (reply.trim())
+        out['reply.md'] = reply;
+    let count = 0;
+    for (const rel of files(cwd)) {
+        const text = readable(join(cwd, rel));
+        if (text === null)
+            continue;
+        const before = sourceDir && existsSync(join(sourceDir, rel)) ? readable(join(sourceDir, rel)) : null;
+        if (before === text)
+            continue;
+        out[`files/${rel}`] = text;
+        if (++count >= FILES_LIMIT)
+            break;
+    }
+    return out;
+}
+/** For a host that supplies nothing: a temporary copy of the task's source, the caller as the scope, and Pi's file and shell tools. */
+/**
+ * A throwaway checkout of a turn snapshot. It is a `--shared` clone, so the person's repository
+ * gains no worktree, ref or file: the clone only reads its object store. HEAD is the commit the
+ * turn started on and the working tree holds the snapshot, so tracked edits show as changes and new
+ * files as untracked, as they were. Ignored files named by `.worktreeinclude` are copied from the
+ * repository as it is now.
+ */
+export async function prepareSnapshotWorkspace(snapshot) {
+    const cwd = mkdtempSync(join(tmpdir(), 'harness-replay-'));
+    const cleanup = async () => rmSync(cwd, { recursive: true, force: true });
+    try {
+        await git(snapshot.repo, ['clone', '--quiet', '--shared', '--no-checkout', snapshot.repo, cwd]);
+        await git(cwd, ['checkout', '--quiet', '--detach', snapshot.commit]);
+        const parent = await git(cwd, ['rev-parse', '--verify', '--quiet', `${snapshot.commit}^`], { allowFail: true });
+        // The tree stays the snapshot; HEAD and the index go back to the commit the turn started on.
+        if (parent.code === 0)
+            await git(cwd, ['reset', '--quiet', parent.stdout.trim()]);
+        copyFiles(snapshot.repo, cwd, await includedFiles(snapshot.repo).catch(() => []));
+        return { cwd, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+export const DEFAULT_REFINE_HOST = {
+    async prepareWorkspace({ task }) {
+        if (task.workspace?.kind === 'git-snapshot')
+            return prepareSnapshotWorkspace(task.workspace);
+        const cwd = mkdtempSync(join(tmpdir(), 'harness-rollout-'));
+        if (task.sourceDir && existsSync(task.sourceDir))
+            cpSync(task.sourceDir, cwd, { recursive: true });
+        return { cwd, cleanup: async () => rmSync(cwd, { recursive: true, force: true }) };
+    },
+    async session({ task }) {
+        return { caller: { agentId: task.scope, actor: 'Code' }, tools: { allow: ['read', 'grep', 'find', 'ls', 'edit', 'write', 'bash'] } };
+    }
+};

package/dist/sdk/refine/ledger.d.ts

@@ -0,0 +1,48 @@
+/** R = 4k: k shared base + 2k candidates + k finals. */
+export declare const expectedRollouts: (k: number) => number;
+/** P = 3k: k INV + k DOM + k compositions. */
+export declare const expectedSessions: (k: number) => number;
+export declare class BudgetError extends Error {
+    constructor(message: string);
+}
+export interface LedgerEntry {
+    kind: 'rollout' | 'session';
+    label: string;
+    usd: number;
+    cached: boolean;
+    attempts: number;
+}
+export interface LedgerRecord {
+    mode: string;
+    taskId: string;
+    k: number;
+    R: number;
+    expectedR: number;
+    P: number;
+    expectedP: number;
+    sessionAttempts: number;
+    usd: number;
+    rolloutUsd: number;
+    sessionUsd: number;
+    rollouts: string[];
+    sessions: string[];
+}
+export declare class Ledger {
+    readonly mode: string;
+    readonly taskId: string;
+    readonly k: number;
+    readonly entries: LedgerEntry[];
+    constructor(mode: string, taskId: string, k: number);
+    rollout(label: string, usd?: number, cached?: boolean): void;
+    session(label: string, usd?: number, options?: {
+        cached?: boolean;
+        attempts?: number;
+    }): void;
+    labels(kind: LedgerEntry['kind']): string[];
+    get R(): number;
+    get P(): number;
+    usd(kind?: LedgerEntry['kind']): number;
+    /** Throws unless the entries show exactly R=4k and P=3k with no repeated label. */
+    assertIdentity(): void;
+    toRecord(): LedgerRecord;
+}

package/dist/sdk/refine/ledger.js

@@ -0,0 +1,76 @@
+// Budget accounting: R = 4k rollouts and P = 3k improvement stages per mode. Base executions
+// count toward each mode; retries are separate attempt counts; selection and reflection are
+// recorded outside this ledger.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/ledger.py`).
+/** R = 4k: k shared base + 2k candidates + k finals. */
+export const expectedRollouts = (k) => 4 * k;
+/** P = 3k: k INV + k DOM + k compositions. */
+export const expectedSessions = (k) => 3 * k;
+export class BudgetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BudgetError';
+    }
+}
+const round = (value) => Math.round(value * 1e6) / 1e6;
+export class Ledger {
+    mode;
+    taskId;
+    k;
+    entries = [];
+    constructor(mode, taskId, k) {
+        this.mode = mode;
+        this.taskId = taskId;
+        this.k = k;
+    }
+    rollout(label, usd = 0, cached = false) {
+        this.entries.push({ kind: 'rollout', label, usd, cached, attempts: 1 });
+    }
+    session(label, usd = 0, options = {}) {
+        this.entries.push({ kind: 'session', label, usd, cached: options.cached ?? false, attempts: options.attempts ?? 1 });
+    }
+    labels(kind) {
+        return this.entries.filter((entry) => entry.kind === kind).map((entry) => entry.label);
+    }
+    get R() {
+        return this.labels('rollout').length;
+    }
+    get P() {
+        return this.labels('session').length;
+    }
+    usd(kind) {
+        return round(this.entries.filter((entry) => !kind || entry.kind === kind).reduce((sum, entry) => sum + entry.usd, 0));
+    }
+    /** Throws unless the entries show exactly R=4k and P=3k with no repeated label. */
+    assertIdentity() {
+        const wantR = expectedRollouts(this.k);
+        const wantP = expectedSessions(this.k);
+        const rl = this.labels('rollout');
+        const sl = this.labels('session');
+        const dupes = [...new Set([...rl.filter((label, i) => rl.indexOf(label) !== i), ...sl.filter((label, i) => sl.indexOf(label) !== i)])].sort();
+        if (!dupes.length && this.R === wantR && this.P === wantP)
+            return;
+        const detail = [`${this.mode}-${this.k} ${this.taskId}: R=${this.R} (want ${wantR}), P=${this.P} (want ${wantP})`, `  rollouts: ${rl.join(', ') || '(none)'}`, `  sessions: ${sl.join(', ') || '(none)'}`];
+        if (dupes.length)
+            detail.push(`  DUPLICATE labels: ${dupes.join(', ')} -- two stages wrote the same run id and one overwrote the other`);
+        throw new BudgetError(detail.join('\n'));
+    }
+    toRecord() {
+        return {
+            mode: this.mode,
+            taskId: this.taskId,
+            k: this.k,
+            R: this.R,
+            expectedR: expectedRollouts(this.k),
+            P: this.P,
+            expectedP: expectedSessions(this.k),
+            sessionAttempts: this.entries.filter((entry) => entry.kind === 'session').reduce((sum, entry) => sum + entry.attempts, 0),
+            usd: this.usd(),
+            rolloutUsd: this.usd('rollout'),
+            sessionUsd: this.usd('session'),
+            rollouts: this.labels('rollout'),
+            sessions: this.labels('session')
+        };
+    }
+}

package/dist/sdk/refine/library.d.ts

@@ -0,0 +1,55 @@
+import { type SurfaceSpec, type Variant } from "../variant/surface.js";
+export interface Experience {
+    cue: string;
+    lesson: string;
+    evidence: string;
+    confidence?: string;
+    /** The edit-by-edit record the lesson rests on. */
+    edits?: string;
+}
+export declare function hasExperience(experience: Partial<Experience> | null | undefined): experience is Experience;
+/** One folder name for a task or area: separators collapse, nothing escapes. */
+export declare function slug(text: string): string;
+export interface LibraryEntry {
+    task: string;
+    label: string;
+    runId: string;
+    cue: string | null;
+    inventory: string;
+}
+export declare function libraryRoot(root: string): string;
+export declare class Library {
+    readonly root: string;
+    readonly scope: string;
+    readonly area: string;
+    readonly surface: SurfaceSpec;
+    constructor(root: string, scope: string, area?: string, surface?: SurfaceSpec);
+    get dir(): string;
+    get index(): string;
+    entryDir(task: string): string;
+    /** The folder handed to an improver, or null when nothing has been learned here yet. */
+    contextDir(): string | null;
+    entries(): string[];
+    variantOf(task: string): Variant;
+    experienceText(task: string): string | null;
+    list(): LibraryEntry[];
+    /** Drops these tasks' entries and rebuilds the index; unknown tasks are ignored. */
+    forget(tasks: readonly string[]): void;
+    /**
+     * Stores one adopted harness and why it was adopted, then rebuilds the index. Nothing is
+     * stored without a supported lesson. Returns the entry folder, or null.
+     */
+    add(task: string, variant: Variant, input: {
+        why?: string;
+        label?: string;
+        runId?: string;
+        experience?: Partial<Experience> | null;
+    }): string | null;
+    rebuildIndex(): string;
+}
+/** A one-line census of the components in a variant. */
+export declare function inventory(surface: SurfaceSpec, variant: Variant): string;
+/** Every scope that has a library. */
+export declare function libraryScopes(root: string): string[];
+/** Every area a scope has entries in. */
+export declare function libraryAreas(root: string, scope: string): string[];