@bglocation/tune-context 2.4.0 → 3.0.0

package/eval/report.mjs

@@ -0,0 +1,881 @@
+#!/usr/bin/env node
+// report — the TASK-089 aggregate and the TASK-090 verdict rendered as ONE
+// self-contained HTML file. See tasks/TASK-091.
+//
+// The failure this file exists to prevent is not a wrong number — analyze.mjs
+// and verdict.mjs already refuse to produce one. It is a page that AGREES with
+// every number on it and still leaves the reader believing something the run did
+// not measure. A chart persuades harder than the figure it draws and much harder
+// than the caveat underneath it: two bars side by side assert "this is a
+// comparison" even when the paragraph beside them says the verdict is withheld.
+// Presentation can undo all of TASK-090's caution without touching a digit.
+//
+// So the rules below are structural, not editorial:
+//
+//   • **A withheld verdict is the page's main content, not a footnote.** When a
+//     gate holds, the arm-comparison chart is NOT DRAWN AT ALL — not drawn and
+//     annotated, not greyed out. The per-pair costs stay in a table, because they
+//     are facts the operator needs to repeat the run; what disappears is the
+//     picture that says "compare these".
+//   • **The two pools are rendered by two calls that share no accumulator.**
+//     There is no code path here that adds paired to natural, and none that could
+//     be introduced by editing one number — the same shape rule analyze.mjs uses.
+//   • **A token count never appears without its five classes.** One helper emits
+//     both or neither, so "total tokens" cannot be printed alone by accident.
+//   • **The honesty counters are a section, not a footer.** They are the first
+//     thing a reader would cut "for clarity", so they sit above the fold of the
+//     natural-work detail, with the rejected rows and the unmeasured delegation
+//     cost among them.
+//   • **Zero network, zero build step.** No src, no href, no @import, no webfont:
+//     the file opens from file:// on a machine with no internet, which is where
+//     it will actually be read. Data rides inside a
+//     <script type="application/json"> block so the numbers behind the page can
+//     be re-read without trusting the prose.
+//
+// Everything visual follows the `dataviz` skill: form chosen before color,
+// categorical hues assigned in fixed order (arms take slots 1-2, token classes
+// slots 3-7), palette validated with the skill's own script in both modes
+// (light: contrast WARN on aqua/yellow/magenta, so both charts ship direct
+// labels AND a table twin — the documented relief), zero-baseline axes,
+// hairline chrome, 2px surface gaps instead of borders.
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { endQuietlyOnClosedPipe, isEntryPoint } from '../cli/entry-point.mjs';
+import { meterStamp } from '../cli/version.mjs';
+import { ARMS } from './analyze.mjs';
+import { TOKEN_CLASS_FIELDS, formatUsd } from './pricing.mjs';
+import { VERDICT_THRESHOLDS, VerdictInputError, verdict as computeVerdict, inputErrorLine, readVerdictInput } from './verdict.mjs';
+
+const USAGE = `
+report — one self-contained HTML file from an analyze aggregate (TASK-091).
+
+Usage:
+  report [--aggregate <path>] [--rejected-runs <path>] [--out <path>]
+
+Options:
+  --aggregate <path>      JSON written by analyze (default: read stdin)
+  --rejected-runs <path>  JSON array of the run journal's §7 rejections,
+                          [{ session, task, arm, prompts, reason }]. OMITTING it
+                          is not the same as passing a file containing []: the
+                          first says nobody asked the journal, and gate 6 holds
+                          the verdict for it. That is deliberate.
+  --out <path>            Where to write the HTML (default: stdout)
+  -h, --help              Show this help
+
+The file it writes has no external references: it opens from file:// with no
+network and no build step.
+`.trim();
+
+const TOKEN_CLASSES = TOKEN_CLASS_FIELDS.map(([name]) => name);
+
+/** Fixed hue order (dataviz: assign in order, never cycle). Arms take slots 1-2,
+ *  token classes 3-7, so a colour never means "off" in one chart and "input" in
+ *  the next. Both subsets were run through the skill's validator in light AND
+ *  dark mode; see the file header. */
+const ARM_SERIES = { off: 'var(--s1)', on: 'var(--s2)' };
+const CLASS_SERIES = {
+  input: 'var(--s3)',
+  cache_read: 'var(--s4)',
+  cache_write_5m: 'var(--s5)',
+  cache_write_1h: 'var(--s6)',
+  output: 'var(--s7)',
+};
+
+/**
+ * Ink for a label sitting INSIDE a coloured fill — the one place dataviz allows
+ * text over a series colour, and only "white or ink by the fill's luminance so
+ * it always clears contrast".
+ *
+ * A CSS variable rather than a value chosen here, because the fill differs by
+ * mode: light-mode yellow #eda100 takes near-black (9.1:1 against it, white is
+ * 2.2:1), while the same slot's dark step takes near-black too but slot 7 flips
+ * between the modes. The per-mode values are computed in STYLE, so a hue swapped
+ * there cannot leave the label behind at 2:1.
+ */
+const CLASS_INK = {
+  input: 'var(--on-s3)',
+  cache_read: 'var(--on-s4)',
+  cache_write_5m: 'var(--on-s5)',
+  cache_write_1h: 'var(--on-s6)',
+  output: 'var(--on-s7)',
+};
+
+// ─── text ───────────────────────────────────────────────────────────────────
+
+/**
+ * HTML escaping for every string that reaches the page.
+ *
+ * Applied without exception, including to strings this repo produced itself:
+ * task names, branch names and reject reasons all come from a transcript or a
+ * branch name, i.e. from outside. A `&` in a branch name that silently ate the
+ * next word would be a rendering bug nobody would think to look for.
+ */
+function esc(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * JSON for a <script type="application/json"> block.
+ *
+ * `</script` inside a string would end the block early and spill the rest of the
+ * data into the document as markup; U+2028/U+2029 are legal in JSON and illegal
+ * in a JavaScript string literal, and a reader who copies the block into a
+ * console would hit a syntax error with no visible cause.
+ */
+function escJson(value) {
+  return JSON.stringify(value, null, 2)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/** Thousands-separated integer, or an em dash for a number that does not exist.
+ *  Never "0": a count nobody measured and a count of zero are different claims. */
+function num(n) {
+  return Number.isFinite(n) ? Math.round(n).toLocaleString('en-US') : '—';
+}
+
+/** Seconds with one decimal. Same em-dash rule as num(). */
+function secs(n) {
+  return Number.isFinite(n) ? `${n.toFixed(1)}s` : '—';
+}
+
+function pct(x) {
+  return Number.isFinite(x) ? `${(x * 100).toFixed(1)}%` : '—';
+}
+
+/** A `{ key: count }` distribution as text, in descending count order. */
+function distText(dist) {
+  const entries = Object.entries(dist ?? {}).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) return '—';
+  return entries.map(([k, n]) => `${esc(k)} ×${num(n)}`).join(', ');
+}
+
+// ─── charts ─────────────────────────────────────────────────────────────────
+
+/**
+ * A horizontal bar with a 4px rounded data-end and a square baseline end
+ * (dataviz mark spec). A rect with `rx` would round the baseline too, which
+ * detaches the mark from the axis it is measured against.
+ */
+function barPath(x, y, w, h, r = 4) {
+  if (!(w > r)) return `M${x},${y} h${Math.max(w, 0)} v${h} h${-Math.max(w, 0)} Z`;
+  return `M${x},${y} H${x + w - r} Q${x + w},${y} ${x + w},${y + r} V${y + h - r} Q${x + w},${y + h} ${x + w - r},${y + h} H${x} Z`;
+}
+
+/**
+ * Roughly how wide a label will render, so a label is never placed where it does
+ * not fit (dataviz: "a label that won't fit doesn't get clipped — measure
+ * first"). Deliberately an over-estimate: the failure mode of guessing high is a
+ * label that moves outside the bar, and of guessing low is clipped text.
+ */
+function textWidth(s, size) {
+  return String(s).length * size * 0.62;
+}
+
+/**
+ * Per-pair cost, one bar per arm, **zero baseline**.
+ *
+ * Drawn ONLY when the verdict is not withheld — the caller enforces that, and
+ * the enforcement is a test (criterion 2). A truncated axis is the cheapest way
+ * to manufacture a difference, so the scale runs 0 → max over every bar in the
+ * chart rather than per pair.
+ *
+ * Returns null rather than an empty frame when there is nothing to draw: a chart
+ * with axes and no marks reads as "measured, and it was zero".
+ */
+function pairChart(pairs) {
+  const usable = pairs.filter((p) => p.complete && ARMS.every((a) => Number.isFinite(p.arms[a]?.list_cost_usd)));
+  if (usable.length === 0) return null;
+
+  const max = Math.max(...usable.flatMap((p) => ARMS.map((a) => p.arms[a].list_cost_usd)));
+  if (!(max > 0)) return null;
+
+  const padL = 96;
+  // Room for the widest tip label, measured rather than assumed: at a fixed
+  // padding the longest amount ran off the right edge and lost its last
+  // characters — a clipped value is worse than no label (dataviz).
+  const padR = Math.ceil(Math.max(...usable.flatMap((p) => ARMS.map((a) => textWidth(formatUsd(p.arms[a].list_cost_usd), 11))))) + 24;
+  const rowH = 62;
+  const barH = 20;
+  const gap = 2; // the surface gap between adjacent bars — never a border
+  const top = 28;
+  const width = 720;
+  const height = top + usable.length * rowH + 34;
+  const plotW = width - padL - padR;
+  const scale = (v) => (v / max) * plotW;
+
+  const parts = [];
+  // Gridlines: hairline, solid, recessive; zero and max only, so the ink stays
+  // on the data (dataviz chrome spec).
+  for (const t of [0, 0.5, 1]) {
+    const x = padL + plotW * t;
+    parts.push(`<line class="grid" x1="${x}" y1="${top - 8}" x2="${x}" y2="${top + usable.length * rowH - 8}"/>`);
+    parts.push(`<text class="tick" x="${x}" y="${top + usable.length * rowH + 12}" text-anchor="middle">${esc(formatUsd(max * t))}</text>`);
+  }
+  parts.push(`<line class="axis" x1="${padL}" y1="${top - 8}" x2="${padL}" y2="${top + usable.length * rowH - 8}"/>`);
+
+  usable.forEach((pair, i) => {
+    const y0 = top + i * rowH;
+    parts.push(`<text class="cat" x="${padL - 12}" y="${y0 + barH + 4}" text-anchor="end">${esc(pair.task)}</text>`);
+    ARMS.forEach((arm, j) => {
+      const a = pair.arms[arm];
+      const y = y0 + j * (barH + gap);
+      const w = scale(a.list_cost_usd);
+      parts.push(
+        `<path fill="${ARM_SERIES[arm]}" d="${barPath(padL, y, w, barH)}">` +
+          `<title>${esc(`${pair.task} — arm ${arm}, pass_order ${a.pass_order ?? 'unknown'}, ${formatUsd(a.list_cost_usd)}, ${a.n_prompts} prompt(s)`)}</title></path>`,
+      );
+      // The amount at the tip, outside the bar — and only the amount. The arm
+      // comes from the legend and the pass order from the table below: a tip
+      // label carrying all three ran into the edge, and identity that needs the
+      // label to fit is identity that disappears at the widest value.
+      parts.push(`<text class="val" x="${padL + w + 8}" y="${y + barH - 5}">${esc(formatUsd(a.list_cost_usd))}</text>`);
+    });
+  });
+
+  // Legend, always, because there are two series (dataviz): identity never rests
+  // on colour-matching against a table further down the page.
+  const legend = ARMS.map(
+    (arm) => `<li><span class="dot" style="background:${ARM_SERIES[arm]}"></span>arm ${esc(arm)}</li>`,
+  ).join('');
+
+  return (
+    `<svg class="chart" viewBox="0 0 ${width} ${height}" role="img" ` +
+    `aria-label="Cost per pair, one bar per arm, axis from zero">${parts.join('')}</svg>` +
+    `<ul class="legend">${legend}</ul>`
+  );
+}
+
+/**
+ * Cost composition by token class, as one 100% stacked bar.
+ *
+ * Pool-level and never split by arm — on purpose. A per-arm split of this chart
+ * would be an arm comparison by another name, and criterion 2 forbids drawing
+ * one while a gate holds. The per-arm class figures are in the tables below,
+ * where they are numbers rather than a picture.
+ *
+ * Its subject is the lever the doctrine talks about most: in the 29-transcript
+ * baseline, cache read + write were 99.8% of the bill and plain input 0.07%.
+ */
+function classShareChart(byClass) {
+  if (!byClass) return null;
+  const entries = TOKEN_CLASSES.map((c) => [c, byClass[c] ?? 0]).filter(([, v]) => v > 0);
+  const total = entries.reduce((a, [, v]) => a + v, 0);
+  if (!(total > 0)) return null;
+
+  const width = 720;
+  const barY = 16;
+  const barH = 24;
+  const gap = 2;
+  const parts = [];
+  let x = 0;
+  entries.forEach(([name, value], i) => {
+    const share = value / total;
+    const w = Math.max(share * width - (i < entries.length - 1 ? gap : 0), 0);
+    const first = i === 0;
+    const last = i === entries.length - 1;
+    const r = 4;
+    // Rounded only on the two outer ends, so the stack reads as one bar and the
+    // interior joints stay square (the 2px surface gap does the separating).
+    const d = first || last
+      ? `M${x + (first ? r : 0)},${barY} H${x + w - (last ? r : 0)} ${last ? `Q${x + w},${barY} ${x + w},${barY + r} V${barY + barH - r} Q${x + w},${barY + barH} ${x + w - r},${barY + barH}` : `V${barY + barH}`} H${x + (first ? r : 0)} ${first ? `Q${x},${barY + barH} ${x},${barY + barH - r} V${barY + r} Q${x},${barY} ${x + r},${barY}` : ''} Z`
+      : `M${x},${barY} h${w} v${barH} h${-w} Z`;
+    parts.push(
+      `<path fill="${CLASS_SERIES[name]}" d="${d}"><title>${esc(`${name}: ${formatUsd(value)} (${pct(share)} of the pool's priced cost)`)}</title></path>`,
+    );
+    // Inside label only where it demonstrably fits — otherwise the legend and
+    // the table carry it (never clipped, never overflowing).
+    const label = pct(share);
+    if (textWidth(label, 11) + 16 < w) {
+      parts.push(
+        `<text class="inbar" fill="${CLASS_INK[name]}" x="${x + w / 2}" y="${barY + barH - 7}" text-anchor="middle">${esc(label)}</text>`,
+      );
+    }
+    x += share * width;
+  });
+
+  const legend = entries
+    .map(
+      ([name, value]) =>
+        `<li><span class="dot" style="background:${CLASS_SERIES[name]}"></span>${esc(name)} — ${esc(formatUsd(value))} (${esc(pct(value / total))})</li>`,
+    )
+    .join('');
+
+  return (
+    `<svg class="chart" viewBox="0 0 ${width} ${barY + barH + 8}" role="img" ` +
+    `aria-label="Share of the priced cost by token class">${parts.join('')}</svg>` +
+    `<ul class="legend">${legend}</ul>`
+  );
+}
+
+// ─── blocks ─────────────────────────────────────────────────────────────────
+
+/**
+ * A token figure and its five classes, or neither (criterion 3).
+ *
+ * One helper for every token count on the page, so "total tokens" has no way of
+ * being printed on its own — the split is not a formatting choice made per call
+ * site, it is the only shape this function can return. `cache_write_unsplit`
+ * rides alongside rather than inside: it is the admission that a write's TTL is
+ * unknown, and folding it into a class would price it.
+ */
+function tokenBlock(tokens) {
+  if (!tokens) return '<span class="dim">no tokens recorded</span>';
+  const classes = TOKEN_CLASSES.map(
+    (c) => `<li><span class="dot" style="background:${CLASS_SERIES[c]}"></span>${esc(c)} <b>${num(tokens.by_class?.[c] ?? 0)}</b></li>`,
+  ).join('');
+  return (
+    `<div class="tokens"><div class="tokens-total">${num(tokens.total)} tokens</div>` +
+    `<ul class="tokens-split">${classes}` +
+    `<li class="unsplit">cache_write_unsplit <b>${num(tokens.cache_write_unsplit ?? 0)}</b> — TTL unknown, so unpriced</li>` +
+    '</ul></div>'
+  );
+}
+
+/**
+ * One arm's column. Median and spread together wherever a per-prompt figure
+ * appears (criterion: never the mean alone where the spread is the finding); the
+ * mean rides along labelled, because the gap between the two IS the finding when
+ * one 44-hour turn sits in the pool.
+ */
+function armColumn(a) {
+  if (a.n_prompts === 0) {
+    // A zero next to an arm that was never measured is the one number this whole
+    // epic exists to keep off the page.
+    return `<td><span class="dim">no rows — not $0.0000, no measurement</span></td>`;
+  }
+  const cost = a.cost_complete
+    ? esc(formatUsd(a.cost.list_cost_usd))
+    : `${esc(formatUsd(a.cost.list_cost_usd))} <span class="flag">INCOMPLETE — ${num(a.cost.unpriced.rows)} unpriced row(s)</span>`;
+  const d = a.delegations;
+  return `<td>
+    <div class="stat"><span class="stat-label">list cost</span><span class="stat-value">${cost}</span></div>
+    <dl>
+      <dt>prompts / sessions / pairs</dt><dd>${num(a.n_prompts)} / ${num(a.n_sessions)} / ${num(a.n_pairs)}</dd>
+      <dt>cost per prompt</dt><dd>median ${esc(formatUsd(a.cost_per_prompt.median))} · IQR ${esc(formatUsd(a.cost_per_prompt.iqr))} · range ${esc(formatUsd(a.cost_per_prompt.min))}–${esc(formatUsd(a.cost_per_prompt.max))}<br><span class="dim">mean ${esc(formatUsd(a.cost_per_prompt.mean))} — printed next to the median, never instead of it</span></dd>
+      <dt>work_s per prompt</dt><dd>median ${secs(a.work_s.median)} · IQR ${secs(a.work_s.iqr)} · max ${secs(a.work_s.max)}<br><span class="dim">${num(a.work_s.missing)} prompt(s) with no assistant reply, excluded rather than counted as 0s</span></dd>
+      <dt>max_gap_s</dt><dd>median ${secs(a.max_gap_s.median)} · max ${secs(a.max_gap_s.max)} <span class="dim">— a large gap is a tool call waiting for the operator, i.e. human time</span></dd>
+      <dt>tokens</dt><dd>${tokenBlock(a.tokens)}</dd>
+      <dt>tool calls</dt><dd>${num(a.tools.calls_total)} total, ${num(a.tools.agent_spawns)} Agent spawn(s)</dd>
+      <dt>delegations</dt><dd>${num(d.spawns)} spawn(s), ${num(d.measured)} with a usable record, ${num(d.unmeasured_spawns)} with none<br>
+        floor cost ${esc(formatUsd(d.cost.list_cost_usd))} <span class="flag">LOWER BOUND — not the cost of delegation, and never zero</span><br>
+        ${tokenBlock(d.tokens)}
+        <span class="dim">${num(d.duplicates_dropped)} duplicate record(s) dropped, ${num(d.unidentified_dropped)} unidentified</span></dd>
+      <dt>models</dt><dd>${distText(a.models)}</dd>
+      <dt>effort</dt><dd>${distText(a.efforts)}</dd>
+    </dl>
+  </td>`;
+}
+
+/**
+ * One pool, rendered on its own.
+ *
+ * Takes exactly one pool and holds no accumulator across calls, which is what
+ * makes criterion 4 true by construction rather than by discipline: there is no
+ * variable in this file that could hold paired + natural, so no edit adds them
+ * by accident.
+ */
+function poolSection({ id, title, lede, pool, chart }) {
+  const empty = ARMS.every((arm) => pool.arms[arm].n_prompts === 0);
+  const body = empty
+    ? '<p class="empty">No rows in this pool. Nothing is drawn and nothing is totalled — an empty axis would say "measured, and it was zero".</p>'
+    : `<table class="arms"><thead><tr><th></th>${ARMS.map((a) => `<th><span class="dot" style="background:${ARM_SERIES[a]}"></span>arm ${esc(a)}</th>`).join('')}</tr></thead>` +
+      `<tbody><tr><th class="rowhead">per arm</th>${ARMS.map((a) => armColumn(pool.arms[a])).join('')}</tr></tbody></table>` +
+      (chart ?? '');
+  return `<section id="${id}"><h2>${esc(title)}</h2><p class="lede">${lede}</p><p class="src">source: ${esc(pool.source)}</p>${body}</section>`;
+}
+
+/** Status chip: colour never carries the meaning alone — icon plus word, per the
+ *  dataviz status rule. */
+function chip(state, text) {
+  const icon = state === 'good' ? '✓' : state === 'critical' ? '✕' : '!';
+  return `<span class="chip chip-${state}"><span class="chip-icon" aria-hidden="true">${icon}</span>${esc(text)}</span>`;
+}
+
+/**
+ * The verdict, as the page's main content.
+ *
+ * A held verdict gets the hero slot and the reason in full — the thing it must
+ * never become is a caption under a chart. Every gate is listed whether it held
+ * or passed, in verdict.mjs's own order, because a reader who fixes one problem
+ * and reruns has paid a whole run to discover the second.
+ */
+function verdictSection(v) {
+  const withheld = v.finding === 'withheld';
+  const hero = withheld
+    ? 'VERDICT WITHHELD'
+    : v.finding === 'no-difference'
+      ? 'NO DIFFERENCE MEASURED'
+      : `CHEAPER ARM: ${String(v.cheaper_arm).toUpperCase()}`;
+  const heroNote = withheld
+    ? `${v.holds.length} of ${v.gates.length} gate(s) hold the verdict. The comparison chart is not drawn — not hidden, not greyed out. The per-pair numbers stay below so the run can be repeated.`
+    : v.finding === 'no-difference'
+      ? 'Every gate passed and the arms cost the same on average. That is a finding, not a failure.'
+      : 'Every gate passed. Still an observation at this sample size — never proof.';
+
+  const gates = v.gates
+    .map((g) => {
+      const state = g.passed ? 'good' : 'critical';
+      const detail = g.passed
+        ? ''
+        : `<p class="gate-reason">${esc(g.reason)}</p><p class="gate-missing"><b>Missing for a verdict:</b> ${esc(g.missing)}</p>`;
+      return (
+        `<li class="gate ${g.passed ? 'pass' : 'hold'}"><div class="gate-head">${chip(state, g.passed ? 'passed' : 'HOLDS')}` +
+        `<b>${esc(g.id)}</b><span class="gate-q">${esc(g.question)}</span></div>${detail}` +
+        `<details><summary>measured</summary><pre>${esc(JSON.stringify(g.measured, null, 2))}</pre></details></li>`
+      );
+    })
+    .join('');
+
+  return `<section id="verdict">
+    <div class="hero ${withheld ? 'hero-hold' : 'hero-ruled'}">
+      <div class="hero-figure">${esc(hero)}</div>
+      <p>${esc(heroNote)}</p>
+      <p class="dim">Pool: paired measurement only (${num(v.n_pairs_used)} usable pair(s)). Natural work is never evidence.
+      ${v.observation_only ? 'This report says "observation", never "proof" — the PO froze a minimum sample, not a level at which it becomes proof.' : ''}</p>
+    </div>
+    <h2>The ${v.gates.length} gates</h2>
+    <ul class="gates">${gates}</ul>
+  </section>`;
+}
+
+/**
+ * The two effects, side by side and always both (§11b).
+ *
+ * The order effect is reported at the same size and in the same place as the arm
+ * effect, because the whole point of §11b is that the second implementation of a
+ * task is cheaper for a reason that has nothing to do with the arm — and a page
+ * that prints the arm effect large and the order effect in a footnote has made
+ * exactly the claim the gate refuses.
+ */
+function effectsSection(v) {
+  const e = v.effects;
+  const rows = e.pairs_used
+    .map(
+      (p) =>
+        `<tr><td>${esc(p.task)}</td><td>${esc(formatUsd(p.off_usd))}</td><td>${esc(formatUsd(p.on_usd))}</td>` +
+        `<td>${esc(formatUsd(p.arm_delta_usd))}</td><td>${esc(formatUsd(p.order_delta_usd))}</td></tr>`,
+    )
+    .join('');
+  const skipped = e.pairs_skipped
+    .map((p) => `<li>${esc(p.task)} — ${esc(p.why)}</li>`)
+    .join('');
+
+  return `<section id="effects">
+    <h2>Arm effect next to order effect</h2>
+    <p class="lede">Both are means over pairs, from the same four numbers. The rotation of §9 is the only thing that
+    separates them; at two pairs each of them stands on two numbers, which is arithmetic, not statistics.</p>
+    <div class="tiles">
+      <div class="tile"><span class="stat-label">arm effect (off − on)</span>
+        <span class="stat-value">${esc(formatUsd(e.arm_effect_usd))}</span>
+        <span class="dim">positive = arm "on" cheaper</span></div>
+      <div class="tile"><span class="stat-label">order effect (pass 1 − pass 2)</span>
+        <span class="stat-value">${esc(formatUsd(e.order_effect_usd))}</span>
+        <span class="dim">positive = the second implementation cheaper, whichever arm it was</span></div>
+      <div class="tile"><span class="stat-label">ratio |arm| / |order|</span>
+        <span class="stat-value">${e.arm_effect_usd === null || e.order_effect_usd === null ? '—' : esc(String(v.gates.find((g) => g.id === 'order_effect')?.measured.ratio ?? '—'))}</span>
+        <span class="dim">a verdict needs ≥ ${num(VERDICT_THRESHOLDS.gates.order_effect.min_arm_over_order)}×</span></div>
+    </div>
+    ${rows === '' ? '<p class="empty">No pair contributed to either effect.</p>' : `<table class="grid-table"><thead><tr><th>pair</th><th>off</th><th>on</th><th>arm Δ</th><th>order Δ</th></tr></thead><tbody>${rows}</tbody></table>`}
+    ${skipped === '' ? '' : `<p class="dim">Pairs skipped, with the reason rather than a default: </p><ul class="dim">${skipped}</ul>`}
+  </section>`;
+}
+
+/**
+ * Per-pair cost — the actual comparison, and the one thing the page withholds.
+ *
+ * The chart is drawn only when `verdict.ruled` is true. The table is always
+ * drawn: those numbers are what the operator needs to repeat a rejected run, and
+ * a table does not make the claim a chart makes. That asymmetry is criterion 2,
+ * and the test for it asserts the ABSENCE of the chart, not the presence of a
+ * caveat.
+ */
+function pairsSection(agg, v) {
+  const pairs = agg.paired.pairs;
+  if (pairs.length === 0) {
+    return '<section id="pairs"><h2>Pairs</h2><p class="empty">No paired rows: no task was measured twice. Nothing to compare, so nothing is drawn.</p></section>';
+  }
+  const rows = pairs
+    .map((p) => {
+      const cells = ARMS.map((arm) => {
+        const a = p.arms[arm];
+        if (!a) return '<td><span class="dim">arm missing</span></td>';
+        return `<td>${esc(formatUsd(a.list_cost_usd))}${a.cost_complete ? '' : ' <span class="flag">INCOMPLETE</span>'}<br>
+          <span class="dim">pass ${a.pass_order ?? '?'} · ${num(a.n_prompts)} prompt(s) · ${num(a.n_sessions)} session(s) · ${num(a.agent_spawns)} spawn(s)</span></td>`;
+      }).join('');
+      return `<tr><td>${esc(p.task)}${p.complete ? '' : ' <span class="flag">INCOMPLETE PAIR</span>'}</td>${cells}</tr>`;
+    })
+    .join('');
+
+  const chart = v.ruled ? pairChart(pairs) : null;
+  const chartBlock = v.ruled
+    ? (chart ??
+      '<p class="empty">No pair has both arms priced, so there is nothing to draw. The numbers stay in the table.</p>')
+    : `<div class="notdrawn">${chip('critical', 'comparison chart not drawn')}
+        <p>A gate holds the verdict, so the arm comparison is not rendered at all. A chart asserts "these two are
+        comparable" more loudly than any caption can withdraw it. The costs below are still here — they are what a
+        repeat run is planned from.</p></div>`;
+
+  return `<section id="pairs">
+    <h2>Cost per pair</h2>
+    <p class="lede">One task, two arms, same base commit. This is the comparison; everything else on this page is context.</p>
+    ${chartBlock}
+    <table class="grid-table"><thead><tr><th>pair</th>${ARMS.map((a) => `<th><span class="dot" style="background:${ARM_SERIES[a]}"></span>${esc(a)}</th>`).join('')}</tr></thead><tbody>${rows}</tbody></table>
+  </section>`;
+}
+
+/**
+ * The honesty counters, as a section of their own.
+ *
+ * Everything here is a number about what the measurement does NOT contain:
+ * rows thrown away and why, sessions that changed arm, branches that missed the
+ * convention, delegation cost that exists but was never captured, turns whose
+ * usage is a known under-count. They are on the page rather than in a footer
+ * because they are the first thing an editor would cut, and cutting them is how
+ * a clean-looking report gets published over a sample that lost a third of its
+ * sessions (that happened — see verdict.mjs, gate 6).
+ */
+function countersSection(agg, v) {
+  const c = agg.counters;
+  const rejected = Object.entries(c.rejected_by_reason ?? {}).sort((a, b) => b[1] - a[1]);
+  const rejectedGate = v.gates.find((g) => g.id === 'rejected');
+  const perArm = ARMS.map((arm) => {
+    const a = agg.paired.arms[arm];
+    const k = a.counters;
+    return `<tr><td>${esc(arm)}</td><td>${num(k.synthetic_turns)}</td><td>${num(k.understated_turns)}</td><td>${num(k.multi_attempt_turns)}</td><td>${num(k.sidechain_turns)}</td><td>${num(k.api_turns)}</td><td>${num(a.cost.unpriced.rows)}</td></tr>`;
+  }).join('');
+
+  return `<section id="counters">
+    <h2>Honesty counters</h2>
+    <p class="lede">What is missing from the numbers above, in numbers. A discard that does not show up is the same
+    class of error as a fabricated verdict, so none of this belongs in a footer.</p>
+    <div class="tiles">
+      <div class="tile"><span class="stat-label">rows in / used / rejected</span>
+        <span class="stat-value">${num(c.rows_in)} / ${num(c.rows_used)} / ${num(c.rows_rejected)}</span>
+        <span class="dim">every row is in exactly one of the last two</span></div>
+      <div class="tile"><span class="stat-label">operator rejections (§7 journal)</span>
+        <span class="stat-value">${esc(String(rejectedGate?.measured.operator_rejects ?? 'NOT REPORTED'))}</span>
+        <span class="dim">a run the operator threw away leaves no trace in the rows; NOT REPORTED is not zero</span></div>
+      <div class="tile"><span class="stat-label">unattributed transcript entries</span>
+        <span class="stat-value">${c.unattributed === null ? 'NOT REPORTED' : num(c.unattributed?.entries ?? c.unattributed)}</span>
+        <span class="dim">entries that landed in no row at all</span></div>
+    </div>
+    <table class="grid-table">
+      <thead><tr><th>arm</th><th>synthetic turns</th><th>understated turns</th><th>multi-attempt</th><th>sidechain</th><th>api turns</th><th>unpriced rows</th></tr></thead>
+      <tbody>${perArm}</tbody>
+    </table>
+    <ul class="counters-list">
+      <li>rejected by reason: ${rejected.length === 0 ? '<span class="dim">none</span>' : rejected.map(([r, n]) => `${esc(r)} ×${num(n)}`).join(', ')}</li>
+      <li>sessions dropped whole for changing arm mid-session: ${num(c.mixed_arm_sessions)}${c.mixed_arm_session_ids.length > 0 ? ` (${c.mixed_arm_session_ids.map(esc).join(', ')})` : ''}</li>
+      <li>branches outside <code>exp/&lt;task&gt;/&lt;arm&gt;</code>: ${num(c.off_convention_branches)}${c.off_convention_branch_names.length > 0 ? ` — ${c.off_convention_branch_names.map(esc).join(', ')}` : ''} <span class="dim">counted, never assigned to an arm</span></li>
+      <li>rows with no session id: ${num(c.rows_without_session)}</li>
+      <li>delegation cost: measured <b>from below</b> in both arms. The subagent's own turns never reach the transcript,
+        so the figure in the tables is a floor multiplied by an unknown factor ≥ 1 — never zero, never a total.</li>
+    </ul>
+  </section>`;
+}
+
+/** The frozen thresholds, with their dates, travelling with the decision they
+ *  judged — a verdict read six months from now has to show what it was measured
+ *  against without anyone trusting that the file still says the same thing. */
+function thresholdsSection(t) {
+  const rows = Object.entries(t.gates)
+    .map(
+      ([id, g]) =>
+        `<tr><td>${esc(id)}</td><td>${esc(
+          Object.entries(g)
+            .filter(([k]) => k !== 'note' && k !== 'frozen')
+            .map(([k, val]) => `${k}=${val}`)
+            .join(', '),
+        )}</td><td>${esc(g.frozen)}</td><td class="note">${esc(g.note)}</td></tr>`,
+    )
+    .join('');
+  return `<section id="thresholds">
+    <h2>Frozen thresholds</h2>
+    <p class="lede">Frozen by ${esc(t.frozen_by)} on ${esc(t.frozen)} — ${esc(t.source)}. Amended after a run:
+    ${t.amended.length === 0 ? 'never.' : esc(JSON.stringify(t.amended))}</p>
+    <table class="grid-table"><thead><tr><th>gate</th><th>threshold</th><th>frozen</th><th>why this number</th></tr></thead><tbody>${rows}</tbody></table>
+  </section>`;
+}
+
+/**
+ * Which code computed this page, step by step — rows, aggregate, verdict
+ * (EPIC-010). In the header rather than the footer, because EPIC-009's verdict
+ * was voided over exactly this question, asked of files that could not answer
+ * it. Whether the stamps agree is the meter_mixed gate's business; this line
+ * only names them, all of them.
+ */
+function meterLine(agg, v) {
+  const rows = Object.entries(agg.meter_versions ?? {});
+  const stamp = (s) => (s ? `<code>${esc(s)}</code>` : '<span class="flag">no stamp</span>');
+  return (
+    `<p class="src">meter — rows: ${rows.length === 0 ? '—' : rows.map(([s, n]) => `${stamp(s)} ×${num(n)}`).join(', ')}` +
+    ` · analyze: ${stamp(agg.analyzed_by)} · verdict: ${stamp(v.judged_by)}</p>`
+  );
+}
+
+// ─── the page ───────────────────────────────────────────────────────────────
+
+/** Palette and chrome from the `dataviz` reference instance, as CSS custom
+ *  properties so the light/dark values swap in one place. Dark mode is selected,
+ *  not an automatic inversion: its own steps from the same ramps, validated
+ *  against the dark surface. */
+const STYLE = `
+:root {
+  color-scheme: light;
+  --surface-1:#fcfcfb; --plane:#f9f9f7; --ink:#0b0b0b; --ink-2:#52514e; --muted:#898781;
+  --grid:#e1e0d9; --axis:#c3c2b7; --border:rgba(11,11,11,0.10);
+  --s1:#2a78d6; --s2:#eb6834; --s3:#1baf7a; --s4:#eda100; --s5:#e87ba4; --s6:#008300; --s7:#4a3aa7;
+  /* Ink for a label inside the fill, picked by luminance (see CLASS_INK). */
+  --on-s3:#0b0b0b; --on-s4:#0b0b0b; --on-s5:#0b0b0b; --on-s6:#fff; --on-s7:#fff;
+  --good:#0ca30c; --warning:#fab219; --critical:#d03b3b;
+}
+@media (prefers-color-scheme: dark) {
+  :root:where(:not([data-theme="light"])) {
+    color-scheme: dark;
+    --surface-1:#1a1a19; --plane:#0d0d0d; --ink:#fff; --ink-2:#c3c2b7; --muted:#898781;
+    --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+    --s1:#3987e5; --s2:#d95926; --s3:#199e70; --s4:#c98500; --s5:#d55181; --s6:#008300; --s7:#9085e9;
+    --on-s3:#0b0b0b; --on-s4:#0b0b0b; --on-s5:#0b0b0b; --on-s6:#fff; --on-s7:#0b0b0b;
+  }
+}
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --surface-1:#1a1a19; --plane:#0d0d0d; --ink:#fff; --ink-2:#c3c2b7; --muted:#898781;
+  --grid:#2c2c2a; --axis:#383835; --border:rgba(255,255,255,0.10);
+  --s1:#3987e5; --s2:#d95926; --s3:#199e70; --s4:#c98500; --s5:#d55181; --s6:#008300; --s7:#9085e9;
+  --on-s3:#0b0b0b; --on-s4:#0b0b0b; --on-s5:#0b0b0b; --on-s6:#fff; --on-s7:#0b0b0b;
+}
+* { box-sizing: border-box; }
+body { margin:0; padding:32px 20px 96px; background:var(--plane); color:var(--ink);
+  font:15px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 980px; margin: 0 auto; }
+h1 { font-size:28px; margin:0 0 6px; }
+h2 { font-size:19px; margin:0 0 8px; }
+section { background:var(--surface-1); border:1px solid var(--border); border-radius:10px;
+  padding:20px 22px; margin:18px 0; }
+.lede { color:var(--ink-2); margin:0 0 14px; max-width:72ch; }
+.src, .dim { color:var(--muted); font-size:13px; }
+.dim b { color:var(--ink-2); }
+.empty { color:var(--ink-2); background:var(--plane); border:1px solid var(--border);
+  border-radius:8px; padding:14px 16px; margin:8px 0; }
+.hero { border:1px solid var(--border); border-radius:10px; padding:20px 22px; background:var(--plane); }
+.hero-figure { font-size:48px; font-weight:650; letter-spacing:-0.02em; line-height:1.1; margin-bottom:8px; }
+.hero-hold .hero-figure { color:var(--critical); }
+.hero-ruled .hero-figure { color:var(--good); }
+.hero p { margin:6px 0 0; max-width:80ch; }
+.gates { list-style:none; padding:0; margin:12px 0 0; }
+.gate { border-top:1px solid var(--border); padding:12px 0; }
+.gate-head { display:flex; align-items:center; gap:10px; flex-wrap:wrap; }
+.gate-q { color:var(--ink-2); }
+.gate-reason { margin:8px 0 4px; max-width:80ch; }
+.gate-missing { margin:0; color:var(--ink-2); max-width:80ch; }
+.chip { display:inline-flex; align-items:center; gap:6px; font-size:12px; font-weight:600;
+  padding:2px 9px; border-radius:999px; border:1px solid var(--border); color:var(--ink); }
+.chip-icon { font-weight:700; }
+.chip-good { background:color-mix(in srgb, var(--good) 16%, transparent); }
+.chip-critical { background:color-mix(in srgb, var(--critical) 16%, transparent); }
+.notdrawn { background:var(--plane); border:1px solid var(--border); border-radius:8px; padding:14px 16px; margin:8px 0 14px; }
+.notdrawn p { margin:8px 0 0; color:var(--ink-2); max-width:80ch; }
+.tiles { display:flex; flex-wrap:wrap; gap:12px; margin:12px 0; }
+.tile { flex:1 1 210px; background:var(--plane); border:1px solid var(--border); border-radius:8px; padding:12px 14px; }
+.stat-label, .stat-value { display:block; }
+.stat-label { font-size:12px; color:var(--muted); text-transform:uppercase; letter-spacing:.04em; }
+.stat-value { font-size:22px; font-weight:620; margin:2px 0 4px; }
+.stat { margin-bottom:10px; }
+table { border-collapse:collapse; width:100%; margin:10px 0; font-size:14px; }
+th, td { text-align:left; vertical-align:top; padding:8px 10px; border-top:1px solid var(--border); }
+th { color:var(--muted); font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:.04em; }
+td { font-variant-numeric: tabular-nums; }
+.rowhead { width:80px; }
+.arms td { width:44%; }
+.note { color:var(--ink-2); font-size:12px; font-variant-numeric:normal; }
+dl { margin:0; }
+dt { font-size:12px; color:var(--muted); text-transform:uppercase; letter-spacing:.04em; margin-top:10px; }
+dd { margin:2px 0 0; }
+.dot { display:inline-block; width:10px; height:10px; border-radius:3px; margin-right:6px; vertical-align:middle; }
+.flag { color:var(--critical); font-weight:600; font-size:12px; }
+.tokens-total { font-weight:600; }
+.tokens-split, .legend, .counters-list { list-style:none; padding:0; margin:4px 0 0; }
+.tokens-split li { font-size:13px; color:var(--ink-2); }
+.legend { display:flex; flex-wrap:wrap; gap:14px; font-size:13px; color:var(--ink-2); }
+.counters-list li { margin:6px 0; max-width:80ch; }
+.unsplit { color:var(--muted); }
+.chart { display:block; width:100%; height:auto; margin:14px 0 6px; overflow:visible; }
+.chart .grid { stroke:var(--grid); stroke-width:1; }
+.chart .axis { stroke:var(--axis); stroke-width:1; }
+.chart .tick, .chart .cat, .chart .val { fill:var(--muted); font-size:11px;
+  font-family:system-ui, sans-serif; font-variant-numeric:tabular-nums; }
+.chart .cat, .chart .val { fill:var(--ink-2); }
+.chart .inbar { font-size:11px; font-family:system-ui, sans-serif; font-weight:600; }
+details { margin-top:8px; }
+summary { cursor:pointer; color:var(--muted); font-size:12px; }
+pre { background:var(--plane); border:1px solid var(--border); border-radius:6px;
+  padding:10px 12px; overflow-x:auto; font-size:12px; }
+code { font-size:13px; }
+.scroll { overflow-x:auto; }
+footer { max-width:980px; margin:0 auto; color:var(--muted); font-size:12px; }
+`.trim();
+
+/**
+ * Aggregate + verdict → one HTML document. Pure: no disk, no clock (the caller
+ * passes `generatedAt`), no ambient state — the same rule analyze() and
+ * verdict() follow, and the reason a test can render a fabricated run without a
+ * fixture directory.
+ *
+ * @param agg  an aggregate from analyze() (schema tune-context/analyze@2)
+ * @param verdict  the decision from verdict(). Computed by the caller rather
+ *        than here, because the journal of §7 rejections is an input this layer
+ *        has no way to read — and a verdict computed without it holds gate 6,
+ *        which is the correct answer, not a bug to route around.
+ */
+export function renderReport(agg, { verdict: v, generatedAt = null } = {}) {
+  if (!agg || typeof agg !== 'object' || agg.schema !== 'tune-context/analyze@2') {
+    throw new TypeError('report: expected an aggregate from analyze() (schema tune-context/analyze@2)');
+  }
+  if (v?.schema !== 'tune-context/verdict@2') {
+    throw new TypeError('report: expected a verdict from verdict() (schema tune-context/verdict@2)');
+  }
+
+  // Pool-level composition: the two arms of ONE pool added together. The pools
+  // themselves are never added — that is the line, and it is drawn here rather
+  // than left to a comment because this is the only place on the page where any
+  // addition happens at all.
+  const pooledClasses = (pool) => {
+    const out = Object.fromEntries(TOKEN_CLASSES.map((c) => [c, 0]));
+    for (const arm of ARMS) {
+      const byClass = pool.arms[arm].cost.list_cost_by_class;
+      if (!byClass) continue;
+      for (const c of TOKEN_CLASSES) out[c] += byClass[c] ?? 0;
+    }
+    return out;
+  };
+
+  const pairedChart = classShareChart(pooledClasses(agg.paired));
+  const naturalChart = classShareChart(pooledClasses(agg.natural));
+  const cacheNote =
+    '<h3>Where the money goes</h3><p class="lede">Share of this pool\'s priced cost by token class. In the ' +
+    '29-transcript baseline, cache read plus cache write were 99.8% of the bill and plain input 0.07% — which is why ' +
+    '<code>/clear</code> before each arm is a validity condition rather than hygiene. Split by class, never by arm: ' +
+    'a per-arm version of this chart would be an arm comparison wearing a different label.</p>';
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EPIC-009 — cost measurement report</title>
+<style>${STYLE}</style>
+</head><body>
+<main>
+<header>
+  <h1>EPIC-009 — paired cost measurement</h1>
+  <p class="lede">The doctrine measured against its own absence: one task implemented twice from the same commit,
+  once with tune-context and RAG on, once with both parked. Generated${generatedAt ? ` ${esc(generatedAt)}` : ''} from
+  an aggregate of ${num(agg.counters.rows_in)} prompt row(s). Costs are <b>list price through the API</b> — what the
+  work would have cost, never money spent.</p>
+  ${meterLine(agg, v)}
+</header>
+${verdictSection(v)}
+${pairsSection(agg, v)}
+${effectsSection(v)}
+${poolSection({
+  id: 'paired',
+  title: 'Paired measurement — the only pool a verdict may be built on',
+  lede: 'Four scripted sessions (§2a): model, effort, task and prompt text held constant, the arm the only difference.',
+  pool: agg.paired,
+  chart: pairedChart ? cacheNote + pairedChart : '',
+})}
+${countersSection(agg, v)}
+${poolSection({
+  id: 'natural',
+  title: 'Natural work — background, never evidence',
+  lede: 'Ordinary daily work attributed by the ledger alone. Nothing is held constant here: different tasks, different days, different prompts. It is useful for asking whether the paired result points the same way, and it is never added to the pool above — not on this page, and not in the aggregate behind it.',
+  pool: agg.natural,
+  chart: naturalChart ? cacheNote + naturalChart : '',
+})}
+${thresholdsSection(v.thresholds)}
+</main>
+<footer>tune-context · EPIC-009 · this page is an observation, not proof — see the frozen thresholds above.</footer>
+<script type="application/json" id="report-data">${escJson({
+    schema: 'tune-context/report@1',
+    generated_at: generatedAt,
+    aggregate: agg,
+    verdict: v,
+  })}</script>
+</body></html>
+`;
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval report` — one parser behind both doors (EPIC-010).
+ */
+export async function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: {
+        aggregate: { type: 'string' },
+        'rejected-runs': { type: 'string' },
+        out: { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    }));
+  } catch (e) {
+    process.stderr.write(`report: ${e.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  // The same reader and the same boundary as `eval verdict` (TASK-096): one
+  // place decides what a readable aggregate and journal are, so this page can
+  // never accept an input the verdict refuses — and only those refusals become
+  // a message. A TypeError from inside a gate or the page is a bug and keeps its
+  // stacktrace, here as there. `rejectedRuns` stays undefined when the flag is
+  // absent — that is what makes gate 6 hold instead of passing on a share whose
+  // denominator nobody supplied.
+  let html;
+  try {
+    const { agg, rejectedRuns } = await readVerdictInput({ aggregate: values.aggregate, rejectedRuns: values['rejected-runs'] });
+    const v = computeVerdict(agg, { rejectedRuns, judgedBy: meterStamp() });
+    html = renderReport(agg, { verdict: v, generatedAt: new Date().toISOString().slice(0, 10) });
+  } catch (e) {
+    if (!(e instanceof VerdictInputError)) throw e;
+    process.stderr.write(`${inputErrorLine('report', e)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (values.out) {
+    try {
+      writeFileSync(values.out, html);
+    } catch (e) {
+      // Where to write is the operator's input too: a missing directory is a
+      // message, not a stacktrace.
+      process.stderr.write(`report: cannot write ${values.out}: ${e.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    process.stderr.write(`report: wrote ${values.out}\n`);
+  } else {
+    process.stdout.write(html);
+  }
+}
+
+if (isEntryPoint(import.meta.url)) {
+  await main();
+}