crewhaus 0.1.8 → 0.2.0

package/dist/retire.d.ts

@@ -0,0 +1,118 @@
+/** Thrown for operational failures (missing harness, active pin without
+ *  --force, a failed step). The CLI routes the message through `die()`. */
+export declare class RetireError extends Error {
+    readonly name = "RetireError";
+}
+/** The retirement log written into the archive. */
+export declare const RETIREMENT_LOG_FILENAME = "retirement.json";
+export type ActivePin = {
+    readonly env: string;
+    readonly version: string;
+};
+/**
+ * Whether the harness's spec has an active deployment pin. `pins` is the
+ * registry manifest's env→version map (empty when unregistered). An active
+ * pin is any env pointing at a registered version. Retirement refuses this
+ * without `--force`.
+ */
+export declare function activePins(pins: Readonly<Record<string, string>>): ActivePin[];
+export type StepOutcome = {
+    readonly step: string;
+    readonly ok: boolean;
+    readonly detail: string;
+};
+/**
+ * The injectable heavy steps. Each returns a `StepOutcome` recorded in the
+ * retirement log. Production wires these to `createStateBackup`, the
+ * compliance collector, `audit verify`, the registry, and knowledge push;
+ * tests inject stubs that record the call order.
+ */
+export type RetirementSteps = {
+    /** Export durable state (`.crewhaus`) into the archive; return the tarball path. */
+    backupState(archiveDir: string): Promise<StepOutcome & {
+        readonly tarball?: string;
+    }>;
+    /** Write the final compliance-evidence bundle into the archive. */
+    complianceEvidence(archiveDir: string): Promise<StepOutcome>;
+    /** Run `audit verify` and record the verdict. */
+    auditVerify(): Promise<StepOutcome>;
+    /** Push the harness's knowledge to the shared store (#63). Skipped when not
+     *  requested; returns a "skipped" outcome then. */
+    pushKnowledge(archiveDir: string): Promise<StepOutcome>;
+    /** Tombstone the registry entry (delete versions → clears pins). */
+    tombstoneRegistry(): Promise<StepOutcome>;
+};
+export type RetirementPlan = {
+    readonly specName: string;
+    readonly harnessDir: string;
+    readonly archiveDir: string;
+    readonly activePins: ReadonlyArray<ActivePin>;
+    readonly force: boolean;
+    readonly pushKnowledge: boolean;
+    /** The ordered step names the run will execute. */
+    readonly steps: ReadonlyArray<string>;
+};
+export type BuildPlanOptions = {
+    readonly specName: string;
+    readonly harnessDir: string;
+    readonly archiveDir: string;
+    readonly pins: Readonly<Record<string, string>>;
+    readonly force: boolean;
+    readonly pushKnowledge: boolean;
+};
+/**
+ * Build the retirement plan (pure). Throws {@link RetireError} when the
+ * harness has an active pin and `--force` was not given — the plan itself is
+ * the refusal gate, so `--dry-run` surfaces the refusal without side effects.
+ */
+export declare function buildRetirementPlan(opts: BuildPlanOptions): RetirementPlan;
+/** Render the plan as the CLI's `--dry-run` lines. */
+export declare function formatPlan(plan: RetirementPlan): ReadonlyArray<string>;
+export type RetirementLog = {
+    readonly specName: string;
+    readonly harnessDir: string;
+    readonly retiredAt: string;
+    readonly force: boolean;
+    readonly activePinsAtRetirement: ReadonlyArray<ActivePin>;
+    readonly outcomes: ReadonlyArray<StepOutcome>;
+    readonly archived: boolean;
+};
+export type RunRetirementOptions = {
+    readonly plan: RetirementPlan;
+    readonly steps: RetirementSteps;
+    readonly dryRun: boolean;
+    readonly now?: () => Date;
+    /** Test seam: whether to actually move/remove the state dir (default true). */
+    readonly performArchive?: boolean;
+    /** F4 — proceed with the destructive move EVEN IF `auditVerify` reports
+     *  tamper or `complianceEvidence` failed. Distinct from `--force`
+     *  (`plan.force`, which only overrides the active-pin refusal). Default
+     *  false: a provably-tampered audit chain ABORTS the retire, state intact. */
+    readonly forceUnverified?: boolean;
+};
+export type RunRetirementResult = {
+    readonly log: RetirementLog;
+    /** Where the retirement log was written (unset on dry run). */
+    readonly logPath?: string;
+    /** True when the live .crewhaus was removed. */
+    readonly removedState: boolean;
+};
+/**
+ * Execute the plan. Each heavy step runs in order and its outcome is recorded.
+ * A step that returns `ok: false` ABORTS the retirement BEFORE the destructive
+ * archive/remove (a failed backup, tombstone, and — per F4 — a failed
+ * compliance-evidence bundle or a tamper-reporting `auditVerify` all abort;
+ * the audit/compliance gate is overridable only with `forceUnverified`). The
+ * retirement log — every step + outcome — is written+fsynced INTO the archive
+ * BEFORE the destructive move (and rewritten after) so a crash mid-remove
+ * still leaves the evidence and the decommission is self-evidenced. Dry runs
+ * execute nothing.
+ */
+export declare function runRetirement(opts: RunRetirementOptions): Promise<RunRetirementResult>;
+/** Read a retirement log back (for verification / display). */
+export declare function readRetirementLog(archiveDir: string): RetirementLog | undefined;
+/** Render a completed retirement as summary lines. */
+export declare function formatRetirementResult(result: RunRetirementResult): ReadonlyArray<string>;
+/** Ensure the archive dir's parent exists + the dir is empty/new; returns the
+ *  resolved dir. */
+export declare function prepareArchiveDir(archiveDir: string): string;

