@gaunt-sloth/batch 2.0.0-beta.9 → 2.0.0

package/dist/bin.d.ts

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
 /**
- * @module bin
- *
  * BATCH-9 — the `gth-batch` executable. A minimal shebang wrapper around {@link runBatchCli}
  * (pipelineCli.ts) whose only job beyond delegating is to keep **stdout a clean machine channel**: the
  * batch runtime's human/status/streaming output all lands on `process.stdout` (via
@@ -9,5 +7,7 @@
  * for the duration of the run. The JSONL cell records are written straight to fd 1 inside
  * `runBatchCli` (`fs.writeSync`), bypassing this redirect — the same "protocol channel" discipline
  * `packages/app/cli.js` uses for the ACP stdio channel.
+ *
+ * @module
  */
 export {};

package/dist/bin.js

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
 /**
- * @module bin
- *
  * BATCH-9 — the `gth-batch` executable. A minimal shebang wrapper around {@link runBatchCli}
  * (pipelineCli.ts) whose only job beyond delegating is to keep **stdout a clean machine channel**: the
  * batch runtime's human/status/streaming output all lands on `process.stdout` (via
@@ -9,6 +7,8 @@
  * for the duration of the run. The JSONL cell records are written straight to fd 1 inside
  * `runBatchCli` (`fs.writeSync`), bypassing this redirect — the same "protocol channel" discipline
  * `packages/app/cli.js` uses for the ACP stdio channel.
+ *
+ * @module
  */
 import { runBatchCli } from '#src/pipelineCli.js';
 const originalStdoutWrite = process.stdout.write.bind(process.stdout);

package/dist/classificationReport.d.ts

@@ -4,8 +4,8 @@ import type { ClassifiedCell, EvalClassificationReport, EvalClassificationSpec,
  * per tag), every declared metric (overall and per tag), the corpus-wide coverage, and the list of
  * `gate: fail` metrics that were breached.
  *
- * Kept separate from both the extractor ({@link ./classification.js}) and the metric engine
- * ({@link ./metrics.js}) so neither imports the other, and so the whole aggregation is exercisable
+ * Kept separate from both the extractor ({@link @gaunt-sloth/batch!"classification.js" | ./classification.js}) and the metric engine
+ * ({@link @gaunt-sloth/batch!"metrics.js" | ./metrics.js}) so neither imports the other, and so the whole aggregation is exercisable
  * from a plain array of {@link ClassifiedCell}s with no runner, no I/O, and no model.
  */
 export declare function buildClassificationReport(spec: EvalClassificationSpec, metricSpecs: EvalMetricSpec[], cells: ClassifiedCell[]): EvalClassificationReport;

package/dist/classificationReport.js

@@ -6,8 +6,8 @@ import { UNRECOGNIZED_LABEL } from '#src/classificationTypes.js';
  * per tag), every declared metric (overall and per tag), the corpus-wide coverage, and the list of
  * `gate: fail` metrics that were breached.
  *
