@dzhechkov/harness-core 0.4.2 → 0.4.3

package/src/backlog.ts

@@ -91,6 +91,9 @@ export type DedupAction = 'duplicate' | 'related' | 'new';
 /** Pure output of the classifier (04) — consumed by capture. */
 export interface DedupVerdict {
   readonly action: DedupAction;
+  /** Ids excluded from VECTOR candidacy because their text was edited without a re-embed yet. A
+   * consumer must read this before treating a `new` verdict as "compared against everything". */
+  readonly staleExcluded?: string[];
   /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
   readonly cosine: number;
   readonly matchedId: string | undefined;
@@ -593,6 +596,160 @@ export function transitionIdeas(
   return { ok: true, dryRun, changes, errors: [], written: true };
 }
 
+/* ── Edit a captured idea's TEXT (idea 1fde7bf6) ─────────────────────────────────────────────
+ *
+ * Why this verb exists at all: editing the store by hand does NOT re-embed the record, so its dedup
+ * vector keeps describing the OLD text and later duplicate checks run against something the record
+ * no longer says. The verb owns the text change; the CALLER owns the re-embed (it is async and needs
+ * the vector tier). Between the two, the record carries `embedStale` — see ADR-001: the guard against
+ * a stale vector lives where the HARM would be (the dedup verdict), not where the failure happened.
+ * ────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Where an edit's PREVIOUS text is preserved. An edit destroys text and `reopen` cannot undo it the
+ * way it undoes `drop`, so the old text is appended here before the store is rewritten. */
+export function editsLogPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'backlog', 'edits.jsonl');
+}
+
+export interface EditReport {
+  readonly ok: boolean;
+  readonly dryRun: boolean;
+  readonly id?: string;
+  readonly previousText?: string;
+  readonly newText?: string;
+  readonly errors: string[];
+  readonly written: boolean;
+}
+
+/**
+ * Replace or extend ONE idea's text. Mirrors `transitionIdeas`' line discipline exactly: the file is
+ * split without discarding anything, every untouched line — including a line the parser cannot read —
+ * goes back BYTE-FOR-BYTE, and only the matched record's line is re-serialised. The store holds
+ * dozens of records; a whole-file JSON round-trip would reformat all of them to change one.
+ */
+export function editIdea(
+  projectRoot: string,
+  prefix: string,
+  opts: { text?: string; append?: string; dryRun?: boolean; nowIso?: string } = {},
+): EditReport {
+  const dryRun = opts.dryRun === true;
+  const hasText = typeof opts.text === 'string' && opts.text !== '';
+  const hasAppend = typeof opts.append === 'string' && opts.append !== '';
+  if (hasText && hasAppend) {
+    return { ok: false, dryRun, errors: ['--text and --append are mutually exclusive — pick one'], written: false };
+  }
+  if (!hasText && !hasAppend) {
+    return { ok: false, dryRun, errors: ['nothing to do: give --text "<new text>" or --append "<more text>"'], written: false };
+  }
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) {
+    return { ok: false, dryRun, errors: ['no backlog store — nothing captured yet (dz backlog add "<idea>")'], written: false };
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (e) {
+    return { ok: false, dryRun, errors: [`cannot read ${path}: ${(e as Error).message}`], written: false };
+  }
+
+  // Same line discipline as transitionIdeas: nothing is discarded, corrupt lines are left alone.
+  const lines = raw.split('\n');
+  const parsed: { index: number; obj: Record<string, unknown>; id: string }[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (typeof obj.id === 'string' && obj.id !== '') parsed.push({ index: i, obj, id: obj.id });
+    } catch {
+      /* corrupt line — left byte-for-byte as-is */
+    }
+  }
+
+  if (!isSafeId(prefix)) {
+    return { ok: false, dryRun, errors: [`refusing an unsafe idea id: ${JSON.stringify(prefix)}`], written: false };
+  }
+  const res = resolveIdPrefix(parsed.map((p) => p.id), prefix);
+  if (res.kind === 'not-found') {
+    return { ok: false, dryRun, errors: [`no idea matches ${prefix} — run dz backlog list to see the ids`], written: false };
+  }
+  if (res.kind === 'ambiguous') {
+    return { ok: false, dryRun, errors: [`ambiguous prefix ${prefix} — matches ${res.matches.join(', ')}; give more characters`], written: false };
+  }
+  const entries = parsed.filter((p) => p.id === res.id);
+  if (entries.length > 1) {
+    // Deciding on the first line while rewriting one is how the sibling verb grew its twin bug.
+    return { ok: false, dryRun, errors: [`${res.id} appears ${entries.length}× in the store (duplicate lines; resolve the duplicate by hand)`], written: false };
+  }
+  const entry = entries[0]!;
+  const previousText = typeof entry.obj.text === 'string' ? (entry.obj.text as string) : '';
+  const newText = hasText ? (opts.text as string) : `${previousText}${previousText === '' ? '' : ' '}${opts.append as string}`;
+  if (newText === previousText) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+  if (dryRun) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+
+  // Only `text` changes, plus the stale marker. Every other field is carried through untouched.
+  entry.obj.text = newText;
+  entry.obj.embedStale = true;
+  lines[entry.index] = JSON.stringify(entry.obj);
+
+  const nowIso = opts.nowIso ?? new Date().toISOString();
+  const logPath = editsLogPath(projectRoot);
+  try {
+    mkdirSync(join(projectRoot, '.dz', 'backlog'), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify({ id: res.id, previousText, newText, ts: nowIso })}\n`);
+  } catch (e) {
+    // The trail is the ONLY copy of the previous text. Refuse rather than destroy it untraceably.
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`edit log write failed, store left untouched: ${(e as Error).message}`], written: false };
+  }
+
+  const tmp = `${path}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* best-effort litter cleanup */ }
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`store write failed: ${(e as Error).message}`], written: false };
+  }
+  return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: true };
+}
+
+/** Clear the stale marker after a successful re-embed. Separate from `editIdea` because the re-embed
+ * is async and belongs to the caller; a marker cleared without a re-embed would be a lie. */
+export function clearEmbedStale(projectRoot: string, id: string): boolean {
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) return false;
+  let raw: string;
+  try { raw = readFileSync(path, 'utf-8'); } catch { return false; }
+  const lines = raw.split('\n');
+  let touched = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (obj.id === id && obj.embedStale === true) {
+        delete obj.embedStale;
+        lines[i] = JSON.stringify(obj);
+        touched = true;
+      }
+    } catch { /* corrupt line — left alone */ }
+  }
+  if (!touched) return false;
+  const tmp = `${path}.tmp-clear-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    try { unlinkSync(tmp); } catch { /* best-effort */ }
+    return false;
+  }
+}
+
 /* ── Store privacy (idea ec4cd60d): raw ideas are prompt-class PRIVATE content, like recall-usage.jsonl. ── */
 
 export type GitignoreAction = 'created' | 'appended' | 'already-covered' | 'user-opted-out' | 'skipped';
@@ -741,6 +898,11 @@ export interface DedupCandidate {
   readonly id: string;
   readonly cosine: number;
   readonly containment?: number;
+  /** Set when the record's text was edited but its vector has not been rewritten yet (ADR-001,
+   * idea 1fde7bf6). Such a candidate is excluded from VECTOR candidacy — its cosine describes text
+   * the record no longer has. The exact-text net still applies: the marker degrades SIMILARITY,
+   * never IDENTITY. */
+  readonly embedStale?: boolean;
 }
 
 /**
@@ -762,10 +924,18 @@ export function classifyDedup(
   // HIGH-4: a non-finite cosine (NaN/±Infinity) sorts unpredictably and can shove a real 0.97 duplicate
   // out of the top slot → misclassified NEW. Drop non-finite candidates BEFORE sorting/banding (the
   // recurring repo `Number.isFinite` lesson).
-  const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
+  // A record whose text was edited but whose vector has not been rewritten is EXCLUDED from vector
+  // candidacy — the same treatment a non-finite cosine gets, and for the same reason: the number does
+  // not describe the record. ADR-001: the guard sits where the HARM would be (this verdict, days after
+  // the edit) rather than where the failure happened (the edit's own output, which nobody re-reads).
+  const staleExcluded = candidates.filter((c) => c.embedStale === true).map((c) => c.id);
+  const sorted = candidates
+    .filter((c) => c.embedStale !== true)
+    .filter((c) => Number.isFinite(c.cosine))
+    .sort((a, b) => b.cosine - a.cosine);
   const top = sorted[0];
   const exactTextOnly = opts.exactTextOnly === true;
-  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly };
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly, staleExcluded };
   const bands = new Map(sorted.map((c) => [c.id, dedupPairBand(c.cosine, c.containment, cfg)]));
   if (bands.get(top.id) === 'duplicate') {
     return {
@@ -775,6 +945,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       ...(top.containment !== undefined ? { containment: top.containment } : {}),
     };
   }
@@ -794,6 +965,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       subsetMatch: true,
       ...(subset.containment !== undefined ? { containment: subset.containment } : {}),
       ...demoted,
@@ -810,11 +982,12 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: related.map((c) => c.id),
       exactTextOnly,
+      staleExcluded,
       ...topContainment,
       ...demoted,
     };
   }
-  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment };
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment , staleExcluded };
 }
 
 /** Injectable deps so the production dedup path is testable without a live agentdb. */

package/src/index.ts

@@ -34,6 +34,7 @@ export * from './operations.js';
 export * from './workflows.js';
 // loop-designer (feature loop-designer): loop-plan/1 schema + generator + lint + trace planes.
 export * from './loop-plan.js';
+export * from './loop-plan-graph.js';
 export * from './loop-render.js';
 // loop-lint: EXPLICIT export list (QE round-2 G14) — `dominators`, the deliberately-WEAKER
 // analysis kept in src/loop-lint.ts solely as AM-1's mutation seam, is NOT part of the published
@@ -53,6 +54,7 @@ export {
   type LintOptions,
 } from './loop-lint.js';
 export * from './loop-trace.js';
+export * from './trace-bundle.js';
 export { BLOBS as LOOP_BLOBS, LOOP_BLOB_NAMES, BLOB_COVERAGE_MANIFEST } from './loop-blobs.generated.js';
 export type { LoopBlob } from './loop-blobs.generated.js';
 export * from './sign.js';
@@ -491,6 +493,7 @@ export * from './session-retro.js';
 export * from './feature-adr-setup.js';
 export * from './challenge-panel.js';
 export * from './routing-outcomes.js';
+export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';

package/src/loop-plan-graph.ts

@@ -0,0 +1,132 @@
+/**
+ * loop-plan-graph (idea d25a3c8a) — the COMPLETENESS leg of loop-plan/1's closed-world checking.
+ *
+ * What existed before this module (the round-7 cross-family reviewer's ONE not-met bar item,
+ * SIGNOFF's "B-not-A reason 1"): `KNOWN_KEYS === INJECT` and the honesty test's `SCANNED` roster
+ * all compare artifacts DOWNSTREAM of FIELD_DOMAINS — equality proves the rosters are consistent
+ * with each other, never that they are COMPLETE against the interface source. The reviewer's
+ * constructive counterexample: declare `LoopStep.extra?: ExtraPolicy`, add only the parent
+ * `{t:'record'}` domain entry, and `extra: { enabeld: true }` escapes every check while every
+ * equality guard stays green — "a new record kind cannot escape is unproven and demonstrably
+ * false" (verbatim). The shipped mitigation was a documented four-step extension discipline — a
+ * layer-4 instruction, exactly the layer the cost-of-detection ladder says such a check must not
+ * live on.
+ *
+ * THE FIX (this module, layer 1): walk the interface graph from `LoopPlan` in the SOURCE TEXT,
+ * transitively collect every reachable named interface, and let the honesty test require that the
+ * reachable set is exactly the wired set. An interface reachable from LoopPlan but absent from the
+ * wiring fails BY CONSTRUCTION, naming itself — no memory, no discipline, no fourth manual step.
+ *
+ * PURE: operates on source text handed in by the caller; no fs, no clock. That is what lets the
+ * acceptance test run the reviewer's counterexample against a SABOTAGED COPY of the source and
+ * require a red, while the real source stays green.
+ */
+
+/** One parsed field: its name and the DECLARED interface names its type text references. */
+export interface GraphField {
+  readonly field: string;
+  readonly refs: readonly string[];
+}
+
+/** interface name → its fields (index signatures like `[xKey: \`x-${string}\`]` are excluded:
+ * they open no named-interface edge and are the extension escape hatch by design). */
+export type InterfaceGraph = ReadonlyMap<string, readonly GraphField[]>;
+
+/** Brace-matched interface extraction. A regex-only scan truncates at the first nested brace
+ * (inline object fields are everywhere in this file), so bodies are cut by depth counting. */
+export function parseInterfaceGraph(source: string): InterfaceGraph {
+  const names = new Set<string>();
+  const headRe = /(?:^|\n)\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/g;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) names.add(m[1]!);
+
+  const graph = new Map<string, GraphField[]>();
+  headRe.lastIndex = 0;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) {
+    const name = m[1]!;
+    const open = source.indexOf('{', m.index + m[0].length);
+    if (open === -1) continue;
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < source.length; i += 1) {
+      const ch = source[i];
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) { close = i; break; }
+      }
+    }
+    if (close === -1) continue;
+    const body = source.slice(open + 1, close);
+
+    // Split the body into top-level entries at depth 0 (`;` inside an inline `{...}` must not cut).
+    const entries: string[] = [];
+    let entry = '';
+    let d = 0;
+    for (const ch of body) {
+      if (ch === '{' || ch === '(' || ch === '<' || ch === '[') d += 1;
+      else if (ch === '}' || ch === ')' || ch === '>' || ch === ']') d -= 1;
+      if (ch === ';' && d === 0) { entries.push(entry); entry = ''; continue; }
+      entry += ch;
+    }
+    if (entry.trim() !== '') entries.push(entry);
+
+    const fields: GraphField[] = [];
+    for (const raw of entries) {
+      // strip comments, then match `readonly? name?: TYPE`
+      const text = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '').trim();
+      if (text === '' || text.startsWith('[')) continue; // index signature — by-design escape hatch
+      const fm = /^(?:readonly\s+)?([A-Za-z_$][\w$]*)\s*\??:\s*([\s\S]+)$/.exec(text);
+      if (fm === null) continue;
+      const typeText = fm[2]!;
+      const refs = new Set<string>();
+      const idRe = /[A-Za-z_$][\w$]*/g;
+      for (let im = idRe.exec(typeText); im !== null; im = idRe.exec(typeText)) {
+        if (names.has(im[0]) && im[0] !== name) refs.add(im[0]);
+      }
+      fields.push({ field: fm[1]!, refs: [...refs] });
+    }
+    graph.set(name, fields);
+  }
+  return graph;
+}
+
+/** Every interface reachable from `root` (inclusive), via any field's declared-interface refs —
+ * arrays, unions and nullables all count: `LoopStep[]`, `RetryProfile | null` open the same edge. */
+export function reachableInterfaces(graph: InterfaceGraph, root: string): string[] {
+  const seen = new Set<string>();
+  const queue = [root];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    if (seen.has(name) || !graph.has(name)) continue;
+    seen.add(name);
+    for (const f of graph.get(name)!) for (const ref of f.refs) if (!seen.has(ref)) queue.push(ref);
+  }
+  return [...seen].sort();
+}
+
+export interface GraphWiringReport {
+  readonly ok: boolean;
+  /** Reachable from the root but NOT in the wired roster — each one is exactly the reviewer's
+   * counterexample: a record kind whose key space is open while every equality guard stays green. */
+  readonly unwired: string[];
+  readonly reachable: string[];
+  /** Wired but no longer reachable — a stale roster entry (the reverse rot). */
+  readonly stale: string[];
+}
+
+/** The completeness check the equality guards could not perform: reachable(source) vs wired. */
+export function checkGraphWiring(source: string, wired: readonly string[], root = 'LoopPlan'): GraphWiringReport {
+  const graph = parseInterfaceGraph(source);
+  const reachable = reachableInterfaces(graph, root);
+  const wiredSet = new Set(wired);
+  const reachableSet = new Set(reachable);
+  const unwired = reachable.filter((n) => !wiredSet.has(n));
+  // The wired roster (KNOWN_KEYS) legitimately mixes interface names with INLINE-record FIELD names
+  // (`artifacts`, `budget`, `checkpointing`, …) — those are the inlineSubFields machinery's
+  // business, not this check's. Staleness is judged only for entries that ARE declared interfaces
+  // in this source: a declared-but-unreachable interface in the roster is real rot; an inline field
+  // name is not an interface and must not be reported as one (caught on the first live run: five
+  // false stale entries, all inline fields).
+  const stale = [...wiredSet].filter((n) => graph.has(n) && !reachableSet.has(n)).sort();
+  return { ok: unwired.length === 0 && stale.length === 0, unwired, reachable, stale };
+}

