@mutagent/helix 0.1.0-alpha.14

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/codegen-evals.ts

@@ -0,0 +1,173 @@
+/**
+ * scripts/codegen-evals.ts — Path B (F14): emit CODE-WRITTEN evals in the target's
+ * own language (Type A — PURE string codegen).
+ * ---------------------------------------------------------------------------
+ * Path B of the EVAL-stage engine fork (eval-engine.ts). For a code-FRAMEWORK
+ * target (Mastra/TS, runtime=bun) this emits a SELF-CONTAINED eval-suite source
+ * file the user runs DIRECTLY — no Claude-Code sub-agents anywhere (F14):
+ *
+ *   - deterministic CODE-CHECKS    (the `codeCheck` helper — objective, no LLM)
+ *   - an LLM-JUDGE call VIA SDK     (the `judgeViaSdk` seam — provider SDK, NOT a
+ *                                    CC sub-agent; the user wires their own key)
+ *   - eval-criteria checks → a per-criterion pass/fail + a gate (runVerdict)
+ *   - the scorecard JSON written to a DISCOVERABLE output sink.
+ *
+ * The emitted code reaches back into NOTHING in `.claude/skills/` (it ships INTO
+ * the target's repo). This module is PURE string assembly — same input →
+ * byte-identical source (no clock / random / network), so the generated suite is
+ * itself reproducible. Subject-agnostic: criteria are DATA.
+ *
+ * Austerity note: this is the Path-B analog of the EV-050 in-house/export seam —
+ * it EMITS a provider-calling artifact for the user to run; the DEFAULT
+ * agent-dispatch (Path A) path never imports it.
+ */
+
+/** A criterion to codegen — the minimal Path-B slice (maps from agentspec success_criteria). */
+export interface CodegenCriterion {
+  id: string;
+  statement: string;
+  /** `code-check` → a deterministic check; `llm-judge` → an SDK judge call. */
+  type: "code-check" | "llm-judge";
+  goal: string;
+}
+
+export interface CodegenInput {
+  subject: string;
+  /** the target runtime ("bun" | "node" | "deno" …) — drives the emitted module style. */
+  runtime: string;
+  targetFramework: string;
+  criteria: CodegenCriterion[];
+  /** the discoverable sink the suite writes its scorecard to. */
+  outputSink: string;
+}
+
+/** JSON-encode a value for safe embedding as a source literal. PURE. */
+function lit(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * Emit a portable, self-contained eval-suite SOURCE file (TS) for the target.
+ * Deterministic. THROWS on an empty criteria set or an unknown criterion type
+ * (fail-loud — never silently emit a no-op suite or skip a criterion). PURE.
+ */
+export function codegenEvalSuite(input: CodegenInput): string {
+  if (input.criteria.length === 0) {
+    throw new Error(
+      "codegenEvalSuite: no criteria — there is nothing to write evals for. " +
+        "Materialize criteria from the agentspec.evals.success_criteria first.",
+    );
+  }
+  for (const c of input.criteria) {
+    if (c.type !== "code-check" && c.type !== "llm-judge") {
+      throw new Error(
+        `codegenEvalSuite: unknown criterion type '${String((c as { type: unknown }).type)}' ` +
+          `on criterion '${c.id}'. Expected 'code-check' | 'llm-judge'.`,
+      );
+    }
+  }
+
+  // The criteria are embedded as data; the runner dispatches by `type` at runtime.
+  const criteriaLiteral = lit(
+    input.criteria.map((c) => ({ id: c.id, statement: c.statement, type: c.type, goal: c.goal })),
+  );
+
+  // NOTE: keep this a single template literal so the codegen is PURE + deterministic.
+  // It deliberately contains NO Claude-Code dispatch — the only LLM path is the
+  // user-supplied `judgeViaSdk` SDK seam (Path B portability, F14).
+  return `/**
+ * code-evals.ts — PORTABLE code-written eval suite for ${input.subject}
+ * Target: ${input.targetFramework} (runtime: ${input.runtime})
+ * GENERATED by mutagent-evaluator (Path B — code-written). Runs WITHOUT Claude Code.
+ *
+ * Wire two seams to your target:
+ *   - runAgent(query): call YOUR built ${input.targetFramework} agent → its output.
+ *   - judgeViaSdk(prompt): call YOUR provider SDK (the LLM judge). NOT a Claude-Code
+ *     sub-agent — your own key, your own SDK. Returns {result:"pass"|"fail", critique}.
+ *
+ * Then: \`${input.runtime} run code-evals.ts <dataset.json>\` → writes the scorecard to
+ *   ${input.outputSink}scorecard.json  (the discoverable sink).
+ */
+
+export interface DatasetCase { id: string; query: string; tuple?: Record<string, string>; }
+export interface CriterionVerdict { criterionId: string; result: "pass" | "fail"; critique: string; }
+export interface Scorecard {
+  subject: string;
+  perCriterion: Record<string, { pass: number; fail: number }>;
+  runVerdict: "pass" | "fail";
+  rows: { caseId: string; verdicts: CriterionVerdict[] }[];
+}
+
+/** The agentspec-derived criteria (embedded as DATA — subject-agnostic). */
+const CRITERIA: { id: string; statement: string; type: "code-check" | "llm-judge"; goal: string }[] =
+  ${criteriaLiteral};
+
+// ── seam 1: run YOUR built agent (wire this to your ${input.targetFramework} entrypoint) ──
+export type RunAgent = (query: string) => Promise<{ output: string; trace?: unknown }>;
+
+// ── seam 2: your provider-SDK LLM judge (NOT a Claude-Code sub-agent — portable) ──
+export type JudgeViaSdk = (prompt: string) => Promise<{ result: "pass" | "fail"; critique: string }>;
+
+/** Deterministic CODE check for an objective criterion (no LLM). Extend per criterion id. */
+export function codeCheck(criterionId: string, output: string): CriterionVerdict {
+  // Default code-check: non-empty, well-formed output. Specialize by criterionId as needed.
+  const ok = typeof output === "string" && output.trim().length > 0;
+  return { criterionId, result: ok ? "pass" : "fail", critique: ok ? "output present" : "empty output" };
+}
+
+/** LLM-judge a subjective criterion VIA the user's SDK seam (critique-before-verdict, binary). */
+export async function judgeCriterion(
+  judgeViaSdk: JudgeViaSdk,
+  criterion: { id: string; statement: string },
+  query: string,
+  output: string,
+): Promise<CriterionVerdict> {
+  const prompt =
+    "Critique FIRST, then a BINARY verdict. Criterion: " + criterion.statement +
+    "\\nUser query: " + query + "\\nAgent output: " + output +
+    "\\nRespond {critique, result: 'pass'|'fail'}.";
+  const { result, critique } = await judgeViaSdk(prompt);
+  return { criterionId: criterion.id, result, critique };
+}
+
+/** Run the full suite over a dataset → a gate-bearing scorecard. Portable. */
+export async function runEvalSuite(
+  dataset: DatasetCase[],
+  runAgent: RunAgent,
+  judgeViaSdk: JudgeViaSdk,
+): Promise<Scorecard> {
+  const perCriterion: Record<string, { pass: number; fail: number }> = {};
+  for (const c of CRITERIA) perCriterion[c.id] = { pass: 0, fail: 0 };
+  const rows: { caseId: string; verdicts: CriterionVerdict[] }[] = [];
+  for (const dc of dataset) {
+    const { output } = await runAgent(dc.query);
+    const verdicts: CriterionVerdict[] = [];
+    for (const c of CRITERIA) {
+      const v =
+        c.type === "code-check"
+          ? codeCheck(c.id, output)
+          : await judgeCriterion(judgeViaSdk, c, dc.query, output);
+      perCriterion[c.id][v.result] += 1;
+      verdicts.push(v);
+    }
+    rows.push({ caseId: dc.id, verdicts });
+  }
+  const anyFail = Object.values(perCriterion).some((p) => p.fail > 0);
+  return { subject: ${lit(input.subject)}, perCriterion, runVerdict: anyFail ? "fail" : "pass", rows };
+}
+
+/** CLI: \`${input.runtime} run code-evals.ts <dataset.json>\` → write the scorecard to the sink. */
+export async function main(
+  datasetPath: string,
+  runAgent: RunAgent,
+  judgeViaSdk: JudgeViaSdk,
+  writeFile: (path: string, body: string) => Promise<void>,
+  readFile: (path: string) => Promise<string>,
+): Promise<Scorecard> {
+  const dataset = JSON.parse(await readFile(datasetPath)) as DatasetCase[];
+  const scorecard = await runEvalSuite(dataset, runAgent, judgeViaSdk);
+  await writeFile(${lit(input.outputSink)} + "scorecard.json", JSON.stringify(scorecard, null, 2));
+  return scorecard;
+}
+`;
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/cold-start-project.ts

@@ -0,0 +1,151 @@
+/**
+ * scripts/cold-start-project.ts — EV-5.3 the EvalTrace → ColdTrace projection.
+ * ---------------------------------------------------------------------------
+ * The COLD front-door (`cold-start-sampler.ts`) balances a bootstrap ✓/✗ suite
+ * from MECHANICAL labels alone (no LLM judge yet). Its input is a `ColdTrace`
+ * (id + `MechanicalSignals` + dedup keys). The determiner PREP stage, however,
+ * works over `EvalTrace[]` (the projection of the handed-over UniTF export). This
+ * module is the thin, PURE adapter between the two — and the SINGLE place the
+ * cold sampler is wired into the determiner/discover path.
+ *
+ * ── HONEST-NULL projection (why the mapping looks the way it does) ────────────
+ * The `EvalTrace` contract does NOT carry a generic `ext.signals` /
+ * `ext.classification` block — the UniTF→EvalTrace projection (`unitf-to-
+ * evaltrace.ts`) FLATTENS only the fields it can ground onto the top level
+ * (`errored` · `status` · `incomplete` · `scores`) and the UniTF source `ext`
+ * itself carries just `ext.eval` (the §9.4.2 fidelity marker). So the mechanical
+ * signals are read from what ACTUALLY survives to `EvalTrace`, and every signal
+ * with no grounded source stays UNKNOWN (absent), never a fabricated `false`:
+ *
+ *   MechanicalSignals.hasError       ← EvalTrace.errored            (ERROR family)
+ *   MechanicalSignals.hasApiErrors   ← EvalTrace.status === "error" (ERROR family)
+ *   MechanicalSignals.incomplete     ← EvalTrace.incomplete         (TERMINAL family)
+ *   MechanicalSignals.hasScore/minScore ← numeric EvalTrace.scores  (SCORE family)
+ *   MechanicalSignals.hasChatFeedback/negativeReaction ← UNKNOWN — the FEEDBACK
+ *       family is not carried on EvalTrace today; omitted (never coerced false).
+ *   ColdTrace.scenario   ← UNKNOWN — no classification field on EvalTrace, so a
+ *       trace has no dedup key and is kept (never a false collapse).
+ *   ColdTrace.worthiness ← UNKNOWN — no worthiness field on EvalTrace (dedup is a
+ *       no-op without a scenario key anyway).
+ *
+ * PURE + deterministic: no clock, no random, no network. A given `EvalTrace[]`
+ * always yields the identical selection (reproducible cold suites — C-PIN-adjacent).
+ */
+import {
+  coldStartSample,
+  type ColdStartSuite,
+  type ColdTrace,
+  type MechanicalSignals,
+} from "./cold-start-sampler.ts";
+import type { EvalTrace } from "./contracts/eval-types.ts";
+
+/**
+ * Read the SCORE family off `EvalTrace.scores`. Scores are carried verbatim
+ * (`unknown[]`, Langfuse-style `{ name, value }`). Only FINITE NUMERIC `value`s
+ * count toward the cold SCORE signal; a non-numeric or absent value contributes
+ * nothing. Returns `{}` (both UNKNOWN) when there is no numeric score — honest-
+ * null, never a fabricated `hasScore:false`.
+ */
+function scoreSignals(scores: unknown[] | undefined): Pick<MechanicalSignals, "hasScore" | "minScore"> {
+  if (scores === undefined || scores.length === 0) return {};
+  let min = Number.POSITIVE_INFINITY;
+  let seen = false;
+  for (const s of scores) {
+    if (s === null || typeof s !== "object") continue;
+    const value = (s as { value?: unknown }).value;
+    if (typeof value === "number" && Number.isFinite(value)) {
+      seen = true;
+      if (value < min) min = value;
+    }
+  }
+  return seen ? { hasScore: true, minScore: min } : {};
+}
+
+/**
+ * Project one `EvalTrace` → the cold sampler's `ColdTrace`. Honest-null: only
+ * grounded signals are set; everything else is left absent (UNKNOWN). Explicit
+ * about the ERROR/TERMINAL/SCORE families it can ground and the FEEDBACK family
+ * it cannot (see the module header).
+ */
+export function projectEvalTraceToCold(trace: EvalTrace): ColdTrace {
+  const signals: MechanicalSignals = {};
+  // ERROR family — `errored` is the always-set structured flag (false = a grounded
+  // not-errored). `status === "error"` is the raw carried tri-state; surface it as
+  // the API-error signal when the source supplied it.
+  if (trace.errored !== undefined) signals.hasError = trace.errored;
+  if (trace.status === "error") signals.hasApiErrors = true;
+  // TERMINAL family — the §9.4.2 truncation marker (absent ⇒ UNKNOWN, never false).
+  if (trace.incomplete !== undefined) signals.incomplete = trace.incomplete;
+  // SCORE family — derived from any numeric platform score.
+  Object.assign(signals, scoreSignals(trace.scores));
+  // FEEDBACK family (hasChatFeedback/negativeReaction), scenario, worthiness: NOT
+  // carried on EvalTrace — deliberately omitted so they read UNKNOWN downstream.
+  return { id: trace.id, signals };
+}
+
+/** Project a batch of `EvalTrace` → `ColdTrace[]`, order-preserving + PURE. */
+export function projectColdTraces(traces: EvalTrace[]): ColdTrace[] {
+  return traces.map(projectEvalTraceToCold);
+}
+
+/**
+ * The cold-start selection metadata surfaced into the discover/determiner report
+ * (the determiner-stage `manifest.json`). `lowConfidence` is the load-bearing
+ * flag: a thin-negative cold suite MUST have its first judge pass treated as
+ * LOW-CONFIDENCE and re-balanced once real verdicts exist.
+ */
+export interface ColdStartMeta {
+  /** the sampler's target suite size (default = incoming trace count → pass-through). */
+  targetSize: number;
+  /** how many traces the batch handed to the sampler. */
+  input: number;
+  /** how many traces the cold suite selected (≤ input; = input on pass-through). */
+  selected: number;
+  passCount: number;
+  failCount: number;
+  /** the ✗-pool was too thin — treat the first cold judge pass as LOW-CONFIDENCE. */
+  lowConfidence: boolean;
+  /** the ✗-pool was rarer than its balanced half → every available fail was taken. */
+  oversampledFailPool: boolean;
+  /** BOTH non-empty pools are represented (never a success-only bootstrap suite). */
+  minBothHeld: boolean;
+}
+
+/**
+ * Wire the cold-start sampler over an `EvalTrace[]` batch and map the balanced
+ * suite BACK to the concrete `EvalTrace[]` the determiner PREP consumes. This is
+ * the SAFE call-site helper: it subsamples FIRST, so the untouched
+ * `prepDeterminerTasks` still emits exactly one determiner task per SELECTED
+ * trace. `size` defaults to the incoming count — a pass-through that only
+ * subsamples when an explicit smaller `size` is given (or the batch's own
+ * ✓/✗ imbalance triggers oversample flagging). PURE + deterministic.
+ */
+export function selectColdStartSuite(
+  traces: EvalTrace[],
+  opts: { size?: number; minBoth?: number; prevalenceFloor?: number; scoreThreshold?: number } = {},
+): { selected: EvalTrace[]; meta: ColdStartMeta; suite: ColdStartSuite } {
+  const size = opts.size ?? traces.length;
+  const suite = coldStartSample(projectColdTraces(traces), {
+    size,
+    minBoth: opts.minBoth,
+    prevalenceFloor: opts.prevalenceFloor,
+    scoreThreshold: opts.scoreThreshold,
+  });
+  // Map the selected cold reps back to their source EvalTrace, preserving the
+  // suite's (✓-then-✗) order. `filter` guards the impossible missing-id case.
+  const byId = new Map(traces.map((t) => [t.id, t] as const));
+  const selected = suite.selected
+    .map((c) => byId.get(c.id))
+    .filter((t): t is EvalTrace => t !== undefined);
+  const meta: ColdStartMeta = {
+    targetSize: size,
+    input: traces.length,
+    selected: selected.length,
+    passCount: suite.passCount,
+    failCount: suite.failCount,
+    lowConfidence: suite.lowConfidence,
+    oversampledFailPool: suite.oversampledFailPool,
+    minBothHeld: suite.minBothHeld,
+  };
+  return { selected, meta, suite };
+}

package/mutagent-evaluator/.claude/skills/mutagent-evaluator/scripts/cold-start-sampler.ts

@@ -0,0 +1,267 @@
+/**
+ * scripts/cold-start-sampler.ts — EV-5.3 the balanced COLD-START sampler.
+ * ---------------------------------------------------------------------------
+ * PRE-SUITE, there is NO LLM judge yet: the EV-042 determiner (`determine-
+ * outcome.ts`) needs a criteria suite to run, and the suite doesn't exist yet.
+ * So the ONLY ✓/✗ labels available at cold start are:
+ *   (a) the agent/skill DEFINITION's success ORACLE, and
+ *   (b) deterministic MECHANICAL signals — the four cold-label families
+ *       ERROR · FEEDBACK · SCORE · TERMINAL (a subset of `ext.signals` plus the
+ *       §9.4.2 terminal/`incomplete` marker). No provider, no judge tokens.
+ *
+ * This is DISTINCT from `sample-traces.ts` `balancedSample`, which balances over
+ * the LLM-determiner's `OutcomeVerdict` labels (a WARM, post-judge input). This
+ * module is the COLD front-door: it manufactures a balanced ✓/✗ bootstrap suite
+ * from mechanical labels alone so the first judge pass is trained on BOTH classes.
+ *
+ * The pipeline (in order):
+ *   stratify → SL-5 prevalence floor → worthiness/scenario dedup →
+ *   MIN-BOTH (a guaranteed minimum from BOTH pools — never a success-only suite) →
+ *   oversample the ✗-pool when rare (and flag the suite LOW-CONFIDENCE).
+ *
+ * PURE + deterministic: no `Math.random`, no clock, no network. A given
+ * (traces, opts) always yields the identical suite (reproducible cold suites —
+ * C-PIN-adjacent). Never fabricates a trace: a scarcer class contributes all it
+ * has and no more.
+ */
+
+// ── Mechanical cold labels (NO LLM judge) ───────────────────────────────────
+
+/** The cold outcome — the ONLY two pools a balanced suite is built from. */
+export const ColdOutcome = { Pass: "pass", Fail: "fail" } as const;
+export type ColdOutcomeValue = (typeof ColdOutcome)[keyof typeof ColdOutcome];
+
+/**
+ * The four MECHANICAL cold-label signal families available pre-suite. Mirrors the
+ * subset of UniTF `ext.signals` (`hasError`/`hasApiErrors`/`hasChatFeedback`/
+ * `negativeReaction`/`hasScore`/`minScore`) plus the §9.4.2 terminal marker
+ * (`incomplete`). All optional/additive: an absent field is UNKNOWN, never a
+ * false — the oracle reads only what is present.
+ */
+export interface MechanicalSignals {
+  /** ERROR family — a run/tool error was recorded. */
+  hasError?: boolean;
+  /** ERROR family — provider/API errors were recorded. */
+  hasApiErrors?: boolean;
+  /** FEEDBACK family — a user chat reaction exists on the trace. */
+  hasChatFeedback?: boolean;
+  /** FEEDBACK family — that reaction was negative (frustration/swear hit). */
+  negativeReaction?: boolean;
+  /** SCORE family — a numeric score exists. */
+  hasScore?: boolean;
+  /** SCORE family — the lowest score seen (compared to `scoreThreshold`). */
+  minScore?: number;
+  /** TERMINAL family — the session was cut off / reached no terminal event. */
+  incomplete?: boolean;
+}
+
+/** One candidate trace at cold start: its id + mechanical signals + dedup keys. */
+export interface ColdTrace {
+  id: string;
+  signals: MechanicalSignals;
+  /** `ext.classification.scenario` — the dedup key (one rep per scenario). */
+  scenario?: string;
+  /** `ext.signals.worthinessScore` [0,1] — dedup keeps the worthiest rep. */
+  worthiness?: number;
+}
+
+/**
+ * The DEFINITION success oracle: maps a cold trace → ✓/✗, or `null` when the
+ * mechanical signals are insufficient to decide. A `null` (UNKNOWN) trace is kept
+ * for coverage but NEVER forced into a pool — it can't help balance and must not
+ * fabricate a label. The default is {@link defaultMechanicalOracle}; a subject
+ * whose DEFINITION encodes a richer success rule injects its own here.
+ */
+export type SuccessOracle = (t: ColdTrace) => ColdOutcomeValue | null;
+
+/** Default SCORE-family pass/fail cut. */
+export const DEFAULT_SCORE_THRESHOLD = 0.5;
+
+/**
+ * The default MECHANICAL oracle over the four cold-label families. A trace is ✗
+ * when ANY negative mechanical signal fired — an error, a NEGATIVE user reaction,
+ * a below-threshold score, or a non-terminal/truncated session — and ✓ otherwise.
+ * PURE + total (never returns `null`): a subject that needs an UNKNOWN verdict
+ * injects its own oracle. No LLM, no provider.
+ */
+export function defaultMechanicalOracle(
+  scoreThreshold: number = DEFAULT_SCORE_THRESHOLD,
+): SuccessOracle {
+  return (t) => {
+    const s = t.signals;
+    const errored = s.hasError === true || s.hasApiErrors === true;
+    const negFeedback = s.hasChatFeedback === true && s.negativeReaction === true;
+    const lowScore =
+      s.hasScore === true && typeof s.minScore === "number" && s.minScore < scoreThreshold;
+    const truncated = s.incomplete === true;
+    return errored || negFeedback || lowScore || truncated ? ColdOutcome.Fail : ColdOutcome.Pass;
+  };
+}
+
+// ── stratify ────────────────────────────────────────────────────────────────
+
+/** The ✓/✗ pools plus the UNKNOWN remainder (oracle abstained). Order-preserving. */
+export interface Stratified {
+  pass: ColdTrace[];
+  fail: ColdTrace[];
+  unknown: ColdTrace[];
+}
+
+/**
+ * Partition traces into the ✓/✗ pools via the oracle (UNKNOWN → `unknown`).
+ * PURE + deterministic; preserves input order within each pool.
+ */
+export function stratify(traces: ColdTrace[], oracle: SuccessOracle): Stratified {
+  const pass: ColdTrace[] = [];
+  const fail: ColdTrace[] = [];
+  const unknown: ColdTrace[] = [];
+  for (const t of traces) {
+    const v = oracle(t);
+    if (v === ColdOutcome.Pass) pass.push(t);
+    else if (v === ColdOutcome.Fail) fail.push(t);
+    else unknown.push(t);
+  }
+  return { pass, fail, unknown };
+}
+
+// ── worthiness / scenario dedup ─────────────────────────────────────────────
+
+/**
+ * Keep ONE representative per `scenario` — the highest `worthiness` (ties → the
+ * first seen). Traces with NO scenario have no dedup key, so they are all kept
+ * (they can't be proven duplicates). Deterministic + order-preserving over the
+ * surviving representatives. Never reorders by worthiness — only DROPS lower-
+ * worthiness same-scenario duplicates.
+ */
+export function dedupByScenario(pool: ColdTrace[]): ColdTrace[] {
+  // First pass: pick the winning id per scenario (highest worthiness, first-seen tie).
+  const winner = new Map<string, ColdTrace>();
+  for (const t of pool) {
+    if (t.scenario === undefined) continue;
+    const cur = winner.get(t.scenario);
+    if (cur === undefined || (t.worthiness ?? 0) > (cur.worthiness ?? 0)) {
+      winner.set(t.scenario, t);
+    }
+  }
+  // Second pass: emit in original order, keeping non-scenario traces + each
+  // scenario's winner exactly once.
+  const emittedScenario = new Set<string>();
+  const out: ColdTrace[] = [];
+  for (const t of pool) {
+    if (t.scenario === undefined) {
+      out.push(t);
+      continue;
+    }
+    if (winner.get(t.scenario) === t && !emittedScenario.has(t.scenario)) {
+      emittedScenario.add(t.scenario);
+      out.push(t);
+    }
+  }
+  return out;
+}
+
+// ── coldStartSample — the balanced cold suite ───────────────────────────────
+
+export interface ColdStartOptions {
+  /** Target suite size (the sampler stays at or under this, MIN-BOTH excepted). */
+  size: number;
+  /**
+   * MIN-BOTH — the guaranteed minimum drawn from EACH non-empty pool (default 1).
+   * When honoring both minimums would exceed `size`, MIN-BOTH WINS: a balanced
+   * bootstrap suite is worth more than a hard size cap, and a success-only suite
+   * is never acceptable.
+   */
+  minBoth?: number;
+  /**
+   * SL-5 PREVALENCE FLOOR — the minimum number of ✗-pool traces retained even when
+   * the ✗ class is scarce (default = `minBoth`). The fail budget never drops below
+   * `min(prevalenceFloor, availableFails)`, so a rare-but-present failure signal is
+   * never balanced away.
+   */
+  prevalenceFloor?: number;
+  /** SCORE-family pass/fail cut for the default oracle (default 0.5). */
+  scoreThreshold?: number;
+  /** The DEFINITION success oracle (default `defaultMechanicalOracle(scoreThreshold)`). */
+  oracle?: SuccessOracle;
+  /** Worthiness/scenario dedup (default true). */
+  dedup?: boolean;
+}
+
+export interface ColdStartSuite {
+  /** The selected cold suite (deduped, balanced): ✓ representatives then ✗. */
+  selected: ColdTrace[];
+  passCount: number;
+  failCount: number;
+  /** true when the ✗-pool was too rare to fill its balanced half → all fails taken. */
+  oversampledFailPool: boolean;
+  /**
+   * true when the suite rests on TOO-FEW negatives — the ✗-pool was oversampled or
+   * couldn't fill its balanced half (or is empty). Downstream MUST treat the first
+   * cold judge pass as LOW-CONFIDENCE and re-balance once real verdicts exist.
+   */
+  lowConfidence: boolean;
+  /**
+   * The MIN-BOTH invariant: BOTH non-empty pools are represented in `selected`.
+   * A success-only suite (or a fail-only suite) ⇒ false. When both pools have
+   * members this is ALWAYS true.
+   */
+  minBothHeld: boolean;
+}
+
+/**
+ * Build a balanced cold-start suite from mechanical labels. Runs the full EV-5.3
+ * pipeline: stratify → SL-5 prevalence floor → scenario/worthiness dedup →
+ * MIN-BOTH → oversample-when-rare. PURE + deterministic; never fabricates.
+ */
+export function coldStartSample(traces: ColdTrace[], opts: ColdStartOptions): ColdStartSuite {
+  const size = Math.max(0, Math.floor(opts.size));
+  const minBoth = Math.max(0, Math.floor(opts.minBoth ?? 1));
+  const oracle = opts.oracle ?? defaultMechanicalOracle(opts.scoreThreshold);
+
+  const strat = stratify(traces, oracle);
+  const pass = opts.dedup === false ? strat.pass : dedupByScenario(strat.pass);
+  const fail = opts.dedup === false ? strat.fail : dedupByScenario(strat.fail);
+
+  const perSide = Math.floor(size / 2);
+  // SL-5 prevalence floor: fails we must keep even when scarce (capped at availability).
+  const prevalenceFloor = Math.max(0, Math.floor(opts.prevalenceFloor ?? minBoth));
+  const failFloor = Math.min(Math.max(prevalenceFloor, minBoth), fail.length);
+
+  let takeFail: number;
+  let takePass: number;
+  let oversampledFailPool = false;
+
+  if (fail.length > 0 && fail.length < perSide) {
+    // ✗-pool RARE — oversample: take EVERY available fail, fill the rest with ✓.
+    oversampledFailPool = true;
+    takeFail = fail.length;
+    takePass = Math.min(pass.length, Math.max(0, size - takeFail));
+  } else {
+    // Balanced take, but never below the SL-5 floor for fails.
+    takeFail = Math.min(fail.length, Math.max(perSide, failFloor));
+    takePass = Math.min(pass.length, Math.max(0, size - takeFail));
+    // If ✓ is scarce and budget remains, let ✗ backfill up to `size`.
+    if (takePass + takeFail < size) {
+      takeFail = Math.min(fail.length, size - takePass);
+    }
+  }
+
+  // MIN-BOTH enforcement — never drop a NON-EMPTY pool below min(minBoth, available).
+  // This is the "never a success-only suite" guarantee; it can push the total over
+  // `size` only in the degenerate small-`size` case, which is intentional.
+  if (fail.length > 0) takeFail = Math.max(takeFail, Math.min(minBoth, fail.length));
+  if (pass.length > 0) takePass = Math.max(takePass, Math.min(minBoth, pass.length));
+
+  const selectedPass = pass.slice(0, takePass);
+  const selectedFail = fail.slice(0, takeFail);
+  const selected = [...selectedPass, ...selectedFail];
+
+  const passCount = selectedPass.length;
+  const failCount = selectedFail.length;
+  const minBothHeld = passCount > 0 && failCount > 0;
+  // Low-confidence when negatives are thin: oversampled, or the ✗-pool couldn't
+  // fill its balanced half, or there are no negatives at all.
+  const lowConfidence = oversampledFailPool || fail.length === 0 || failCount < perSide;
+
+  return { selected, passCount, failCount, oversampledFailPool, lowConfidence, minBothHeld };
+}