@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/bench_ab_size_claim.ts

@@ -13,6 +13,8 @@
  * change to either has to touch the record and the code together.
  */
 
+import { decidePairedVerdict, floorWarning, MIN_DISCORDANT } from './paired_verdict.js';
+
 /** T1 — median added lines must fall by at least this much. */
 export const T1_MEDIAN_LINES_PCT = -10;
 /** Two-sided significance for every endpoint in the pair. */
@@ -25,7 +27,15 @@ export interface PairedContinuous {
     /** `null` when the baseline median is 0 — no percent change exists. */
     median_delta_pct: number | null;
     median_delta: number;
+    /**
+     * Retained for TRIAGE and reporting. Since PREREG amendment v2 it decides
+     * nothing — see {@link evaluateSizeClaim}.
+     */
     wilcoxon_p: number;
+    /** Non-tied pairs in the direction of interest. Absent on a pre-amendment report. */
+    direction_wins?: number | undefined;
+    /** Non-tied pairs against the direction of interest. Absent on a pre-amendment report. */
+    direction_losses?: number | undefined;
 }
 
 /** A paired binary endpoint (the safety tier). */
@@ -56,6 +66,44 @@ export interface SizeClaimVerdict {
     safety_measured: boolean;
 }
 
+
+
+/** One clause naming the directional evidence, printable in a verdict reason. */
+function describeDirection(v: ReturnType<typeof decidePairedVerdict> | null): string {
+    if (v === null) {
+        return `no direction counts in the report — pre-amendment or unmeasured, so the direction bar is not met`;
+    }
+    if (v.kind === 'underpowered') {
+        return `underpowered: ${String(v.discordant)} non-tied pair(s) below the derived floor of ${String(MIN_DISCORDANT)}`;
+    }
+    const warn = floorWarning(v);
+    return `${String(v.wins)}/${String(v.discordant)} non-tied pairs, one-sided exact p=${v.p.toFixed(4)}` +
+        (warn === null ? '' : ` — ${warn}`);
+}
+
+/**
+ * The directional verdict for one endpoint, or `null` when it cannot be formed.
+ *
+ * `null` means the report carries no direction counts — a pre-amendment report,
+ * or an unmeasured endpoint. The caller treats that as "not significant" rather
+ * than reaching for `wilcoxon_p`, which is the whole point of the amendment.
+ *
+ * The counts are reconstructed into a delta vector of ±1 rather than carrying
+ * raw deltas through the report: the exact sign test needs direction only, and
+ * a council seat noted the raw deltas are preferable for auditability but not
+ * mathematically required. The raw values remain in the trial artifacts.
+ */
+function directionVerdict(e: PairedContinuous): ReturnType<typeof decidePairedVerdict> | null {
+    if (!e.measured) return null;
+    const w = e.direction_wins;
+    const l = e.direction_losses;
+    if (w === undefined || l === undefined) return null;
+    return decidePairedVerdict({
+        deltas: [...Array<number>(w).fill(1), ...Array<number>(l).fill(-1)],
+        alpha: ALPHA,
+    });
+}
+
 /**
  * Evaluate the size claim for one comparison — binding, and structurally unable
  * to report a win on size alone.
@@ -98,9 +146,52 @@ export function evaluateSizeClaim(input: SizeClaimInput): SizeClaimVerdict {
         };
     }
 
-    const cx_rose = cx.measured && cx.median_delta > 0 && cx.wilcoxon_p < ALPHA;
+    // ── PREREG amendment v2, 2026-08-26 — direction decides significance ────
+    //
+    // The significance half of every endpoint below was a Wilcoxon signed-rank
+    // p, which ranks by |difference| and is therefore magnitude-weighted. That
+    // was shown to disagree with the exact test on twelve records up to ten
+    // trials, PERMISSIVE in every one, with the visible symptom inverted: an
+    // artifact winning every trial still failed, because a few large
+    // opposite-direction deltas outweighed a clean sweep of small ones.
+    //
+    // TWO PROPOSITIONS, KEPT SEPARATE — this is the refinement both council
+    // seats independently required (2026-08-26, 2/2) and it is the half that
+    // makes the amendment safe. A sign test answers "did this help more often
+    // than it hurt" and says NOTHING about how much. Replacing Wilcoxon with it
+    // outright would let a clean sweep of negligible improvements claim a SIZE
+    // win. So:
+    //   · directional reliability → exact one-sided sign test over non-tied pairs
+    //   · practical magnitude     → the pre-registered T1_MEDIAN_LINES_PCT bar,
+    //                               unchanged and still independently binding
+    // Both must hold. Dropping either is a different claim and needs its own
+    // amendment.
+    //
+    // A report predating the amendment carries no direction counts. It is
+    // treated as UNMEASURED for the significance half rather than falling back
+    // to `wilcoxon_p`, because a silent fallback to the defective test is
+    // exactly what this amendment removes.
+    const sizeDir = directionVerdict(size);
+    const cxDir = directionVerdict(cx);
+    // ASYMMETRY, deliberate and the conservative direction of it. A PASS needs
+    // the direction bar MET; a REFUSAL fires on EITHER signal. Applying the
+    // strict reading to both would make the anti-golfing refusal disappear on
+    // any report without direction counts — a missing input silently rescuing
+    // an arm is the failure mode a refusal exists to prevent, and it is the
+    // opposite of what the amendment is for. So the refusal keeps the legacy
+    // Wilcoxon signal as a second trigger; the claim does not.
+    const cx_rose =
+        cx.measured &&
+        cx.median_delta > 0 &&
+        (cxDir === null ? cx.wilcoxon_p < ALPHA : cxDir.kind === 'regression');
+    // `regression`, NOT `pass`, and the distinction cost a test run to find.
+    // `direction_wins` counts the endpoint's IMPROVEMENT direction — a negative
+    // delta — for every continuous endpoint, so on complexity a `pass` means
+    // complexity FELL. What `cx_rose` needs is the opposite tail, which is
+    // exactly what `regression` names. Writing `pass` here reads correctly in
+    // English and inverts the anti-golfing guard.
     const pct = size.measured ? size.median_delta_pct : null;
-    const lines_fell = pct !== null && pct <= T1_MEDIAN_LINES_PCT && size.wilcoxon_p < ALPHA;
+    const lines_fell = pct !== null && pct <= T1_MEDIAN_LINES_PCT && sizeDir?.kind === 'pass';
 
     // (2b) Golfing is refused as soon as T2 shows it, and does NOT wait for T4.
     //
@@ -161,8 +252,11 @@ export function evaluateSizeClaim(input: SizeClaimInput): SizeClaimVerdict {
         ...base,
         verdict: lines_fell ? 'PASS' : 'NO-SIZE-WIN',
         reason: lines_fell
-            ? `median added lines ${pct}% at p=${size.wilcoxon_p} with no significant complexity rise and no safety regression`
-            : `T1 not met (median added lines ${pct}% at p=${size.wilcoxon_p}; bar is <= ${T1_MEDIAN_LINES_PCT}% at p<${ALPHA})`,
+            ? `median added lines ${pct}% (magnitude bar) AND ${describeDirection(sizeDir)} (direction bar) ` +
+              'with no significant complexity rise and no safety regression'
+            : `T1 not met (median added lines ${pct}%, bar <= ${T1_MEDIAN_LINES_PCT}%; ` +
+              `direction: ${describeDirection(sizeDir)}). Wilcoxon p=${size.wilcoxon_p} is reported for ` +
+              'triage and decides nothing.',
         lines_fell,
         size_measured: true,
         complexity_measured: true,

package/src/scripts/_lib/benchmark_cache_fields.ts

@@ -0,0 +1,158 @@
+/**
+ * The `cache` block of a benchmark / cost report — required fields, and the one
+ * legitimate way to not have a number (`road-to-runtime-context-floors` step 4.1).
+ *
+ * Both fields are REQUIRED. A report that cannot compute one states a reason; it
+ * does not omit the key and it does not emit a zero. A blank reads as "no cache
+ * activity" and a zero reads as "the worst possible ratio" — both are claims, and
+ * neither is the claim "this was not measured".
+ *
+ * Contract: `docs/contracts/benchmark-report-schema.md` § The `cache` block.
+ */
+
+export const REQUIRED_CACHE_FIELDS = ['read_write_ratio', 'stable_prefix_share'] as const;
+export type RequiredCacheField = (typeof REQUIRED_CACHE_FIELDS)[number];
+
+/**
+ * What produced the report (`road-to-delivered-cost-truth` step 4.2).
+ *
+ * A benchmark number without its provenance cannot be reproduced or challenged,
+ * and this repository carries a measured instance of that failure: an external
+ * round's headline figures are recorded `unverifiable` precisely because the run
+ * behind them is unreachable. These four keep a report here from becoming that.
+ */
+export const REQUIRED_PROVENANCE_FIELDS = [
+    'host_binary_hash',
+    'harness_commit',
+    'harness_dirty',
+    'reproducibility',
+] as const;
+export type RequiredProvenanceField = (typeof REQUIRED_PROVENANCE_FIELDS)[number];
+
+/** A measured number, or a stated reason there is none. Never a bare absence. */
+export type CacheFieldValue = number | { unavailable: string };
+
+export interface CacheBlock {
+    read_write_ratio: CacheFieldValue;
+    stable_prefix_share: CacheFieldValue;
+}
+
+export type AnyRequiredField = RequiredCacheField | RequiredProvenanceField;
+
+export type FieldProblem =
+    | { field: AnyRequiredField; kind: 'missing' }
+    | { field: AnyRequiredField; kind: 'blank-unavailable' }
+    | { field: AnyRequiredField; kind: 'not-a-number'; value: unknown }
+    | { field: AnyRequiredField; kind: 'out-of-range'; value: number }
+    | { field: AnyRequiredField; kind: 'blank-value' };
+
+export function unavailable(reason: string): CacheFieldValue {
+    return { unavailable: reason };
+}
+
+function validateField(field: RequiredCacheField, raw: unknown): FieldProblem | null {
+    if (raw === undefined || raw === null) return { field, kind: 'missing' };
+    if (typeof raw === 'object') {
+        const reason = (raw as { unavailable?: unknown }).unavailable;
+        if (typeof reason !== 'string' || reason.trim().length === 0) {
+            return { field, kind: 'blank-unavailable' };
+        }
+        return null;
+    }
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) return { field, kind: 'not-a-number', value: raw };
+    // A share is a fraction; a ratio is unbounded above but never negative.
+    if (raw < 0) return { field, kind: 'out-of-range', value: raw };
+    if (field === 'stable_prefix_share' && raw > 1) return { field, kind: 'out-of-range', value: raw };
+    return null;
+}
+
+/** Validate a report's `cache` block. Empty array = valid. */
+export function validateCacheBlock(report: unknown): FieldProblem[] {
+    const cache = (report as { cache?: unknown } | null)?.cache;
+    if (cache === undefined || cache === null || typeof cache !== 'object') {
+        return REQUIRED_CACHE_FIELDS.map((field) => ({ field, kind: 'missing' as const }));
+    }
+    const rec = cache as Record<string, unknown>;
+    return REQUIRED_CACHE_FIELDS.map((f) => validateField(f, rec[f])).filter((p): p is FieldProblem => p !== null);
+}
+
+function blockOf(field: AnyRequiredField): string {
+    return (REQUIRED_PROVENANCE_FIELDS as readonly string[]).includes(field) ? 'provenance' : 'cache';
+}
+
+export function describeProblem(p: FieldProblem): string {
+    const q = `${blockOf(p.field)}.${p.field}`;
+    switch (p.kind) {
+        case 'missing':
+            return `${q} is missing — it is required; emit { unavailable: "<reason>" } when it cannot be supplied`;
+        case 'blank-unavailable':
+            return `${q} declares itself unavailable with no reason — a reason is the whole point of the form`;
+        case 'blank-value':
+            return `${q} is an empty string, which states nothing; emit { unavailable: "<reason>" } instead`;
+        case 'not-a-number':
+            return `${q} is ${JSON.stringify(p.value)}, which is neither a number nor { unavailable: "<reason>" }`;
+        case 'out-of-range':
+            return `${q} is ${String(p.value)}, outside its valid range`;
+    }
+}
+
+/**
+ * Validate a report's `provenance` block.
+ *
+ * `harness_dirty` is a BOOLEAN and the others are strings, so the shape check is
+ * per-field rather than uniform — and `false` must pass, which a truthiness
+ * check would silently reject. That is the bug this comment exists to prevent on
+ * the next edit: a dirty flag of `false` is the good case.
+ */
+export function validateProvenanceBlock(report: unknown): FieldProblem[] {
+    const block = (report as { provenance?: unknown } | null)?.provenance;
+    if (block === undefined || block === null || typeof block !== 'object') {
+        return REQUIRED_PROVENANCE_FIELDS.map((field) => ({ field, kind: 'missing' as const }));
+    }
+    const rec = block as Record<string, unknown>;
+    const out: FieldProblem[] = [];
+    for (const field of REQUIRED_PROVENANCE_FIELDS) {
+        const raw = rec[field];
+        if (raw === undefined || raw === null) {
+            out.push({ field, kind: 'missing' });
+            continue;
+        }
+        if (typeof raw === 'object') {
+            const reason = (raw as { unavailable?: unknown }).unavailable;
+            if (typeof reason !== 'string' || reason.trim().length === 0) out.push({ field, kind: 'blank-unavailable' });
+            continue;
+        }
+        if (field === 'harness_dirty') {
+            if (typeof raw !== 'boolean') out.push({ field, kind: 'not-a-number', value: raw });
+            continue;
+        }
+        if (typeof raw !== 'string') out.push({ field, kind: 'not-a-number', value: raw });
+        else if (raw.trim().length === 0) out.push({ field, kind: 'blank-value' });
+    }
+    return out;
+}
+
+/**
+ * Compute the ratio from token totals, or state why not.
+ *
+ * Zero cache-creation tokens is the interesting case: the ratio is undefined,
+ * not infinite and not zero, and the honest report says so.
+ */
+export function readWriteRatio(cacheRead: number, cacheCreation: number): CacheFieldValue {
+    if (!Number.isFinite(cacheRead) || !Number.isFinite(cacheCreation)) {
+        return unavailable('the session source carries no cache_read/cache_creation token fields');
+    }
+    if (cacheCreation === 0) {
+        return unavailable('no cache-creation tokens were recorded in this window, so the ratio is undefined rather than zero');
+    }
+    return cacheRead / cacheCreation;
+}
+
+/** The STABLE cohort as a fraction of dispatches carrying the field, or why not. */
+export function stablePrefixShare(stableN: number, unstableN: number): CacheFieldValue {
+    const total = stableN + unstableN;
+    if (total === 0) {
+        return unavailable('no dispatch in this window recorded both payload_hash and cache_hit');
+    }
+    return stableN / total;
+}

