@hmharness/evolution 0.14.5 → 0.14.9

package/dist/bench.d.ts.v2bak.v2bak

@@ -0,0 +1,44 @@
+export interface BenchCase {
+    name: string;
+    prompt: string;
+    /** All substrings (split on &&) must appear in the output, case-insensitive. */
+    expect: string[];
+    /** Output must equal this string exactly (both trimmed). */
+    expectExact?: string;
+    /** Output must match this regex (whole output, case-sensitive). */
+    expectRegex?: string;
+    /** Substrings that must NOT appear (failure-marker exclusion). */
+    expectNone?: string[];
+    /** At least ONE of these substrings must appear. */
+    expectAny?: string[];
+    /** When true the case runs through the full agent loop with tools. */
+    tools: boolean;
+    /** Holdout cases are excluded from the promotion gate and re-verify after promotion (anti-memorization, GDPevo style). */
+    holdout: boolean;
+    /** Candidate token-cost ceiling as a multiple of the baseline run. */
+    costCap?: number;
+}
+export interface BenchResult {
+    name: string;
+    pass: boolean;
+    detail: string;
+}
+export declare function matchExpect(output: string, expect: string[]): boolean;
+/** Fence convention: when the reply is a fenced block, assertions test the
+ *  fence INNER content (day-55 finding: models preserve literals verbatim
+ *  inside code fences while normalizing them in prose - the fence is the
+ *  reply convention that makes exactness attainable for habit-prone models).
+ *  Tolerates a trailing space after the opening fence markers. */
+export declare function fenceInner(output: string): string;
+/** Full structured assertion: every declared mode must hold. */
+export declare function matchCase(output: string, c: Pick<BenchCase, 'expect' | 'expectExact' | 'expectRegex' | 'expectNone' | 'expectAny'>): {
+    pass: boolean;
+    detail: string;
+};
+export declare function listCases(home: string): Promise<BenchCase[]>;
+export declare function runBench(home: string, run: (c: BenchCase) => Promise<string>): Promise<{
+    results: BenchResult[];
+    passRate: number;
+}>;
+/** Starter cases so the evolve gate has a signal from day one. */
+export declare function seedCases(home: string): Promise<string[]>;

package/dist/bench.js.v2bak.v2bak

