@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/_lib/standing_bound_ratchet.ts

@@ -3,38 +3,63 @@
  *
  * WHY THIS EXISTS
  * ---------------
- * `src/config/preamble-payload-budget.json` says of its grace ceiling: *"It may
- * never move UP."* `grace_ceiling_history` in the same file records it moving up
- * twice — 138,212 → 138,273 on 2026-09-02 and 138,273 → 138,490 on 2026-09-08 —
- * each with a careful prose justification. ADR-264 resolved that contradiction
- * against the practice: the sentence stands, the two raises are violations caused
- * by contradictory wording, and standing-rule growth needs a compensating
- * reduction elsewhere.
+ * `src/config/preamble-payload-budget.json` said of its grace ceiling: *"It may
+ * never move UP."* `grace_ceiling_history` in the same file recorded it moving
+ * up twice — 138,212 → 138,273 on 2026-09-02 and 138,273 → 138,490 on
+ * 2026-09-08 — each with a careful prose justification. ADR-264 resolved that
+ * contradiction against the practice: the sentence stands, the two raises are
+ * violations caused by contradictory wording, and standing-rule growth needs a
+ * compensating reduction elsewhere.
  *
  * That decision then had no enforcement. A sentence in a JSON string is not a
- * gate, and the file's own history is the evidence: nothing objected either time.
- * This module is the enforcement — and it is the ONLY thing
- * `road-to-a-standing-budget-with-headroom` step 1.3 ships, because the 128-token
- * Iron Law reserve that step designed was refused by an AI council 2/2 on
- * 2026-09-08. See ADR-265.
+ * gate, and the file's own history was the evidence: nothing objected either
+ * time. This module is the enforcement.
+ *
+ * WHAT IT BOUNDS NOW — AND WHY THE SUBJECT CHANGED
+ * -------------------------------------------------
+ * It used to bound one number, `ci_delivery.grace_ceiling`. That key is GONE
+ * (`road-to-delivery-for-every-host` 4.4): the ceiling is no longer stored, it
+ * is MEASURED at the base ref as `max(design_ceiling, base + active grants)`.
+ * A measured ceiling captures every merged reduction automatically, which a
+ * stored one never did.
+ *
+ * Moving the ceiling out of the config did not remove the need for a
+ * shrink-only bound — it moved the attack surface. Three numbers in the tree
+ * can still widen the effective ceiling without adding a single token of
+ * payload, and all three are now bounded:
+ *
+ *   · `design_ceiling`, derived from `baseline_tokens` × `headroom_pct`. It is
+ *     the FLOOR of the measured ceiling, so raising it raises the ceiling
+ *     directly. ADR-264's sentence applies to it verbatim.
+ *   · every existing exception's `granted_tokens` — enlarging a live grant is
+ *     a raise wearing a break-glass label.
+ *   · every existing exception's `watermark` — the watermark is what pins the
+ *     base while a grant is live, so raising it launders the grant into the
+ *     next base, which is precisely the failure the watermark exists to stop.
+ *
+ * A NEW exception id is deliberately NOT a violation: recording a fresh,
+ * approved, dated grant is the break-glass path working. Editing one that
+ * already existed is not.
  *
  * WHAT IT CANNOT DO, STATED PLAINLY
  * ---------------------------------
  * The change under review can edit this file. Both council seats named that as
- * the defect fatal to the reserve — "the checker, its imports, token census,
- * workflow, and status context are all part of the trusted computing base", so a
- * protected record read by an unprotected verifier grants nothing. It is fatal to
- * a mechanism that GRANTS budget and it is not fatal to one that only REFUSES,
- * which is the whole reason the reserve stayed unshipped and this ratchet did
- * not: disabling this check requires visibly editing it, and every gate in this
- * repository already rests on that same review. A ratchet whose only failure mode
- * is "someone deleted the ratchet" is strictly better than the sentence it
- * replaces, which had no failure mode because it did nothing.
+ * the defect fatal to a mechanism that GRANTS budget, and it is not fatal to
+ * one that only REFUSES: disabling this check requires visibly editing it, and
+ * every gate in this repository already rests on that same review. A ratchet
+ * whose only failure mode is "someone deleted the ratchet" is strictly better
+ * than the sentence it replaces, which had no failure mode because it did
+ * nothing. The 2026-09-10 verdict added one mitigation on top and named its
+ * limit in the same breath: CI runs this code AS IT EXISTS AT THE BASE REF, so
+ * a same-PR weakening cannot measure its own change — *"the mechanism does not
+ * prevent the exploit; it makes the exploit auditable."*
  */
 import { spawnSync } from 'node:child_process';
 
