crewhaus 0.1.7 → 0.2.0

package/dist/propose.js

@@ -0,0 +1,184 @@
+/**
+ * Item 59 (half 2) — PR-based spec-change proposals. `crewhaus propose
+ * <proposed-spec.yaml>` is the team-governance wrapper around the
+ * write-back verbs (`optimize --write-back`, `advise`, `model-scan`): instead
+ * of mutating the live spec in place, it packages the proposed change into a
+ * REVIEW artifact — a `patch.json` field diff, a rendered changelog entry, the
+ * eval score delta, and provenance — and opens a GitHub PR so the team reviews
+ * a prompt/model change like code. It NEVER auto-merges: the PR is the human
+ * gate (mirroring the flywheel workflow's "never add an auto-merge step").
+ *
+ * Factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Assembly is pure; git/gh live behind an injected `GitPrDriver` seam, so the
+ * artifact bundle + PR body are unit-tested without a network or a real repo.
+ *
+ * INPUTS the review bundle carries:
+ *   - patch.json: the structural field diff (`diffSpecYaml`) between the
+ *     CURRENT spec and the PROPOSED spec — the reviewable "what changed";
+ *   - CHANGELOG entry: `renderChangelogEntry` over the same before/after (+
+ *     any optimizer provenance the proposed dir carries), the human-readable
+ *     summary;
+ *   - eval delta: when a baseline + candidate eval score are supplied
+ *     (`--score-before`/`--score-after`, or read from the optimize run), the
+ *     measured improvement that justifies the change;
+ *   - provenance: the source verb (`optimize`/`advise`/`manual`), the content
+ *     hash of the proposed spec, and the run id when present.
+ *
+ * The PR is opened on a fresh branch carrying ONLY the spec change + the
+ * review bundle under `.crewhaus/proposals/<id>/`. The proposal is itself
+ * audit-logged (`governance_proposal`) so its provenance is evidenced before
+ * any human acts on it.
+ */
+import { createHash } from "node:crypto";
+import { diffSpecYaml } from "@crewhaus/spec-patch";
+import { renderChangelogEntry } from "./spec-changelog";
+/** Thrown for operational failures (unreadable spec, no change, driver
+ *  failure). The CLI routes the message through `die()`; tests assert on
+ *  `.message`. */
+export class ProposeError extends Error {
+    name = "ProposeError";
+}
+/** Where a proposal's review bundle lands within the repo. */
+export const PROPOSALS_RELDIR = ".crewhaus/proposals";
+/** sha256 hex of a spec's bytes — the patch identity carried into provenance. */
+export function specContentHash(yaml) {
+    return createHash("sha256").update(yaml).digest("hex");
+}
+/**
+ * Assemble the review bundle from current + proposed spec YAML. Pure — no
+ * filesystem, no git. Throws when the proposed spec is byte-identical to the
+ * current one (nothing to propose); a structurally-empty-but-reformatted
+ * change is allowed through with a note (comments matter to reviewers).
+ */
+export function assembleProposal(opts) {
+    if (opts.proposedYaml === opts.currentYaml) {
+        throw new ProposeError("proposed spec is byte-identical to the current spec — nothing to propose");
+    }
+    let diff;
+    try {
+        diff = diffSpecYaml(opts.currentYaml, opts.proposedYaml);
+    }
+    catch (err) {
+        throw new ProposeError(`could not diff the specs: ${err.message}`);
+    }
+    const generatedAt = (opts.now?.() ?? new Date()).toISOString();
+    const provenance = {
+        source: opts.source,
+        specName: opts.specName,
+        patchHash: specContentHash(opts.proposedYaml),
+        ...(opts.runId !== undefined ? { runId: opts.runId } : {}),
+        generatedAt,
+    };
+    const patch = {
+        specName: opts.specName,
+        diff,
+        provenance,
+        ...(opts.evalDelta !== undefined ? { evalDelta: opts.evalDelta } : {}),
+    };
+    const patchJson = `${JSON.stringify(patch, null, 2)}\n`;
+    const changelogEntry = renderChangelogEntry({
+        version: opts.proposedVersion,
+        yaml: opts.proposedYaml,
+        previousYaml: opts.currentYaml,
+        ...(opts.optimizeRootDir !== undefined ? { optimizeRootDir: opts.optimizeRootDir } : {}),
+        ...(opts.patchJsonPath !== undefined ? { patchJsonPath: opts.patchJsonPath } : {}),
+        ...(opts.now !== undefined ? { now: opts.now() } : {}),
+    });
+    const prTitle = `propose: ${opts.specName} ${opts.proposedVersion} (${opts.source})`;
+    const prBody = buildPrBody({
+        specName: opts.specName,
+        version: opts.proposedVersion,
+        source: opts.source,
+        diff,
+        ...(opts.evalDelta !== undefined ? { evalDelta: opts.evalDelta } : {}),
+        ...(opts.runId !== undefined ? { runId: opts.runId } : {}),
+        patchHash: provenance.patchHash,
+    });
+    return {
+        patch,
+        patchJson,
+        changelogEntry,
+        prTitle,
+        prBody,
+        hasStructuralChange: diff.length > 0,
+    };
+}
+function buildPrBody(args) {
+    const lines = [];
+    lines.push(`Proposed change to **${args.specName}** (${args.version}), source: \`${args.source}\`.`);
+    lines.push("");
+    lines.push("This PR was opened by `crewhaus propose` — the spec was NOT modified in place.");
+    lines.push("Review it like code; merging is the human gate (there is no auto-merge).");
+    lines.push("");
+    if (args.evalDelta !== undefined) {
+        const d = args.evalDelta;
+        const arrow = d.scoreAfter >= d.scoreBefore ? "↑" : "↓";
+        lines.push(`**Eval delta**: ${d.scoreBefore.toFixed(3)} → ${d.scoreAfter.toFixed(3)} ${arrow}${d.datasetName !== undefined ? ` (${d.datasetName})` : ""}`);
+        lines.push("");
+    }
+    lines.push("**Structural diff**");
+    if (args.diff.length === 0) {
+        lines.push("- no structural changes (comments/formatting only)");
+    }
+    else {
+        for (const d of args.diff)
+            lines.push(diffLine(d));
+    }
+    lines.push("");
+    if (args.runId !== undefined)
+        lines.push(`Run: \`${args.runId}\``);
+    lines.push(`Patch hash: \`${args.patchHash.slice(0, 16)}…\``);
+    lines.push("");
+    lines.push(`The full review bundle (\`patch.json\` + changelog entry) is in \`${PROPOSALS_RELDIR}/\`.`);
+    return `${lines.join("\n")}\n`;
+}
+function diffLine(d) {
+    switch (d.kind) {
+        case "added":
+            return `- added \`${d.path}\`: ${d.after ?? ""}`;
+        case "removed":
+            return `- removed \`${d.path}\`: ${d.before ?? ""}`;
+        case "changed":
+            return `- changed \`${d.path}\`: ${d.before ?? ""} → ${d.after ?? ""}`;
+    }
+}
+/** Slug-safe proposal id: `<spec>-<version>-<shorthash>-<stamp>`. */
+export function proposalId(specName, version, patchHash, now) {
+    const slug = specName.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    const stamp = now.toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    return `${slug || "spec"}-${version}-${patchHash.slice(0, 8)}-${stamp}`;
+}
+/** Assemble the branch/commit/PR plan + the review-bundle files. Pure. */
+export function buildProposalPrPlan(opts) {
+    const now = opts.now?.() ?? new Date();
+    const id = proposalId(opts.assembled.patch.specName, opts.proposedVersion, opts.assembled.patch.provenance.patchHash, now);
+    const bundleDir = `${PROPOSALS_RELDIR}/${id}`;
+    const files = {
+        [opts.specRelPath]: opts.proposedYaml,
+        [`${bundleDir}/patch.json`]: opts.assembled.patchJson,
+        [`${bundleDir}/CHANGELOG-entry.md`]: opts.assembled.changelogEntry,
+        [`${bundleDir}/PR-body.md`]: opts.assembled.prBody,
+    };
+    const plan = {
+        branch: `propose/${id}`,
+        title: opts.assembled.prTitle,
+        body: opts.assembled.prBody,
+        files,
+        commitMessage: `propose(${opts.assembled.patch.specName}): ${opts.proposedVersion} for review`,
+    };
+    return { plan, proposalId: id };
+}
+export function buildProposalAuditPayload(assembled, opened, proposedVersion, now) {
+    return {
+        source: assembled.patch.provenance.source,
+        specName: assembled.patch.specName,
+        patchHash: assembled.patch.provenance.patchHash,
+        proposedVersion,
+        ...(assembled.patch.evalDelta !== undefined ? { evalDelta: assembled.patch.evalDelta } : {}),
+        ...(opened.prNumber !== undefined ? { prNumber: opened.prNumber } : {}),
+        prUrl: opened.url,
+        branch: opened.branch,
+        ts: now(),
+    };
+}

