@dzhechkov/harness-core 0.3.150 → 0.4.2

package/src/challenge-panel.ts

@@ -24,6 +24,10 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const CHALLENGE_PANEL_BLOB_VERSION = '1.0.0';
+
 export type CId = 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8';
 export type ChallengeSeverity = 'P0' | 'P1' | 'P2';
 const SEV_RANK: Record<ChallengeSeverity, number> = { P0: 3, P1: 2, P2: 1 };

package/src/export-holdout.ts

@@ -0,0 +1,235 @@
+/**
+ * Domain hold-out for the portable export — DEFENCE IN DEPTH, not the guarantee.
+ *
+ * WHY THIS EXISTS — AND WHY IT IS THE SECOND LINE, NOT THE FIRST.
+ * (This heading once read "the thing that actually protects anything", contradicting the
+ * first line of the same comment. ADR-004 moved the guarantee to a separate store; this
+ * file did not move with it.)
+ *
+ * `health-advisor` teaches lessons learned from a real person's investigations. The
+ * first design tried to keep patient data out of the store by INSPECTING THE TEXT —
+ * deciding, from prose, whether a lesson described a method or a person. Seven rounds
+ * of independent cross-model review graded that F and the finding count never
+ * converged, because the question is about meaning: every pattern answering it fails
+ * in both directions, and none of them can see the case that matters most (a rare
+ * combination identifies a person with no name and no digits in the sentence).
+ *
+ * So the guarantee moved to where a guarantee can live. The realistic way a learned
+ * store leaks is not "somebody read the disk" — it is that the store gets SHARED:
+ * exported to JSON, committed, carried to another machine. `dz recall --all --json` is
+ * that path by design; it is documented as the portable sharing form.
+ *
+ * Holding a domain out of that export is decided by a tag the writer set rather than by
+ * parsing prose, so it is language-independent and provable by a test. But it is NOT the
+ * isolation guarantee, and an earlier version of this comment claiming otherwise was
+ * wrong: filtering each command that emits lesson text is itself an enumeration, and
+ * review produced five more such commands (`guard promote --json`, `epoch-replay
+ * --emit`, `vector harmonize`, `consolidate --prune-quarantine`, the `recall --forget`
+ * preview) the moment four were closed. The guarantee is ADR-004 — health lessons are
+ * written to a SEPARATE store and never reach this one. What remains here is a second
+ * line for stray or legacy records, which is worth having and is not the promise.
+ *
+ * THE PROMISE, NARROWLY. This governs the EXPORT. It does not encrypt the local store,
+ * it does not stop a human from copying a file, and it does not make the lesson text
+ * safe to publish. It means: the one command whose job is to hand the store to someone
+ * else will not hand over this domain unless you say so out loud.
+ */
+
+import type { PatternRecord } from './patterns.js';
+
+/**
+ * Canonical key for hold-out comparison — deliberately NOT `normalizeDomain`.
+ *
+ * `normalizeDomain` serves the RANKING boost, where being slightly wrong costs
+ * ordering. Here being slightly wrong costs a leak, so the two must not share a
+ * definition: review found `Health - Research` normalising to `health---research` and a
+ * FULLWIDTH hyphen (U+FF0D) surviving as its own character — both then exported by the
+ * `else` branch. A hold-out that a spelling variant defeats is not a hold-out.
+ *
+ * So: NFKC-fold first, then lower case, then collapse EVERY run of non-alphanumeric
+ * characters to a single `-`. That is an allowlist over the key (letters and digits
+ * survive, nothing else does) rather than a list of separators to keep up to date.
+ *
+ * NFKC is not decoration. Without it `Ｈｅａｌｔｈ－Ｒｅｓｅａｒｃｈ` in fullwidth forms
+ * produced `ｈｅａｌｔｈ-ｒｅｓｅａｒｃｈ` — a different key, so the record exported. Compatibility
+ * normalisation folds fullwidth, ligature and other presentation variants onto the
+ * characters they stand for, which is exactly the equivalence a tag comparison needs.
+ */
+export function canonicalDomainKey(domain: string | null | undefined): string {
+  return String(domain ?? '')
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Domains held out of the portable export by default.
+ *
+ * `health-research` is written by the `goap-research-ed25519` skill when it runs inside
+ * `health-advisor`. It is listed here rather than configured because a default that has
+ * to be switched ON protects nobody: the person who would have configured it is the
+ * person who already understood the risk.
+ */
+export const DEFAULT_HELD_OUT_DOMAINS: readonly string[] = ['health-research'];
+
+export interface HoldoutResult<T> {
+  /** What the export may hand over. */
+  readonly exported: readonly T[];
+  /** What was withheld — returned, not silently dropped, so the caller can COUNT it. */
+  readonly withheld: readonly T[];
+  /** Which held-out domains actually matched, for an honest message. */
+  readonly domains: readonly string[];
+}
+
+/**
+ * Split records into what may be exported and what is held back.
+ *
+ * Comparison goes through `canonicalDomainKey`, so `Health-Research`, `health_research`,
+ * `Health - Research` and a fullwidth-hyphen spelling are one domain — a tag that leaks
+ * through a spelling variant would be the same class of defect as the text guard this
+ * replaced.
+ *
+ * AN UNTAGGED RECORD IS EXPORTED, and that is a real limit of tag-based isolation rather
+ * than an oversight: with no domain there is nothing to compare, and withholding every
+ * untagged lesson would empty the export for the ordinary case. What closes it upstream
+ * is that the writer always tags — `learning_bridge.py` passes `--domain` on every call.
+ */
+export function applyExportHoldout<T extends { readonly domain?: string | null }>(
+  records: readonly T[],
+  heldOut: readonly string[] = DEFAULT_HELD_OUT_DOMAINS,
+): HoldoutResult<T> {
+  const targets = new Set(heldOut.map(canonicalDomainKey).filter((d) => d !== ''));
+  if (targets.size === 0) return { exported: records, withheld: [], domains: [] };
+  const exported: T[] = [];
+  const withheld: T[] = [];
+  const matched = new Set<string>();
+  for (const record of records) {
+    const domain = canonicalDomainKey(record.domain);
+    if (domain !== '' && targets.has(domain)) {
+      withheld.push(record);
+      matched.add(domain);
+    } else {
+      exported.push(record);
+    }
+  }
+  return { exported, withheld, domains: [...matched].sort() };
+}
+
+/**
+ * The line the export prints when it held something back.
+ *
+ * Empty when nothing was withheld, so the common case stays quiet. When something WAS
+ * withheld the count is stated: a silent hold-out would leave the reader believing they
+ * had exported the whole store, which is its own kind of lie — and it would make a
+ * broken hold-out indistinguishable from an empty domain.
+ */
+export function renderHoldoutNote(result: HoldoutResult<unknown>): string {
+  if (result.withheld.length === 0) return '';
+  const n = result.withheld.length;
+  const domains = result.domains.join(', ');
+  return `  ${n} lesson(s) in ${domains} were HELD BACK from this export — that domain carries medical research and does not travel by default. To include it deliberately: --include-domain ${domains}`;
+}
+
+/** Parse a comma-separated `--include-domain` value into the hold-out list that remains. */
+export function heldOutAfterOptIn(
+  optIn: string | undefined,
+  heldOut: readonly string[] = DEFAULT_HELD_OUT_DOMAINS,
+): readonly string[] {
+  if (optIn === undefined) return heldOut;
+  const requested = new Set(
+    optIn.split(',').map((d) => canonicalDomainKey(d)).filter((d) => d !== ''),
+  );
+  return heldOut.filter((d) => !requested.has(canonicalDomainKey(d)));
+}
+
+/** Convenience for callers holding full `PatternRecord`s. */
+export type PatternHoldout = HoldoutResult<PatternRecord>;
+
+/**
+ * The advice printed when a held-out domain is written into a SHARED store.
+ *
+ * NOT a refusal. Someone who wants their medical lessons in the shared store owns both
+ * directories and the `dz` binary, and stopping them would mean defending a user against
+ * themselves — which this design deliberately does not attempt (ADR-004, threat model).
+ * What it does instead is make sure the choice is INFORMED: say what follows from it,
+ * name the default, and show the one command that does it the other way.
+ *
+ * The distinction that decides whether to warn is the STORE, not the person: a project
+ * whose directory is the health brain is exactly where these lessons belong, so writing
+ * one there is silent. Anywhere else, the lesson is about to join lessons that travel.
+ *
+ * `projectRoot` MUST already be resolved by the caller. Deciding from the unresolved
+ * NAME meant `ln -s <a shared project> /tmp/.health-brain` silenced the advice while the
+ * write landed in the shared store — the advice went quiet in exactly the case it exists
+ * for. A name is a claim about a path; only a resolved path is the path.
+ */
+export function renderSharedStoreAdvice(domain: string | null | undefined, resolvedProjectRoot: string): string {
+  const key = canonicalDomainKey(domain);
+  if (key === '' || !DEFAULT_HELD_OUT_DOMAINS.map(canonicalDomainKey).includes(key)) return '';
+  if (/[\\/]\.health-brain\/?$/.test(resolvedProjectRoot)) return '';
+  return [
+    `  ⚠ "${domain}" is a medical domain, and this is a SHARED store.`,
+    '    Lessons here are read by every command that reads this store, and the portable',
+    '    export (dz recall --all --json) is how a store leaves a machine. We recommend',
+    '    against it by default: keep medical lessons in their own store, which also keeps',
+    '    the prompts and transcripts of that work in one place you can inspect or delete.',
+    `    The other way: dz teach "<lesson>" --domain ${domain} --project <dir>/.health-brain`,
+    '    Nothing was blocked — this is your call, and it is now on the record.',
+  ].join('\n');
+}
+
+export interface VectorExportDecision {
+  readonly allow: boolean;
+  /** Why it was refused — empty when allowed. */
+  readonly reason: string;
+  /** What the caller should pass to proceed deliberately. */
+  readonly optInHint: string;
+}
+
+/**
+ * Whether `dz vector export` may write a checkpoint.
+ *
+ * EXTRACTED SO IT CAN BE TESTED. The decision used to live inline in the CLI behind an
+ * earlier `return` (the RVF engine is opt-in and absent on most machines), so the branch
+ * that matters could not be exercised at all in a normal checkout — I could reason about
+ * it and not run it, which is the position this project treats as unverified.
+ *
+ * The rule: a `.rvf` checkpoint carries embeddings keyed by id and NO domain, so its
+ * contents cannot be classified from the file. This export is also all-or-nothing — the
+ * adapter copies the store whole. So when such a file exists the answer is REFUSE unless
+ * the caller names what travels; `recall --forget` deletes a lexical record and leaves
+ * its embedding behind, which is exactly why the lexical store cannot stand in for this.
+ */
+export function decideVectorExport(input: {
+  readonly rvfExists: boolean;
+  readonly heldOutLexicalCount: number;
+  readonly heldOutDomains: readonly string[];
+  readonly optedIn: string | undefined;
+}): VectorExportDecision {
+  // "NAMED" means the HELD-OUT domain was named, not that some flag was passed. The
+  // first version accepted any non-empty value, so `--include-domain security` unlocked
+  // an unclassifiable checkpoint — the message said "name what travels" and the code
+  // asked only "did you type something". Worse, the test I wrote alongside it asserted
+  // the same weak condition, so it locked the defect in instead of catching it.
+  const optedKeys = new Set(
+    (input.optedIn ?? '').split(',').map((d) => canonicalDomainKey(d)).filter((d) => d !== ''),
+  );
+  const named = DEFAULT_HELD_OUT_DOMAINS.some((d) => optedKeys.has(canonicalDomainKey(d)));
+  const hint = (input.heldOutDomains.length > 0 ? input.heldOutDomains : DEFAULT_HELD_OUT_DOMAINS).join(',');
+  if (input.rvfExists && !named) {
+    return {
+      allow: false,
+      reason: 'a .rvf checkpoint stores embeddings keyed by id with no domain, so this gate cannot tell whether it holds held-out lessons — and it is exported whole',
+      optInHint: hint,
+    };
+  }
+  if (input.heldOutLexicalCount > 0 && !named) {
+    return {
+      allow: false,
+      reason: `the store holds ${input.heldOutLexicalCount} lesson(s) in ${input.heldOutDomains.join(', ')}, and this export is all-or-nothing`,
+      optInHint: hint,
+    };
+  }
+  return { allow: true, reason: '', optInHint: hint };
+}

package/src/feature-adr-checkpoints.ts

@@ -24,6 +24,10 @@
  * the wiring test asserts the mirror stays present.
  */
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const BLOB_VERSION = '1.1.0';
+
 /** Stages the workflow checkpoints, in pipeline order. Cheap side-channel agents (usage probes,
  * fa-record, auto-cost selects) are never checkpointed; the opt-in Delivery gate re-runs by design
  * (advisory verdicts should reflect the CURRENT tree). */
@@ -74,7 +78,7 @@ export function fnv1a(str: string): string {
  * findable collisions (Codex QE #9 produced a real pair at `11a08b58`); two passes make the
  * single-pair collision odds ~2^-64 — adequate for one slug's checkpoint file. */
 export function fnv1a64(str: string): string {
-  return fnv1a(str) + fnv1a('
fa-ckpt-salt
' + str);
+  return fnv1a(str) + fnv1a('fa-ckpt-salt' + str);
 }
 
 /** The stage's input fingerprint: a JSON-tuple (delimiter-ambiguity class — never a separator join)
@@ -219,3 +223,289 @@ export function checkpointAppendCmd(fdirAbs: string, line: string): string {
   const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');
   return 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Training-pair capture (backlog 70e0f083) — the PURE half.
+//
+// Goal: fully-local development on compact models in 4–6 months needs a dataset of
+// STAGE INPUT (full context+prompt) → STAGE OUTPUT (artifact/result) → EVALUATION
+// (QE grade + the lessons injected into context) records. Everything is already in
+// hand at the moment each feature-adr stage completes — so capture is instrumented
+// NOW (every un-captured run is a lost pair); the dataset itself is built later.
+//
+// Storage: ONE JSONL file per stage under .dz/fa-training/<slug>/<stage>.jsonl
+// (owner decision 2026-08). Deliberately NOT gitignored (owner decision — pairs may
+// contain target-repo code; the capture dir carries a README privacy note instead).
+//
+// Stage asymmetry (the reason provenance.family is load-bearing): the downstream
+// dataset must honour the cross-model rule — QE pairs must come from a DIFFERENT
+// family than the coder's pairs; router/plan distill easily, code is hardest.
+//
+// Pure and deterministic like the checkpoint half: ts is PASSED IN (never read from a clock
+// — the workflow sandbox forbids Date, and tests must stay deterministic); the
+// workflow mirrors these functions inline and fills ts shell-side via sed.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type CaptureMode = 'capture' | 'backfill' | 'skip-disabled' | 'skip-empty';
+
+/** Decide whether this completion is captured. A resumed stage is backfilled rather than
+ * skipped: its input (stage template + args) and checkpointed output are both in scope at the
+ * capture site, so the pair is deterministically reconstructible. trainingPairBackfillCmd's
+ * persistent atomic mark makes that write at-most-once, so concurrent invocations and later
+ * runIds cannot double-append the same pair. */
+export function decideCaptureMode(opts: { enabled: boolean; resumed: boolean; recordCount: number }): CaptureMode {
+  if (!opts.enabled) return 'skip-disabled';
+  if (!Number.isInteger(opts.recordCount) || opts.recordCount <= 0) return 'skip-empty';
+  return opts.resumed ? 'backfill' : 'capture';
+}
+
+export type CaptureFailureReason = 'threw' | 'unserializable' | 'unverified' | 'backfill-unverified' | 'empty-output';
+
+export interface CaptureFailureRecord {
+  stage: string;
+  mode: CaptureMode | null;
+  reason: CaptureFailureReason;
+  detail: string | null;
+}
+
+/** Normalize capture failures for collection by the caller. This recorder must never throw:
+ * replacing the original capture failure with a reporting failure would hide the real cause. */
+export function captureFailureRecord(stage: unknown, mode: unknown, reason: unknown, detail: unknown): CaptureFailureRecord {
+  const normalizedStage = typeof stage === 'string' && stage.trim() !== '' ? stage : 'unknown';
+  const normalizedMode: CaptureMode | null =
+    mode === 'capture' || mode === 'backfill' || mode === 'skip-disabled' || mode === 'skip-empty'
+      ? mode
+      : null;
+  const normalizedReason: CaptureFailureReason =
+    reason === 'threw' || reason === 'unserializable' || reason === 'unverified' || reason === 'backfill-unverified' || reason === 'empty-output'
+      ? reason
+      : 'threw';
+  let normalizedDetail: string | null = null;
+  if (detail !== null && detail !== undefined) {
+    try {
+      const text = String(detail);
+      if (text !== '') normalizedDetail = text.length > 500 ? text.slice(0, 500) + '…' : text;
+    } catch {
+      normalizedDetail = null;
+    }
+  }
+  return { stage: normalizedStage, mode: normalizedMode, reason: normalizedReason, detail: normalizedDetail };
+}
+
+/** Training-pair record format version. Bump on any field-shape change. */
+export const TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-2';
+
+/** Oversize guard cap over input+output combined (same posture as
+ * CHECKPOINT_MAX_RESULT_CHARS, sized for full stage prompts): an over-cap pair is
+ * TRUNCATED with a named marker + a hash of the full text — never silently dropped
+ * (a lost pair is a lost training sample), never unbounded (a 10MB line would make
+ * the JSONL unusable and the write-agent prompt explode). */
+export const TRAINPAIR_MAX_IO_CHARS = 48_000;
+
+export type TrainingPairFamily = 'claude' | 'codex';
+
+/** The family a model spec/label/runner-name belongs to. Family ∈ {claude, codex} —
+ * the field the cross-model dataset rule stands on. Anything naming codex/gpt/openai
+ * is 'codex' (incl. 'codex-fallback' — codex ACTUALLY produced that stage); everything
+ * else (opus/sonnet/fable/haiku, role agentTypes, 'claude-fallback') is 'claude'. */
+export function trainingPairFamily(spec: unknown): TrainingPairFamily {
+  return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';
+}
+
+export interface TrainingPairEvaluation {
+  /** The QE grade for this pair, or null when the stage honestly has none (router). */
+  grade: string | null;
+  /** Who graded it (runner + model label), or null when ungraded. */
+  gradedBy: string | null;
+  /** Lesson texts/ids recalled into THIS stage's context (Step-0 recall). */
+  lessonsInjected: string[];
+}
+
+export interface TrainingPairProvenance {
+  /** The model label that produced the stage output. */
+  model: string;
+  /** The model FAMILY — load-bearing for the cross-model dataset rule. */
+  family: TrainingPairFamily;
+  /** The stage role: 'router' | 'design:*' | 'planner' | 'coder' | 'reviewer' | 'fleet-qe'. */
+  role: string;
+  tokens: number | null;
+  minutes: number | null;
+}
+
+export interface TrainingPairTruncation {
+  /** Original (pre-truncation) char counts + full-text hashes — what was cut is NAMED. */
+  inputChars: number;
+  outputChars: number;
+  inputHash: string;
+  outputHash: string;
+}
+
+/** One SFT-ready record: prompt → completion → evaluation, one JSON object per line. */
+export interface TrainingPair {
+  schema: string;
+  slug: string;
+  stage: string;
+  /** ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint. */
+  ts: number | string | null;
+  input: string;
+  output: string;
+  evaluation: TrainingPairEvaluation;
+  provenance: TrainingPairProvenance;
+  truncated: TrainingPairTruncation | null;
+  captureMode: 'capture' | 'backfill';
+  resumed: boolean;
+}
+
+/** Per-stage JSONL path, relative to the repo root. ONE file per stage. */
+export function trainingPairPath(slug: string, stage: string): string {
+  return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';
+}
+
+/** README dropped once into the capture dir. The caveat is documented ON DISK because the
+ * directory is deliberately not gitignored (explicit owner decision, 2026-08). */
+export const TRAINPAIR_PRIVACY_NOTE =
+  "feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it. ts is the CAPTURE time. On a record with captureMode: 'backfill' that is the RECONSTRUCTION time, NOT the stage's observation time — the original stage's timing lives in that run's .fa-state checkpoint.";
+
+/** Coerce a stage input/output to text: strings pass through; objects serialize to JSON;
+ * an unserializable value degrades to String(v) — buildTrainingPair NEVER throws (capture
+ * is non-blocking by contract). */
+function coerceText(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (v === null || v === undefined) return '';
+  try {
+    const s = JSON.stringify(v);
+    return typeof s === 'string' ? s : String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+/** Assemble one SFT-ready training pair. Deterministic (ts passed in). Applies the oversize
+ * guard: when input+output exceed TRAINPAIR_MAX_IO_CHARS combined, each over-budget side is
+ * truncated with a marker naming the cut char count + the fnv1a64 of its FULL text (the
+ * budget flows to the smaller side, so a small prompt next to a huge output stays verbatim).
+ * Evaluation honesty: an empty/whitespace grade normalizes to null — a stub never reads as
+ * a real evaluation. Provenance: an explicit valid family wins; otherwise it is DERIVED from
+ * the model spec via modelFamily (an invalid family never leaks into the dataset). */
+export function buildTrainingPair(opts: {
+  slug: string;
+  stage: string;
+  ts: number | string | null;
+  input: unknown;
+  output: unknown;
+  evaluation?: Partial<TrainingPairEvaluation> | null;
+  provenance?: Partial<TrainingPairProvenance> | null;
+  captureMode?: unknown;
+  resumed?: unknown;
+}): TrainingPair {
+  let input = coerceText(opts.input);
+  let output = coerceText(opts.output);
+  let truncated: TrainingPairTruncation | null = null;
+  if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {
+    truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };
+    const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);
+    let inKeep = input.length;
+    let outKeep = output.length;
+    if (outKeep <= half) inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;
+    else if (inKeep <= half) outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;
+    else { inKeep = half; outKeep = TRAINPAIR_MAX_IO_CHARS - half; }
+    if (inKeep < input.length) input = input.slice(0, inKeep) + '\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';
+    if (outKeep < output.length) output = output.slice(0, outKeep) + '\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';
+  }
+  const ev = opts.evaluation || {};
+  const pv = opts.provenance || {};
+  return {
+    schema: TRAINPAIR_SCHEMA_VERSION,
+    slug: opts.slug,
+    stage: opts.stage,
+    ts: opts.ts === undefined ? null : opts.ts,
+    input,
+    output,
+    evaluation: {
+      grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,
+      gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,
+      lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s): s is string => typeof s === 'string' && s !== '') : [],
+    },
+    provenance: {
+      model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',
+      family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),
+      role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',
+      tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,
+      minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,
+    },
+    truncated,
+    captureMode: opts.captureMode === 'backfill' ? 'backfill' : 'capture',
+    resumed: opts.resumed === true,
+  };
+}
+
+/** Serialize one training pair to a JSONL line. The oversize guard already bounds the pair,
+ * so this only fails on the impossible (all fields are plain data) — null on that, never a throw. */
+export function serializeTrainingPair(pair: TrainingPair): string | null {
+  try {
+    const line = JSON.stringify(pair);
+    return typeof line === 'string' ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The one Bash command the write agent runs: mkdir the slug dir, drop the privacy README
+ * once (if-absent guard), then append ONE line (single-quote-escaped byte-faithfully, same
+ * idiom as checkpointAppendCmd). */
+export function trainingPairAppendCmd(repoAbs: string, slug: string, stage: string, line: string): string {
+  const dirAbs = repoAbs + '/.dz/fa-training/' + slug;
+  const readmeAbs = repoAbs + '/.dz/fa-training/README.md';
+  const fileAbs = dirAbs + '/' + stage + '.jsonl';
+  return (
+    'mkdir -p ' + shellQuote(dirAbs) +
+    ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \'%s\\n\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +
+    " && printf '%s\\n' " + shellQuote(line) + ' >> ' + shellQuote(fileAbs)
+  );
+}
+
+/** Readback sentinels for the caller to distinguish an at-most-once write from an existing pair. */
+export const TP_BACKFILL_OK = 'TP-BACKFILL-OK';
+export const TP_BACKFILL_SKIP = 'TP-BACKFILL-SKIP';
+export const TP_BACKFILL_DUP = 'TP-BACKFILL-DUP';
+
+/** Build the deterministic resume-backfill command. The persistent mkdir mark is the atomic
+ * at-most-once primitive; the inner file-absence guard also protects pair files created before
+ * marks existed. The mark is RELEASED when — and only when — the append fails, so a failed backfill
+ * stays retryable. The `[ -f ]` path keeps the mark because the pair genuinely exists.
+ * KNOWN RESIDUAL: a process killed (SIGKILL, sandbox timeout) between the `mkdir` claim and the end
+ * of the append still leaves a poisoned mark. That window is strictly narrower than "any append
+ * failure" and is the same externally-killed class this feature already names for the ledger row.
+ * `TP_BACKFILL_SKIP` means "the per-stage pair file already existed"; `TP_BACKFILL_DUP` means
+ * "another run already owns this content". The two strings are deliberately NON-PREFIXING because
+ * the two producers parse the readback differently — the generated loop compares `===` after
+ * `trim`, while the `feature-adr.js` twin tests an UNANCHORED regex; a prefixed name would be `DUP`
+ * to one parser and `SKIP` to the other from the same bytes. The default `markKey` is per-CONTENT
+ * only; a caller whose line embeds a per-run identifier must pass a run-independent `markKey`.
+ * Marks are deliberately never pruned. */
+export function trainingPairBackfillCmd(repoAbs: string, slug: string, stage: string, lines: readonly string[], markKey?: string): string | null {
+  if (typeof repoAbs !== 'string' || repoAbs === '') return null;
+  if (typeof slug !== 'string' || slug === '') return null;
+  if (typeof stage !== 'string' || stage === '') return null;
+  if (!Array.isArray(lines) || lines.length === 0 || !lines.every(line => typeof line === 'string' && line !== '')) return null;
+
+  const dirAbs = repoAbs + '/.dz/fa-training/' + slug;
+  const readmeAbs = repoAbs + '/.dz/fa-training/README.md';
+  const fileAbs = dirAbs + '/' + stage + '.jsonl';
+  const markDir = repoAbs + '/.dz/fa-training/.backfill-marks';
+  const markStage = stage.replace(/\.\./g, '_').replace(/\//g, '_');
+  const resolvedMarkKey = markKey === undefined ? fnv1a64(stage + '\0' + lines.join('\n')) : markKey;
+  const markPath = markDir + '/' + markStage + '-' + resolvedMarkKey;
+  const appends = lines
+    .map(line => "printf '%s\\n' " + shellQuote(line) + ' >> ' + shellQuote(fileAbs))
+    .join(' && ');
+  return (
+    'mkdir -p ' + shellQuote(dirAbs) +
+    ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \'%s\\n\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +
+    ' && mkdir -p ' + shellQuote(markDir) +
+    ' && if mkdir ' + shellQuote(markPath) + ' 2>/dev/null; then ' +
+    'if [ -f ' + shellQuote(fileAbs) + ' ]; then echo ' + shellQuote(TP_BACKFILL_SKIP) +
+    '; else { ' + appends + ' && echo ' + shellQuote(TP_BACKFILL_OK) + '; } || { rmdir ' + shellQuote(markPath) + ' 2>/dev/null; false; }; fi' +
+    '; else echo ' + shellQuote(TP_BACKFILL_DUP) + '; fi'
+  );
+}

package/src/feature-adr-routing.ts

@@ -27,6 +27,10 @@
  * @packageDocumentation
  */
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const BLOB_VERSION = '1.0.0';
+
 /** A resolved `agent()` opts fragment: either a Claude `{model}` or a codex spec. */
 export interface StageOpts {
   readonly model?: string;