package/dist/retire.js

@@ -0,0 +1,291 @@
+/**
+ * Item 64 — `crewhaus retire <spec>`: the lifecycle's missing last phase. A
+ * clean, evidenced decommission of a harness:
+ *
+ *   1. refuse if the spec still has an ACTIVE deployment pin (an env points at
+ *      a live version) — unless `--force`; retiring a deployed bot silently
+ *      would be the worst failure mode;
+ *   2. export the harness's durable state to the archive (reuse `crewhaus
+ *      state backup` — the merged tarball path — so sessions/feedback/memories/
+ *      audit travel out byte-identical);
+ *   3. record a FINAL compliance-evidence bundle + an `audit verify` result,
+ *      so the shutdown itself is provable;
+ *   4. optionally push the harness's knowledge to the shared store (#63) so a
+ *      retired bot's lessons outlive it;
+ *   5. tombstone the registry entry — delete the spec's registered versions,
+ *      which clears every env pin pointing at them (the "unpin/rollback"
+ *      step);
+ *   6. archive everything + remove the live `.crewhaus` state, with a
+ *      retirement log (`retirement.json`) written INTO the archive recording
+ *      every step + its outcome — so the retirement is itself evidenced.
+ *
+ * `--dry-run` prints the plan and touches nothing.
+ *
+ * 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).
+ * Side-effect-free on import, mirroring `state-backup.ts`. The heavy steps —
+ * state backup, compliance-evidence, audit-verify, registry tombstone,
+ * knowledge push — are INJECTED as a `RetirementSteps` seam, so the
+ * orchestration (order, refusal, dry-run, the archived log) is unit-tested
+ * without running any of them; the CLI wires the real steps.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** Thrown for operational failures (missing harness, active pin without
+ *  --force, a failed step). The CLI routes the message through `die()`. */
+export class RetireError extends Error {
+    name = "RetireError";
+}
+/** The retirement log written into the archive. */
+export const RETIREMENT_LOG_FILENAME = "retirement.json";
+/**
+ * Whether the harness's spec has an active deployment pin. `pins` is the
+ * registry manifest's env→version map (empty when unregistered). An active
+ * pin is any env pointing at a registered version. Retirement refuses this
+ * without `--force`.
+ */
+export function activePins(pins) {
+    return Object.entries(pins)
+        .map(([env, version]) => ({ env, version }))
+        .sort((a, b) => a.env.localeCompare(b.env));
+}
+/**
+ * Build the retirement plan (pure). Throws {@link RetireError} when the
+ * harness has an active pin and `--force` was not given — the plan itself is
+ * the refusal gate, so `--dry-run` surfaces the refusal without side effects.
+ */
+export function buildRetirementPlan(opts) {
+    const pins = activePins(opts.pins);
+    if (pins.length > 0 && !opts.force) {
+        throw new RetireError(`refusing to retire "${opts.specName}" — it has ${pins.length} active deployment pin(s): ${pins
+            .map((p) => `${p.env}→${p.version}`)
+            .join(", ")}. Roll back / unpin first, or pass --force to retire anyway (the pins will be tombstoned).`);
+    }
+    const steps = [
+        "backupState",
+        "complianceEvidence",
+        "auditVerify",
+        ...(opts.pushKnowledge ? ["pushKnowledge"] : []),
+        "tombstoneRegistry",
+        "archive",
+    ];
+    return {
+        specName: opts.specName,
+        harnessDir: resolve(opts.harnessDir),
+        archiveDir: resolve(opts.archiveDir),
+        activePins: pins,
+        force: opts.force,
+        pushKnowledge: opts.pushKnowledge,
+        steps,
+    };
+}
+/** Render the plan as the CLI's `--dry-run` lines. */
+export function formatPlan(plan) {
+    const lines = [
+        `retire ${plan.specName} — plan (dry run):`,
+        `  harness:  ${plan.harnessDir}`,
+        `  archive:  ${plan.archiveDir}`,
+    ];
+    if (plan.activePins.length > 0) {
+        lines.push(`  ⚠ active pins (will be tombstoned, --force): ${plan.activePins
+            .map((p) => `${p.env}→${p.version}`)
+            .join(", ")}`);
+    }
+    lines.push("  steps:");
+    for (const s of plan.steps)
+        lines.push(`    ${describeStep(s, plan)}`);
+    lines.push("  nothing was executed (dry run)");
+    return lines;
+}
+function describeStep(step, plan) {
+    switch (step) {
+        case "backupState":
+            return "1. export durable state (.crewhaus → archive tarball)";
+        case "complianceEvidence":
+            return "2. write a final compliance-evidence bundle";
+        case "auditVerify":
+            return "3. verify the audit chain (tamper check)";
+        case "pushKnowledge":
+            return "4. push knowledge to the shared store (#63)";
+        case "tombstoneRegistry":
+            return `${plan.pushKnowledge ? "5" : "4"}. tombstone the registry entry (delete versions → clear pins)`;
+        case "archive":
+            return `${plan.pushKnowledge ? "6" : "5"}. archive + remove the live .crewhaus state`;
+        default:
+            return step;
+    }
+}
+/**
+ * Execute the plan. Each heavy step runs in order and its outcome is recorded.
+ * A step that returns `ok: false` ABORTS the retirement BEFORE the destructive
+ * archive/remove (a failed backup, tombstone, and — per F4 — a failed
+ * compliance-evidence bundle or a tamper-reporting `auditVerify` all abort;
+ * the audit/compliance gate is overridable only with `forceUnverified`). The
+ * retirement log — every step + outcome — is written+fsynced INTO the archive
+ * BEFORE the destructive move (and rewritten after) so a crash mid-remove
+ * still leaves the evidence and the decommission is self-evidenced. Dry runs
+ * execute nothing.
+ */
+export async function runRetirement(opts) {
+    const { plan, steps } = opts;
+    const now = opts.now ?? (() => new Date());
+    const retiredAt = now().toISOString();
+    if (opts.dryRun) {
+        return {
+            log: {
+                specName: plan.specName,
+                harnessDir: plan.harnessDir,
+                retiredAt,
+                force: plan.force,
+                activePinsAtRetirement: plan.activePins,
+                outcomes: [],
+                archived: false,
+            },
+            removedState: false,
+        };
+    }
+    mkdirSync(plan.archiveDir, { recursive: true });
+    const outcomes = [];
+    const record = (o) => {
+        outcomes.push(o);
+        return o;
+    };
+    const forceUnverified = opts.forceUnverified ?? false;
+    // 1–4/5: the non-destructive steps. A failure aborts before archiving.
+    const backup = record(await steps.backupState(plan.archiveDir));
+    if (!backup.ok)
+        throw new RetireError(`state backup failed — aborting before any destructive step: ${backup.detail}`);
+    // F4 — the compliance-evidence bundle and the audit-verify verdict GATE the
+    // destructive step: a provably-tampered audit chain (or a failed evidence
+    // bundle) must ABORT the retire so the `.crewhaus` state is left intact for
+    // investigation, NOT moved+removed. `--force-unverified` is the explicit
+    // override (distinct from `--force`, which only overrides the active-pin
+    // refusal). The log is written into the archive before we bail, so the
+    // refusal is itself evidenced.
+    const compliance = record(await steps.complianceEvidence(plan.archiveDir));
+    const audit = record(await steps.auditVerify());
+    if (plan.pushKnowledge)
+        record(await steps.pushKnowledge(plan.archiveDir));
+    const tamperReasons = [];
+    if (!audit.ok)
+        tamperReasons.push(`audit verify reported tamper: ${audit.detail}`);
+    if (!compliance.ok)
+        tamperReasons.push(`compliance evidence failed: ${compliance.detail}`);
+    if (tamperReasons.length > 0 && !forceUnverified) {
+        // Persist the aborted-run log into the archive so the refusal is evidenced,
+        // then abort BEFORE tombstone/archive — the live state stays put.
+        const abortedLog = {
+            specName: plan.specName,
+            harnessDir: plan.harnessDir,
+            retiredAt,
+            force: plan.force,
+            activePinsAtRetirement: plan.activePins,
+            outcomes,
+            archived: false,
+        };
+        writeLogDurably(join(plan.archiveDir, RETIREMENT_LOG_FILENAME), abortedLog);
+        throw new RetireError(`aborting retire before any destructive step — ${tamperReasons.join("; ")}. The live .crewhaus state was left intact. Pass --force-unverified to retire anyway.`);
+    }
+    const tombstone = record(await steps.tombstoneRegistry());
+    if (!tombstone.ok) {
+        throw new RetireError(`registry tombstone failed — aborting before archiving: ${tombstone.detail}`);
+    }
+    // F4 — write + fsync the retirement log into the archive BEFORE the
+    // destructive move, so a crash mid-remove still leaves the evidence beside
+    // the backup that already exists pre-destruction. The `archive` outcome is
+    // appended after the move and the log is rewritten to capture it.
+    const logPath = join(plan.archiveDir, RETIREMENT_LOG_FILENAME);
+    const preMoveLog = {
+        specName: plan.specName,
+        harnessDir: plan.harnessDir,
+        retiredAt,
+        force: plan.force,
+        activePinsAtRetirement: plan.activePins,
+        outcomes,
+        archived: false,
+    };
+    writeLogDurably(logPath, preMoveLog);
+    // Destructive archive/remove: move the live .crewhaus into the archive, then
+    // it is gone from the harness. Guarded by performArchive for tests.
+    const performArchive = opts.performArchive ?? true;
+    let removedState = false;
+    const stateDir = join(plan.harnessDir, ".crewhaus");
+    if (performArchive && existsSync(stateDir)) {
+        const movedTo = join(plan.archiveDir, "crewhaus-state");
+        // The state backup already captured a byte-identical tarball; MOVE the
+        // live dir into the archive too (belt + braces) then it's removed from the
+        // harness. A pre-existing target is replaced to keep the op idempotent.
+        if (existsSync(movedTo))
+            rmSync(movedTo, { recursive: true, force: true });
+        renameSync(stateDir, movedTo);
+        removedState = true;
+        record({ step: "archive", ok: true, detail: `moved .crewhaus → ${movedTo}` });
+    }
+    else {
+        record({
+            step: "archive",
+            ok: true,
+            detail: existsSync(stateDir)
+                ? "archive skipped (test seam)"
+                : "no .crewhaus state to archive",
+        });
+    }
+    const log = {
+        specName: plan.specName,
+        harnessDir: plan.harnessDir,
+        retiredAt,
+        force: plan.force,
+        activePinsAtRetirement: plan.activePins,
+        outcomes,
+        archived: removedState,
+    };
+    // Rewrite the log now that the `archive` outcome is known (the pre-move write
+    // above is the crash-safety copy; this is the final, complete record).
+    writeLogDurably(logPath, log);
+    return { log, logPath, removedState };
+}
+/** Write a retirement log and fsync it to disk before returning, so a crash
+ *  immediately after cannot lose the evidence. */
+function writeLogDurably(logPath, log) {
+    const body = `${JSON.stringify(log, null, 2)}\n`;
+    const fd = openSync(logPath, "w", 0o600);
+    try {
+        writeSync(fd, body);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Read a retirement log back (for verification / display). */
+export function readRetirementLog(archiveDir) {
+    const p = join(archiveDir, RETIREMENT_LOG_FILENAME);
+    if (!existsSync(p))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Render a completed retirement as summary lines. */
+export function formatRetirementResult(result) {
+    const lines = [`retired ${result.log.specName} @ ${result.log.retiredAt}`];
+    for (const o of result.log.outcomes) {
+        lines.push(`  ${o.ok ? "✓" : "✗"} ${o.step}: ${o.detail}`);
+    }
+    if (result.logPath !== undefined)
+        lines.push(`  retirement log: ${result.logPath}`);
+    lines.push(result.removedState
+        ? "  live .crewhaus state removed (archived)"
+        : "  live state left in place");
+    return lines;
+}
+/** Ensure the archive dir's parent exists + the dir is empty/new; returns the
+ *  resolved dir. */
+export function prepareArchiveDir(archiveDir) {
+    const resolved = resolve(archiveDir);
+    mkdirSync(dirname(resolved), { recursive: true });
+    return resolved;
+}

package/dist/right-size.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Item 25 — `crewhaus model right-size <spec>`: an enumerate → compile → eval
+ * loop that searches for a CHEAPER model in ONE slot that HOLDS quality.
+ *
+ * This is a DEDICATED loop, deliberately NOT the prompt mutator: the
+ * `MutationProvider` seam optimize uses is prompt-string-only, whereas
+ * right-sizing swaps model IDENTIFIERS (agent.model, cli sub-agents[*].model,
+ * compaction.model, the judge model). Each candidate is the spec with exactly
+ * ONE model slot swapped to a cheaper same-provider pricing-table sibling; the
+ * candidate is evaled, its per-candidate USD computed from the eval's token
+ * aggregates (eval artifacts carry no `cost_accrual`, so cost is projected via
+ * `resolvePricing`), and the set ranked by score-retained-per-dollar-saved.
+ * A candidate is RECOMMENDED only when pass-rate holds and cost drops >= N%.
+ *
+ * Proposal-only: model paths stay outside `OPTIMIZABLE_PATHS`, so nothing is
+ * auto-applied — a documented `--write` does the direct comment-preserving CST
+ * edit (reusing `writeModelField`). This module is the pure/injectable core
+ * (candidate enumeration + cost projection + ranking); the CLI wires the real
+ * compile+eval.
+ */
+import { type PricingTable, type RankedRightSize } from "@crewhaus/cost-tracker";
+/** A swappable model slot in the spec, addressed by its patch path. */
+export type ModelSlot = {
+    /** Human label (agent.model, compaction.model, sub-agent <name>.model, judge). */
+    readonly label: string;
+    /** The spec model string currently in the slot. */
+    readonly currentModel: string;
+    /** The patch path (for the eventual CST edit); undefined for the judge (a
+     *  CLI flag, not a spec field). */
+    readonly path?: ReadonlyArray<string>;
+};
+/** One candidate: the spec with `slot` swapped to `candidateModel`. */
+export type SlotCandidate = {
+    readonly slot: ModelSlot;
+    readonly candidateModel: string;
+};
+export type EnumerateSlotCandidatesOptions = {
+    readonly pricing?: PricingTable;
+    /** Cap the candidates per slot (cheapest-first). Default 3. */
+    readonly perSlotLimit?: number;
+};
+/**
+ * Enumerate downshift candidates across every slot: each slot yields its
+ * cheaper SAME-PROVIDER siblings (cheapest-first, current excluded, capped).
+ * Cross-provider is out of scope here — a right-size stays on the provider so
+ * credentials/cache continuity hold; cross-provider replacement is model-scan's
+ * job. Slots whose model isn't table-backed contribute nothing.
+ */
+export declare function enumerateSlotCandidates(slots: ReadonlyArray<ModelSlot>, opts?: EnumerateSlotCandidatesOptions): SlotCandidate[];
+/**
+ * Project a candidate run's USD from its token aggregates, for its model.
+ * Returns `undefined` on a pricing miss (an unpriced model can't be compared
+ * on cost, so it's never recommended). USD, not micros, for legible reports.
+ */
+export declare function projectCostUsd(model: string, tokens: {
+    readonly input: number;
+    readonly output: number;
+}, pricing?: PricingTable): number | undefined;
+/** The eval outcome of one slot candidate (from the injected runner). */
+export type SlotEvalOutcome = {
+    readonly candidate: SlotCandidate;
+    readonly passRate: number;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+    readonly error?: string;
+};
+/** The baseline (unchanged spec) eval outcome. */
+export type BaselineEvalOutcome = {
+    readonly passRate: number;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /** The primary agent model (for cost projection of the baseline). */
+    readonly model: string;
+};
+export type RightSizeReport = {
+    readonly baseline: {
+        readonly passRate: number;
+        readonly costUsd: number;
+    };
+    readonly ranked: ReadonlyArray<RankedRightSize>;
+    readonly best?: RankedRightSize & {
+        readonly slotPath?: ReadonlyArray<string>;
+    };
+};
+/**
+ * Fold baseline + per-candidate eval outcomes into a ranked right-size report.
+ * Baseline cost is projected from ITS tokens on ITS model; each candidate's
+ * cost from its tokens on its swapped model. Ranking + the recommend gate
+ * (holds pass rate AND cost drop >= minCostDropRatio) come from cost-tracker's
+ * `rankRightSizeProposals`.
+ */
+export declare function buildRightSizeReport(baseline: BaselineEvalOutcome, outcomes: ReadonlyArray<SlotEvalOutcome>, opts: {
+    readonly minCostDropRatio: number;
+    readonly passRateTolerance?: number;
+    readonly pricing?: PricingTable;
+}): RightSizeReport;

package/dist/right-size.js

@@ -0,0 +1,123 @@
+/**
+ * Item 25 — `crewhaus model right-size <spec>`: an enumerate → compile → eval
+ * loop that searches for a CHEAPER model in ONE slot that HOLDS quality.
+ *
+ * This is a DEDICATED loop, deliberately NOT the prompt mutator: the
+ * `MutationProvider` seam optimize uses is prompt-string-only, whereas
+ * right-sizing swaps model IDENTIFIERS (agent.model, cli sub-agents[*].model,
+ * compaction.model, the judge model). Each candidate is the spec with exactly
+ * ONE model slot swapped to a cheaper same-provider pricing-table sibling; the
+ * candidate is evaled, its per-candidate USD computed from the eval's token
+ * aggregates (eval artifacts carry no `cost_accrual`, so cost is projected via
+ * `resolvePricing`), and the set ranked by score-retained-per-dollar-saved.
+ * A candidate is RECOMMENDED only when pass-rate holds and cost drops >= N%.
+ *
+ * Proposal-only: model paths stay outside `OPTIMIZABLE_PATHS`, so nothing is
+ * auto-applied — a documented `--write` does the direct comment-preserving CST
+ * edit (reusing `writeModelField`). This module is the pure/injectable core
+ * (candidate enumeration + cost projection + ranking); the CLI wires the real
+ * compile+eval.
+ */
+import { DEFAULT_PRICING, computeCostMicros, enumerateCandidates, providerOfSpecString, rankRightSizeProposals, resolvePricing, } from "@crewhaus/cost-tracker";
+/**
+ * Enumerate downshift candidates across every slot: each slot yields its
+ * cheaper SAME-PROVIDER siblings (cheapest-first, current excluded, capped).
+ * Cross-provider is out of scope here — a right-size stays on the provider so
+ * credentials/cache continuity hold; cross-provider replacement is model-scan's
+ * job. Slots whose model isn't table-backed contribute nothing.
+ */
+export function enumerateSlotCandidates(slots, opts = {}) {
+    const perSlotLimit = opts.perSlotLimit ?? 3;
+    const out = [];
+    const seen = new Set();
+    for (const slot of slots) {
+        const parsed = providerOfSpecString(slot.currentModel);
+        if (parsed === undefined)
+            continue;
+        const siblings = enumerateCandidates(parsed, {
+            ...(opts.pricing !== undefined ? { pricing: opts.pricing } : {}),
+            sameProviderOnly: true,
+            excludeCurrent: true,
+        });
+        // Only DOWNSHIFTS: cheaper than the current model.
+        const currentPrice = blendedOf(parsed, opts.pricing);
+        let taken = 0;
+        for (const sib of siblings) {
+            if (currentPrice !== undefined && sib.blendedPer1M >= currentPrice)
+                continue;
+            const key = `${slot.label}→${sib.modelString}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ slot, candidateModel: sib.modelString });
+            if (++taken >= perSlotLimit)
+                break;
+        }
+    }
+    return out;
+}
+function blendedOf(parsed, pricing) {
+    const row = resolvePricing(pricing ?? DEFAULT_PRICING, parsed.provider, parsed.modelId);
+    if (row === undefined)
+        return undefined;
+    return (row.inputPer1M * 3 + row.outputPer1M) / 4;
+}
+/**
+ * Project a candidate run's USD from its token aggregates, for its model.
+ * Returns `undefined` on a pricing miss (an unpriced model can't be compared
+ * on cost, so it's never recommended). USD, not micros, for legible reports.
+ */
+export function projectCostUsd(model, tokens, pricing) {
+    const parsed = providerOfSpecString(model);
+    if (parsed === undefined)
+        return undefined;
+    const row = resolvePricing(pricing ?? DEFAULT_PRICING, parsed.provider, parsed.modelId);
+    if (row === undefined)
+        return undefined;
+    return computeCostMicros(row, tokens.input, tokens.output, 0) / 1_000_000;
+}
+/**
+ * Fold baseline + per-candidate eval outcomes into a ranked right-size report.
+ * Baseline cost is projected from ITS tokens on ITS model; each candidate's
+ * cost from its tokens on its swapped model. Ranking + the recommend gate
+ * (holds pass rate AND cost drop >= minCostDropRatio) come from cost-tracker's
+ * `rankRightSizeProposals`.
+ */
+export function buildRightSizeReport(baseline, outcomes, opts) {
+    const baselineCostUsd = projectCostUsd(baseline.model, baseline.tokens, opts.pricing) ?? 0;
+    const proposals = [];
+    const pathByKey = new Map();
+    for (const o of outcomes) {
+        if (o.error !== undefined)
+            continue; // a crashed cell can't be compared
+        const costUsd = projectCostUsd(o.candidate.candidateModel, o.tokens, opts.pricing);
+        if (costUsd === undefined)
+            continue; // pricing miss → not comparable
+        const key = `${o.candidate.slot.label}→${o.candidate.candidateModel}`;
+        pathByKey.set(key, o.candidate.slot.path);
+        proposals.push({
+            modelString: o.candidate.candidateModel,
+            slot: o.candidate.slot.label,
+            passRate: o.passRate,
+            costUsd,
+        });
+    }
+    const ranked = rankRightSizeProposals({ passRate: baseline.passRate, costUsd: baselineCostUsd }, proposals, {
+        minCostDropRatio: opts.minCostDropRatio,
+        ...(opts.passRateTolerance !== undefined
+            ? { passRateTolerance: opts.passRateTolerance }
+            : {}),
+    });
+    const topRecommended = ranked.find((r) => r.recommended);
+    const best = topRecommended !== undefined
+        ? {
+            ...topRecommended,
+            slotPath: pathByKey.get(`${topRecommended.slot}→${topRecommended.modelString}`),
+        }
+        : undefined;
+    return {
+        baseline: { passRate: baseline.passRate, costUsd: baselineCostUsd },
+        ranked,
+        ...(best !== undefined ? { best } : {}),
+    };
+}