package/dist/refresh-goldens.d.ts

@@ -0,0 +1,82 @@
+import type { Sample } from "@crewhaus/eval-dataset";
+import { type FeedbackRecord, type SessionTurn } from "./feedback";
+/** Thrown on malformed flags / unusable inputs. The CLI entry file routes it
+ *  through `die()`; tests assert on `.message`. */
+export declare class RefreshGoldensError extends Error {
+    readonly name = "RefreshGoldensError";
+}
+/** Default rating threshold above which a turn is "up-rated" (mirrors distill). */
+export declare const DEFAULT_REFRESH_MIN_SCORE = 0.7;
+/** Similarity at/above which a feedback turn matches a stored sample by input. */
+export declare const INPUT_MATCH_SIMILARITY = 0.6;
+export type GoldEvidence = "correction" | "up-rated-divergence";
+/** One proposed gold update for a stored sample. */
+export type GoldProposal = {
+    readonly sampleId: string;
+    /** Content hash of the CURRENT stored sample (registry hashSample). */
+    readonly currentHash: string;
+    readonly input: string;
+    /** The stored gold (may be undefined — a sample with no expected_output). */
+    readonly currentGold?: string;
+    /** The proposed new gold, drawn from the correction/up-rated answer. */
+    readonly proposedGold: string;
+    readonly evidence: GoldEvidence;
+    /** Where the proposed gold came from (sessionId#turn). */
+    readonly sourceRef: string;
+    /** True when the run-history index shows this sample failing across runs. */
+    readonly stale: boolean;
+};
+export type RefreshResult = {
+    readonly proposals: ReadonlyArray<GoldProposal>;
+    /** Feedback turns that matched no stored sample (informational). */
+    readonly unmatched: number;
+    /** Number of samples inspected. */
+    readonly sampleCount: number;
+};
+/**
+ * Find the stored sample a feedback turn's input reconciles with: exact
+ * (normalized) input equality first, then the best token-overlap match at/above
+ * {@link INPUT_MATCH_SIMILARITY}. Returns undefined when nothing is close
+ * enough — a genuinely new input is not a gold refresh (that is `dataset mine`).
+ */
+export declare function matchSampleByInput(input: string, samples: ReadonlyArray<Sample>): Sample | undefined;
+/** Minimal per-run sample outcome the staleness check reads. */
+export type RunSampleOutcome = {
+    sampleId: string;
+    passed: boolean;
+};
+/**
+ * A sample is STALE when it FAILED in every run that included it AND was seen
+ * in at least `minRuns` runs — a persistent eval failure. Callers pair this
+ * with a live up-rating to conclude the GOLD is wrong, not the agent. A sample
+ * absent from the run history carries no stale signal (returns false) — we
+ * never fabricate one.
+ */
+export declare function isStaleSample(sampleId: string, runs: ReadonlyArray<ReadonlyArray<RunSampleOutcome>>, minRuns?: number): boolean;
+/**
+ * Reconcile merged feedback against the stored samples, proposing gold updates
+ * where a correction or up-rated answer diverges from the stored
+ * `expected_output`. `turns` supplies each feedback record's input + observed
+ * answer (keyed sessionId#turn). `runOutcomes` (from the run-history index)
+ * powers the stale flag; pass [] to skip staleness.
+ *
+ * A proposal is emitted only when the proposed gold is non-empty and actually
+ * DIFFERS from the stored gold — a correction that matches the current gold is
+ * already reconciled.
+ */
+export declare function reconcileGoldens(opts: {
+    samples: ReadonlyArray<Sample>;
+    turns: ReadonlyArray<SessionTurn>;
+    records: ReadonlyArray<FeedbackRecord>;
+    minScore: number;
+    runOutcomes?: ReadonlyArray<ReadonlyArray<RunSampleOutcome>>;
+}): RefreshResult;
+/**
+ * Apply proposals to the stored samples, producing the NEW sample array to
+ * register as a fresh version. Never mutates the input; a proposed sample gets
+ * its `expected_output` replaced and a provenance note added to metadata.
+ * Samples with no proposal pass through unchanged.
+ */
+export declare function applyProposals(samples: ReadonlyArray<Sample>, proposals: ReadonlyArray<GoldProposal>): Sample[];
+/** The review diff — a per-proposal old→new gold report (printed by default). */
+export declare function renderProposals(result: RefreshResult, datasetLabel: string): string;

