@dzhechkov/harness-core 0.8.37 → 0.8.39

package/src/agentdb-index.ts

@@ -1168,9 +1168,9 @@ export async function importVectorsToAgentdb(
 }
 
 /**
- * lesson-quarantine: clear the `qStatus` marker from mirrored rows after a promotion — the hook
- * daemon reads ONLY this mirror's metadata, so a promoted lesson must stop being excluded there
- * too. Best-effort, same custody model as {@link bumpAgentdbUses} (missing db/deps ⇒ no-op).
+ * lesson-quarantine: mark mirrored rows as promoted after a promotion — the hook daemon reads ONLY
+ * this mirror's metadata, so a promoted lesson must stop being excluded there while retaining its
+ * quarantine history. Best-effort, same custody model as {@link bumpAgentdbUses} (missing db/deps ⇒ no-op).
  */
 export function clearAgentdbQuarantine(
   projectRoot: string,
@@ -1194,12 +1194,12 @@ export function clearAgentdbQuarantine(
       db.pragma('busy_timeout = 5000');
       db.exec(REASONING_BANK_SCHEMA);
       const stmt = db.prepare(
-        "UPDATE reasoning_patterns SET metadata = json_remove(metadata, '$.qStatus', '$.quarantinedAt') WHERE json_extract(metadata, '$.dzId') = ? AND json_extract(metadata, '$.qStatus') = 'quarantined'",
+        "UPDATE reasoning_patterns SET metadata = json_set(metadata, '$.qStatus', 'promoted', '$.promotedAt', ?) WHERE json_extract(metadata, '$.dzId') = ? AND json_extract(metadata, '$.qStatus') = 'quarantined'",
       );
       const tx = db.transaction(() => {
         let cleared = 0;
         for (const dzId of dzIds) {
-          const r = stmt.run(dzId);
+          const r = stmt.run(new Date().toISOString(), dzId);
           cleared += Number((r as unknown as { changes?: number }).changes ?? 0);
         }
         return cleared;

package/src/amendment-trace.ts

@@ -138,7 +138,10 @@ export function extractTestTitles(body: string): string[] {
 }
 
 export function normalizeTestId(s: string): string {
-  return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  // Unicode letter/number classes: the old `[^a-z0-9]` erased Cyrillic outright, so a Russian test title
+  // normalised to '' and tripped the floor as the author's fault (MEASURED 2026-09-04, backlog 191853a2).
+  // Re-run over all 519 features on 2026-09-20: zero verdicts changed — this only adds matches.
+  return s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
 }
 
 /**

package/src/backlog.ts

@@ -266,7 +266,7 @@ export function readBacklogConfig(projectRoot: string): BacklogConfig {
 }
 
 /* ================================================================== */
-/*  STORE (AM-1) — .dz/backlog/ideas.jsonl (append-only JSONL, ADR-005) */
+/*  STORE (AM-1) — .dz/backlog/ideas.jsonl (JSONL rewritten WHOLE per write, ADR-005 + amendment 2026-09-20) */
 /* ================================================================== */
 
 export function backlogDir(projectRoot: string): string {
@@ -335,7 +335,8 @@ function normaliseIdea(raw: Record<string, unknown>): IdeaRecord | undefined {
   return rec;
 }
 
-/** Read the append-only store. A corrupt line is SKIPPED (never fatal) — the whole store never throws. */
+/** Read the store (one current line per id — `writeIdeas` rewrites it whole and never appends). A corrupt
+ *  line is SKIPPED (never fatal) — the whole store never throws. */
 export function readIdeas(projectRoot: string): IdeaRecord[] {
   const path = ideasPath(projectRoot);
   if (!existsSync(path)) return [];

package/src/brain.ts

@@ -21,6 +21,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdir
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
+import { openSqliteReadOnly } from '@dzhechkov/memory';
 import { putBookKnowledge, queryBookKnowledge, bookKbPath, type BookKU, type BookKUHit } from './book-kb.js';
 import { indexPatternsToAgentdb, searchAgentdbPatterns, reindexAgentdbRows, type AgentdbRow } from './agentdb-index.js';
 import type { SnapshotRotationReport } from './agentdb-snapshot-rotation.js';
@@ -193,7 +194,8 @@ export function readBookKus(opts: {
     return { kus: [], error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
   }
   try {
-    const db = new Database(opts.storePath, { readonly: true });
+    const handle = openSqliteReadOnly(opts.storePath, { Database });
+    const db = handle.db as NativeDb;
     try {
       const cols = 'book, ku_id, corpus_version, type, name, problem, content, chapter, pages, metadata';
       const rows = (opts.source !== undefined
@@ -201,7 +203,11 @@ export function readBookKus(opts: {
         : db.prepare(`SELECT ${cols} FROM book_knowledge`).all()) as ProjRow[];
       return { kus: rows.map(rowToKu) };
     } finally {
-      db.close();
+      try {
+        db.close();
+      } finally {
+        handle.cleanup();
+      }
     }
   } catch (err) {
     return { kus: [], error: `read book KB failed: ${err instanceof Error ? err.message : String(err)}` };

package/src/bto-optimize.ts

@@ -20,6 +20,8 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 
+import { maskMarkdown } from './markdown-masker.js';
+
 export type BtoDimension = 'METHODOLOGY' | 'DEPTH' | 'CORRECTNESS' | 'USABILITY' | 'ROBUSTNESS';
 export const BTO_DIMENSIONS: readonly BtoDimension[] = Object.freeze(['METHODOLOGY', 'DEPTH', 'CORRECTNESS', 'USABILITY', 'ROBUSTNESS']);
 export type DimScores = Record<BtoDimension, number>;
@@ -203,22 +205,22 @@ const bodyAfterFrontmatter = (t: string): string => {
 
 /**
  * ALL structural markers on the BODY, not just space-delimited ATX (QE: `##\tNEW`, bare `##`, and setext
- * `Title\n===` / `Title\n---` evaded the old regex). Fenced code blocks (``` / ~~~) are SKIPPED so a `===`/`---`
- * line INSIDE code is not misread as a heading (QE false-positive). Collect ATX (`#`..`######` + any/no ws)
- * AND setext underlines (a non-empty line immediately followed by `=+`/`-+`).
+ * `Title\n===` / `Title\n---` evaded the old regex). The canonical masker skips fenced code blocks before
+ * collecting ATX (`#`..`######` + any/no ws) and setext underlines (a non-empty line immediately followed
+ * by `=+`/`-+`). Its `unclosed: 'restore'` policy is load-bearing: measured over 7,121 headed Markdown
+ * documents, the old parity toggle missed a deletion in 39 documents, masking with `hide` missed 22, and
+ * masking with `restore` missed 0.
  */
 const headings = (t: string): string[] => {
-  const lines = bodyAfterFrontmatter(t).split('\n');
+  const body = bodyAfterFrontmatter(t);
+  const lines = maskMarkdown(body, { unclosed: 'restore' }).split('\n');
   const out: string[] = [];
-  let inFence = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
-    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
-    if (inFence) continue;
     const atx = /^(#{1,6})(?:\s.*)?$/.exec(line.replace(/\s+$/, ''));
     if (atx) { out.push('ATX:' + line.trim()); continue; }
     const next = lines[i + 1];
-    if (line.trim() !== '' && !/^\s*(```|~~~)/.test(next ?? '') && next !== undefined && /^(=+|-+)\s*$/.test(next)) {
+    if (line.trim() !== '' && next !== undefined && /^(=+|-+)\s*$/.test(next)) {
       out.push('SETEXT:' + line.trim() + '|' + next.trim());
     }
   }

package/src/claim-check.ts

@@ -122,6 +122,8 @@ function paragraphAround(lines: readonly string[], i: number): string {
 /** Tags that make a claim honest (case-insensitive). */
 // `estimated` agrees with the `estimated: true` honest-uncertainty marker `dz usage` already
 // emits — the two honesty systems must not contradict each other.
+import { maskMarkdown } from './markdown-masker.js';
+
 const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baseline', 'estimated'];
 
 /**
@@ -136,17 +138,27 @@ const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baselin
  */
 export function isFenced(text: string, line: number): boolean {
   if (typeof text !== 'string' || typeof line !== 'number' || !isFinite(line) || line < 1) return false;
-  const lines = text.split(/\r?\n/);
-  const upTo = Math.min(line - 1, lines.length);
-  let open: '`' | '~' | null = null;
-  for (let i = 0; i < upTo; i++) {
-    const m = FENCE_RE.exec(lines[i] || '');
-    if (!m) continue;
-    const marker = m[1]![0] as '`' | '~';
-    if (open === null) open = marker;
-    else if (open === marker) open = null;
-  }
-  return open !== null;
+  // DELEGATED to the canonical masker. The local walk this replaces already tracked the marker
+  // CHARACTER — the naive-toggle bug the comment above describes was genuinely fixed — but it still
+  // broke two further CommonMark rules, and both were MEASURED 2026-09-20 to answer `false` for a
+  // line that IS inside a block: a closing fence may carry NO info string, so a second info-string
+  // line closed the block; and a closing fence may not be SHORTER than the opening one, so a
+  // three-backtick line closed a four-backtick block. Both make the engine scan a QUOTED example as
+  // a real claim, and make the hook's deny path stop exempting it.
+  //
+  // `unclosed: 'hide'` keeps the local walk's policy: an unclosed opener leaves every later line
+  // inside the block. One deliberate difference: the OPENING delimiter line now answers `true` (the
+  // local walk answered `false` for it and `true` for the closing one) — an info string is not
+  // prose, and the two delimiters answering differently was an artifact, not a decision.
+  let masked = false;
+  try {
+    const target = line - 1;
+    maskMarkdown(text.replace(/\r\n/g, '\n'), {
+      unclosed: 'hide',
+      onMasked: (i?: number) => { if (i === target) masked = true; },
+    });
+  } catch { return false; }
+  return masked;
 }
 
 const FENCE_RE = /^\s*(`{3,}|~{3,})/;
@@ -189,9 +201,33 @@ const MAP_METRIC_RE = new RegExp(
  * A shell reproducer is STRUCTURAL, never a word. `(MEASURED — reproducer)` is self-certifying and
  * must not pass; a backticked span whose first token is a command this repo actually measures with is
  * evidence. The allowlist boundary is exactly that: an unknown binary is a claim ABOUT evidence.
+ *
+ * `python3` joined the list for backlog 0b53470a, on the list's OWN criterion rather than by
+ * widening it: `packages/@dzhechkov/health-advisor/test/goap-python-suite.test.js` makes
+ * `python3 -m unittest discover` a GATE, so it is a command this repo measures with. Before the
+ * addition a Python measurer could not cite itself — MEASURED by twins, one line differing only in
+ * the backticked binary: `python3 …` → 1 finding "Tagged MEASURED but cites no reproducer",
+ * `pytest …` → 0, `git show …` → 0. Bare `python` was deliberately NOT added (cross-family review
+ * r1, MEDIUM): the gate this repo runs is `python3`, and the only measured usage in the tree is
+ * `python3 -m unittest` — an entry nothing measures with would be exactly the "claim ABOUT
+ * evidence" this list refuses. The list stays CLOSED: a measurer in any other language meets the
+ * same wall and needs the same deliberate entry. That is the price of the boundary, not a defect.
+ *
+ * THE BOUNDARY IS `(?![\w-])`, NOT `\b`, and that turned out to matter far beyond python
+ * (cross-family review r1, HIGH). `\b` treats a hyphen as a word boundary, so every backticked
+ * FILE NAME that begins with a listed command counted as a reproducer. MEASURED 2026-09-19:
+ * `pnpm-lock.yaml`, `dz-harness-hub`, `git-workflow` and `npm-shrinkwrap.json` all passed as
+ * evidence for a MEASURED claim, while `node_modules` was correctly refused — only because `_` is
+ * a word character and `-` is not. The repository holds hundreds of such tokens, so the check has
+ * been accepting file names as measurements for as long as the list has existed.
+ *
+ * WHAT THIS CHECK DOES NOT DO, said plainly because the previous wording implied more: it verifies
+ * the SHAPE of a citation, never that a measurement happened. `git --version` in backticks is
+ * accepted by construction — validating arguments per binary is a different mechanism with a
+ * different cost, and pretending otherwise would be the very laundering this file exists to stop.
  */
 const SHELL_REPRO_RE =
-  /`\s*\$?\s*(?:ps|stat|lsof|time|git|npm|npx|node|pnpm|yarn|dz|curl|wc|grep|find|cargo|make|docker|kubectl|awk|sed|du|df|vitest|pytest)\b[^`]*`/i;
+  /`\s*\$?\s*(?:ps|stat|lsof|time|git|npm|npx|node|pnpm|yarn|dz|curl|wc|grep|find|cargo|make|docker|kubectl|awk|sed|du|df|vitest|pytest|python3)(?![\w-])[^`]*`/i;
 
 /** Reproducer references that count as evidence backing a MEASURED claim. */
 const REPRODUCER_HINTS = [

package/src/cross-family-control.ts

@@ -579,10 +579,47 @@ export function buildControlRow(input: BuildControlRowInput): BuildControlRowRes
   };
 }
 
+/**
+ * experiment-instrument FR-4/A6 (ADR-001): a `stage:'control'` row `dz control-review` writes when
+ * the run REFUSED before producing a diff — the failure-leaves-a-row half of the ADR's safety
+ * property. Distinguished from {@link ControlLedgerRow} by `outcome:'refused'`, which a successful
+ * row never carries; the two schemas share nothing else structurally on purpose — a refused run has
+ * no diff, no tree hashes, no grades to validate.
+ */
+export interface ControlRefusedRow {
+  readonly slug: string;
+  readonly stage: 'control';
+  readonly outcome: 'refused';
+  /** Which half was responsible: the claude review, the codex review, or neither (a setup/tree/
+   *  aggregation failure that belongs to neither half specifically). */
+  readonly half: 'claude' | 'codex' | 'setup';
+  readonly reason: string;
+  readonly runId: string;
+  /** Known only when the coder family was determined before the refusal — absent for the earliest
+   *  failures (the claude half itself failing before it can report which family it reviewed). When
+   *  present, the SAME `bucket(coderFamily, reviewerOfInterest)` a successful control row uses. */
+  readonly coderFamily?: 'codex' | 'claude';
+  readonly minutes: number | null;
+}
+
+function isValidControlRefusedRow(obj: Record<string, unknown>): boolean {
+  if (typeof obj['slug'] !== 'string' || obj['slug'].trim() === '') return false;
+  if (typeof obj['runId'] !== 'string' || obj['runId'].trim() === '') return false;
+  if (obj['half'] !== 'claude' && obj['half'] !== 'codex' && obj['half'] !== 'setup') return false;
+  if (typeof obj['reason'] !== 'string' || obj['reason'].trim() === '') return false;
+  if (!(obj['minutes'] === null || (typeof obj['minutes'] === 'number' && Number.isFinite(obj['minutes'])))) return false;
+  if (obj['coderFamily'] !== undefined && obj['coderFamily'] !== 'codex' && obj['coderFamily'] !== 'claude') return false;
+  return true;
+}
+
 /* ── D5: reading the ledger back (FR-7; A8) ──────────────────────────────────────────────────── */
 
 export interface ParsedControlRows {
   readonly rows: readonly ControlLedgerRow[];
+  /** experiment-instrument FR-4/A6: `stage:'control'` rows with `outcome:'refused'` — a run that
+   *  never produced a diff. Schema-validated (`isValidControlRefusedRow`) the same way `rows` is;
+   *  one that fails validation is `unreadable`, same as a malformed successful row. */
+  readonly refusedRows: readonly ControlRefusedRow[];
   readonly roundRows: readonly Record<string, unknown>[];
   readonly fullRows: readonly Record<string, unknown>[];
   /** A8: a line that is not parseable JSON, or parses to something that is not a plain object, or
@@ -678,6 +715,7 @@ function isValidControlRow(obj: Record<string, unknown>): boolean {
  */
 export function parseControlRows(lines: readonly string[]): ParsedControlRows {
   const rows: ControlLedgerRow[] = [];
+  const refusedRows: ControlRefusedRow[] = [];
   const roundRows: Record<string, unknown>[] = [];
   const fullRows: Record<string, unknown>[] = [];
   let unreadable = 0;
@@ -698,6 +736,17 @@ export function parseControlRows(lines: readonly string[]): ParsedControlRows {
     const obj = parsed as Record<string, unknown>;
     const stage = obj['stage'];
     if (stage === 'control') {
+      // experiment-instrument FR-4/A6: `outcome:'refused'` is a DIFFERENT schema from a successful
+      // control row — checked FIRST, so a refused row is never mistaken for a malformed successful
+      // one (which would count it `unreadable`, losing exactly the receipt this feature adds).
+      if (obj['outcome'] === 'refused') {
+        if (!isValidControlRefusedRow(obj)) {
+          unreadable++;
+          continue;
+        }
+        refusedRows.push(obj as unknown as ControlRefusedRow);
+        continue;
+      }
       if (!isValidControlRow(obj)) {
         unreadable++;
         continue;
@@ -711,7 +760,7 @@ export function parseControlRows(lines: readonly string[]): ParsedControlRows {
     // Every other stage (plan/impl/fix/loop-run/round-exec/…) and the header/comment row (no
     // string `stage`) are readable, just not addressed by this module.
   }
-  return { rows, roundRows, fullRows, unreadable };
+  return { rows, refusedRows, roundRows, fullRows, unreadable };
 }
 
 /* ── D6: the per-family-pair aggregate (FR-7; A6, A8) ────────────────────────────────────────── */
@@ -769,6 +818,10 @@ export interface FamilyPairAggregate {
   readonly refutedShare: { readonly n: number; readonly value: number | 'unknown' };
   readonly costPerConfirmed: { readonly n: number; readonly value: number | 'unknown' };
   readonly draftToShipped: ReadonlyArray<{ readonly slug: string; readonly first: string; readonly final: string; readonly finals: number }>;
+  /** experiment-instrument FR-4/A6: `stage:'control'` rows refused for THIS pair (attributed by a
+   *  known `coderFamily` on the refused row) — a real cost line (the run was attempted and failed),
+   *  never counted in `n` (which measures completed reviews). */
+  readonly refusedRuns: number;
 }
 
 export interface FamilyAggregate {
@@ -781,6 +834,11 @@ export interface FamilyAggregate {
   /** A6: the raw count of `stage:'control'` rows folded in — `0` means every `foreignUnique`
    *  figure below is a true, honestly-printed absence, not a fabricated non-observation. */
   readonly controlRows: number;
+  /** experiment-instrument FR-4/A6: EVERY `stage:'control'` refused row seen, attributed or not —
+   *  the total accounting figure `refusedRuns` (per pair) can never exceed, and the gap between the
+   *  sum of per-pair `refusedRuns` and this total is exactly how many refusals had no determinable
+   *  coderFamily (the earliest failures — printed here rather than silently dropped). */
+  readonly refusedControlRows: number;
 }
 
 interface MutablePair {
@@ -801,13 +859,14 @@ interface MutablePair {
   costN: number;
   costSum: number;
   drafts: Array<{ slug: string; first: string; final: string; finals: number }>;
+  refusedRuns: number;
 }
 
 function newPair(): MutablePair {
   return {
     n: 0, grades: {}, shipped: 0, shippedTotal: 0, fixRoundsList: [],
     foreignN: 0, foreignBySeverity: {}, foreignAuto: 0, foreignAdjudicated: 0, foreignAutoRuns: 0, foreignAdjudicatedRuns: 0, foreignIncomplete: 0,
-    refutedN: 0, refutedSum: 0, costN: 0, costSum: 0, drafts: [],
+    refutedN: 0, refutedSum: 0, costN: 0, costSum: 0, drafts: [], refusedRuns: 0,
   };
 }
 
@@ -886,6 +945,18 @@ export function aggregateByFamily(
     else { b.foreignAutoRuns++; b.foreignAuto += foreignTotal; }
   }
 
+  // experiment-instrument FR-4/A6: a refused row is bucketed the SAME way a successful control row
+  // is — by its own coderFamily and the complementary reviewer — but ONLY when coderFamily is known
+  // (the earliest failures, before the claude half reports which family it reviewed, cannot be
+  // attributed to a pair; they still count toward `refusedControlRows` at the top level below,
+  // never silently dropped). `n` is deliberately untouched: `n` measures COMPLETED reviews.
+  for (const rr of parsed.refusedRows) {
+    if (rr.coderFamily === undefined) continue;
+    const reviewerOfInterest = rr.coderFamily === 'codex' ? 'claude' : 'codex';
+    const b = bucket(rr.coderFamily, reviewerOfInterest);
+    b.refusedRuns++;
+  }
+
   // draftToShipped: earliest known verdict per slug (a qe-bridge signoff, or this control row's
   // own claude-half grade when no signoff was given) against the slug's final grade — keyed by
   // slug PLUS the normalized (coder,reviewer) family pair (r1-14: two final rows for the same slug
@@ -952,9 +1023,16 @@ export function aggregateByFamily(
       refutedShare: { n: b.refutedN, value: b.refutedN > 0 ? b.refutedSum / b.refutedN : 'unknown' },
       costPerConfirmed: { n: b.costN, value: b.costN > 0 ? b.costSum / b.costN : 'unknown' },
       draftToShipped: b.drafts,
+      refusedRuns: b.refusedRuns,
     };
   }
 
   const incompleteControlRows = parsed.rows.filter((r) => !r.complete).length;
-  return { pairs: out, incomplete: parsed.unreadable > 0 || incompleteControlRows > 0, incompleteControlRows, controlRows: parsed.rows.length };
+  return {
+    pairs: out,
+    incomplete: parsed.unreadable > 0 || incompleteControlRows > 0,
+    incompleteControlRows,
+    controlRows: parsed.rows.length,
+    refusedControlRows: parsed.refusedRows.length,
+  };
 }

package/src/experiment-assign.ts

@@ -0,0 +1,276 @@
+/**
+ * Deterministic, blocked arm assignment for a prospective ablation (ADR-001, ablation-c-start).
+ *
+ * WHY. The owner's question — does the Step-8 QE mode change task speed — is only answerable
+ * causally if the variant a task receives is decided by chance, BEFORE the work starts, and tied to
+ * the task's own identity so a repeated query for the same task never reassigns it. This module is
+ * that decision: a PURE function of `(experiment, stratum, seed, index)`. No filesystem, no clock,
+ * no network — the caller (the cli) owns the journal, the lock, and the "did work already start?"
+ * check; this module only computes.
+ *
+ * ALGORITHM — block randomization, one pair per arm-combination per block. `mulberry32` is the
+ * repo's ONLY pseudo-random generator (`compounding.ts` — "no second RNG in this repo"); reused
+ * here rather than adding a second stream. Block size is `arms.length * 2` — two occurrences of
+ * every arm per block, so a completed block is always perfectly balanced and `propensity` (the
+ * arm's actual share of its block) is a fixed `1 / arms.length` — never guessed, never assumed
+ * 0.5 by default (NFR-4). The block's own permutation is seeded from
+ * `fnv1a(JSON.stringify([experiment, stratum, seed, block]))` (a JSON-tuple, not a delimiter join —
+ * the same reason `workOrderDigestInput` in epoch-replay.ts uses tuples: a delimiter in `experiment`
+ * or `stratum` could otherwise make two different keys hash identically) — so different strata (and
+ * different experiments) never share a stream, and the SAME `(experiment, stratum, seed, index)`
+ * always rederives the SAME arm (A1 idempotency, A2 block balance, A3 propensity).
+ */
+
+import { fnv1a } from './feature-adr-checkpoints.js';
+import { mulberry32 } from './compounding.js';
+
+export interface AssignArmInput {
+  readonly experiment: string;
+  readonly stratum: string;
+  /** Pre-registered seed — fixed once, before any assignment is made. */
+  readonly seed: number;
+  /** 0-based ordinal of this task within its `(experiment, stratum)` sequence. */
+  readonly index: number;
+  /** The arms on offer, e.g. `['direct', 'reference']`. At least 2, all non-empty, all unique. */
+  readonly arms: readonly string[];
+}
+
+export type AssignArmResult =
+  | { readonly ok: true; readonly arm: string; readonly propensity: number; readonly block: number; readonly position: number }
+  | { readonly ok: false; readonly reason: string };
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim() !== '';
+}
+
+/** Fisher-Yates, driven by the given deterministic RNG. Does not mutate its input. */
+function shuffle<T>(items: readonly T[], rand: () => number): T[] {
+  const out = items.slice();
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1));
+    const tmp = out[i]!;
+    out[i] = out[j]!;
+    out[j] = tmp;
+  }
+  return out;
+}
+
+/**
+ * Deterministically assign one arm to task ordinal `index` within `(experiment, stratum)`. Refuses
+ * (never throws, never guesses) on any malformed input — empty strings, a non-integer seed/index, a
+ * negative index, fewer than two arms, duplicate or blank arm names.
+ */
+export function assignArm(input: AssignArmInput): AssignArmResult {
+  if (!isNonEmptyString(input?.experiment)) return { ok: false, reason: 'experiment: expected a non-empty string' };
+  if (!isNonEmptyString(input?.stratum)) return { ok: false, reason: 'stratum: expected a non-empty string' };
+  if (!Number.isInteger(input?.seed) || input.seed < 0) return { ok: false, reason: 'seed: expected a non-negative integer' };
+  if (!Number.isInteger(input?.index) || input.index < 0) return { ok: false, reason: 'index: expected a non-negative integer' };
+  if (!Array.isArray(input?.arms) || input.arms.length < 2) {
+    return { ok: false, reason: 'arms: expected an array of at least 2 arm names' };
+  }
+  if (!input.arms.every(isNonEmptyString)) return { ok: false, reason: 'arms: every arm name must be a non-empty string' };
+  const seen = new Set<string>();
+  for (const a of input.arms) {
+    if (seen.has(a)) return { ok: false, reason: `arms: duplicate arm name ${JSON.stringify(a)}` };
+    seen.add(a);
+  }
+
+  const blockSize = input.arms.length * 2; // two copies of every arm — always a perfect block
+  const block = Math.floor(input.index / input.arms.length / 2); // == Math.floor(index / blockSize)
+  const position = input.index % blockSize;
+
+  const key = JSON.stringify({ experiment: input.experiment, stratum: input.stratum, seed: input.seed, block });
+  const rand = mulberry32(parseInt(fnv1a(key), 16) >>> 0);
+  // Base card set for this block: every arm twice, in the input's own order — then permuted by the
+  // block-seeded stream, so the CONTENT of every block is fixed by construction (perfect balance)
+  // and only the ORDER is randomized.
+  const cards: string[] = [];
+  for (const a of input.arms) { cards.push(a); cards.push(a); }
+  const permuted = shuffle(cards, rand);
+  const arm = permuted[position]!;
+  const propensity = 2 / blockSize; // == 1 / arms.length — the arm's fixed, actual share of its block
+
+  return { ok: true, arm, propensity, block, position };
+}
+
+export interface AssignmentRecord {
+  readonly ts: string;
+  readonly experiment: string;
+  readonly taskId: string;
+  readonly stratum: string;
+  readonly seed: number;
+  readonly index: number;
+  readonly block: number;
+  readonly position: number;
+  readonly arm: string;
+  readonly propensity: number;
+  readonly assignedAt: string;
+}
+
+export interface ReadAssignmentsResult {
+  readonly records: readonly AssignmentRecord[];
+  /** Non-blank lines that did not parse as a valid assignment record. Never silently dropped: a
+   * caller checking "is this task assigned?" must be able to tell "no" from "the journal is
+   * unreadable here" (A5). */
+  readonly malformedLines: number;
+}
+
+/** fix-round-1 (Codex r1 HIGH #7): `new Date().toISOString()` is the ONLY producer of `ts`/
+ * `assignedAt` (see the cli's `experimentJournalPath` writer) — a record whose timestamp does not
+ * match that exact shape did not come from this code path, so it is corruption, not merely an
+ * unusual value. */
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isValidIsoTimestamp(v: unknown): v is string {
+  // Lead delta after Codex r2 (MEDIUM): shape + `Date.parse` accepts impossible calendar dates —
+  // `2026-02-30T00:00:00.000Z` parses (it rolls into March) and passed. Round-tripping through
+  // `toISOString()` is the exact check: only a real instant re-serializes to the same string.
+  if (typeof v !== 'string' || !ISO_TIMESTAMP_RE.test(v)) return false;
+  const ms = Date.parse(v);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === v;
+}
+
+/**
+ * PURELY STRUCTURAL: every field is present and the right TYPE. This is `readAssignments`'s gate —
+ * it decides whether a journal LINE parses at all (A5's `malformedLines`). It deliberately does NOT
+ * validate timestamp FORMAT, propensity RANGE, or arm MEMBERSHIP: a line that is well-typed but
+ * semantically wrong (a hand-edited `position:99`, `propensity:2`, a flipped `arm`) is exactly the
+ * "syntactically valid corruption" `verifyAssignmentRecord` below exists to catch — folding those
+ * checks in here would make a single semantically-tampered record poison `readAssignments` for
+ * every caller, including ones (like `status`'s per-task duration math) that need to name WHICH
+ * task is bad rather than refuse the whole read (fix-round-1 HIGH #7/#8 — see `verifyAssignmentRecord`).
+ */
+function isValidAssignmentRecord(v: unknown): v is AssignmentRecord {
+  if (typeof v !== 'object' || v === null) return false;
+  const r = v as Record<string, unknown>;
+  return (
+    isNonEmptyString(r['ts']) &&
+    isNonEmptyString(r['experiment']) &&
+    isNonEmptyString(r['taskId']) &&
+    isNonEmptyString(r['stratum']) &&
+    Number.isInteger(r['seed']) && (r['seed'] as number) >= 0 &&
+    Number.isInteger(r['index']) && (r['index'] as number) >= 0 &&
+    Number.isInteger(r['block']) && (r['block'] as number) >= 0 &&
+    Number.isInteger(r['position']) && (r['position'] as number) >= 0 &&
+    isNonEmptyString(r['arm']) &&
+    typeof r['propensity'] === 'number' && Number.isFinite(r['propensity'] as number) &&
+    isNonEmptyString(r['assignedAt'])
+  );
+}
+
+export type VerifyAssignmentResult =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly reason: string;
+      /** Lead delta after Codex r2: `null` when the record failed on its SEED — there is nothing to
+       *  expect, because the tuple it would be derived from is itself the thing under suspicion. */
+      readonly expected: { readonly arm: string; readonly block: number; readonly position: number; readonly propensity: number } | null;
+      readonly actual: { readonly arm: string; readonly block: number; readonly position: number; readonly propensity: number };
+    };
+
+/**
+ * fix-round-1 (Codex r1 HIGH #7) — "syntactically valid journal corruption is accepted and returned
+ * as the task's assignment". A record that passes `isValidAssignmentRecord`'s SHAPE checks can still
+ * have been hand-edited to a different arm/block/position/propensity while keeping every field the
+ * right TYPE (e.g. flipping `arm:"direct"` to `arm:"reference"`, or `position:99`). The only way to
+ * catch that is to REDERIVE the assignment from the record's own tuple
+ * `(experiment, stratum, seed, index)` via the SAME pure `assignArm` that produced it, and compare —
+ * never trust the stored arm/block/position/propensity on their own. `arms` is the experiment's own
+ * registered arm set (from its `dz experiment init` config), passed in by the caller — this module
+ * stays pure and fs-free.
+ */
+export function verifyAssignmentRecord(record: AssignmentRecord, arms: readonly string[], pinnedSeed?: number): VerifyAssignmentResult {
+  // Lead delta after Codex r2 (BLOCKER): rederiving from `record.seed` proves the record is
+  // internally CONSISTENT, never that it is AUTHENTIC — a row carrying any seed at all passes,
+  // because the check compares the row with itself. The experiment's pinned seed (from its
+  // `dz experiment init` config, the one value fixed before the first assignment) is the trusted
+  // side of the comparison; a row that disagrees with it is tampered, however well-formed.
+  if (pinnedSeed !== undefined && record.seed !== pinnedSeed) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)} carries seed ${record.seed}, but experiment ${JSON.stringify(record.experiment)} is pinned to seed ${pinnedSeed} — a record's own seed can never authenticate it`,
+      expected: null,
+      actual: { arm: record.arm, block: record.block, position: record.position, propensity: record.propensity },
+    };
+  }
+  const recomputed = assignArm({ experiment: record.experiment, stratum: record.stratum, seed: record.seed, index: record.index, arms });
+  const actual = { arm: record.arm, block: record.block, position: record.position, propensity: record.propensity };
+  const expected = recomputed.ok
+    ? { arm: recomputed.arm, block: recomputed.block, position: recomputed.position, propensity: recomputed.propensity }
+    : { arm: '(tuple refused)', block: -1, position: -1, propensity: -1 };
+
+  if (!recomputed.ok) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s stored tuple (experiment=${JSON.stringify(record.experiment)}, stratum=${JSON.stringify(record.stratum)}, seed=${record.seed}, index=${record.index}) no longer rederives a valid assignment (${recomputed.reason}) — the stored record does not match what assignArm would produce from its own tuple`,
+      expected,
+      actual,
+    };
+  }
+  if (expected.arm !== actual.arm || expected.block !== actual.block || expected.position !== actual.position || expected.propensity !== actual.propensity) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s stored assignment does not match what assignArm rederives from its own tuple (experiment=${JSON.stringify(record.experiment)}, stratum=${JSON.stringify(record.stratum)}, seed=${record.seed}, index=${record.index}) — the journal line was modified after it was written`,
+      expected,
+      actual,
+    };
+  }
+  // fix-round-1 HIGH #7 (named explicitly in the brief, beyond what recompute-and-compare already
+  // implies): timestamp FORMAT, propensity RANGE, and arm MEMBERSHIP. Recompute already makes a
+  // WRONG arm/propensity/block/position fail above; these three checks catch what recompute cannot
+  // — `assignArm` never produces a `ts`/`assignedAt` at all (they are wall-clock, not derived from
+  // the tuple), so a hand-edited "not-a-date" needs its own check.
+  if (!isValidIsoTimestamp(record.ts) || !isValidIsoTimestamp(record.assignedAt)) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s ts/assignedAt is not a valid ISO-8601 UTC timestamp (ts=${JSON.stringify(record.ts)}, assignedAt=${JSON.stringify(record.assignedAt)})`,
+      expected,
+      actual,
+    };
+  }
+  if (!(record.propensity >= 0 && record.propensity <= 1)) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s propensity ${record.propensity} is outside the valid [0,1] range`,
+      expected,
+      actual,
+    };
+  }
+  if (!arms.includes(record.arm)) {
+    return {
+      ok: false,
+      reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s arm ${JSON.stringify(record.arm)} is not one of this experiment's registered arms (${arms.join(', ')})`,
+      expected,
+      actual,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Parse a JSONL assignments journal (one record per line) into records, WITHOUT touching the
+ * filesystem — the caller reads the file, this only parses its text (NFR-1: the core stays
+ * `node:fs`-free). A line that is blank is skipped silently (append-only files end in a trailing
+ * newline); a line that is non-blank but does not parse as JSON, or parses to something missing a
+ * required field, counts toward `malformedLines` and is otherwise ignored — corruption is named, not
+ * folded into "not assigned" (A5).
+ */
+export function readAssignments(text: string): ReadAssignmentsResult {
+  const records: AssignmentRecord[] = [];
+  let malformedLines = 0;
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.trim();
+    if (line === '') continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      malformedLines++;
+      continue;
+    }
+    if (isValidAssignmentRecord(parsed)) records.push(parsed);
+    else malformedLines++;
+  }
+  return { records, malformedLines };
+}