- * Kept separate from both the extractor ({@link ./classification.js}) and the metric engine
- * ({@link ./metrics.js}) so neither imports the other, and so the whole aggregation is exercisable
+ * Kept separate from both the extractor ({@link @gaunt-sloth/batch!"classification.js" | ./classification.js}) and the metric engine
+ * ({@link @gaunt-sloth/batch!"metrics.js" | ./metrics.js}) so neither imports the other, and so the whole aggregation is exercisable
  * from a plain array of {@link ClassifiedCell}s with no runner, no I/O, and no model.
  */
 export function buildClassificationReport(spec, metricSpecs, cells) {

package/dist/classificationTypes.d.ts

@@ -3,7 +3,7 @@
  * BATCH-25 — the shapes for a CLASSIFIER eval: a suite-declared label/action enum, the extractors
  * that turn a SUT answer into a label, the confusion matrix, and declared aggregate metrics.
  *
- * Deliberately its own file rather than more weight in {@link ./evalTypes.js}: eval's per-case
+ * Deliberately its own file rather than more weight in `evalTypes.js`: eval's per-case
  * PASS/FAIL shapes and a classifier's corpus-wide *distribution* shapes answer different questions,
  * and only the latter needs the anti-blind-metric machinery below.
  *
@@ -91,7 +91,7 @@ export interface EvalClassificationSpec {
  *
  * There is deliberately **no `model.action`**: the deterministic layer overrides the label and
  * produces the action, so an "action the model chose" does not exist and a predicate on it could
- * never match. {@link ./metrics.js parseMetricPredicate} rejects it by name.
+ * never match. {@link "metrics.js"!parseMetricPredicate | parseMetricPredicate} rejects it by name.
  */
 export type MetricField = 'expected.label' | 'expected.action' | 'actual.label' | 'actual.action' | 'model.label';
 /** The literal `none` in a predicate — matches a cell where that field is absent. */
@@ -267,7 +267,7 @@ export interface EvalConfusionMatrix {
 }
 /**
  * The suite-level classification report — the classifier eval's answer, attached to
- * {@link ./evalTypes.js EvalSuiteSummary}. Absent entirely for a suite that declares no
+ * {@link "evalTypes.js"!EvalSuiteSummary | EvalSuiteSummary}. Absent entirely for a suite that declares no
  * `classification:` block, so a #405-era suite's `results.json` is unchanged.
  */
 export interface EvalClassificationReport {
@@ -295,7 +295,7 @@ export interface EvalClassificationReport {
 }
 /**
  * One graded cell reduced to what the matrices and the metrics need. Built by
- * {@link ../evalRunner.js} from the graded results; its own tiny shape so both consumers read the
+ * `evalRunner.js` from the graded results; its own tiny shape so both consumers read the
  * same thing and the aggregation is unit-testable without constructing whole `EvalCaseResult`s.
  */
 export interface ClassifiedCell {
@@ -307,13 +307,13 @@ export interface ClassifiedCell {
     actualAction?: string;
     /** BATCH-26 — the judgement the MODEL rendered, read by `model.label`. Equal to
      * {@link actualLabel} except where a deterministic step raised it; absent when nobody judged. See
-     * {@link ./evalTypes.js ClassifyOutcome.modelLabel}. */
+     * {@link "evalTypes.js"!ClassifyOutcome.modelLabel | ClassifyOutcome.modelLabel}. */
     modelLabel?: string;
     /** `false` = the SUT did not run / the classifier failed, so this cell has no place in any matrix
      * or denominator. It is counted as `excluded` and reported, never as a wrong answer. */
     scored: boolean;
 }
-/** One cell's classification, as recorded on its {@link ./evalTypes.js EvalCaseResult}. */
+/** One cell's classification, as recorded on its {@link "evalTypes.js"!EvalCaseResult | EvalCaseResult}. */
 export interface EvalCaseClassification {
     expectedLabel?: string;
     expectedAction?: string;
@@ -322,7 +322,7 @@ export interface EvalCaseClassification {
     /** BATCH-26 — the judgement the MODEL rendered, before any deterministic step overrode it. Equal
      * to {@link actualLabel} except where one did; absent when nobody judged. Written to the cell's
      * `results.json` so a floored case is diagnosable without re-running, and read by a `model.label`
-     * metric. See {@link ./evalTypes.js ClassifyOutcome.modelLabel}. */
+     * metric. See {@link "evalTypes.js"!ClassifyOutcome.modelLabel | ClassifyOutcome.modelLabel}. */
     modelLabel?: string;
     /** The raw text the extractors read, kept so an `(unrecognized)` result is diagnosable without
      * re-running. Omitted when it is identical to the cell's `answer`. */

package/dist/classificationTypes.js

@@ -3,7 +3,7 @@
  * BATCH-25 — the shapes for a CLASSIFIER eval: a suite-declared label/action enum, the extractors
  * that turn a SUT answer into a label, the confusion matrix, and declared aggregate metrics.
  *
- * Deliberately its own file rather than more weight in {@link ./evalTypes.js}: eval's per-case
+ * Deliberately its own file rather than more weight in `evalTypes.js`: eval's per-case
  * PASS/FAIL shapes and a classifier's corpus-wide *distribution* shapes answer different questions,
  * and only the latter needs the anti-blind-metric machinery below.
  *

package/dist/evalCompare.d.ts

@@ -1,4 +1,5 @@
 import type { EvalSuite, EvalSuiteSummary, EvalSweep } from '#src/evalTypes.js';
+import type { RaterPromptArm } from '#src/raterPromptArm.js';
 /**
  * BATCH-25 — the comparison layer: run the same corpus across a sweep of configurations and emit
  * ONE comparison table, and diff a run against a previous one.
@@ -30,6 +31,16 @@ export interface SweepCell {
     model?: string;
     /** The merged plain-data config overrides for this cell. */
     config: Record<string, unknown>;
+    /**
+     * [[BATCH-31]] — the cell's rater prompt arm, when an axis value declares one.
+     *
+     * **A sibling of {@link config}, never a key inside it, and that separation is the facility's
+     * first enforcement leg.** `initConfigForCell` deep-merges `config` onto the resolved `GthConfig`
+     * and nothing else; keeping the arm out of it is what makes the omission unable to become a
+     * config value — and therefore unable to be written in a config file, an env var or a CLI flag,
+     * the three carriers that would make it reachable from a live session's approvals gate.
+     */
+    notes?: RaterPromptArm;
 }
 /**
  * Expand a {@link EvalSweep} into its cartesian product of cells, in declared axis order.
@@ -71,6 +82,101 @@ export interface RunDiffEntry {
     before: string;
     after: string;
 }
+/**
+ * BATCH-33 — how a run-over-run JUDGE-SCORE drift report is filtered.
+ *
+ * ## Why there is a filter at all, and why the raw form is not a member of this union
+ *
+ * A judge score is a model's 0-10 opinion, and it wobbles between identical runs. Reporting every
+ * per-case delta therefore prints a section on every run, most of it noise, and trains the reader to
+ * skip it — at which point the real slide is skipped along with it. That is strictly WORSE than
+ * reporting no drift at all: a section nobody reads still spends the run's credibility, which is the
+ * same failure BATCH-25's untrusted metric ran into.
+ *
+ * So the raw unfiltered form is deliberately not representable. There is no `all` member, and no
+ * value of the knobs below reaches one — {@link parseJudgeDriftFilter} rejects `min:0` and bounds
+ * the threshold-ward tolerance, because a knob that admits its own degenerate value ships the form
+ * this type exists to withhold.
+ *
+ * ## What each member is for
+ *
+ * - `threshold-ward` (**the default**) — report a case only when its score CROSSED the pass
+ *   threshold, or moved DOWN to within `tolerance` points of it. Distance to the gate is the thing
+ *   worth alerting on: a 10 → 8 that stays clear of a gate at 6 is a different event from a 7 → 6
+ *   sitting on it, and only the second is about to cost a verdict. It is the default because it is
+ *   the one filter whose false-positive rate on a stable suite is near zero: at the default
+ *   tolerance a score must land at or below its own gate to report, so a corpus grading anywhere
+ *   above its gate wobbles freely and prints nothing.
+ * - `min-points` — report any movement of at least N points, either direction. The blunt
+ *   instrument: it sees large swings wherever they land, and pays for that by firing on a wobbly
+ *   judge no matter how much headroom the case had.
+ * - `mean` — report only the suite-level mean. Averaging over the corpus cancels the wobble, so it
+ *   is the quietest form of all and the one that cannot say WHICH case moved.
+ * - `off` — no drift report. Opting out is not the raw form; it prints less, not more.
+ */
+export type JudgeDriftFilter = {
+    mode: 'threshold-ward';
+    tolerance: number;
+} | {
+    mode: 'min-points';
+    points: number;
+} | {
+    mode: 'mean';
+} | {
+    mode: 'off';
+};
+/**
+ * How many points above the gate still counts as sitting ON it, when the caller names no tolerance.
+ *
+ * Zero, and the reason is a measurement rather than a preference. A local judge asked to re-rate one
+ * fixed answer against one fixed rubric twelve times returned rates spanning a full point (7 and 8,
+ * on the same input every time). So one point of movement carries no information: it is the width of
+ * the noise. A shoulder of 1 would report every cell that wobbled from 8 to 7 against the default
+ * gate of 6 — an ordinary judged suite grades right there, so the section would fire on a stable
+ * re-run, which is the one failure this node exists to avoid.
+ *
+ * At zero the rule still reports both movements the node names: a 7 → 6 lands ON the gate and
+ * reports, a 10 → 8 stays clear and does not. The shoulder was buying nothing those two clauses did
+ * not already cover, and was costing exactly the measured noise band. Widen it deliberately with
+ * `--drift threshold-ward:<n>` on a corpus whose judge is steadier than this.
+ */
+export declare const DEFAULT_JUDGE_DRIFT_TOLERANCE = 0;
+/**
+ * The widest tolerance a caller may ask for. The judge scale is 0-10 and a typical gate is 6, so a
+ * shoulder much wider than this covers the whole usable band and every downward move reports —
+ * the unfiltered form by another route, which is what the bound exists to refuse.
+ */
+export declare const MAX_JUDGE_DRIFT_TOLERANCE = 3;
+/** The filter {@link diffRuns} applies when the caller names none. */
+export declare const DEFAULT_JUDGE_DRIFT_FILTER: JudgeDriftFilter;
+/**
+ * Parse a `--drift` spec into a {@link JudgeDriftFilter}, throwing on anything unrecognised —
+ * including the degenerate values that would reconstitute the raw per-case report.
+ *
+ * Accepted: `threshold-ward` (or `threshold-ward:<tolerance>`), `min:<points>`, `mean`, `off`.
+ */
+export declare function parseJudgeDriftFilter(spec: string): JudgeDriftFilter;
+/** One case whose JUDGE SCORE moved between two runs, as kept by a {@link JudgeDriftFilter}. */
+export interface JudgeDriftEntry {
+    id: string;
+    before: number;
+    after: number;
+    /** `after - before`. Negative is a slide toward the gate. */
+    delta: number;
+    /** The gate the movement is measured against — THIS run's, since that is the one now in force. */
+    passThreshold: number;
+    /** Why the filter kept it: the score crossed the gate, slid onto the gate's shoulder, or simply
+     * moved far enough for a `min-points` filter. */
+    reason: 'crossed' | 'near-threshold' | 'moved';
+}
+/** The suite-level judge-score mean — the `mean` filter's whole output. */
+export interface JudgeDriftMean {
+    before: number;
+    after: number;
+    delta: number;
+    /** Cases carrying a rate on BOTH sides, i.e. the mean's denominator. */
+    cases: number;
+}
 /** The run-over-run diff. */
 export interface RunDiff {
     /** Cases in both runs. */
@@ -88,6 +194,20 @@ export interface RunDiff {
         after: number | null;
         delta: number | null;
     }[];
+    /**
+     * BATCH-33 — per-case judge-score movements the active filter kept. The signal a VERDICT-only
+     * diff structurally cannot see: a judge-graded suite with no `classification:` block has neither
+     * `reclassified` nor `metricDeltas`, so before this its diff was strictly binary and a score
+     * sliding toward its gate reported "no change." until the run it finally broke.
+     *
+     * EMPTY under the `mean` and `off` filters, which report no per-case rows at all.
+     */
+    judgeDrift: JudgeDriftEntry[];
+    /** The suite-level mean, under the `mean` filter only. */
+    judgeDriftMean?: JudgeDriftMean;
+    /** The filter that produced the two fields above, echoed so the render can name it: a quiet drift
+     * section means nothing unless the reader can see WHICH filter was quiet. */
+    judgeDriftFilter: JudgeDriftFilter;
     /** Ids in only one of the two runs — reported, so a shrunken corpus cannot read as "no change". */
     onlyInBefore: string[];
     onlyInAfter: string[];
@@ -100,8 +220,15 @@ export interface RunDiff {
  * gate reads, verdict fixes are what a change claims to have done, and RECLASSIFICATIONS are what
  * a prompt edit actually moved — a case can keep its verdict while the label underneath it changes,
  * and that is exactly the drift a pass-rate comparison cannot see.
+ *
+ * A fourth, {@link RunDiff.judgeDrift}, covers the suites the other three cannot: `reclassified`
+ * and `metricDeltas` both need a `classification:` block, so an ordinary judge-graded corpus got a
+ * strictly binary diff and learned nothing until a score finally broke its gate. `filter` decides
+ * how much of that movement is worth printing — see {@link JudgeDriftFilter} for why it defaults to
+ * the threshold-ward one and why the unfiltered form is not on offer. **The default lives here, not
+ * only in the CLI**, so every caller gets the quiet behaviour without having to know to ask.
  */
-export declare function diffRuns(before: EvalSuiteSummary, after: EvalSuiteSummary): RunDiff;
+export declare function diffRuns(before: EvalSuiteSummary, after: EvalSuiteSummary, filter?: JudgeDriftFilter): RunDiff;
 /** Render a {@link RunDiff} as plain lines. */
 export declare function renderRunDiff(diff: RunDiff): string[];
 /** Does this suite declare a sweep? Small helper so the command reads declaratively. */

package/dist/evalCompare.js

@@ -20,17 +20,24 @@ export function expandSweep(sweep) {
     return cells.map((cell) => {
         let model;
         let config = {};
+        // [[BATCH-31]] — the arm follows `model`'s rule, not `config`'s: a later axis REPLACES it rather
+        // than merging. Two axes declaring arms are describing the same knob twice (the cell name shows
+        // it), and a union of their omissions would build a third arm neither axis wrote.
+        let notes;
         for (const part of cell.parts) {
             if (part.value.model !== undefined)
                 model = part.value.model;
             if (part.value.config)
                 config = deepMerge(config, part.value.config);
+            if (part.value.notes !== undefined)
+                notes = part.value.notes;
         }
         return {
             name: cell.parts.map((part) => `${part.axis}=${part.value.name}`).join(' · '),
             dirName: cell.parts.map((part) => `${part.axis}-${part.value.name}`).join('__'),
             model,
             config,
+            ...(notes !== undefined ? { notes } : {}),
         };
     });
 }
@@ -128,6 +135,137 @@ function cellMetricValue(column, metricName, tag) {
         return 'n/a';
     return formatTally(tally);
 }
+/**
+ * How many points above the gate still counts as sitting ON it, when the caller names no tolerance.
+ *
+ * Zero, and the reason is a measurement rather than a preference. A local judge asked to re-rate one
+ * fixed answer against one fixed rubric twelve times returned rates spanning a full point (7 and 8,
+ * on the same input every time). So one point of movement carries no information: it is the width of
+ * the noise. A shoulder of 1 would report every cell that wobbled from 8 to 7 against the default
+ * gate of 6 — an ordinary judged suite grades right there, so the section would fire on a stable
+ * re-run, which is the one failure this node exists to avoid.
+ *
+ * At zero the rule still reports both movements the node names: a 7 → 6 lands ON the gate and
+ * reports, a 10 → 8 stays clear and does not. The shoulder was buying nothing those two clauses did
+ * not already cover, and was costing exactly the measured noise band. Widen it deliberately with
+ * `--drift threshold-ward:<n>` on a corpus whose judge is steadier than this.
+ */
+export const DEFAULT_JUDGE_DRIFT_TOLERANCE = 0;
+/**
+ * The widest tolerance a caller may ask for. The judge scale is 0-10 and a typical gate is 6, so a
+ * shoulder much wider than this covers the whole usable band and every downward move reports —
+ * the unfiltered form by another route, which is what the bound exists to refuse.
+ */
+export const MAX_JUDGE_DRIFT_TOLERANCE = 3;
+/** The filter {@link diffRuns} applies when the caller names none. */
+export const DEFAULT_JUDGE_DRIFT_FILTER = {
+    mode: 'threshold-ward',
+    tolerance: DEFAULT_JUDGE_DRIFT_TOLERANCE,
+};
+/**
+ * Parse a `--drift` spec into a {@link JudgeDriftFilter}, throwing on anything unrecognised —
+ * including the degenerate values that would reconstitute the raw per-case report.
+ *
+ * Accepted: `threshold-ward` (or `threshold-ward:<tolerance>`), `min:<points>`, `mean`, `off`.
+ */
+export function parseJudgeDriftFilter(spec) {
+    const parts = spec.trim().split(':');
+    if (parts.length > 2)
+        throw new Error(driftSpecError(spec));
+    const mode = parts[0].trim().toLowerCase();
+    const value = parts[1];
+    if (mode === 'off' || mode === 'mean') {
+        if (value !== undefined)
+            throw new Error(driftSpecError(spec));
+        return mode === 'off' ? { mode: 'off' } : { mode: 'mean' };
+    }
+    if (mode === 'min') {
+        const points = driftNumber(value, spec);
+        // 0 or less would keep every movement — the unfiltered report this filter exists to avoid.
+        if (points < 1 || points > 10) {
+            throw new Error(`--drift min:<points> takes 1-10, so "${spec}" is not accepted: it would report every ` +
+                'judge-score movement, which is the unfiltered form that trains readers to skip the ' +
+                'section.');
+        }
+        return { mode: 'min-points', points };
+    }
+    if (mode === 'threshold-ward' || mode === 'threshold') {
+        if (value === undefined)
+            return { mode: 'threshold-ward', tolerance: DEFAULT_JUDGE_DRIFT_TOLERANCE };
+        const tolerance = driftNumber(value, spec);
+        if (tolerance < 0 || tolerance > MAX_JUDGE_DRIFT_TOLERANCE) {
+            throw new Error(`--drift threshold-ward:<tolerance> takes 0-${MAX_JUDGE_DRIFT_TOLERANCE}, so "${spec}" is ` +
+                'not accepted: a shoulder that wide reports nearly every downward move, which is the ' +
+                'unfiltered form that trains readers to skip the section.');
+        }
+        return { mode: 'threshold-ward', tolerance };
+    }
+    throw new Error(driftSpecError(spec));
+}
+function driftSpecError(spec) {
+    return (`unrecognised --drift filter "${spec}". Use "threshold-ward" (the default, optionally ` +
+        `"threshold-ward:<0-${MAX_JUDGE_DRIFT_TOLERANCE}>"), "min:<1-10>", "mean", or "off".`);
+}
+function driftNumber(raw, spec) {
+    if (raw === undefined || raw.trim() === '')
+        throw new Error(driftSpecError(spec));
+    const value = Number(raw.trim());
+    if (!Number.isInteger(value))
+        throw new Error(driftSpecError(spec));
+    return value;
+}
+/**
+ * The judge rate representing one CELL, or `undefined` when no verdict was rendered for it.
+ *
+ * A single-turn cell carries its own {@link EvalCaseResult.judge}. A MULTI-TURN cell leaves that
+ * unset and grades per turn, so its representative rate is the LOWEST any turn scored: the cell
+ * passes iff every turn passes, which makes the weakest turn the one sitting nearest the gate and
+ * therefore the one this report is about. Reading only the top-level field would hand every
+ * multi-turn suite an empty drift section forever — the same silence this node exists to end.
+ */
+function judgeRateOf(result) {
+    const direct = rateOfOutcome(result.judge);
+    if (direct !== undefined)
+        return direct;
+    const turnRates = (result.turns ?? [])
+        .map((turn) => rateOfOutcome(turn.judge))
+        .filter((rate) => rate !== undefined);
+    return turnRates.length === 0 ? undefined : Math.min(...turnRates);
+}
+/** A usable 0-10 rate, or `undefined`. A judge that errored, timed out, returned something
+ * unparseable or was never asked has no score to compare, and substituting one would report a slide
+ * nobody measured. */
+function rateOfOutcome(judge) {
+    if (judge?.ok !== true)
+        return undefined;
+    const rate = judge.verdict?.rate;
+    return typeof rate === 'number' && Number.isFinite(rate) ? rate : undefined;
+}
+/**
+ * Does one movement survive the filter? Returns the reason it was kept, or `undefined`.
+ *
+ * The threshold-ward rule is two clauses and BOTH are load-bearing:
+ *
+ * - a CROSSING of the gate, either direction, always reports. That is the moment the score changed
+ *   what it is worth, and its numbers are what explain the verdict flip printed beside it.
+ * - otherwise, only a DOWNWARD move landing within `tolerance` of the gate. Direction alone is not
+ *   the rule — a 10 → 8 is downward and still clear of a gate at 6, and keeping it is exactly how
+ *   the section fills with wobble. Proximity alone is not the rule either, or a case recovering
+ *   6 → 7 would report. It is the pair, and a reader tempted to simplify one clause away should
+ *   expect the section to go noisy on the next stable re-run.
+ */
+function driftReason(before, after, passThreshold, filter) {
+    if (filter.mode === 'min-points') {
+        return Math.abs(after - before) >= filter.points ? 'moved' : undefined;
+    }
+    if (filter.mode !== 'threshold-ward')
+        return undefined;
+    if (before >= passThreshold !== after >= passThreshold)
+        return 'crossed';
+    if (after < before && after <= passThreshold + filter.tolerance)
+        return 'near-threshold';
+    return undefined;
+}
 /** The key a cell is diffed on across runs: id plus identity, since a matrix cell's id alone is
  * ambiguous. */
 function diffKey(result) {
@@ -140,19 +278,44 @@ function diffKey(result) {
  * gate reads, verdict fixes are what a change claims to have done, and RECLASSIFICATIONS are what
  * a prompt edit actually moved — a case can keep its verdict while the label underneath it changes,
  * and that is exactly the drift a pass-rate comparison cannot see.
+ *
+ * A fourth, {@link RunDiff.judgeDrift}, covers the suites the other three cannot: `reclassified`
+ * and `metricDeltas` both need a `classification:` block, so an ordinary judge-graded corpus got a
+ * strictly binary diff and learned nothing until a score finally broke its gate. `filter` decides
+ * how much of that movement is worth printing — see {@link JudgeDriftFilter} for why it defaults to
+ * the threshold-ward one and why the unfiltered form is not on offer. **The default lives here, not
+ * only in the CLI**, so every caller gets the quiet behaviour without having to know to ask.
  */
-export function diffRuns(before, after) {
+export function diffRuns(before, after, filter = DEFAULT_JUDGE_DRIFT_FILTER) {
     const beforeByKey = new Map(before.cases.map((result) => [diffKey(result), result]));
     const afterByKey = new Map(after.cases.map((result) => [diffKey(result), result]));
     const regressed = [];
     const fixed = [];
     const reclassified = [];
+    const ratePairs = [];
+    let lostRates = 0;
+    let movedGates = 0;
     let compared = 0;
     for (const [key, afterCase] of afterByKey) {
         const beforeCase = beforeByKey.get(key);
         if (!beforeCase)
             continue;
         compared += 1;
+        const beforeRate = judgeRateOf(beforeCase);
+        const afterRate = judgeRateOf(afterCase);
+        if (beforeRate !== undefined && afterRate !== undefined) {
+            ratePairs.push({
+                key,
+                before: beforeRate,
+                after: afterRate,
+                passThreshold: afterCase.passThreshold,
+            });
+            if (beforeCase.passThreshold !== afterCase.passThreshold)
+                movedGates += 1;
+        }
+        else if (beforeRate !== undefined) {
+            lostRates += 1;
+        }
         if (beforeCase.verdict === 'PASS' && afterCase.verdict === 'FAIL') {
             regressed.push({ id: key, before: 'PASS', after: 'FAIL' });
         }
@@ -181,7 +344,48 @@ export function diffRuns(before, after) {
             delta: beforeValue === null || afterValue === null ? null : afterValue - beforeValue,
         });
     }
+    // BATCH-33 — the judge-score drift, as much of it as the filter keeps. `mean` reports only the
+    // suite aggregate (no per-case rows); every other filter reports rows and no aggregate.
+    const judgeDrift = [];
+    let judgeDriftMean;
+    if (filter.mode === 'mean') {
+        if (ratePairs.length > 0) {
+            const mean = (pick) => ratePairs.reduce((sum, pair) => sum + pick(pair), 0) / ratePairs.length;
+            const meanBefore = mean((pair) => pair.before);
+            const meanAfter = mean((pair) => pair.after);
+            judgeDriftMean = {
+                before: meanBefore,
+                after: meanAfter,
+                delta: meanAfter - meanBefore,
+                cases: ratePairs.length,
+            };
+        }
+    }
+    else {
+        for (const pair of ratePairs) {
+            const reason = driftReason(pair.before, pair.after, pair.passThreshold, filter);
+            if (reason === undefined)
+                continue;
+            judgeDrift.push({
+                id: pair.key,
+                before: pair.before,
+                after: pair.after,
+                delta: pair.after - pair.before,
+                passThreshold: pair.passThreshold,
+                reason,
+            });
+        }
+    }
     const warnings = [];
+    if (lostRates > 0 && filter.mode !== 'off') {
+        warnings.push(`${lostRates} case(s) were judged in the baseline and produced no judge score in this run, ` +
+            'so their drift could not be computed. A quiet drift section here is not "the scores held".');
+    }
+    if (movedGates > 0 && filter.mode !== 'off') {
+        warnings.push(`${movedGates} case(s) changed their pass threshold between the two runs. Drift is measured ` +
+            "against THIS run's gate, so some of the distance reported here is the gate moving rather " +
+            'than the score.');
+    }
     if (onlyInBefore.length > 0 || onlyInAfter.length > 0) {
         warnings.push(`the two runs do not cover the same cases: ${onlyInBefore.length} only in the baseline, ` +
             `${onlyInAfter.length} only in this run. The comparison covers ${compared} case(s); a ` +
@@ -193,6 +397,9 @@ export function diffRuns(before, after) {
         fixed,
         reclassified,
         metricDeltas,
+        judgeDrift,
+        judgeDriftMean,
+        judgeDriftFilter: filter,
         onlyInBefore,
         onlyInAfter,
         warnings,
@@ -221,6 +428,33 @@ export function renderRunDiff(diff) {
     list('REGRESSED', diff.regressed);
     list('fixed', diff.fixed);
     list('reclassified', diff.reclassified);
+    // BATCH-33 — judge drift under its own heading, so a judge-graded suite with no `classification:`
+    // block has something to read here at all. Nothing is printed when the filter kept nothing: a
+    // quiet section IS the report on a stable re-run, and adding a reassuring "no drift" line would
+    // put a row on every run, which is the noise the filter exists to prevent.
+    if (diff.judgeDrift.length > 0) {
+        lines.push(`  JUDGE DRIFT — ${describeDriftFilter(diff.judgeDriftFilter)} (${diff.judgeDrift.length}):`);
+        for (const entry of diff.judgeDrift) {
+            const sign = entry.delta >= 0 ? '+' : '';
+            const margin = entry.after - entry.passThreshold;
+            const where = entry.reason === 'crossed'
+                ? `CROSSED the pass threshold ${entry.passThreshold}`
+                : entry.reason === 'near-threshold'
+                    ? margin === 0
+                        ? `now AT the pass threshold ${entry.passThreshold}`
+                        : margin < 0
+                            ? `now ${-margin} BELOW the pass threshold ${entry.passThreshold}`
+                            : `now ${margin} above the pass threshold ${entry.passThreshold}`
+                    : `pass threshold ${entry.passThreshold}`;
+            lines.push(`    ${entry.id}: ${entry.before} → ${entry.after} (${sign}${entry.delta}) — ${where}`);
+        }
+    }
+    if (diff.judgeDriftMean) {
+        const mean = diff.judgeDriftMean;
+        const sign = mean.delta >= 0 ? '+' : '';
+        lines.push(`  judge mean: ${mean.before.toFixed(2)} → ${mean.after.toFixed(2)} ` +
+            `(${sign}${mean.delta.toFixed(2)}) over ${mean.cases} case(s)`);
+    }
     if (diff.metricDeltas.length > 0) {
         lines.push('  metric deltas:');
         for (const delta of diff.metricDeltas) {
@@ -234,11 +468,28 @@ export function renderRunDiff(diff) {
     if (diff.regressed.length === 0 &&
         diff.fixed.length === 0 &&
         diff.reclassified.length === 0 &&
-        diff.metricDeltas.every((delta) => delta.delta === 0)) {
+        diff.metricDeltas.every((delta) => delta.delta === 0) &&
+        // BATCH-33 — drift has to count here too, or a run that printed a JUDGE DRIFT section would
+        // print "no change." underneath it and contradict itself.
+        diff.judgeDrift.length === 0 &&
+        (diff.judgeDriftMean === undefined || diff.judgeDriftMean.delta === 0)) {
         lines.push('  no change.');
     }
     return lines;
 }
+/** How the active drift filter is named in the report heading. */
+function describeDriftFilter(filter) {
+    switch (filter.mode) {
+        case 'threshold-ward':
+            return `toward the pass threshold (tolerance ${filter.tolerance})`;
+        case 'min-points':
+            return `movements of ${filter.points}+ point(s)`;
+        case 'mean':
+            return 'suite mean';
+        case 'off':
+            return 'off';
+    }
+}
 /** Does this suite declare a sweep? Small helper so the command reads declaratively. */
 export function suiteSweep(suite) {
     return suite.sweep;