@@ -0,0 +1,156 @@
+/**
+ * @hmharness/evolution - bench
+ * The fitness signal for self-evolution. bench/cases/*.task files are:
+ *   line 1        the prompt
+ *   expect: a && b   substrings that must ALL appear in the final output
+ *   expect-exact: "..."   the output equals this string (trimmed)
+ *   expect-regex: ...     a regex the output must match
+ *   expect-none: a && b   substrings that must NOT appear
+ *   expect-any: a || b    one of these substrings must appear
+ *   tools: loop   (optional) run through the full agent loop with tools
+ *   cost-cap: 1.3  (optional) candidate cost multiplier ceiling vs baseline
+ * Skill or prompt changes must keep the bench green before promotion - the
+ * evolve loop enforces this A/B (baseline vs candidate).
+ *
+ * Assertion upgrade (gate methodology): plain substring matching lets
+ * verbose-but-wrong outputs pass; the structured modes pin exact shapes,
+ * forbid failure markers, and (with cost-cap) stop a candidate that only
+ * passes by burning 3x tokens. Old files keep working - `expect:` keeps
+ * its ALL-substrings semantics.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export function matchExpect(output, expect) {
+    const lower = output.toLowerCase();
+    return expect.every((e) => lower.includes(e.toLowerCase()));
+}
+/** Fence convention: when the reply is a fenced block, assertions test the
+ *  fence INNER content (day-55 finding: models preserve literals verbatim
+ *  inside code fences while normalizing them in prose - the fence is the
+ *  reply convention that makes exactness attainable for habit-prone models).
+ *  Tolerates a trailing space after the opening fence markers. */
+export function fenceInner(output) {
+    const m = output.match(/```[a-zA-Z]*[ \t]*\r?\n([\s\S]*?)(?:\r?\n)?```/);
+    return m ? m[1] : output;
+}
+/** Full structured assertion: every declared mode must hold. */
+export function matchCase(output, c) {
+    const body = fenceInner(output);
+    if (c.expectExact !== undefined && body.trim() !== c.expectExact.trim()) {
+        return { pass: false, detail: `exact mismatch: got "${body.trim().slice(0, 80)}"` };
+    }
+    if (c.expectRegex !== undefined) {
+        try {
+            if (!new RegExp(c.expectRegex).test(body))
+                return { pass: false, detail: `regex mismatch: /${c.expectRegex.slice(0, 60)}/` };
+        }
+        catch {
+            return { pass: false, detail: `invalid regex in case: ${c.expectRegex.slice(0, 40)}` };
+        }
+    }
+    if (c.expectNone && c.expectNone.some((e) => body.toLowerCase().includes(e.toLowerCase()))) {
+        return { pass: false, detail: `forbidden marker present: ${c.expectNone.join(' && ')}` };
+    }
+    if (c.expectAny && !c.expectAny.some((e) => body.toLowerCase().includes(e.toLowerCase()))) {
+        return { pass: false, detail: `none of the allowed markers found: ${c.expectAny.join(' || ')}` };
+    }
+    if (!matchExpect(body, c.expect)) {
+        return { pass: false, detail: `missing "${c.expect.join('" && "')}" in output` };
+    }
+    return { pass: true, detail: 'ok' };
+}
+export async function listCases(home) {
+    const dir = join(home, 'bench', 'cases');
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith('.task'));
+    }
+    catch {
+        return [];
+    }
+    const cases = [];
+    for (const f of files.sort()) {
+        const raw = (await readFile(join(dir, f), 'utf8')).trim();
+        const lines = raw.split('\n');
+        const prompt = lines[0];
+        const pick = (key) => {
+            const l = lines.find((x) => x.startsWith(key + ':'));
+            return l ? l.slice(key.length + 1).trim() : undefined;
+        };
+        const list = (key) => {
+            const v = pick(key);
+            return v ? v.split(/&&|\|\|/).map((s) => s.trim()).filter(Boolean) : undefined;
+        };
+        const costCap = Number(pick('cost-cap'));
+        cases.push({
+            name: f.replace(/\.task$/, ''),
+            prompt,
+            expect: list('expect') ?? [],
+            expectExact: pick('expect-exact')?.replace(/^"|"$/g, ''),
+            expectRegex: pick('expect-regex'),
+            expectNone: list('expect-none'),
+            expectAny: list('expect-any'),
+            tools: pick('tools') === 'loop',
+            holdout: pick('holdout') === 'true',
+            costCap: Number.isFinite(costCap) && costCap > 0 ? costCap : undefined,
+        });
+    }
+    return cases;
+}
+export async function runBench(home, run) {
+    const cases = await listCases(home);
+    const results = [];
+    for (const c of cases) {
+        try {
+            const out = await run(c);
+            const r = matchCase(out, c);
+            results.push({ name: c.name, pass: r.pass, detail: r.detail });
+        }
+        catch (err) {
+            results.push({ name: c.name, pass: false, detail: String(err).slice(0, 120) });
+        }
+    }
+    const passed = results.filter((r) => r.pass).length;
+    // persist a history record: readiness's "eval-regression-stable" condition
+    // reads evolution/benches/*.json - without these records the RL gate's
+    // stability condition can never be met (day-20 audit gap)
+    try {
+        const dir = join(home, 'evolution', 'benches');
+        await mkdir(dir, { recursive: true });
+        const record = {
+            time: new Date().toISOString(),
+            total: cases.length,
+            passed,
+            passRate: cases.length === 0 ? 1 : passed / cases.length,
+            results: results.map((r) => ({ name: r.name, pass: r.pass, detail: r.detail.slice(0, 200) })),
+        };
+        await writeFile(join(dir, `${record.time.replace(/[:.]/g, '-')}.json`), JSON.stringify(record, null, 2) + '\n', 'utf8');
+    }
+    catch { /* history is best-effort; the run result still returns */ }
+    return { results, passRate: cases.length === 0 ? 1 : passed / cases.length };
+}
+/** Starter cases so the evolve gate has a signal from day one. */
+export async function seedCases(home) {
+    const dir = join(home, 'bench', 'cases');
+    const written = [];
+    const seeds = [
+        ['toolchain-report.task', '运行鸿蒙工具链体检,然后逐项说出一共检查了哪三个工具的名称\nexpect: hdc && hvigorw && ohpm\ntools: loop\n'],
+        ['reply-determinism.task', '只回复这六个字符,不要任何其他内容:HMH-OK\nexpect: HMH-OK\n'],
+        ['toolchain-ohpm-status.task', '运行鸿蒙工具链体检,然后只回答 ohpm 的状态是 OK 还是 MISSING\nexpect: OK\ntools: loop\nholdout: true\n'],
+    ];
+    let existing = [];
+    try {
+        existing = await readdir(dir);
+    }
+    catch {
+        /* first seed */
+    }
+    for (const [name, body] of seeds) {
+        if (existing.includes(name))
+            continue;
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, name), body, 'utf8');
+        written.push(name);
+    }
+    return written;
+}