package/src/scripts/_lib/candidate_pair_delta.ts

@@ -0,0 +1,349 @@
+/**
+ * The missing seam: two candidate records over one observation, and one signed
+ * delta per trial.
+ *
+ * A recorded search over this tree established that nothing read two
+ * {@link CandidateRecord}s and emitted a delta, a {@link PairedVerdict} or a
+ * {@link MetricVector}. The only live `decidePairedVerdict` caller runs over
+ * benchmark task pairs, the only paired-row construction is a deserialiser, and
+ * the evaluation cascade takes its vector from the caller. So the comparison a
+ * two-arm proposer experiment needs had no producer at all: the verdict
+ * function existed and nothing could feed it from candidates.
+ *
+ * This module is that producer, and it is deliberately the only thing it is.
+ *
+ * Everything about the SHAPE of the comparison is derived from constants
+ * committed before either arm existed: the sign convention from
+ * {@link PairedInput}'s own contract, the direction handling from
+ * {@link MetricDirection}, the tie epsilon from the value the A/B report
+ * already uses, the aggregation and the significance bar from
+ * {@link decidePairedVerdict}. What is NOT here is the outcome scalar itself.
+ * {@link TrialOutcome} is supplied by a caller, because choosing what a trial
+ * MEASURES is the one decision in this experiment that could favour an arm, and
+ * a module that invented one would be answering it in the wrong place. The
+ * artifact-count delta is supplied on the same terms and for a sharper reason:
+ * the pairing makes every pair-derived path count differ by exactly 0, so a
+ * derivation here would report a constant and call it a measurement.
+ *
+ * The honest consequence, stated rather than left to be discovered: this
+ * producer has no live population today. No shipped evaluator emits a
+ * {@link TrialOutcome} for a candidate over the frozen corpus, so every test
+ * here supplies its own. A producer with no population is exactly as honest as
+ * a guard with no caller, and the same disclosure applies.
+ */
+
+import type { CandidateRecord } from './candidate_record.js';
+import {
+    ARTIFACT_COUNT_METRIC,
+    buildVector,
+    type MetricDirection,
+    type MetricRow,
+    type MetricVector,
+} from './evaluation_vector.js';
+import { decidePairedVerdict, type PairedVerdict } from './paired_verdict.js';
+
+/**
+ * Deltas within this of zero are ties.
+ *
+ * NOT chosen here: it is the value the A/B report's own direction counts
+ * already use, and its reason is recorded there, that two definitions of a tie
+ * in one report is how the numbers start disagreeing. Restating that value
+ * rather than picking a fresh one keeps a candidate comparison and a bench
+ * comparison answering to the same notion of no difference.
+ */
+export const TIE_EPSILON = 1e-9;
+
+export class PairingError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PairingError';
+    }
+}
+
+/**
+ * The pairing key, derived from the record alone.
+ *
+ * A record carries no observation field, so the key is reconstructed from what
+ * it does carry: the mutation dimension and the sorted mutation paths. That is
+ * exactly the observation identity for this experiment, because each fixed
+ * recipe owns one dimension and each observation names one subject. Keying on
+ * the candidate id would pair nothing, since an id hashes the mutated bytes, so
+ * two arms that produced different text have different ids by construction,
+ * which is the whole reason there is something to compare.
+ */
+export function pairingKey(record: CandidateRecord): string {
+    const paths = record.mutations.map((m) => m.path).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return `${record.dimension} ${paths.join(' ')}`;
+}
+
+export interface CandidatePair {
+    readonly key: string;
+    readonly control: CandidateRecord;
+    readonly treatment: CandidateRecord;
+    /**
+     * The arms produced byte-identical mutations.
+     *
+     * Not an error and not silently dropped. It means every trial on this pair
+     * is a structural tie, so the pair contributes to the trial count and to no
+     * discordant count, and a reader who sees `underpowered` without this flag
+     * would look for the cause in the measurement rather than in the arms.
+     */
+    readonly identical_arms: boolean;
+}
+
+function serialiseMutations(r: CandidateRecord): string {
+    return [...r.mutations]
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .map((m) => `${m.path} ${m.content}`)
+        .join('');
+}
+
+/**
+ * Pair two arms' record sets, refusing every shape where half a pair exists.
+ *
+ * An unmatched record on either side is refused rather than dropped. Dropping
+ * it would make the trial count depend on which observations each arm happened
+ * to satisfy, and a comparison whose denominator is chosen by one of the arms
+ * is not a paired comparison.
+ */
+export function pairCandidates(
+    control: readonly CandidateRecord[],
+    treatment: readonly CandidateRecord[],
+): CandidatePair[] {
+    const byKey = new Map<string, CandidateRecord>();
+    for (const r of treatment) {
+        const k = pairingKey(r);
+        if (byKey.has(k)) {
+            throw new PairingError(
+                `treatment arm emitted two records for '${k}': one observation is one candidate ` +
+                    'per arm, and a second would make the pairing pick a winner before any trial ran',
+            );
+        }
+        byKey.set(k, r);
+    }
+    const out: CandidatePair[] = [];
+    const seen = new Set<string>();
+    for (const c of control) {
+        const k = pairingKey(c);
+        if (seen.has(k)) {
+            throw new PairingError(`control arm emitted two records for '${k}'`);
+        }
+        seen.add(k);
+        const t = byKey.get(k);
+        if (t === undefined) {
+            throw new PairingError(
+                `no treatment record for '${k}': half a pair is no result, not a partial one`,
+            );
+        }
+        out.push({
+            key: k,
+            control: c,
+            treatment: t,
+            identical_arms: serialiseMutations(c) === serialiseMutations(t),
+        });
+    }
+    for (const k of byKey.keys()) {
+        if (!seen.has(k)) {
+            throw new PairingError(
+                `no control record for '${k}': the treatment arm ran an observation the control did not`,
+            );
+        }
+    }
+    return out;
+}
+
+/**
+ * One measured trial: the same scalar, on both arms, under the same conditions.
+ *
+ * Both values are required. An absent arm is refused rather than imputed,
+ * because imputing it would put a number the run did not observe into a
+ * denominator that decides a verdict.
+ */
+export interface TrialOutcome {
+    /**
+     * Unique across the WHOLE comparison, not merely within its pair.
+     *
+     * Stated rather than left implicit, because the two readings differ in what
+     * they refuse and the ambiguity was the defect. `pairedDeltas` refuses a
+     * repeat within one call and cannot see across pairs; {@link compareArms}
+     * pools every pair's deltas into ONE sample, and the denominator of that
+     * sample is what the sign test adjudicates. A caller that derives the
+     * outcomes map wrongly — the realistic shape being the same measurement
+     * array reached under two keys — then contributes one set of deltas twice.
+     * Under a pair-scoped reading that is undetectable; under this one it is a
+     * refusal, and the cost is that a caller names its trials per pair.
+     */
+    readonly trial_id: string;
+    readonly control: number;
+    readonly treatment: number;
+}
+
+/**
+ * The signed deltas for one pair. Positive favours the TREATMENT, always.
+ *
+ * The convention is not this module's to set: the verdict's own input contract
+ * states one signed delta per trial with positive favouring the treatment, so
+ * the direction handling here is a translation of {@link MetricDirection} into
+ * that fixed convention rather than a second convention beside it. For a
+ * lower-better metric the subtraction is reversed, so a caller never has to
+ * remember which endpoint it is looking at.
+ */
+export function pairedDeltas(
+    outcomes: readonly TrialOutcome[],
+    direction: MetricDirection,
+): number[] {
+    if (outcomes.length === 0) {
+        throw new PairingError(
+            'no trials: a verdict over zero trials is a fabricated result, not an empty one',
+        );
+    }
+    const ids = new Set<string>();
+    for (const o of outcomes) {
+        if (ids.has(o.trial_id)) {
+            throw new PairingError(
+                `duplicate trial id '${o.trial_id}': one trial counted twice inflates the discordant count`,
+            );
+        }
+        ids.add(o.trial_id);
+        if (!Number.isFinite(o.control) || !Number.isFinite(o.treatment)) {
+            throw new PairingError(
+                `trial '${o.trial_id}' carries a non-finite outcome: an unmeasured trial is absent, never zero`,
+            );
+        }
+    }
+    return outcomes.map((o) =>
+        direction === 'higher-better' ? o.treatment - o.control : o.control - o.treatment,
+    );
+}
+
+export interface PairComparison {
+    readonly pairs: readonly CandidatePair[];
+    readonly trials: number;
+    readonly verdict: PairedVerdict;
+    /** Pairs whose arms produced identical bytes, so every one of their trials tied. */
+    readonly identical_pairs: readonly string[];
+}
+
+export interface ComparisonInput {
+    readonly control: readonly CandidateRecord[];
+    readonly treatment: readonly CandidateRecord[];
+    /** Trials keyed by pairing key. Every pair must carry at least one. */
+    readonly outcomes: Readonly<Record<string, readonly TrialOutcome[]>>;
+    readonly direction: MetricDirection;
+}
+
+/**
+ * The comparison, pooled across pairs.
+ *
+ * Pooling is what raises the experiment off the discordant floor: with one
+ * delta per pair the trial count equals the corpus size, which sits exactly on
+ * the derived floor, so a single dissent makes a pass arithmetically
+ * unreachable before the run starts. Pooling per-trial deltas across pairs
+ * makes the count the number of TRIALS rather than the number of pairs.
+ *
+ * The assumption that buys it is stated rather than assumed away: the exact
+ * sign test treats each delta as an independent draw, and trials on the same
+ * pair share a subject. A caller that cannot defend that independence should
+ * pass one aggregate delta per pair and accept the smaller sample, which this
+ * function supports by simply being given fewer trials.
+ */
+export function compareArms(input: ComparisonInput): PairComparison {
+    const pairs = pairCandidates(input.control, input.treatment);
+    const keys = new Set(pairs.map((p) => p.key));
+    for (const k of Object.keys(input.outcomes)) {
+        if (!keys.has(k)) {
+            throw new PairingError(
+                `outcomes carry key '${k}', which matches no pair: the key is a formatted string ` +
+                    'the caller derives rather than receives, so an unmatched one is a mis-derived ' +
+                    'or stale measurement set, and pooling only the keys that happened to match ' +
+                    'is the same silently smaller denominator the opposite refusal names',
+            );
+        }
+    }
+    const deltas: number[] = [];
+    const seenTrials = new Set<string>();
+    for (const p of pairs) {
+        const trials = input.outcomes[p.key];
+        if (trials === undefined || trials.length === 0) {
+            throw new PairingError(
+                `pair '${p.key}' has no trials: a pair present in the arms and absent from the ` +
+                    'measurements silently shrinks the denominator',
+            );
+        }
+        for (const t of trials) {
+            if (seenTrials.has(t.trial_id)) {
+                throw new PairingError(
+                    `trial id '${t.trial_id}' appears on more than one pair: the refusal in ` +
+                        'pairedDeltas is scoped to one pair and cannot see a reuse across pairs, ' +
+                        'and one trial counted twice inflates the discordant count either way',
+                );
+            }
+            seenTrials.add(t.trial_id);
+        }
+        deltas.push(...pairedDeltas(trials, input.direction));
+    }
+    return {
+        pairs,
+        trials: deltas.length,
+        verdict: decidePairedVerdict({ deltas, tieEpsilon: TIE_EPSILON }),
+        identical_pairs: pairs.filter((p) => p.identical_arms).map((p) => p.key),
+    };
+}
+
+/**
+ * The comparison as a metric vector the evaluation cascade can consume.
+ *
+ * The artifact-count row is not optional: {@link buildVector} refuses a vector
+ * without it, so a candidate cannot reach the promotion verdict without its
+ * artifact delta having been measured. The delta is SUPPLIED here rather than
+ * derived, and the reason is the same one that keeps {@link TrialOutcome} out
+ * of this module.
+ *
+ * Why this module cannot derive it. {@link pairingKey} folds the sorted mutation-path list into the key and
+ * {@link pairCandidates} forms a pair only on an exact key match, so control
+ * and treatment of every pair carry identical path multisets by construction.
+ * Any count taken over those paths therefore differs by exactly 0 for every
+ * pair and every candidate — not usually, but always. A row filled that way
+ * satisfies the builder's SHAPE check while making the ceiling branch in
+ * `promotionVerdict` unreachable, which defeats the invariant the shape
+ * check exists to carry: the vector would be refused for omitting the row and
+ * accepted for carrying a constant.
+ *
+ * The quantity the gate actually names is baseline-relative growth — how many
+ * artifacts the candidate ADDS to the tree it is a variant of. That is a fact
+ * about the candidate against an unmutated baseline, and this module sees
+ * neither the baseline nor the filesystem. So the caller that knows which
+ * mutated paths are new files passes the count, and a caller that has not
+ * measured it has nothing to pass.
+ *
+ * @param artifactDelta signed count of artifacts the candidate adds against
+ *   its baseline. Must be a finite integer; a fractional or non-finite value is
+ *   refused rather than rounded, because a rounded ceiling comparison is a
+ *   verdict on a number nobody measured.
+ * @throws {PairingError} when `artifactDelta` is not a finite integer.
+ */
+export function comparisonVector(
+    candidate_id: string,
+    metric: string,
+    direction: MetricDirection,
+    comparison: PairComparison,
+    artifactDelta: number,
+): MetricVector {
+    if (!Number.isInteger(artifactDelta)) {
+        throw new PairingError(
+            `artifact delta ${String(artifactDelta)} is not a finite integer: the artifact-count ` +
+                'row is a count of artifacts, and a gate that compared a fraction against its ' +
+                'ceiling would be adjudicating a quantity the run never observed',
+        );
+    }
+    const rows: MetricRow[] = [
+        { kind: 'paired', metric, direction, verdict: comparison.verdict },
+        {
+            kind: 'counted',
+            metric: ARTIFACT_COUNT_METRIC,
+            direction: 'lower-better',
+            delta: artifactDelta,
+        },
+    ];
+    return buildVector(candidate_id, rows);
+}