-/** Repo-relative path of the budget config the bound lives in. */
+/** Repo-relative path of the budget config the bounds live in. */
 export const BUDGET_CONFIG_PATH = 'src/config/preamble-payload-budget.json';
+/** Repo-relative path of the break-glass ledger the grant bounds live in. */
+export const EXCEPTIONS_CONFIG_PATH = 'src/config/preamble-payload-exceptions.json';
 
 /** Injection seam: run git, capture output, never throw on a non-zero exit. */
 export type GitRunner = (args: readonly string[], cwd: string) => {
@@ -48,15 +73,66 @@ export const realGit: GitRunner = (args, cwd) => {
     return { ok: r.status === 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
 };
 
+/** Named shrink-only numbers, keyed by a stable bound id. */
+export type BoundSet = Record<string, number>;
+
 export interface BoundsRatchetVerdict {
     ok: boolean;
     violations: string[];
-    /** The bound read at the base ref, or `null` when it could not be read. */
-    baseGraceCeiling: number | null;
+    /** The bounds read at the base ref, or `null` when they could not be read. */
+    baseBounds: BoundSet | null;
     /** The ref compared against, or `null` when none resolved. */
     baseRef: string | null;
     /** Why the comparison was skipped, when it was. Printed, never silent. */
     note: string | null;
+    /**
+     * `false` means the bounds could not be READ, not that one rose.
+     *
+     * Two refusals reach a caller with `ok: false` and they need opposite
+     * actions: a risen bound is fixed by lowering the addition, an unverifiable
+     * one by repairing the checkout. A completion review caught both being
+     * rendered as "ROSE", which would send an operator to shrink a rule over
+     * what was a fetch problem.
+     */
+    verified: boolean;
+}
+
+/**
+ * The bound map, derived identically from head and base configs.
+ *
+ * ONE function for both sides, on purpose: two derivations of one boundary is
+ * the drift shape that let the grace ceiling rise twice under a sentence
+ * forbidding it. `budget` and `exceptions` are parsed JSON, or `null` when the
+ * file is absent — an absent exceptions ledger contributes no bounds, which is
+ * correct: there are no grants to protect.
+ */
+export function boundsFrom(budget: unknown, exceptions: unknown): BoundSet | null {
+    const b = (budget ?? null) as Record<string, unknown> | null;
+    if (b === null) return null;
+    const baseline = Number(b['baseline_tokens']);
+    const headroom = Number(b['headroom_pct']);
+    if (!Number.isFinite(baseline) || !Number.isFinite(headroom)) return null;
+    // `design_ceiling` is the whole config-side bound now. The retained stored
+    // allowance stage 1 kept beside it was deleted in stage 2 (ADR-276), so a
+    // tree at or below design is bounded by this number and a tree above it is
+    // bounded by its own base measurement — neither of which lives in a field
+    // anyone can edit upward.
+    const out: BoundSet = { design_ceiling: Math.round(baseline * (1 + headroom / 100)) };
+
+    const ex = (exceptions ?? null) as Record<string, unknown> | null;
+    const list = ex === null ? null : ex['exceptions'];
+    if (Array.isArray(list)) {
+        for (const item of list) {
+            const e = (item ?? {}) as Record<string, unknown>;
+            const id = e['id'];
+            if (typeof id !== 'string' || id.trim() === '') continue;
+            const granted = Number(e['granted_tokens']);
+            const watermark = Number(e['watermark']);
+            if (Number.isFinite(granted)) out[`exception:${id}:granted_tokens`] = granted;
+            if (Number.isFinite(watermark)) out[`exception:${id}:watermark`] = watermark;
+        }
+    }
+    return out;
 }
 
 function showAtRef(git: GitRunner, repoRoot: string, ref: string, relPath: string): string | null {
@@ -65,90 +141,193 @@ function showAtRef(git: GitRunner, repoRoot: string, ref: string, relPath: strin
 }
 
 /**
- * Compare the grace ceiling in this tree against the one at the base ref.
+ * A condition that stops the comparison: skip when advisory, refuse when not.
  *
- * SKIPS rather than fails when the base ref or the base config cannot be read.
- * That is the opposite of the fail-closed posture the same council demanded for
- * the reserve, and the asymmetry is deliberate: an unreadable base there would
- * have GRANTED budget on an infrastructure failure, whereas here it would REFUSE
- * a change on one. A shallow clone, a first commit and a detached build all
- * legitimately have no base, and a gate that reds on them gets switched off —
- * which is how a repository loses the enforcement it just built. The skip is
+ * One helper for all causes rather than an inline branch each, so the posture
+ * cannot drift between them — the failure this closes was four independent
+ * `ok: true` returns that all had to be found before any of them could be
+ * trusted.
+ */
+function unverified(reason: string, requireBase: boolean, baseRef: string | null): BoundsRatchetVerdict {
+    if (requireBase) {
+        return {
+            ok: false,
+            verified: false,
+            baseBounds: null,
+            baseRef,
+            note: `${reason}, so the shrink-only bounds were NOT verified in this run`,
+            violations: [
+                `the shrink-only bounds could not be verified: ${reason}. This run is `
+                    + 'ENFORCING, so an unverifiable bound refuses rather than skips — an '
+                    + 'unreadable base would otherwise grant budget on an infrastructure '
+                    + 'failure. This is NOT a bound rise: fix the checkout (a full fetch '
+                    + 'of the base ref) rather than lowering the addition.',
+            ],
+        };
+    }
+    return {
+        ok: true,
+        verified: false,
+        violations: [],
+        baseBounds: null,
+        baseRef,
+        note: `${reason}, so the shrink-only bounds were NOT verified in this run`,
+    };
+}
+
+/**
+ * Compare every shrink-only bound in this tree against the one at the base ref.
+ *
+ * TWO POSTURES, AND WHICH ONE APPLIES IS THE CALLER'S TO DECLARE.
+ *
+ * Advisory (the default): a base ref or base config that cannot be read SKIPS,
  * reported in both the human and JSON output so it cannot pass for a check.
+ * That default is not laziness and the original reasoning still holds — a
+ * shallow clone, a first commit and a detached build all legitimately have no
+ * base, and a gate that reds on them gets switched off, which is how a
+ * repository loses the enforcement it just built.
+ *
+ * Enforcing (`requireBase: true`): the same conditions REFUSE. An AI council
+ * (2/2, 2026-09-10) made this blocking for the move to a base-measured ceiling,
+ * because the asymmetry inverts once the base ref stops being a cross-check and
+ * becomes the ceiling itself. Today an unreadable base costs a comparison;
+ * there it would grant an unbounded budget on an infrastructure failure.
+ *
+ * The flag is the caller's rather than derived from `GITHUB_ACTIONS` here: this
+ * module cannot tell an enforcing CI run from a diagnostic one on the same
+ * runner, and a gate that guesses its own strictness from an environment
+ * variable is one `env` change away from being advisory everywhere.
  */
 export function assertBoundsDidNotRise(opts: {
     repoRoot: string;
     baseRef: string | null;
     git?: GitRunner;
     /**
-     * The ceiling this run actually compares the payload against.
+     * Refuse instead of skipping when the base cannot be read.
      *
-     * The CI step passes `--ceiling <grace_ceiling>`, so the effective bound can
-     * be raised either by editing the config or by passing a bigger number. Both
-     * arrive here as one value, which closes the second path without a second
-     * check.
+     * Absent is advisory, which keeps every pre-existing caller on the
+     * behaviour it was written against. The CI path sets it.
      */
-    headGraceCeiling: number;
+    requireBase?: boolean;
+    /**
+     * The shrink-only numbers as they stand in THIS tree.
+     *
+     * Passed in rather than re-read here so head and base go through
+     * `boundsFrom` from the caller's own configuration objects — including an
+     * effective value the caller may have taken from a flag rather than the
+     * file, which is the second path a bound could otherwise be widened by.
+     */
+    headBounds: BoundSet;
 }): BoundsRatchetVerdict {
     const git = opts.git ?? realGit;
+    const requireBase = opts.requireBase === true;
     if (opts.baseRef === null || opts.baseRef.trim() === '') {
-        return {
-            ok: true,
-            violations: [],
-            baseGraceCeiling: null,
-            baseRef: null,
-            note: 'no base ref resolved, so the shrink-only bound was NOT verified in this run',
-        };
+        return unverified('no base ref resolved', requireBase, null);
     }
     const cfg = showAtRef(git, opts.repoRoot, opts.baseRef, BUDGET_CONFIG_PATH);
     if (cfg === null) {
-        return {
-            ok: true,
-            violations: [],
-            baseGraceCeiling: null,
-            baseRef: opts.baseRef,
-            note: `${BUDGET_CONFIG_PATH} could not be read at ${opts.baseRef}, so the shrink-only bound was NOT verified`,
-        };
+        return unverified(`${BUDGET_CONFIG_PATH} could not be read at ${opts.baseRef}`, requireBase, opts.baseRef);
     }
-    let baseGrace: number | null = null;
+    let baseBudget: unknown;
     try {
-        const parsed = JSON.parse(cfg) as Record<string, unknown>;
-        const delivery = (parsed['ci_delivery'] ?? {}) as Record<string, unknown>;
-        const n = Number(delivery['grace_ceiling']);
-        baseGrace = Number.isFinite(n) ? n : null;
+        baseBudget = JSON.parse(cfg);
     } catch {
-        return {
-            ok: true,
-            violations: [],
-            baseGraceCeiling: null,
-            baseRef: opts.baseRef,
-            note: `${BUDGET_CONFIG_PATH} at ${opts.baseRef} is not parseable, so the shrink-only bound was NOT verified`,
-        };
+        return unverified(`${BUDGET_CONFIG_PATH} at ${opts.baseRef} is not parseable`, requireBase, opts.baseRef);
     }
-    if (baseGrace === null) {
-        return {
-            ok: true,
-            violations: [],
-            baseGraceCeiling: null,
-            baseRef: opts.baseRef,
-            note: `no ci_delivery.grace_ceiling at ${opts.baseRef}, so there is no earlier bound to ratchet against`,
-        };
+    // An absent exceptions ledger at the base ref is normal — it did not exist
+    // before this mechanism landed, and a ref predating it has no grants to
+    // protect. An unparseable one is not, and refuses like a bad budget.
+    const exRaw = showAtRef(git, opts.repoRoot, opts.baseRef, EXCEPTIONS_CONFIG_PATH);
+    let baseExceptions: unknown = null;
+    if (exRaw !== null) {
+        try {
+            baseExceptions = JSON.parse(exRaw);
+        } catch {
+            return unverified(
+                `${EXCEPTIONS_CONFIG_PATH} at ${opts.baseRef} is not parseable`,
+                requireBase,
+                opts.baseRef,
+            );
+        }
     }
-    if (opts.headGraceCeiling > baseGrace) {
-        return {
-            ok: false,
-            baseGraceCeiling: baseGrace,
-            baseRef: opts.baseRef,
-            note: null,
-            violations: [
-                `the standing-payload grace ceiling rose from ${String(baseGrace)} to ` +
-                    `${String(opts.headGraceCeiling)} against ${opts.baseRef}. ` +
-                    `${BUDGET_CONFIG_PATH} says it may not move upward and ADR-264 decided that ` +
-                    'the sentence stands: standing-rule growth needs a compensating reduction ' +
-                    'elsewhere, not a bigger ceiling. Lower the addition, migrate the prose out of ' +
-                    'the standing rule, or reduce another standing asset by the same amount.',
-            ],
-        };
+
+    const baseBounds = boundsFrom(baseBudget, baseExceptions);
+    if (baseBounds === null) {
+        return unverified(
+            `there are no shrink-only bounds at ${opts.baseRef} to ratchet against`,
+            requireBase,
+            opts.baseRef,
+        );
+    }
+
+    const violations: string[] = [];
+    for (const [name, head] of Object.entries(opts.headBounds)) {
+        const base = baseBounds[name];
+        // A bound absent at the base is a NEW one — a freshly recorded grant,
+        // which is the break-glass path working rather than a rise.
+        if (base === undefined) continue;
+        if (head > base) violations.push(explain(name, base, head, opts.baseRef));
+    }
+
+    // DELETION CANNOT DISCHARGE DEBT. A grant that existed at the base and is
+    // gone at head was not repaid, it was erased — the 2026-09-11 council's
+    // blocking finding #3, and the one failure a shrink-only comparison misses
+    // by construction, because a removed number is not a smaller number.
+    // Only `exception:` bounds are checked for deletion: `design_ceiling` is
+    // always present, and the stored allowance that used to need an exemption
+    // here no longer exists.
+    const reportedDeletions = new Set<string>();
+    for (const name of Object.keys(baseBounds)) {
+        if (!name.startsWith('exception:')) continue;
+        if (opts.headBounds[name] !== undefined) continue;
+        const m = /^exception:(.+):(?:granted_tokens|watermark)$/.exec(name);
+        const id = m === null ? name : String(m[1]);
+        // One record carries two bounds; report the record once.
+        if (reportedDeletions.has(id)) continue;
+        reportedDeletions.add(id);
+        violations.push(
+            `standing-payload exception '${id}' existed at ${opts.baseRef} and is gone at head. A deleted ` +
+                'record is not a repaid one: repayment is established by the payload returning to the ' +
+                'watermark, and erasing the entry erases the debt along with the evidence of it. Mark it ' +
+                'repaid once the measurement supports that, or leave it in place.',
+        );
+    }
+
+    if (violations.length > 0) {
+        return { ok: false, verified: true, baseBounds, baseRef: opts.baseRef, note: null, violations };
+    }
+    return { ok: true, verified: true, violations: [], baseBounds, baseRef: opts.baseRef, note: null };
+}
+
+/** One refusal message per bound kind — a generic "a bound rose" sends the
+ *  reader nowhere, and the three kinds have three different fixes. */
+function explain(name: string, base: number, head: number, baseRef: string): string {
+    const rose = `rose from ${String(base)} to ${String(head)} against ${baseRef}`;
+    if (name === 'design_ceiling') {
+        return (
+            `the standing-payload design ceiling ${rose}. It derives from baseline_tokens × ` +
+            `headroom_pct in ${BUDGET_CONFIG_PATH}, and it is the FLOOR of the measured ceiling, so ` +
+            'raising it widens every future budget without adding a token of payload. ADR-264 decided ' +
+            'that standing-rule growth needs a compensating reduction elsewhere, not a bigger ceiling. ' +
+            'Lower the addition, migrate the prose out of the standing rule, or reduce another standing ' +
+            'asset by the same amount.'
+        );
+    }
+    const m = /^exception:(.+):(granted_tokens|watermark)$/.exec(name);
+    if (m !== null && m[2] === 'granted_tokens') {
+        return (
+            `standing-payload exception '${String(m[1])}' had its grant ${rose}. Enlarging a grant that ` +
+            'already exists is a ceiling raise wearing a break-glass label. Record a NEW approved, dated ' +
+            'exception instead, so the enlargement carries its own approver, reason and expiry.'
+        );
+    }
+    if (m !== null) {
+        return (
+            `standing-payload exception '${String(m[1])}' had its watermark ${rose}. The watermark pins the ` +
+            'base while the grant is live, and raising it launders the granted tokens into the next base — ' +
+            'which is exactly the failure the watermark exists to prevent. It is the payload measured ' +
+            'BEFORE the grant and does not change afterwards.'
+        );
     }
-    return { ok: true, violations: [], baseGraceCeiling: baseGrace, baseRef: opts.baseRef, note: null };
+    return `the shrink-only bound '${name}' ${rose}, and ${BUDGET_CONFIG_PATH} says it may not move upward.`;
 }

package/src/scripts/_lib/tolerance_shadow.ts

@@ -0,0 +1,177 @@
+/**
+ * Shadow records for the value-reconciliation tolerance — the window whose
+ * distribution a threshold may later be read off.
+ *
+ * NO NEW CONCERN. `check_estate_count` reports zero growth allowance on hook
+ * concerns, and the roadmap step says so in as many words: extend the existing
+ * shadow gate. These records therefore ride `source_first_gate_hook.ts`'s
+ * `SHADOW_LOG` — the same JSONL file, the same gitignored local-only path — and
+ * are told apart by their own `record` discriminator. Nothing new is registered,
+ * nothing new fires, and the concern count is unmoved.
+ *
+ * NO SELF-REPORTED VERDICT, which is the property the step's verify clause
+ * names and the one most easily lost. A record says what the distance WAS and
+ * what each candidate threshold WOULD have done with it. It never says whether
+ * that was right. A field like `was_correct` would be the mechanism grading its
+ * own homework, and a distribution of self-assessments measures the assessor —
+ * the same reason `source_first_gate_hook` records `would_warn` per candidate
+ * instead of one `warn`.
+ *
+ * COUNTERFACTUAL, NOT CHOSEN. `CANDIDATE_COLOR_THRESHOLDS` and
+ * `CANDIDATE_LENGTH_THRESHOLDS` are evaluation points, not defaults: every
+ * record carries the outcome at each, so the window yields a curve rather than
+ * a yes/no. That is the council's own instruction — evaluate several candidate
+ * thresholds counterfactually, never select one as behaviour — and it is why a
+ * spread exists at all. `SHIPPED_TOLERANCE` stays `null` on both axes
+ * throughout the window.
+ *
+ * PRIVACY BY CONSTRUCTION. The record type carries a kind, a metric, numbers,
+ * a token NAME, and booleans. It has no field able to hold a file path, a
+ * prompt, a selector, or any document content — the same stance
+ * `source_first_gate_hook.ts` states for its own record. A token name is a
+ * project's own vocabulary and is the one string here; it is what makes a
+ * distribution readable per token rather than only in aggregate.
+ */
+import { appendShadowLine } from '../hooks/source_first_gate_hook.js';
+
+import type {
+    COLOR_DISTANCE_METRIC,
+    LENGTH_DISTANCE_METRIC,
+    ValueKind,
+    ValueRow,
+} from './design_tolerance.js';
+
+/**
+ * Colour ΔEOK evaluation points. Spread deliberately across two orders of
+ * magnitude: the window has to show where the curve bends, and a spread
+ * clustered around a guess would only confirm the guess.
+ */
+export const CANDIDATE_COLOR_THRESHOLDS: readonly number[] = [0.001, 0.005, 0.01, 0.02, 0.05];
+
+/**
+ * Length evaluation points, in CSS pixels. `1` is here because it is the one
+ * externally observed candidate in the evidence set (Primer's spacing plugin),
+ * and it is one point on a curve rather than a preferred value.
+ */
+export const CANDIDATE_LENGTH_THRESHOLDS: readonly number[] = [0.5, 1, 2, 4];
+
+/** Discriminator on the shared shadow log. */
+export const TOLERANCE_SHADOW_RECORD = 'tolerance_shadow' as const;
+
+export interface CounterfactualOutcome {
+    threshold: number;
+    /** Would this value have been reconciled onto the token at that threshold? */
+    would_reconcile: boolean;
+}
+
+export interface ToleranceShadowRecord {
+    record: typeof TOLERANCE_SHADOW_RECORD;
+    kind: ValueKind;
+    metric: typeof COLOR_DISTANCE_METRIC | typeof LENGTH_DISTANCE_METRIC;
+    /** Distance to the nearest project token, in `metric`. */
+    distance: number;
+    /** The token's own name. No value, no path, no content. */
+    nearest_token: string;
+    /** What the mechanism actually did — `false` throughout the shadow window. */
+    acted: boolean;
+    counterfactual: CounterfactualOutcome[];
+}
+
+export function candidatesFor(kind: ValueKind): readonly number[] {
+    return kind === 'color' ? CANDIDATE_COLOR_THRESHOLDS : CANDIDATE_LENGTH_THRESHOLDS;
+}
+
+/**
+ * Build a record from a reconciled value row, or `null` when the row carries
+ * nothing to measure.
+ *
+ * A row with no candidate token is deliberately NOT recorded as a distance of
+ * zero or of infinity: it is the absence of a measurement, and a window that
+ * silently folded those in would report a distribution over a population that
+ * includes non-observations.
+ */
+export function toleranceShadowRecord(
+    kind: ValueKind,
+    row: ValueRow,
+): ToleranceShadowRecord | null {
+    if (row.nearest === null || row.distance === null || row.metric === null) return null;
+    const distance = row.distance;
+    return {
+        record: TOLERANCE_SHADOW_RECORD,
+        kind,
+        metric: row.metric,
+        distance,
+        nearest_token: row.nearest.name,
+        acted: row.outcome === 'reconciled',
+        counterfactual: candidatesFor(kind).map((threshold) => ({
+            threshold,
+            would_reconcile: distance <= threshold,
+        })),
+    };
+}
+
+/**
+ * Append the records for one reconciliation pass to the shared shadow log.
+ *
+ * THE WINDOW IS ONLY OPEN IF SOMETHING WRITES TO IT. A blind review of the
+ * branch that shipped this module found the header above claiming records ride
+ * `SHADOW_LOG` while the module had no writer and no caller — so
+ * `FLIP_CRITERION`'s reverse trigger ("fewer than 20 records in 8 weeks")
+ * was satisfied by construction, which is a criterion that measures nothing.
+ * The writer is `appendShadowLine`, reused rather than reimplemented: it is
+ * already replay-aware and already fail-open, and a second writer to one log is
+ * two chances to disagree about the format.
+ *
+ * Returns the number of records written — rows with nothing to measure are
+ * skipped, so this is not `rows.length`.
+ */
+export function recordToleranceShadow(
+    root: string,
+    rows: ReadonlyArray<{ kind: ValueKind; row: ValueRow }>,
+): number {
+    let written = 0;
+    for (const { kind, row } of rows) {
+        const record = toleranceShadowRecord(kind, row);
+        if (record === null) continue;
+        appendShadowLine(root, record as unknown as Record<string, unknown>);
+        written += 1;
+    }
+    return written;
+}
+
+/**
+ * Pre-registered flip criterion, written BEFORE the window opens — which is the
+ * third clause of the step's verify and the one a later reader cannot
+ * reconstruct. Prose rather than code on purpose: nothing evaluates it
+ * automatically, and a function that returned `true` here would be the
+ * mechanism authorising its own promotion.
+ */
+export const FLIP_CRITERION = `
+Shadow -> a shipped tolerance, when ALL of:
+
+  a. >= 200 tolerance_shadow records, or >= 4 weeks of window, whichever comes
+     first, with at least 50 records on EACH axis. Colour and length are
+     separate distributions and a threshold read off a pooled one is read off
+     the wrong population.
+  b. The chosen candidate's counterfactual FALSE-RECONCILIATION share -- rows a
+     human reviewer marks as "should have been preserved" that the candidate
+     would have reconciled -- is at or below 1 %, estimated per axis. The
+     reviewer labels are collected OUTSIDE this record type on purpose: a
+     record that carried its own correctness label would be the self-report
+     this module refuses.
+  c. The MISSED-reconciliation share is reported alongside it and is not
+     optimised away. A threshold of zero trivially satisfies (b) and is useless;
+     both error directions are stated or the criterion is not met.
+  d. The distribution is not obviously bimodal. A bimodal curve means the
+     tolerance model itself is wrong -- two populations are being measured as
+     one -- and the response is to re-cut the model, never to pick a threshold
+     between the modes.
+
+Reverse trigger: fewer than 20 records in 8 weeks -> evaluate removing the
+mechanism. A reconciliation nobody exercises is prose with a config key.
+
+Never lifted by this criterion: enabling the mechanism BY DEFAULT is a
+consumer-facing default flip and stays owner-reserved, recorded in
+agents/roadmaps/stubs/road-to-frontend-power-default-flip.md. Meeting a to d
+authorises a shipped tolerance VALUE, not a shipped default.
+`.trim();