package/dist/candidates.d.ts.v2bak.v2bak

@@ -0,0 +1,114 @@
+import type { BenchCase } from './bench.ts';
+export type CandidateTarget = 'prompt' | 'skill' | 'context' | 'tool_policy' | 'model_router' | 'workflow' | 'harness';
+export declare const CANDIDATE_TARGETS: CandidateTarget[];
+export interface EvolutionCandidate {
+    id: string;
+    target: CandidateTarget;
+    /** the version this candidate is measured against (baseline pointer) */
+    baseVersion: string;
+    candidateVersion: string;
+    hypothesis: string;
+    /** metric the experiment reports on, e.g. 'bench.passRate' */
+    expectedMetric: string;
+    /** target-specific payload: skill markdown, prompt delta, router table… */
+    payload?: string;
+    /** who proposed it - 'agent' proposals on prompt/harness need human sign-off */
+    origin?: string;
+    createdAt: string;
+}
+export declare function registerCandidate(home: string, cand: Omit<EvolutionCandidate, 'id' | 'createdAt'> & {
+    id?: string;
+}): Promise<EvolutionCandidate>;
+export declare function listCandidates(home: string): Promise<EvolutionCandidate[]>;
+export declare function getCandidate(home: string, id: string): Promise<EvolutionCandidate | null>;
+/** Two-proportion two-sided test (treatment vs control pass rates). */
+export declare function twoProportionTest(control: {
+    pass: number;
+    n: number;
+}, treatment: {
+    pass: number;
+    n: number;
+}): {
+    z: number;
+    p: number;
+    diff: number;
+};
+export interface ArmResult {
+    pass: boolean;
+    /** token cost of the arm run (cost-cap honesty, same currency as estTokens) */
+    tokens: number;
+}
+/** Injected by the caller: run one bench case under one arm. The runner owns
+ *  the actual injection point (skills block, memory config, router table…). */
+export type ArmRunner = (c: BenchCase, arm: 'control' | 'treatment') => Promise<ArmResult>;
+export interface ExperimentArm {
+    pass: number;
+    n: number;
+    passRate: number;
+    tokens: number;
+    /** per-case rows (day-56): which case flipped is the point of a diff */
+    results?: Array<{
+        name: string;
+        pass: boolean;
+        tokens: number;
+    }>;
+}
+export interface ExperimentReport {
+    candidateId: string;
+    ranAt: string;
+    cases: number;
+    control: ExperimentArm;
+    treatment: ExperimentArm;
+    diff: number;
+    z: number;
+    p: number;
+    verdict: 'promote-eligible' | 'reject' | 'needs-data';
+    reason: string;
+}
+/** Per-arm minimum before any verdict counts (aligned with impact.ts canary
+ *  threshold: >=8 sessions, and blueprint "one success is not significance"). */
+export declare const MIN_ARM_N = 8;
+export declare function verdictFor(control: {
+    pass: number;
+    n: number;
+}, treatment: {
+    pass: number;
+    n: number;
+}): {
+    verdict: ExperimentReport['verdict'];
+    reason: string;
+    z: number;
+    p: number;
+    diff: number;
+};
+export declare function runCandidateExperiment(home: string, candidateId: string, opts: {
+    runCase: ArmRunner;
+    cases: BenchCase[];
+    maxCases?: number;
+}): Promise<ExperimentReport>;
+/** Latest experiment report for a candidate (promotion evidence). */
+export declare function latestExperiment(home: string, candidateId: string): Promise<ExperimentReport | null>;
+export interface ActiveVersion {
+    target: CandidateTarget;
+    version: string;
+    candidateId: string;
+    since: string;
+    reportAt?: string;
+}
+export declare function activeVersions(home: string): Promise<Record<string, ActiveVersion>>;
+export interface PromoteResult {
+    ok: boolean;
+    error?: string;
+    active?: ActiveVersion;
+}
+/** Blueprint gates, enforced: latest report must be promote-eligible, a
+ *  previous pointer is written BEFORE activation, agent-origin prompt/harness
+ *  candidates need approvedByHuman. Skill promotions ride the existing
+ *  promoteSkill canary channel. */
+export declare function promoteCandidate(home: string, candidateId: string, opts?: {
+    approvedByHuman?: boolean;
+}): Promise<PromoteResult>;
+export declare function rollbackCandidate(home: string, target: CandidateTarget): Promise<{
+    ok: boolean;
+    error?: string;
+}>;