package/dist/refresh-goldens.js

@@ -0,0 +1,221 @@
+/**
+ * Item 5 — `crewhaus dataset refresh-goldens`: reconcile the human
+ * corrections + up-rated turns that accumulated in production against an
+ * existing dataset's stored gold answers. When a user's accepted/corrected
+ * output diverges from a sample's `expected_output`, PROPOSE a gold update
+ * (never in-place — the write is always a NEW dataset-registry version).
+ *
+ * Two evidence classes drive a proposal:
+ *   - CORRECTION: a `user_feedback` record carrying a `correction` (the user
+ *     typed a better answer) on a turn whose input matches a stored sample.
+ *   - UP-RATED DIVERGENCE: an up-rated turn (normalized rating ≥ min-score)
+ *     whose observed answer differs from the stored gold — the live behavior
+ *     the user liked is not what the dataset asserts.
+ *
+ * Matching is input-equality first, then token-overlap similarity (the same
+ * similarity the sibling flywheel features use), so a lightly-reworded prompt
+ * still reconciles. Samples that FAIL consistently across eval runs yet are
+ * repeatedly up-rated live are flagged STALE using the run-history index; a
+ * sample with no cross-run history simply carries no stale signal (we never
+ * fabricate one).
+ *
+ * Provenance: each proposal records the stored sample's content hash (via the
+ * registry's own `hashSample`, so hashes line up with what `put` recorded) and
+ * the evidence class. Kept in a side-effect-free module mirroring
+ * `feedback.ts` / `graders-suggest.ts`; all filesystem access + the registry
+ * version write live in `apps/cli/src/index.ts`.
+ */
+import { hashSample } from "@crewhaus/dataset-registry";
+import { mergeFeedback, normalizeRating } from "./feedback";
+import { normalizeEvidenceTokens } from "./graders-suggest";
+/** Thrown on malformed flags / unusable inputs. The CLI entry file routes it
+ *  through `die()`; tests assert on `.message`. */
+export class RefreshGoldensError extends Error {
+    name = "RefreshGoldensError";
+}
+/** Default rating threshold above which a turn is "up-rated" (mirrors distill). */
+export const DEFAULT_REFRESH_MIN_SCORE = 0.7;
+/** Similarity at/above which a feedback turn matches a stored sample by input. */
+export const INPUT_MATCH_SIMILARITY = 0.6;
+// -------- similarity --------
+function tokenSet(text) {
+    return new Set(normalizeEvidenceTokens(text));
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersection += 1;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/** Normalize an input for equality matching (whitespace-collapsed, trimmed). */
+function normInput(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+/**
+ * Find the stored sample a feedback turn's input reconciles with: exact
+ * (normalized) input equality first, then the best token-overlap match at/above
+ * {@link INPUT_MATCH_SIMILARITY}. Returns undefined when nothing is close
+ * enough — a genuinely new input is not a gold refresh (that is `dataset mine`).
+ */
+export function matchSampleByInput(input, samples) {
+    const target = normInput(input);
+    for (const s of samples) {
+        if (normInput(s.input) === target)
+            return s;
+    }
+    const targetTokens = tokenSet(input);
+    if (targetTokens.size === 0)
+        return undefined;
+    let best;
+    let bestOverlap = INPUT_MATCH_SIMILARITY;
+    for (const s of samples) {
+        const overlap = jaccard(targetTokens, tokenSet(s.input));
+        if (overlap >= bestOverlap) {
+            // Strictly-greater keeps the FIRST best on ties (stable across runs);
+            // use > so a later equal match doesn't flip the winner.
+            if (overlap > bestOverlap || best === undefined) {
+                bestOverlap = overlap;
+                best = s;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * A sample is STALE when it FAILED in every run that included it AND was seen
+ * in at least `minRuns` runs — a persistent eval failure. Callers pair this
+ * with a live up-rating to conclude the GOLD is wrong, not the agent. A sample
+ * absent from the run history carries no stale signal (returns false) — we
+ * never fabricate one.
+ */
+export function isStaleSample(sampleId, runs, minRuns = 2) {
+    let seen = 0;
+    let failedEvery = true;
+    for (const run of runs) {
+        const outcome = run.find((o) => o.sampleId === sampleId);
+        if (outcome === undefined)
+            continue;
+        seen += 1;
+        if (outcome.passed)
+            failedEvery = false;
+    }
+    return seen >= minRuns && failedEvery;
+}
+// -------- reconciliation --------
+/**
+ * Reconcile merged feedback against the stored samples, proposing gold updates
+ * where a correction or up-rated answer diverges from the stored
+ * `expected_output`. `turns` supplies each feedback record's input + observed
+ * answer (keyed sessionId#turn). `runOutcomes` (from the run-history index)
+ * powers the stale flag; pass [] to skip staleness.
+ *
+ * A proposal is emitted only when the proposed gold is non-empty and actually
+ * DIFFERS from the stored gold — a correction that matches the current gold is
+ * already reconciled.
+ */
+export function reconcileGoldens(opts) {
+    const turnByKey = new Map();
+    for (const t of opts.turns)
+        turnByKey.set(`${t.sessionId}#${t.turnNumber}`, t);
+    const runs = opts.runOutcomes ?? [];
+    const bySample = new Map();
+    let unmatched = 0;
+    for (const fb of mergeFeedback(opts.records)) {
+        const turn = turnByKey.get(`${fb.sessionId}#${fb.turnNumber}`);
+        if (turn === undefined) {
+            unmatched += 1;
+            continue;
+        }
+        const score = normalizeRating(fb);
+        const upRated = score !== undefined && score >= opts.minScore;
+        // The candidate better-answer: an explicit correction, else the up-rated
+        // live answer.
+        const proposed = fb.correction !== undefined && fb.correction.trim() !== ""
+            ? fb.correction
+            : upRated && turn.output.trim() !== ""
+                ? turn.output
+                : undefined;
+        if (proposed === undefined)
+            continue;
+        const sample = matchSampleByInput(turn.input, opts.samples);
+        if (sample === undefined) {
+            unmatched += 1;
+            continue;
+        }
+        const currentGold = sample.expected_output;
+        if (currentGold !== undefined && normInput(currentGold) === normInput(proposed)) {
+            continue; // already reconciled
+        }
+        const evidence = fb.correction !== undefined ? "correction" : "up-rated-divergence";
+        const proposal = {
+            sampleId: sample.id,
+            currentHash: hashSample(sample),
+            input: sample.input,
+            ...(currentGold !== undefined ? { currentGold } : {}),
+            proposedGold: proposed,
+            evidence,
+            sourceRef: `${fb.sessionId}#${fb.turnNumber}`,
+            stale: isStaleSample(sample.id, runs),
+        };
+        // A correction outranks an up-rated divergence for the same sample; on a
+        // tie the first-seen wins (deterministic given merged-feedback order).
+        const existing = bySample.get(sample.id);
+        if (existing === undefined ||
+            (existing.evidence !== "correction" && evidence === "correction")) {
+            bySample.set(sample.id, proposal);
+        }
+    }
+    const proposals = [...bySample.values()].sort((a, b) => a.sampleId.localeCompare(b.sampleId));
+    return { proposals, unmatched, sampleCount: opts.samples.length };
+}
+/**
+ * Apply proposals to the stored samples, producing the NEW sample array to
+ * register as a fresh version. Never mutates the input; a proposed sample gets
+ * its `expected_output` replaced and a provenance note added to metadata.
+ * Samples with no proposal pass through unchanged.
+ */
+export function applyProposals(samples, proposals) {
+    const byId = new Map(proposals.map((p) => [p.sampleId, p]));
+    return samples.map((s) => {
+        const p = byId.get(s.id);
+        if (p === undefined)
+            return s;
+        const metadata = { ...(s.metadata ?? {}) };
+        metadata["gold_refreshed"] = {
+            from: p.currentGold ?? null,
+            evidence: p.evidence,
+            source: p.sourceRef,
+            prevHash: p.currentHash,
+        };
+        return { ...s, expected_output: p.proposedGold, metadata };
+    });
+}
+// -------- rendering --------
+const clip = (s, max) => (s.length > max ? `${s.slice(0, max)}…` : s);
+/** The review diff — a per-proposal old→new gold report (printed by default). */
+export function renderProposals(result, datasetLabel) {
+    const lines = [];
+    lines.push(`refresh-goldens: ${result.proposals.length} proposed gold update(s) for ${datasetLabel} (${result.sampleCount} sample(s))`);
+    if (result.unmatched > 0) {
+        lines.push(`  (${result.unmatched} feedback turn(s) matched no stored sample — skipped)`);
+    }
+    lines.push("");
+    if (result.proposals.length === 0) {
+        lines.push("no gold updates — stored golds already agree with corrections and up-rated turns.");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const p of result.proposals) {
+        lines.push(`● ${p.sampleId}  [${p.evidence}${p.stale ? ", STALE across runs" : ""}]`);
+        lines.push(`    input:    ${clip(p.input, 100)}`);
+        lines.push(`    - old:    ${p.currentGold !== undefined ? clip(p.currentGold, 120) : "(none)"}`);
+        lines.push(`    + new:    ${clip(p.proposedGold, 120)}`);
+        lines.push(`    source:   ${p.sourceRef}`);
+    }
+    lines.push("");
+    lines.push("re-run with --apply to write these as a NEW dataset version (never in-place).");
+    return `${lines.join("\n")}\n`;
+}

package/dist/regression-pin.d.ts

@@ -0,0 +1,160 @@
+import { type DatasetRegistry } from "@crewhaus/dataset-registry";
+import type { Sample } from "@crewhaus/eval-dataset";
+/** The per-spec regression suite's registry name. */
+export declare function regressionSuiteName(specName: string): string;
+export declare function isRegistrySafeName(name: string): boolean;
+export type PinRegressionsResult = {
+    readonly suiteName: string;
+    /** Newly pinned samples (0 → nothing was written). */
+    readonly pinned: number;
+    /** The new registry version; present only when `pinned > 0`. */
+    readonly version?: string;
+};
+export type PinRecoveredSamplesOptions = {
+    readonly registry: DatasetRegistry;
+    readonly specName: string;
+    /** The recovered (fail→pass) samples to pin. */
+    readonly samples: ReadonlyArray<Sample>;
+    /** Name of the dataset the samples came from (provenance). */
+    readonly sourceDataset: string;
+    /** The run that produced the pin (the optimize runId on the post-accept
+     *  path; the eval runId on the failure-arbiter path). */
+    readonly optimizeRunId: string;
+    /** Provenance tag naming WHAT produced the pin (e.g. "failure-arbiter").
+     *  Recorded as `metadata.regression_pin.source` when present; absent on
+     *  the optimize post-accept path (byte-identical to the pre-item-7 pin). */
+    readonly source?: string;
+    /** Warning sink for the registry-unsafe-name no-op; defaults to stderr. */
+    readonly warn?: (line: string) => void;
+    /** Clock override for deterministic tests. */
+    readonly now?: () => Date;
+};
+/**
+ * Append recovered samples to the per-spec regression suite as a new
+ * auto-bumped version: union of the previous latest version's samples and
+ * the new ones, deduped by sample id (existing pins win, so re-pinning the
+ * same recovery is idempotent and keeps its original provenance). All
+ * samples live in the `train` split — the suite is a single-split dataset.
+ * Provenance (optimize runId, pin date, source dataset) is recorded in each
+ * newly pinned sample's `metadata.regression_pin` (SampleSchema carries an
+ * open `metadata` record). No new samples → no-op: no version is written.
+ */
+export declare function pinRecoveredSamples(opts: PinRecoveredSamplesOptions): Promise<PinRegressionsResult>;
+export type PinRecoveriesAfterOptimizeOptions = {
+    readonly registry: DatasetRegistry;
+    readonly specName: string;
+    /** `!--no-pin-regressions` — false → skip entirely (returns undefined). */
+    readonly pin: boolean;
+    /** Baseline (candidate-0) eval-run dir; undefined → nothing to diff. */
+    readonly baselineRunDir?: string;
+    /** Winning candidate's eval-run dir; undefined → nothing to diff. */
+    readonly candidateRunDir?: string;
+    /** The dev-set samples by id — recovered sampleIds are looked up here. */
+    readonly samplesById: ReadonlyMap<string, Sample>;
+    readonly sourceDataset: string;
+    readonly optimizeRunId: string;
+    readonly now?: () => Date;
+};
+/**
+ * The optimize success path: diff the baseline eval run against the winning
+ * candidate's, extract `recoveries` (fail→pass sampleIds), look those up in
+ * the dataset that was used, and pin them via {@link pinRecoveredSamples}.
+ * Returns undefined when pinning is disabled or either run dir is missing
+ * (e.g. a fitness fn that doesn't report `runDir`).
+ */
+export declare function pinRecoveriesAfterOptimize(opts: PinRecoveriesAfterOptimizeOptions): Promise<PinRegressionsResult | undefined>;
+export type RegressionUnionResult = {
+    /** Primary samples first, then suite additions (dedupe: primary wins). */
+    readonly samples: Sample[];
+    /** `<primaryName>+regressions@vX` when the union ADDED samples; the
+     *  untouched primary name when it added none (keyset unchanged → the
+     *  run-index/baseline lineage must stay comparable, see below). */
+    readonly datasetName: string;
+    /** Primary hash with the suite's content hash folded in when the union
+     *  added samples; the untouched primary hash otherwise. */
+    readonly datasetHash: string;
+    /** Suite samples actually added (collisions with the primary excluded). */
+    readonly added: number;
+    readonly suiteName: string;
+    readonly suiteVersion: string;
+};
+export type ApplyRegressionUnionOptions = {
+    readonly registry: DatasetRegistry;
+    readonly specName: string;
+    /** `!--no-regressions` — false → no union (returns undefined). */
+    readonly includeRegressions: boolean;
+    /**
+     * Registry name of the primary dataset when it came from a `registry:`
+     * ref. Evaling the regression suite itself must not union it into
+     * itself (and must not suffix its own name), so that case is skipped.
+     */
+    readonly primaryRegistryName?: string;
+    /** Lazy primary samples — only materialized once a suite is found, so
+     *  the streaming file-dataset path stays streaming when there is none. */
+    readonly loadPrimarySamples: () => Promise<ReadonlyArray<Sample>>;
+    readonly datasetName: string;
+    readonly datasetHash: string;
+    /** Warning sink for the registry-unsafe-name no-op; defaults to stderr. */
+    readonly warn?: (line: string) => void;
+};
+/**
+ * Union the per-spec regression suite into an eval's dataset (dedupe by
+ * sample id; the primary dataset wins on collision). Returns undefined when
+ * disabled, when no suite exists, or when the primary IS the suite (a
+ * `registry:` ref to it, or a file whose basename matches it — an exported
+ * copy must not union the suite into itself).
+ *
+ * Item-3 interaction, by design: a union that ADDS samples changes the
+ * run's sample keyset, so the returned `datasetName` is suffixed
+ * `+regressions@vX` and the returned `datasetHash` folds the suite's
+ * content hash into the primary's. Run-index entries and (spec, dataset)
+ * baselines then key on the honest union lineage — the first ADDING union
+ * starts a new baseline lineage instead of tripping diffReports'
+ * keyset-mismatch guard against the pre-union baseline. A union that adds
+ * NOTHING (every suite sample already in the primary) keeps the primary
+ * identity untouched: the keyset didn't change, so rewriting the key would
+ * orphan the existing baseline and silently disarm the gate.
+ */
+export declare function applyRegressionUnion(opts: ApplyRegressionUnionOptions): Promise<RegressionUnionResult | undefined>;
+export type GuardedUnionOutcome = {
+    /** Dataset identity to record: the union's when one was applied, the
+     *  untouched primary's otherwise. */
+    readonly datasetName: string;
+    readonly datasetHash: string;
+    /** Samples to run. Always safe to iterate: when the union attempt threw
+     *  AFTER consuming the primary stream, this is the materialized primary
+     *  array — never an exhausted iterable. */
+    readonly samples: AsyncIterable<Sample>;
+    /** Present when a union was applied (its `added` may be 0). */
+    readonly union?: RegressionUnionResult;
+};
+/**
+ * `applyRegressionUnion` with the failure semantics `crewhaus eval` needs:
+ * best-effort (a broken suite record warns and falls back to the primary
+ * dataset) AND stream-loss-proof. The primary samples are captured as they
+ * are materialized for the union attempt, so a throw AFTER the one-shot
+ * primary stream was consumed (e.g. a suite record that passes the shape
+ * check but breaks the hash fold) falls back to the captured array instead
+ * of handing the runner an exhausted iterable — which would silently run a
+ * 0-sample eval.
+ */
+export declare function applyRegressionUnionGuarded(opts: {
+    readonly registry: DatasetRegistry;
+    readonly specName: string;
+    readonly includeRegressions: boolean;
+    readonly primaryRegistryName?: string;
+    readonly primary: {
+        readonly name: string;
+        readonly samples: AsyncIterable<Sample>;
+    };
+    readonly datasetHash: string;
+    /** Warning sink; defaults to stderr. */
+    readonly warn?: (line: string) => void;
+}): Promise<GuardedUnionOutcome>;
+/**
+ * One stable sha256 folding the regression suite's content hash into the
+ * primary dataset's, with domain separators (mirrors `overallDatasetHash`'s
+ * style). Keeps RunIndexEntry.datasetHash honest for unioned runs: it
+ * changes when EITHER the primary bytes or the suite content change.
+ */
+export declare function foldDatasetHash(primaryHash: string, suiteHash: string): string;