@dzhechkov/harness-core 0.3.142 → 0.3.144

package/dist/epoch-replay.js

@@ -0,0 +1,695 @@
+/**
+ * `dz epoch-replay` — the executable cold-vs-warm EPOCH RUNNER (feature epoch-replay, scout idea #4).
+ *
+ * `dz compounding` answers READINESS ("N unique prompt events recorded — a replay can now be RUN").
+ * This module answers the RESULT: Epoch-0 (cold, no injected lessons) vs Epoch-1 (warm, the SAME
+ * instances plus exactly the lessons the apply leg injected), scored into a three-valued verdict
+ * whose positive branch requires two DISJOINT Wilson confidence intervals.
+ *
+ * ── The honesty boundary (ADR-002) ─────────────────────────────────────────────────────────────
+ * This runner ORCHESTRATES and SCORES. It NEVER calls a model. Real mode is a three-stage protocol
+ * over files:
+ *   1. `buildWorkOrder`   — emits the instances + per-arm generation instructions + the
+ *                           PRE-REGISTERED blind A/B assignment (seeded, decided before any plan
+ *                           text exists) + an integrity `digest` over that pre-registered core.
+ *   2. `buildJudgePrompts`— renders the blind judge prompts from the filled plans. The judge-facing
+ *                           payload is `{id, prompt}` and NOTHING else.
+ *   3. `verifyWorkOrder` + `unblindJudgments` + `scoreEpochReplay` — check the order really is the
+ *                           pre-registered one (digest + seed-derived assignment), un-blind against
+ *                           it (never against a field the judge wrote), and compute the verdict.
+ * Every stage is pure and deterministic, so the protocol is testable with zero LLM dependency.
+ *
+ * ── What "blind" has to mean ───────────────────────────────────────────────────────────────────
+ * The first version shipped `warmIsA` INSIDE the judge artifact: the judge could read the answer
+ * key, so the blinding was theatre (Codex QE CRITICAL-1). `warmIsA` now exists only in the work
+ * order, which `--score` consumes and the judge never sees — and the artifact is byte-identical
+ * whichever way the assignment fell.
+ *
+ * ── The conformance firewall ───────────────────────────────────────────────────────────────────
+ * The warm arm's only delta is the lessons the apply leg ALREADY injects for that prompt. Gold
+ * answers, judge verdicts, and outcome labels never enter the warm context — feedback flows from
+ * SOLVE OUTCOMES ONLY. `buildWorkOrder` therefore reads instances, not results, and there is no
+ * code path from an `EpochOutcome` back into a work order.
+ *
+ * ── `--mock` ───────────────────────────────────────────────────────────────────────────────────
+ * A seeded synthetic outcome generator (reusing `mulberry32` — no second RNG in this repo) with a
+ * configurable TRUE effect, so the verdict math is exercised at $0 before any real data exists.
+ *
+ * Everything here is PURE: callers read/write files; this module only computes.
+ */
+// One-way dependency: epoch-replay → compounding. `mulberry32` (the repo's only PRNG), the darwin
+// min-n and the single `replayableInstances` definition all live there; importing them keeps this
+// module free of a second RNG and of a second definition of "a replayable pair".
+import { createHash } from 'node:crypto';
+import { mulberry32, MIN_SAMPLES_PER_ARM, replayableInstances, } from './compounding.js';
+export { replayableInstances };
+// ── Wilson score interval (ADR-003) ────────────────────────────────────────────────────────────
+/** 95% two-sided normal quantile. Named so a future 90%/99% run is a parameter, not a fork. */
+export const WILSON_Z = 1.96;
+/** Per-arm minimum. Shared with the darwin FDR discipline already pinned in compounding.ts. */
+export const MIN_INSTANCES = MIN_SAMPLES_PER_ARM;
+/**
+ * Floor of DECISIVE pairs for the no-lift branch. Necessary, NOT sufficient: reaching it only makes
+ * the non-superiority test eligible — the test itself must still pass (see {@link NO_LIFT_MARGIN}).
+ *
+ * The first draft FALSIFIED on `warmWins <= coldWins` at this n, which made 6/12 vs 6/12 read as
+ * "refuted". That is indefensible: a tie at n=12 is UNDER-POWERED, not evidence of no effect
+ * (Codex QE HIGH-3).
+ */
+export const FALSIFY_NO_LIFT_MIN_N = 2 * MIN_SAMPLES_PER_ARM;
+/**
+ * Pre-registered NON-SUPERIORITY margin, on the LIFT scale (see {@link liftInterval}). "No lift" is
+ * claimed only when the UPPER bound of the lift interval sits below this — i.e. the data EXCLUDE
+ * any lift worth having, rather than merely failing to show one.
+ *
+ * Consequence, stated plainly: at this margin the branch needs ~1200 decisive pairs. That is the
+ * honest price of an equivalence-style claim, and it is exactly why a 6/6 tie at n=12 is
+ * INCONCLUSIVE rather than FALSIFIED.
+ */
+export const NO_LIFT_MARGIN = 0.05;
+/** A margin outside this range is REFUSED, never clamped: `--margin 99` must not buy FALSIFIED. */
+export const MARGIN_MIN_EXCLUSIVE = 0;
+export const MARGIN_MAX = 0.5;
+/** True for a margin that may be pre-registered — finite and in `(0, 0.5]`. */
+export function isValidMargin(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > MARGIN_MIN_EXCLUSIVE && value <= MARGIN_MAX;
+}
+/**
+ * Wilson score interval for a binomial proportion. Returns `null` — never a fabricated interval —
+ * for any input that is not a real (k, n) pair: n <= 0, non-integers, k out of [0, n], non-finite
+ * numbers, or a non-finite/non-positive z. A `null` interval can only ever produce INCONCLUSIVE.
+ */
+export function wilsonInterval(k, n, z = WILSON_Z) {
+    if (!Number.isFinite(k) || !Number.isFinite(n) || !Number.isFinite(z))
+        return null;
+    if (!Number.isInteger(k) || !Number.isInteger(n))
+        return null;
+    if (n <= 0 || k < 0 || k > n)
+        return null;
+    if (z <= 0)
+        return null;
+    const p = k / n;
+    const z2 = z * z;
+    const denom = 1 + z2 / n;
+    const centre = (p + z2 / (2 * n)) / denom;
+    const half = (z / denom) * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    if (!Number.isFinite(centre) || !Number.isFinite(half))
+        return null;
+    return {
+        k,
+        n,
+        p,
+        lower: Math.max(0, Math.min(1, centre - half)),
+        upper: Math.max(0, Math.min(1, centre + half)),
+        z,
+    };
+}
+/**
+ * Map the Wilson interval for `p̂ = P(warm wins | decisive)` onto the LIFT scale, `2p − 1`.
+ *
+ * WHY THE SCALE MATTERS (and why it is not cosmetic): `margin` is stated as "a lift worth having",
+ * which is what a reader reasons about, and it kept exactly the meaning it had under the previous
+ * (wrong) two-proportion model. On the raw `p̂` scale the equivalent threshold is `0.5 + margin/2`,
+ * NOT `0.5 + margin` — reading the margin on the `p̂` scale would silently DOUBLE the strictness of
+ * the non-superiority branch, i.e. make FALSIFIED easier. That is the anti-conservative direction,
+ * which is precisely the class of error the paired rewrite exists to remove.
+ *
+ * Worked check (the case that drove the rewrite): 500 warm / 500 cold over 1000 decisive pairs gives
+ * `p̂` CI `[0.4691, 0.5309]` → lift CI `[-0.0619, +0.0619]`. Upper `0.0619` exceeds the default
+ * margin `0.05`, so it reads INCONCLUSIVE. The discarded two-proportion Newcombe interval put the
+ * upper bound at `0.0437` and called the same data FALSIFIED.
+ */
+export function liftInterval(pWarm) {
+    if (pWarm === null)
+        return null;
+    const d = 2 * pWarm.p - 1;
+    const lower = 2 * pWarm.lower - 1;
+    const upper = 2 * pWarm.upper - 1;
+    if (!Number.isFinite(d) || !Number.isFinite(lower) || !Number.isFinite(upper))
+        return null;
+    return { d, lower, upper };
+}
+// ── Stage 1: the work order (ADR-002) ──────────────────────────────────────────────────────────
+export const WORK_ORDER_KIND = 'dz-epoch-replay-work-order';
+/**
+ * v3: the integrity `digest` (v2) plus the PRE-REGISTERED `margin` and `corpusFingerprint`, and an
+ * unambiguous JSON digest input. An older order cannot be verified under these rules, so it is
+ * refused rather than half-trusted.
+ */
+export const WORK_ORDER_VERSION = 3;
+function clampInt(value, fallback, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function clampNumber(value, fallback, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, value));
+}
+export const DEFAULT_WORD_MIN = 80;
+export const DEFAULT_WORD_MAX = 150;
+/**
+ * The digest input is the PRE-REGISTERED core and nothing else: version, seed, margin, the corpus
+ * fingerprint, and every `[id, warmIsA]` pair in order. Deliberately EXCLUDED are the fields the
+ * protocol requires a human to fill after emit — `coldPlan`, `warmPlan` and `class` — so filling
+ * them keeps the order verifiable. (Limitation stated in ADR-002: `class` is NOT covered.)
+ *
+ * Serialization is `JSON.stringify` over an array of TUPLES, not a delimiter-joined string. The
+ * first version used `${id}:${flag}` joined by `,`, so an id containing `:` or `,` could make two
+ * DIFFERENT orders hash identically — e.g. `[['a:1,b', false]]` and `[['a', true], ['b', false]]`
+ * both flattened to `a:1,b:0` (Codex QE MED-D). JSON escaping removes the ambiguity.
+ */
+function workOrderDigestInput(core) {
+    return JSON.stringify({
+        v: core.version,
+        seed: core.seed,
+        margin: core.margin,
+        corpus: core.corpusFingerprint,
+        items: core.items.map((i) => [i.id, i.warmIsA]),
+    });
+}
+/** sha256 over the ordered instance identity — lets a reviewer see two orders share a corpus. */
+export function corpusFingerprint(instances) {
+    return createHash('sha256')
+        .update(JSON.stringify(instances.map((i) => [i.id, i.query])))
+        .digest('hex');
+}
+/**
+ * sha256 over {@link workOrderDigestInput}. Pure computation — no IO, no key material.
+ *
+ * HONEST SCOPE — read this before describing what it proves. This is an integrity check against
+ * ACCIDENTAL corruption and mismatch; it is NOT a cryptographic commitment. The digest is
+ * self-contained, so a determined operator can re-forge it (at n=12 a seed search finds a matching
+ * assignment in a few thousand tries). The threat model is US making mistakes — a hand-edited file,
+ * a stale order paired with fresh judgments — exactly the corruption-detection scoping the
+ * hash-chain backlog idea already carries. The honest-use contract is procedural: emit once, then
+ * judge, and keep the emitted file.
+ */
+export function workOrderDigest(order) {
+    return createHash('sha256')
+        .update(workOrderDigestInput({
+        version: order.version,
+        seed: order.seed,
+        margin: order.margin,
+        corpusFingerprint: order.corpusFingerprint,
+        items: order.items,
+    }))
+        .digest('hex');
+}
+/**
+ * The one sentence that states what the digest is and is not. Held in a constant so the CLI error
+ * text, the module documentation and the honest-scope regression test all read the SAME words —
+ * this promise must not quietly regrow into "commitment" language (Codex QE HIGH-C).
+ */
+export const DIGEST_HONEST_SCOPE = 'integrity check against accidental corruption/mismatch — not a cryptographic commitment; ' +
+    'a determined operator can re-forge it, and the honest-use contract is emit-once-then-judge';
+/**
+ * Integrity-check a work order before ANY verdict may depend on it (Codex QE HIGH-2).
+ *
+ * Checking `kind` and `Array.isArray(items)` was vacuous: a hand-written file with the right two
+ * fields and an invented `warmIsA` un-blinded into whatever verdict its author wanted. Four checks
+ * now have to agree:
+ *   1. the `digest` recomputes over (version, seed, margin, corpus fingerprint, `[id, warmIsA]`…);
+ *   2. every `warmIsA` is REDERIVABLE from the stated `seed` — the same `mulberry32` stream that
+ *      emitted it;
+ *   3. the pre-registered `margin` is in range;
+ *   4. structural sanity — unique non-empty ids, boolean assignments, integer seed.
+ *
+ * WHAT THIS IS NOT: see {@link DIGEST_HONEST_SCOPE}. Re-deriving from the seed raises the bar from
+ * "edit one field" to "search for a seed", which at n=12 is a few thousand tries — a deterrent
+ * against slips, not a defence against intent. Nothing here is a cryptographic commitment, and no
+ * amount of hashing inside the file itself could make it one.
+ */
+export function verifyWorkOrder(value) {
+    const problems = [];
+    if (typeof value !== 'object' || value === null)
+        return { ok: false, problems: ['not an object'] };
+    const o = value;
+    if (o.kind !== WORK_ORDER_KIND)
+        problems.push(`kind is not ${WORK_ORDER_KIND}`);
+    if (o.version !== WORK_ORDER_VERSION)
+        problems.push(`version is not ${WORK_ORDER_VERSION} (older orders cannot be verified under these rules)`);
+    if (!Number.isInteger(o.seed) || o.seed < 0)
+        problems.push('seed is not a non-negative integer');
+    if (!isValidMargin(o.margin)) {
+        problems.push(`pre-registered margin ${JSON.stringify(o.margin)} is not a number in (0, ${MARGIN_MAX}]`);
+    }
+    if (typeof o.corpusFingerprint !== 'string' || o.corpusFingerprint === '')
+        problems.push('missing corpusFingerprint');
+    if (!Array.isArray(o.items)) {
+        problems.push('items is not an array');
+        return { ok: false, problems };
+    }
+    const items = o.items;
+    const seen = new Set();
+    const core = [];
+    for (let i = 0; i < items.length; i++) {
+        const it = (typeof items[i] === 'object' && items[i] !== null ? items[i] : {});
+        const id = typeof it.id === 'string' ? it.id : '';
+        if (id.trim() === '')
+            problems.push(`item ${i}: missing id`);
+        else if (seen.has(id))
+            problems.push(`item ${i}: duplicate id ${JSON.stringify(id)}`);
+        seen.add(id);
+        if (typeof it.warmIsA !== 'boolean')
+            problems.push(`item ${i}: warmIsA is not a boolean`);
+        core.push({ id, warmIsA: it.warmIsA === true });
+    }
+    if (problems.length > 0)
+        return { ok: false, problems };
+    const expected = workOrderDigest({
+        seed: o.seed,
+        version: o.version,
+        margin: o.margin,
+        corpusFingerprint: o.corpusFingerprint,
+        items: core,
+    });
+    if (typeof o.digest !== 'string' || o.digest !== expected) {
+        problems.push(`digest mismatch — the pre-registered core (seed / margin / corpus / ids / assignments) was altered after emit. ` +
+            `NOTE: ${DIGEST_HONEST_SCOPE}`);
+    }
+    // Re-derive the assignment from the stated seed: the same one call per item, in item order.
+    const rand = mulberry32(o.seed);
+    for (let i = 0; i < core.length; i++) {
+        const derived = rand() < 0.5;
+        if (derived !== core[i].warmIsA) {
+            problems.push(`item ${i} (${core[i].id}): warmIsA does not derive from seed ${o.seed} — the assignment was not pre-registered`);
+            break; // one is enough; listing all would just be noise
+        }
+    }
+    return { ok: problems.length === 0, problems };
+}
+/**
+ * Emit the generation work order. Deterministic in (instances, seed): the same corpus and seed
+ * produce the same blind assignment, which is what makes "pre-registered" checkable after the fact.
+ */
+export function buildWorkOrder(instances, options = {}) {
+    // A margin is a PRE-REGISTRATION, so a bad one is an error, not something to quietly round into
+    // range: `margin: 99` clamped to 0.5 would silently pre-register a bar nothing can fail.
+    if (options.margin !== undefined && !isValidMargin(options.margin)) {
+        throw new RangeError(`margin ${JSON.stringify(options.margin)} must be a number in (${MARGIN_MIN_EXCLUSIVE}, ${MARGIN_MAX}]`);
+    }
+    const margin = options.margin ?? NO_LIFT_MARGIN;
+    const seed = clampInt(options.seed, 20260729, 0, 2 ** 31 - 1);
+    const wordMin = clampInt(options.wordMin, DEFAULT_WORD_MIN, 10, 5000);
+    const wordMax = Math.max(wordMin, clampInt(options.wordMax, DEFAULT_WORD_MAX, 10, 5000));
+    const limit = clampInt(options.limit, 0, 0, 100000);
+    const picked = limit > 0 ? instances.slice(0, limit) : instances.slice();
+    const rand = mulberry32(seed);
+    const items = picked.map((inst) => {
+        const warmIsA = rand() < 0.5;
+        const shared = `Answer the user prompt below as a first-response PLAN of ${wordMin}-${wordMax} words. ` +
+            'Plain prose, no headings, no lists. Say what you would DO first and why.';
+        return {
+            id: inst.id,
+            query: inst.query,
+            class: inst.class,
+            warmIsA,
+            cold: { instruction: shared, lessons: [] },
+            warm: {
+                instruction: `${shared} The following learned lessons were surfaced for this prompt; use them if relevant.`,
+                lessons: inst.lessons.slice(),
+            },
+        };
+    });
+    const emittedAt = typeof options.nowTs === 'string' ? options.nowTs : new Date().toISOString();
+    const fingerprint = corpusFingerprint(picked.map((i) => ({ id: i.id, query: i.query })));
+    return {
+        kind: WORK_ORDER_KIND,
+        version: WORK_ORDER_VERSION,
+        seed,
+        generatedAt: emittedAt,
+        emittedAt,
+        margin,
+        corpusFingerprint: fingerprint,
+        wordMin,
+        wordMax,
+        protocol: [
+            'PRE-REGISTERED before any plan text exists. Do not edit `warmIsA`, `seed`, `margin`, or `id`.',
+            'COLD arm = the prompt alone. WARM arm = the same prompt plus exactly the lessons the apply leg injected.',
+            'CONFORMANCE FIREWALL: never place a gold answer, a judge verdict, or an outcome label in either arm.',
+            `Fill coldPlan/warmPlan for each item (${wordMin}-${wordMax} words, symmetric length).`,
+            'Assign `class` NOW if you intend to slice — a class chosen after outcomes are known is not a pre-registration.',
+            'Then: `dz epoch-replay --judge <this file>` → judge each prompt with an EXTERNAL model → `dz epoch-replay --score <judgments> --work-order <this file>`.',
+            `The non-superiority margin (${margin}) is PRE-REGISTERED HERE. --score reads it from this file and rejects a --margin flag.`,
+            'PRIVACY: this file contains raw local prompt texts. Keep it out of version control.',
+            `INTEGRITY: \`digest\` covers version + seed + margin + corpus + every [id, warmIsA]. Editing any of them makes --judge/--score refuse. It is an ${DIGEST_HONEST_SCOPE}.`,
+        ],
+        items,
+        digest: workOrderDigest({ seed, version: WORK_ORDER_VERSION, margin, corpusFingerprint: fingerprint, items }),
+    };
+}
+/**
+ * Render blind A/B judge prompts from a FILLED work order. An item missing either plan is skipped
+ * with a reason: half a pair is not a comparison, and substituting an empty string would hand the
+ * judge a rigged contest.
+ */
+export function buildJudgePrompts(order) {
+    const prompts = [];
+    const skipped = [];
+    for (const item of order.items ?? []) {
+        const cold = typeof item.coldPlan === 'string' ? item.coldPlan.trim() : '';
+        const warm = typeof item.warmPlan === 'string' ? item.warmPlan.trim() : '';
+        if (cold === '' || warm === '') {
+            skipped.push({
+                id: item.id,
+                reason: cold === '' && warm === '' ? 'both plans missing' : cold === '' ? 'coldPlan missing' : 'warmPlan missing',
+            });
+            continue;
+        }
+        const a = item.warmIsA ? warm : cold;
+        const b = item.warmIsA ? cold : warm;
+        prompts.push({
+            id: item.id,
+            prompt: [
+                'You are a blind judge. An assistant received this user prompt:',
+                `PROMPT: ${item.query}`,
+                '',
+                'Two candidate first-response plans. Judge which better serves the user: concreteness,',
+                'correct first actions, avoiding known failure modes. Ignore verbosity and style.',
+                '',
+                `PLAN A: ${a}`,
+                '',
+                `PLAN B: ${b}`,
+                '',
+                'Reply with EXACTLY 3 lines:',
+                'WINNER: A|B|TIE',
+                'DECISIVE: <the single concrete element that made the winner better, one line>',
+                'CONFIDENCE: high|medium|low',
+            ].join('\n'),
+        });
+    }
+    return { prompts, skipped };
+}
+/**
+ * Map blind judgments back to arms using the work order's PRE-REGISTERED `warmIsA`. The judgments
+ * file deliberately carries no arm labels: if un-blinding read a label the judge (or a later hand
+ * edit) supplied, the blinding would be decorative.
+ *
+ * Unknown ids and unparseable winners are SKIPPED with a reason, never guessed. DUPLICATE ids are
+ * different: they are a CORRUPT input, not a skippable row, so the whole call is REFUSED. Skipping
+ * the second copy silently accepted a file in which one judgment had been pasted five times — which
+ * scored as n=5 and reached SUPPORTED off a single opinion (Codex QE MED-4).
+ */
+export function unblindJudgments(order, judgments) {
+    const byId = new Map();
+    for (const item of order.items ?? [])
+        byId.set(item.id, item);
+    const outcomes = [];
+    const skipped = [];
+    const seen = new Set();
+    // Refuse BEFORE interpreting anything: a duplicated id makes the whole file untrustworthy.
+    const dupes = new Set();
+    const walked = new Set();
+    for (const j of judgments ?? []) {
+        const id = typeof j?.id === 'string' ? j.id : '';
+        if (id === '')
+            continue;
+        if (walked.has(id))
+            dupes.add(id);
+        walked.add(id);
+    }
+    if (dupes.size > 0) {
+        return {
+            ok: false,
+            error: `corrupt judgments: duplicate id(s) ${[...dupes].sort().map((d) => JSON.stringify(d)).join(', ')} — one instance may be judged exactly once`,
+            outcomes: [],
+            skipped: [],
+        };
+    }
+    for (const j of judgments ?? []) {
+        const id = typeof j?.id === 'string' ? j.id : '';
+        if (id === '') {
+            skipped.push({ id: String(j?.id ?? ''), reason: 'missing id' });
+            continue;
+        }
+        const item = byId.get(id);
+        if (!item) {
+            skipped.push({ id, reason: 'id not in the work order (cannot un-blind)' });
+            continue;
+        }
+        const raw = typeof j.winner === 'string' ? j.winner.trim().toUpperCase() : '';
+        let winner;
+        if (raw === 'TIE')
+            winner = 'tie';
+        else if (raw === 'A')
+            winner = item.warmIsA ? 'warm' : 'cold';
+        else if (raw === 'B')
+            winner = item.warmIsA ? 'cold' : 'warm';
+        else {
+            skipped.push({ id, reason: `unparseable winner ${JSON.stringify(j.winner)} (expected A|B|TIE)` });
+            continue;
+        }
+        seen.add(id);
+        outcomes.push({ id, class: item.class ?? null, winner });
+    }
+    return { ok: true, error: null, outcomes, skipped };
+}
+/**
+ * The three-valued verdict (ADR-003, as amended).
+ *
+ * THE MODEL — a SINGLE binomial over DECISIVE pairs. Each instance yields ONE judgment about ONE
+ * prompt, so the arms are PAIRED, not two independent samples. Let `W` = warm wins, `C` = cold
+ * wins, `D = W + C` (ties are excluded from the test and reported separately). The statistic is
+ * `p̂ = W/D` with a Wilson interval, mapped to the lift scale by {@link liftInterval}:
+ *
+ *   SUPPORTED     lift lower bound > 0        (equivalently: Wilson lower on p̂ > 0.5)
+ *   FALSIFIED     harm — lift upper bound < 0 (Wilson upper on p̂ < 0.5); OR non-superiority —
+ *                 lift upper bound < `margin` with `D >= FALSIFY_NO_LIFT_MIN_N`
+ *   INCONCLUSIVE  everything else, including `D < MIN_INSTANCES`. A first-class honest outcome.
+ *
+ * This is exactly the statistic the manual 2026-07-29 experiment used, and it is the correction the
+ * re-QE demanded: the previous two-proportion (Newcombe) framing treated the paired judgments as
+ * independent samples and was ANTI-CONSERVATIVE — 500/500 over 1000 decisive pairs produced an
+ * upper bound of 0.0437 and a FALSIFIED verdict where the paired form gives 0.0619 and INCONCLUSIVE
+ * (Codex QE HIGH-A).
+ *
+ * REFUSALS (verdict is a placeholder, `refusal` is set): duplicate instance ids, an invalid `z`, or
+ * an out-of-range `margin`.
+ */
+export function scoreEpochReplay(outcomes, options = {}) {
+    const slice = typeof options.slice === 'string' && options.slice.trim() !== '' ? options.slice.trim() : 'all';
+    // HIGH-B: a margin is a PRE-REGISTRATION. Out of range is an error, not something to round into
+    // range — clamping `--margin 99` down to a legal value would buy FALSIFIED for free.
+    const marginGiven = options.margin !== undefined;
+    const marginValid = !marginGiven || isValidMargin(options.margin);
+    const margin = marginGiven && marginValid ? options.margin : NO_LIFT_MARGIN;
+    // MED-5: `z` used to be CLAMPED into [0.0001, 10]. A caller passing 0 therefore got a near-zero
+    // -width interval, which is trivially disjoint from anything — SUPPORTED fabricated out of a bad
+    // argument. An invalid z is refused, consistent with `wilsonInterval`'s null discipline.
+    const zGiven = options.z !== undefined;
+    const zValid = !zGiven || (typeof options.z === 'number' && Number.isFinite(options.z) && options.z > 0 && options.z <= 10);
+    const z = zGiven && zValid ? options.z : WILSON_Z;
+    const pool = (outcomes ?? []).filter((o) => {
+        if (!o || typeof o.id !== 'string')
+            return false;
+        if (o.winner !== 'cold' && o.winner !== 'warm' && o.winner !== 'tie')
+            return false;
+        return slice === 'all' ? true : (o.class ?? null) === slice;
+    });
+    // MED-4: five copies of one judgement are not five observations. Refuse — a duplicated instance
+    // id means the input is corrupt, and D must never be inflated by a paste.
+    const dupes = new Set();
+    const walkedIds = new Set();
+    for (const o of pool) {
+        if (walkedIds.has(o.id))
+            dupes.add(o.id);
+        walkedIds.add(o.id);
+    }
+    const n = pool.length;
+    const warmWins = pool.filter((o) => o.winner === 'warm').length;
+    const coldWins = pool.filter((o) => o.winner === 'cold').length;
+    const ties = pool.filter((o) => o.winner === 'tie').length;
+    // HIGH-A: ONE binomial over DECISIVE pairs. Ties carry no directional information, so they are
+    // excluded from the denominator (and reported); `p̂ = W/D` is the paired statistic.
+    const decisive = warmWins + coldWins;
+    const pWarm = wilsonInterval(warmWins, decisive, z);
+    const lift = liftInterval(pWarm);
+    // Cold's interval is the exact complement of warm's — reported for readability, never a second test.
+    const coldCi = wilsonInterval(coldWins, decisive, z);
+    const warm = { arm: 'warm', wins: warmWins, n: decisive, ci: pWarm };
+    const cold = { arm: 'cold', wins: coldWins, n: decisive, ci: coldCi };
+    const base = {
+        slice,
+        n,
+        ties,
+        decisive,
+        cold,
+        warm,
+        lift,
+        z,
+        minN: MIN_INSTANCES,
+        falsifyNoLiftMinN: FALSIFY_NO_LIFT_MIN_N,
+        noLiftMargin: margin,
+    };
+    // ── refusals: a corrupt input yields NO measurement ──
+    if (!zValid) {
+        return {
+            ...base,
+            z: WILSON_Z,
+            verdict: 'INCONCLUSIVE',
+            refusal: `invalid z ${JSON.stringify(options.z)} — must be a finite number in (0, 10]; refused rather than clamped, because a tiny z manufactures a significant interval`,
+            reason: 'REFUSED: invalid confidence parameter — no verdict was computed',
+        };
+    }
+    if (!marginValid) {
+        return {
+            ...base,
+            noLiftMargin: NO_LIFT_MARGIN,
+            verdict: 'INCONCLUSIVE',
+            refusal: `invalid margin ${JSON.stringify(options.margin)} — must be a number in (${MARGIN_MIN_EXCLUSIVE}, ${MARGIN_MAX}]; refused rather than clamped, because an oversized margin buys FALSIFIED`,
+            reason: 'REFUSED: invalid non-superiority margin — no verdict was computed',
+        };
+    }
+    if (dupes.size > 0) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            refusal: `corrupt outcomes: duplicate instance id(s) ${[...dupes].sort().map((d) => JSON.stringify(d)).join(', ')} — one instance counts exactly once`,
+            reason: 'REFUSED: duplicate instance ids would inflate the denominator — no verdict was computed',
+        };
+    }
+    if (decisive < MIN_INSTANCES) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            refusal: null,
+            reason: `insufficient data: ${decisive} DECISIVE pair(s) in slice "${slice}"` +
+                `${ties > 0 ? ` (${ties} tie(s) carry no direction and are excluded)` : ''}, ` +
+                `${MIN_INSTANCES} needed (darwin FDR discipline — n=3 gave a 33% false-discovery rate)`,
+        };
+    }
+    if (pWarm === null || lift === null) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            refusal: null,
+            reason: `no valid confidence interval could be computed for slice "${slice}" (degenerate counts)`,
+        };
+    }
+    const shape = `warm ${warmWins}/${decisive} decisive (p=${pWarm.p.toFixed(3)}, CI [${pWarm.lower.toFixed(3)}, ${pWarm.upper.toFixed(3)}]); ` +
+        `lift [${lift.lower.toFixed(3)}, ${lift.upper.toFixed(3)}]`;
+    // Belt-and-braces: `lift.lower > 0` already implies warm won more, but asserting it makes a
+    // SUPPORTED unreachable through a single edited comparison.
+    if (lift.lower > 0 && warmWins > coldWins) {
+        return {
+            ...base,
+            verdict: 'SUPPORTED',
+            refusal: null,
+            reason: `${shape} — the lift interval lies ENTIRELY above zero (warm wins more than half of decisive pairs)`,
+        };
+    }
+    if (lift.upper < 0 && coldWins > warmWins) {
+        return {
+            ...base,
+            verdict: 'FALSIFIED',
+            refusal: null,
+            reason: `harm: ${shape} — the lift interval lies ENTIRELY below zero (cold wins more than half of decisive pairs)`,
+        };
+    }
+    // NON-SUPERIORITY, not "warm didn't win". The data must EXCLUDE a lift as large as the margin;
+    // an equal split at small D excludes nothing (Codex QE HIGH-3).
+    if (decisive >= FALSIFY_NO_LIFT_MIN_N && lift.upper < margin) {
+        return {
+            ...base,
+            verdict: 'FALSIFIED',
+            refusal: null,
+            reason: `no lift: ${shape} — the lift UPPER bound is below the pre-registered margin ${margin} over ${decisive} decisive pair(s), so a lift worth having is excluded`,
+        };
+    }
+    return {
+        ...base,
+        verdict: 'INCONCLUSIVE',
+        refusal: null,
+        reason: `${shape} — neither excludes zero nor excludes a ${margin} lift; under-powered, keep the corpus growing`,
+    };
+}
+export const DEFAULT_MOCK_N = 12;
+export const DEFAULT_MOCK_SEED = 20260729;
+/**
+ * Synthetic judge outcomes from ONE seeded stream (`mulberry32` — the repo's only PRNG). Same
+ * (n, effect, tieRate, seed) → byte-identical outcomes, so a `--mock` demo is a reproducer.
+ */
+export function generateMockOutcomes(options = {}) {
+    const n = clampInt(options.n, DEFAULT_MOCK_N, 0, 100000);
+    const effect = clampNumber(options.effect, 0, -1, 1);
+    const tieRate = clampNumber(options.tieRate, 0, 0, 1);
+    const seed = clampInt(options.seed, DEFAULT_MOCK_SEED, 0, 2 ** 31 - 1);
+    const pWarm = Math.max(0, Math.min(1, 0.5 + effect / 2));
+    const rand = mulberry32(seed);
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const tieRoll = rand();
+        const armRoll = rand();
+        const winner = tieRoll < tieRate ? 'tie' : armRoll < pWarm ? 'warm' : 'cold';
+        out.push({ id: `mock-${i}`, class: options.class ?? null, winner });
+    }
+    return out;
+}
+// ── Rendering ──────────────────────────────────────────────────────────────────────────────────
+function fmtCi(ci) {
+    return ci === null ? 'n/a' : `[${ci.lower.toFixed(3)}, ${ci.upper.toFixed(3)}]`;
+}
+export function renderEpochReplayResult(r) {
+    const out = [];
+    out.push('dz epoch-replay — cold (epoch 0) vs warm (epoch 1), Wilson-CI three-valued verdict');
+    out.push('');
+    if (r.refusal !== null) {
+        out.push('  REFUSED — the input is corrupt, so NO measurement was made:');
+        out.push(`    ${r.refusal}`);
+        return out.join('\n');
+    }
+    out.push(`  SLICE: ${r.slice} · ${r.n} scored instance(s) · ${r.decisive} DECISIVE pair(s)` +
+        `${r.ties > 0 ? ` · ${r.ties} tie(s) excluded from the test` : ''}`);
+    const ciLabel = r.z === WILSON_Z ? 'CI95' : `CI(z=${r.z})`;
+    out.push(`  COLD (epoch 0, no injected lessons): ${r.cold.wins}/${r.cold.n} decisive  ${ciLabel} ${fmtCi(r.cold.ci)}`);
+    out.push(`  WARM (epoch 1, apply-leg lessons):   ${r.warm.wins}/${r.warm.n} decisive  ${ciLabel} ${fmtCi(r.warm.ci)}`);
+    out.push(`  LIFT (paired, 2p−1 over decisive pairs): ${r.lift === null ? 'n/a' : `${r.lift.d >= 0 ? '+' : ''}${r.lift.d.toFixed(3)}  [${r.lift.lower.toFixed(3)}, ${r.lift.upper.toFixed(3)}]`}`);
+    out.push('');
+    out.push(`  VERDICT: ${r.verdict}`);
+    out.push(`    ${r.reason}`);
+    out.push('');
+    out.push(`  rule: ONE binomial over DECISIVE pairs (ties carry no direction and are excluded).`);
+    out.push(`        SUPPORTED only when the lift interval lies ENTIRELY above zero.`);
+    out.push(`        FALSIFIED only on HARM (entirely below zero) or on a passed NON-SUPERIORITY test — the lift UPPER bound below the pre-registered margin ${r.noLiftMargin} at D >= ${r.falsifyNoLiftMinN}.`);
+    out.push(`        Everything else is INCONCLUSIVE (min ${r.minN} decisive pairs). A tie is UNDER-POWERED, never "refuted".`);
+    return out.join('\n');
+}
+export function renderWorkOrderSummary(order, outPath) {
+    const withClass = order.items.filter((i) => typeof i.class === 'string' && i.class !== '').length;
+    const out = [];
+    out.push(`dz epoch-replay --emit → ${outPath}`);
+    out.push('');
+    out.push(`  ${order.items.length} instance(s) · seed ${order.seed} · blind A/B assignment PRE-REGISTERED`);
+    out.push(`  integrity digest: ${order.digest.slice(0, 16)}… (covers version + seed + every id:warmIsA)`);
+    out.push(`  slice labels assigned: ${withClass}/${order.items.length}`);
+    out.push(`  plan length target: ${order.wordMin}-${order.wordMax} words per arm`);
+    out.push('');
+    out.push('  NEXT (this runner never calls a model):');
+    out.push('   1. Fill coldPlan/warmPlan for every item with an agent, arms generated symmetrically.');
+    out.push(`   2. dz epoch-replay --judge ${outPath}   → blind judge prompts`);
+    out.push('   3. Have an EXTERNAL (cross-model) judge answer each prompt; collect {id, winner} rows.');
+    out.push(`   4. dz epoch-replay --score <judgments.json> --work-order ${outPath}`);
+    out.push('');
+    out.push('  PRIVACY: the work order embeds raw local prompt texts — keep it out of version control.');
+    return out.join('\n');
+}
+export function renderJudgePromptsSummary(result, outPath) {
+    const out = [];
+    out.push(`dz epoch-replay --judge → ${outPath}`);
+    out.push('');
+    out.push(`  ${result.prompts.length} blind judge prompt(s) rendered — the file carries {id, prompt} and NOTHING else`);
+    if (result.skipped.length > 0) {
+        out.push(`  ${result.skipped.length} item(s) SKIPPED (half a pair is not a comparison):`);
+        for (const s of result.skipped)
+            out.push(`    · ${s.id}: ${s.reason}`);
+        out.push('    (this list stays HERE — its reasons name arms, so it is never written to the judge file)');
+    }
+    out.push('');
+    out.push('  Give each prompt to an EXTERNAL judge model (cross-model: not the generator).');
+    out.push('  Collect the answers as [{ "id": "<id>", "winner": "A|B|TIE" }, ...] — no arm labels:');
+    out.push('  un-blinding uses the work order\'s pre-registered assignment, not anything the judge wrote.');
+    return out.join('\n');
+}
+//# sourceMappingURL=epoch-replay.js.map