package/src/loop-plan.ts

@@ -389,22 +389,20 @@ export const FIELD_DOMAINS: Record<string, FieldDomain> = {
 // domain entry fails the honesty test; adding it WITH one makes it known here automatically. There
 // is exactly one roster, and it is the source's.
 //
-// WHAT THIS DOES AND DOES NOT PROVE (QE round-7, the cross-family reviewer's ONE not-met bar item,
-// CONCEDED). PROVEN, and tested: every record path CURRENTLY WIRED here is closed — no key of any
-// present-day spelling reaches the plan without a diagnostic, and the accepted roster is the
-// source's, not a second hand-list. NOT PROVEN, and it would be an overclaim to say otherwise: that
-// a record kind added in the FUTURE is closed AUTOMATICALLY. Three things remain hand-bounded —
-// (a) the honesty test's `SCANNED` names the interfaces it scans, (b) the fuzz's `INJECT` names the
-// injection sites, and (c) `checkKeys`' parser DESCENT names which nested records it walks. The
-// reviewer's constructive counterexample: declare `LoopStep.extra?: ExtraPolicy` with only a
-// `LoopStep.extra: {t:'record'}` domain entry and an `ExtraPolicy { enabled?: boolean }` interface —
-// unless someone ALSO hand-adds ExtraPolicy's own domains, the descent, `SCANNED` and `INJECT`, then
-// `extra: { enabeld: true }` escapes closed-world checking WHILE the equality assertions stay green.
-// That is a future-extension / proof-maintenance hole, not an input bypass that works today.
+// WHAT THIS PROVES (updated 2026-08-17, idea d25a3c8a — the round-7 not-met bar item is now MET).
+// PROVEN, and tested: every record path wired here is closed, the accepted roster is the source's,
+// AND the roster is COMPLETE against the interface graph: `loop-plan-graph.ts` walks the interfaces
+// reachable from LoopPlan in this file's SOURCE and the honesty test requires reachable == wired ==
+// SCANNED. The reviewer's constructive counterexample (`LoopStep.extra?: ExtraPolicy` with a
+// parent-only domain entry) is the ACCEPTANCE TEST: it goes red naming ExtraPolicy, by
+// construction, before any hand step. Still out of scope, said plainly: interfaces referenced only
+// through type ALIASES are followed one identifier deep (the graph collects declared-interface
+// names from the field's type text); an alias chain that hides an interface behind a non-interface
+// alias would need the alias declared in this file to be walked.
 //
-// EXTENSION DISCIPLINE (the manual step the derivation does not perform for you). When you add a
-// NEW nested record-typed field, do ALL FOUR in the same change, or the key space it opens is not
-// closed: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
+// EXTENSION CONVENIENCE (no longer load-bearing — the graph-completeness test reddens on a missed
+// step by construction; this list just tells you what the red means). When you add a NEW nested
+// record-typed field: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
 // (not just the `{t:'record'}` entry on its PARENT); 2) add the new interface to the honesty test's
 // `SCANNED`; 3) add an `INJECT` site for it in the closed-world fuzz; 4) descend into it in
 // `checkKeys`. A structural fix that derives 2–4 from the interface graph — so a new record kind is

package/src/model-recommender.ts

@@ -0,0 +1,228 @@
+/**
+ * model-recommender (backlog a9c3dd5c, function 3) — the PURE half of `dz routing recommend`.
+ *
+ * NOT a fifth analyzer (ADR-001 D1): this module HARVESTS per-stage (model → success) samples out of
+ * the harness's own workflow records (and imported run-meta sidecars) and hands them to the EXISTING
+ * `selectAutoCost` brain in routing-outcomes.ts — the same brain the `auto-cost` plan spec reads. The
+ * store that brain trusts (`.dz/routing-outcomes.json`) had never been fed before this feature.
+ *
+ * Honesty rules, load-bearing:
+ *  - The ONLY grade a record carries is RUN-level. Attributing it to every stage's model is an
+ *    INFERENCE, and the printed basis states the rule rather than implying it (ADR-001 D2).
+ *  - Cross-family QE is UNREPRESENTABLE, not filtered: the qe pick is computed with the family
+ *    parameter forced to the cross of the code pick's family (ADR-001 D3).
+ *  - `--apply` idempotency lives here as a pure plan (`planFeed`): double-feeding the same runs
+ *    would manufacture confidence the data does not contain (ADR-001 D4).
+ *
+ * No fs, no clock, no randomness — the CLI reads records and does the I/O.
+ */
+
+import { COST_LADDER, selectAutoCost, type AutoCostPick, type Family, type ModelRung } from './routing-outcomes.js';
+
+/** success ⇔ grade ≥ this floor. DATA, exported, and printed in every basis (FR-4). */
+export const GRADE_SUCCESS_FLOOR = 'B';
+const SUCCESS_GRADES = new Set(['A+', 'A', 'A-', 'B+', 'B']);
+
+export function gradeIsSuccess(grade: string): boolean {
+  return SUCCESS_GRADES.has(grade.trim().toUpperCase());
+}
+
+export interface HarvestSample {
+  readonly runId: string;
+  readonly ts: string | null;
+  readonly tier: string;
+  readonly stage: string;
+  /** Normalized to a COST_LADDER rung id (e.g. `codex:gpt-5.5:xhigh (usage-switched)` → `gpt-5.5`). */
+  readonly model: string;
+  readonly success: boolean;
+  readonly grade: string;
+}
+
+export interface Harvest {
+  readonly samples: HarvestSample[];
+  readonly runsUsed: number;
+  readonly window: { min: string; max: string } | null;
+  /** Records that contributed nothing, by WHY — printed in the basis, never silent (FR-7). */
+  readonly skipped: { noResult: number; noModels: number; noGrade: number; unknownModel: number };
+  /** The attribution rule, stated for the reader of every recommendation. */
+  readonly rule: string;
+}
+
+const RULE_TEXT =
+  `success ⇔ QE grade ≥ ${GRADE_SUCCESS_FLOOR} (run-level); the run's ONE grade is attributed to every ` +
+  `stage's model of that run — an inference, stated here because a hidden basis is an opinion in uniform`;
+
+/** `codex:gpt-5.5:xhigh (usage-switched)` → `gpt-5.5`; claude ids pass through; unknown → null. */
+export function normalizeModelId(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw === '') return null;
+  let id = raw.replace(/ \(usage-switched\)$/, '').trim();
+  const codex = /^codex:([^:]+)(?::[a-z]+)?$/.exec(id);
+  if (codex !== null) id = codex[1]!;
+  return COST_LADDER.some((r) => r.id === id) ? id : null;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The run-level grade, wherever this record's era put it (`result.qeGrade`, `result.grade`,
+ * `result.qe.grade`). A string that does not look like a grade is not one. */
+function extractGrade(result: Record<string, unknown>): string | null {
+  const looksLikeGrade = (v: unknown): v is string => typeof v === 'string' && /^[A-F][+-]?$/.test(v.trim().toUpperCase());
+  if (looksLikeGrade(result['qeGrade'])) return (result['qeGrade'] as string).trim().toUpperCase();
+  if (looksLikeGrade(result['grade'])) return (result['grade'] as string).trim().toUpperCase();
+  const qe = result['qe'];
+  if (isRecord(qe) && looksLikeGrade(qe['grade'])) return (qe['grade'] as string).trim().toUpperCase();
+  return null;
+}
+
+/** Harvest per-stage samples from already-read records (live harness records AND the `runMeta.records`
+ * of imported run-meta sidecars — they are the same shape by construction). */
+export function harvestStageOutcomes(records: readonly unknown[]): Harvest {
+  const samples: HarvestSample[] = [];
+  const skipped = { noResult: 0, noModels: 0, noGrade: 0, unknownModel: 0 };
+  const runs = new Set<string>();
+  let min: string | null = null;
+  let max: string | null = null;
+  for (const source of records) {
+    if (!isRecord(source)) { skipped.noResult += 1; continue; }
+    const result = source['result'];
+    if (!isRecord(result)) { skipped.noResult += 1; continue; }
+    const modelsUsed = result['modelsUsed'];
+    if (!isRecord(modelsUsed)) { skipped.noModels += 1; continue; }
+    const grade = extractGrade(result);
+    if (grade === null) { skipped.noGrade += 1; continue; }
+    const runId = typeof source['runId'] === 'string' ? source['runId'] : JSON.stringify(modelsUsed).slice(0, 40);
+    const ts = typeof source['timestamp'] === 'string' ? source['timestamp'] : null;
+    const tier = typeof result['tier'] === 'string' && result['tier'] !== '' ? result['tier'] : 'unknown';
+    let contributed = false;
+    for (const [stage, rawModel] of Object.entries(modelsUsed)) {
+      const model = normalizeModelId(rawModel);
+      if (model === null) { skipped.unknownModel += 1; continue; }
+      contributed = true;
+      samples.push({ runId, ts, tier, stage, model, success: gradeIsSuccess(grade), grade });
+    }
+    if (contributed) {
+      runs.add(runId);
+      if (ts !== null) {
+        if (min === null || ts < min) min = ts;
+        if (max === null || ts > max) max = ts;
+      }
+    }
+  }
+  return {
+    samples,
+    runsUsed: runs.size,
+    window: min !== null && max !== null ? { min, max } : null,
+    skipped,
+    rule: RULE_TEXT,
+  };
+}
+
+export interface StageRecommendation {
+  readonly stage: string;
+  /** The spec string for `args.models` — claude rung ids pass through; openai rungs render as `codex:<id>:high`. */
+  readonly spec: string;
+  readonly pick: AutoCostPick;
+  readonly family: Family;
+  readonly samples: number;
+  /** `selectAutoCost` met its quality bar on ≥minSamples — otherwise this is cold-start, SAID. */
+  readonly insufficientData: boolean;
+}
+
+export interface Recommendation {
+  readonly perStage: StageRecommendation[];
+  readonly basis: {
+    readonly runsUsed: number;
+    readonly window: Harvest['window'];
+    readonly rule: string;
+    readonly skipped: Harvest['skipped'];
+    readonly crossFamilyNote: string;
+  };
+}
+
+function rungFamily(id: string): Family {
+  const rung: ModelRung | undefined = COST_LADDER.find((r) => r.id === id);
+  return rung !== undefined ? rung.family : 'claude';
+}
+
+function toSpec(id: string): string {
+  return rungFamily(id) === 'openai' ? `codex:${id}:high` : id;
+}
+
+const CROSS_NOTE =
+  'the qe pick is computed with the family FORCED to the cross of the code pick — a same-family qe recommendation is unrepresentable (ADR-001 D3)';
+
+/** Recommend per stage over the harvested samples (optionally one tier's slice). */
+export function recommendModels(harvest: Harvest, opts: { tier?: string; qualityBar?: number; minSamples?: number } = {}): Recommendation {
+  const slice = opts.tier === undefined ? harvest.samples : harvest.samples.filter((s) => s.tier === opts.tier);
+  const tierLabel = opts.tier ?? 'all';
+  const byStage = new Map<string, HarvestSample[]>();
+  for (const s of slice) {
+    const bucket = byStage.get(s.stage) ?? [];
+    bucket.push(s);
+    byStage.set(s.stage, bucket);
+  }
+  const statsFor = (stage: string) => (model: string) => {
+    const rows = (byStage.get(stage) ?? []).filter((s) => s.model === model);
+    const successes = rows.filter((s) => s.success).length;
+    return { attempts: rows.length, successes, successRate: rows.length === 0 ? 0 : successes / rows.length };
+  };
+  const pickFor = (stage: string, family?: Family): StageRecommendation => {
+    const pick = selectAutoCost(stage, tierLabel, statsFor(stage), {
+      ...(opts.qualityBar !== undefined ? { qualityBar: opts.qualityBar } : {}),
+      ...(opts.minSamples !== undefined ? { minSamples: opts.minSamples } : {}),
+      ...(family !== undefined ? { family } : {}),
+    });
+    return {
+      stage,
+      spec: toSpec(pick.model),
+      pick,
+      family: rungFamily(pick.model),
+      samples: (byStage.get(stage) ?? []).length,
+      insufficientData: !pick.metBar,
+    };
+  };
+
+  const stages = [...byStage.keys()].sort();
+  const perStage: StageRecommendation[] = [];
+  // code first — the qe family depends on it (D3).
+  const code = pickFor('code');
+  for (const stage of stages) {
+    if (stage === 'qe') {
+      const cross: Family = code.family === 'claude' ? 'openai' : 'claude';
+      perStage.push(pickFor('qe', cross));
+    } else {
+      perStage.push(pickFor(stage));
+    }
+  }
+  if (!stages.includes('code')) perStage.unshift(code);
+  return {
+    perStage,
+    basis: { runsUsed: harvest.runsUsed, window: harvest.window, rule: harvest.rule, skipped: harvest.skipped, crossFamilyNote: CROSS_NOTE },
+  };
+}
+
+/* ── the idempotent feed plan (ADR-001 D4) ─────────────────────────────────────────────── */
+
+export interface FeedPlan {
+  /** Samples whose runId has not been fed before — the CLI calls finalizeOutcome for each. */
+  readonly toFeed: HarvestSample[];
+  readonly skippedRuns: string[];
+  /** The new fed-set the CLI persists after feeding. */
+  readonly fedAfter: string[];
+}
+
+/** A run feeds ONCE. Double-feeding the same telemetry manufactures confidence the data does not
+ * contain — the second `--apply` must feed 0 and say which runs it skipped. */
+export function planFeed(samples: readonly HarvestSample[], alreadyFed: readonly string[]): FeedPlan {
+  const fed = new Set(alreadyFed);
+  const toFeed: HarvestSample[] = [];
+  const skippedRuns = new Set<string>();
+  for (const s of samples) {
+    if (fed.has(s.runId)) skippedRuns.add(s.runId);
+    else toFeed.push(s);
+  }
+  const fedAfter = [...new Set([...alreadyFed, ...toFeed.map((s) => s.runId)])].sort();
+  return { toFeed, skippedRuns: [...skippedRuns].sort(), fedAfter };
+}