package/dist/candidates.js.v2bak.v2bak

@@ -0,0 +1,232 @@
+/**
+ * @hmharness/evolution - candidates (V2 M9: Evolution 泛化)
+ * Blueprint M9: a typed candidate registry (prompt/skill/context/tool_policy/
+ * model_router/workflow/harness), a Control/Treatment experiment runner,
+ * statistical comparison, and gated promotion/rollback. See ADR-0003.
+ *
+ * 红线 (blueprint 14.3, enforced here, not by convention):
+ *  - 无实验报告(promote-eligible)不晋升 —— no baseline, no improvement claim
+ *  - 激活前必写 previous 指针 —— no rollback, no promotion
+ *  - origin=agent 的 prompt/harness 候选需人工标记才可激活 —— agents never
+ *    self-modify the production prompt
+ *  - 晋升判据是双比例检验,LLM self-report 无效力 —— M2 证据阶梯双保险
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { screenForPoison } from "./evolve.js";
+export const CANDIDATE_TARGETS = [
+    'prompt', 'skill', 'context', 'tool_policy', 'model_router', 'workflow', 'harness',
+];
+/* ---------------- registry ---------------- */
+function candDir(home) {
+    return join(home, 'evolution', 'candidates');
+}
+export async function registerCandidate(home, cand) {
+    if (!CANDIDATE_TARGETS.includes(cand.target))
+        throw new Error(`unknown candidate target: ${cand.target}`);
+    if (!cand.hypothesis.trim() || !cand.candidateVersion.trim())
+        throw new Error('candidate needs a hypothesis and a candidateVersion');
+    const poison = screenForPoison(cand.hypothesis + '\n' + (cand.payload ?? ''));
+    if (poison)
+        throw new Error(`candidate rejected by safety screen: ${poison}`);
+    const full = {
+        ...cand,
+        id: cand.id ?? `cand_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        createdAt: new Date().toISOString(),
+    };
+    await mkdir(candDir(home), { recursive: true });
+    await writeFile(join(candDir(home), `${full.id}.json`), JSON.stringify(full, null, 2) + '\n', 'utf8');
+    return full;
+}
+export async function listCandidates(home) {
+    let files = [];
+    try {
+        files = (await readdir(candDir(home))).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            out.push(JSON.parse(await readFile(join(candDir(home), f), 'utf8')));
+        }
+        catch { /* skip torn */ }
+    }
+    return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+export async function getCandidate(home, id) {
+    try {
+        return JSON.parse(await readFile(join(candDir(home), `${id}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/* ---------------- statistics ---------------- */
+/** Standard normal CDF, Zelen & Severo approximation of A&S 26.2.17 (|err|<7.5e-8). */
+function normalCdf(z) {
+    const t = 1 / (1 + 0.2316419 * Math.abs(z));
+    const d = Math.exp(-z * z / 2) / Math.sqrt(2 * Math.PI);
+    const poly = t * (0.319381530 + t * (-0.356563782 + t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    const upper = d * poly; // P(Z > |z|) tail
+    return z >= 0 ? 1 - upper : upper;
+}
+/** Two-proportion two-sided test (treatment vs control pass rates). */
+export function twoProportionTest(control, treatment) {
+    if (control.n <= 0 || treatment.n <= 0)
+        return { z: 0, p: 1, diff: 0 };
+    const pc = control.pass / control.n;
+    const pt = treatment.pass / treatment.n;
+    const pool = (control.pass + treatment.pass) / (control.n + treatment.n);
+    const se = Math.sqrt(pool * (1 - pool) * (1 / control.n + 1 / treatment.n));
+    const z = se > 0 ? (pt - pc) / se : 0;
+    return { z, p: 2 * (1 - normalCdf(Math.abs(z))), diff: pt - pc };
+}
+/** Per-arm minimum before any verdict counts (aligned with impact.ts canary
+ *  threshold: >=8 sessions, and blueprint "one success is not significance"). */
+export const MIN_ARM_N = 8;
+export function verdictFor(control, treatment) {
+    const { z, p, diff } = twoProportionTest(control, treatment);
+    if (control.n < MIN_ARM_N || treatment.n < MIN_ARM_N) {
+        return { verdict: 'needs-data', reason: `samples below ${MIN_ARM_N} per arm (control ${control.n}, treatment ${treatment.n})`, z, p, diff };
+    }
+    if (p < 0.05 && diff >= 0.10)
+        return { verdict: 'promote-eligible', reason: `significant lift (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+    if ((p < 0.05 && diff <= -0.05) || diff <= -0.10) {
+        return { verdict: 'reject', reason: `regression (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+    }
+    return { verdict: 'needs-data', reason: `no significant difference (p=${p.toFixed(4)}, diff=${(diff * 100).toFixed(1)}%)`, z, p, diff };
+}
+export async function runCandidateExperiment(home, candidateId, opts) {
+    const cand = await getCandidate(home, candidateId);
+    if (!cand)
+        throw new Error(`no candidate: ${candidateId}`);
+    // holdout cases are excluded from promotion gates (bench.ts anti-memorization)
+    const gate = opts.cases.filter((c) => !c.holdout).slice(0, Math.max(1, opts.maxCases ?? 12));
+    let cPass = 0, cTok = 0, tPass = 0, tTok = 0;
+    // per-case rows (day-56 observability: which case flipped is the whole
+    // point of a diff - aggregates alone cannot answer it)
+    const ctlRows = [];
+    const trtRows = [];
+    for (const c of gate) {
+        const ctl = await opts.runCase(c, 'control');
+        if (ctl.pass)
+            cPass++;
+        cTok += ctl.tokens;
+        ctlRows.push({ name: c.name, pass: ctl.pass, tokens: ctl.tokens });
+        const trt = await opts.runCase(c, 'treatment');
+        if (trt.pass)
+            tPass++;
+        tTok += trt.tokens;
+        trtRows.push({ name: c.name, pass: trt.pass, tokens: trt.tokens });
+    }
+    const v = verdictFor({ pass: cPass, n: gate.length }, { pass: tPass, n: gate.length });
+    const report = {
+        candidateId,
+        ranAt: new Date().toISOString(),
+        cases: gate.length,
+        control: { pass: cPass, n: gate.length, passRate: gate.length ? cPass / gate.length : 0, tokens: cTok, results: ctlRows },
+        treatment: { pass: tPass, n: gate.length, passRate: gate.length ? tPass / gate.length : 0, tokens: tTok, results: trtRows },
+        ...v,
+    };
+    const dir = join(home, 'evolution', 'experiments', candidateId);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${report.ranAt.replace(/[:.]/g, '-')}.json`), JSON.stringify(report, null, 2) + '\n', 'utf8');
+    return report;
+}
+/** Latest experiment report for a candidate (promotion evidence). */
+export async function latestExperiment(home, candidateId) {
+    const dir = join(home, 'evolution', 'experiments', candidateId);
+    let files = [];
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith('.json')).sort();
+    }
+    catch {
+        return null;
+    }
+    if (files.length === 0)
+        return null;
+    try {
+        return JSON.parse(await readFile(join(dir, files[files.length - 1]), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+const activeDir = (home) => join(home, 'evolution', 'active');
+export async function activeVersions(home) {
+    const out = {};
+    let files = [];
+    try {
+        files = await readdir(activeDir(home));
+    }
+    catch {
+        return out;
+    }
+    for (const f of files.filter((f) => f.endsWith('.json') && !f.endsWith('.previous.json'))) {
+        try {
+            const v = JSON.parse(await readFile(join(activeDir(home), f), 'utf8'));
+            out[v.target] = v;
+        }
+        catch { /* skip torn */ }
+    }
+    return out;
+}
+/** Blueprint gates, enforced: latest report must be promote-eligible, a
+ *  previous pointer is written BEFORE activation, agent-origin prompt/harness
+ *  candidates need approvedByHuman. Skill promotions ride the existing
+ *  promoteSkill canary channel. */
+export async function promoteCandidate(home, candidateId, opts = {}) {
+    const cand = await getCandidate(home, candidateId);
+    if (!cand)
+        return { ok: false, error: `no candidate: ${candidateId}` };
+    const report = await latestExperiment(home, candidateId);
+    if (!report)
+        return { ok: false, error: 'no experiment report - run the experiment first (no baseline, no promotion)' };
+    if (report.verdict !== 'promote-eligible') {
+        return { ok: false, error: `latest report verdict is ${report.verdict} (${report.reason}) - not promotable` };
+    }
+    if ((cand.target === 'prompt' || cand.target === 'harness') && cand.origin === 'agent' && !opts.approvedByHuman) {
+        return { ok: false, error: 'agent-origin prompt/harness candidate requires approvedByHuman (production prompt is not agent-writable)' };
+    }
+    await mkdir(activeDir(home), { recursive: true });
+    const cur = await activeVersions(home);
+    const previous = cur[cand.target];
+    if (previous) {
+        await writeFile(join(activeDir(home), `${cand.target}.previous.json`), JSON.stringify(previous, null, 2) + '\n', 'utf8');
+    }
+    if (cand.target === 'skill') {
+        // payload = skill name; the audited canary channel stays the only skill path
+        const { promoteSkill } = await import("./skills.js");
+        if (!cand.payload)
+            return { ok: false, error: 'skill candidate has no payload (skill name)' };
+        await promoteSkill(home, cand.payload, { canary: true });
+    }
+    const active = {
+        target: cand.target,
+        version: cand.candidateVersion,
+        candidateId: cand.id,
+        since: new Date().toISOString(),
+        reportAt: report.ranAt,
+    };
+    await writeFile(join(activeDir(home), `${cand.target}.json`), JSON.stringify(active, null, 2) + '\n', 'utf8');
+    return { ok: true, active };
+}
+export async function rollbackCandidate(home, target) {
+    const dir = activeDir(home);
+    const prevPath = join(dir, `${target}.previous.json`);
+    let previous = null;
+    try {
+        previous = JSON.parse(await readFile(prevPath, 'utf8'));
+    }
+    catch { /* no previous */ }
+    if (!previous)
+        return { ok: false, error: `no previous pointer for ${target} - nothing to roll back to` };
+    if (target === 'skill') {
+        const { rollbackSkill } = await import("./skills.js");
+        await rollbackSkill(home, previous.version);
+    }
+    await writeFile(join(dir, `${target}.json`), JSON.stringify(previous, null, 2) + '\n', 'utf8');
+    return { ok: true };
+}

package/dist/dataset.d.ts.v2bak.v2bak

@@ -0,0 +1,64 @@
+export interface DatasetSample {
+    runId: string;
+    task: string;
+    outcome: string;
+    turns: number;
+    toolUses: number;
+    toolFailRate: number;
+    toolsUsed: string[];
+    model: string;
+    /** evidence rank from the M2 ladder when the run was evaluated (0 = none) */
+    evidenceRank: number;
+    /** interpretable reward in [0,1]; llm-judged runs never reach 1.0 (M2 cap) */
+    reward: number;
+    /** evaluation notes / failure snippets attach here (bounded) */
+    evidence?: string;
+    split: 'train' | 'eval';
+}
+export interface DatasetManifest {
+    version: string;
+    createdAt: string;
+    /** inclusive run-id scan window (first..last seen, lexicographic) */
+    runWindow: {
+        first: string | null;
+        last: string | null;
+    };
+    filterFingerprint: string;
+    splitSeed: number;
+    splitRatio: number;
+    counts: {
+        scanned: number;
+        kept: number;
+        dropped: number;
+        duplicates: number;
+        train: number;
+        eval: number;
+    };
+    rewardHistogram: Record<string, number>;
+}
+export interface DatasetBuildResult {
+    manifest: DatasetManifest;
+    dir: string;
+}
+/** Interpretable reward mapping (ADR-0004): ok runs start at 1.0 and lose
+ *  0.1 per 20% tool-failure rate; non-ok runs cap at 0.3. Evidence rank
+ *  from the M2 ladder nudges confidence but never creates a free perfect. */
+export declare function rewardFor(outcome: string, toolFailRate: number, evidenceRank?: number): number;
+/** Stable fingerprint of the filter config - manifest must be reproducible. */
+export declare function filterFingerprint(opts: {
+    keepOutcome?: string[];
+    minTurns?: number;
+}): string;
+/** Deterministic hash-based split (same run always lands in the same half). */
+export declare function splitFor(runId: string, seed: number, evalRatio?: number): 'train' | 'eval';
+export interface BuildDatasetOptions {
+    version?: string;
+    /** outcomes to keep; default keeps everything labeled */
+    keepOutcome?: string[];
+    minTurns?: number;
+    evalRatio?: number;
+    splitSeed?: number;
+}
+export declare function buildDataset(home: string, opts?: BuildDatasetOptions): Promise<DatasetBuildResult>;
+export declare function listDatasets(home: string): Promise<DatasetManifest[]>;
+export declare function loadDataset(home: string, version: string, split?: 'train' | 'eval'): Promise<DatasetSample[]>;