/**
 * A figure nothing holds is a figure that drifts, and the guard that would catch it cannot
 * see it.
 *
 * `check-cited` resolves every citation marker in the corpus against the artifact it names.
 * It is a good reader and it has exactly one blind spot, which is structural rather than a
 * bug: it can only resolve the markers that exist. A measured figure written into prose with
 * NO marker beside it is not a failed citation — it is not a citation at all, and nothing
 * looks at it ever again.
 *
 * That is not hypothetical. Desk pass 11 found "a median 24 rounds" in the Pacing Note and
 * "24 if the column joins" in EXPOSURE. The baseline holds 21 at two of the column joining
 * and 25 at three. 24 is neither, it had been wrong through every pass that checked
 * citations, and it survived because it carried no marker to check. The same document
 * printed its four-player wipe rate uncited twice while citing it correctly four times —
 * and that figure is the one that was published at 58.7% until a truncated sweep was found.
 *
 * ⚠ THE SHAPES HAVE A BLIND SPOT AND IT IS STRUCTURAL. R-299 said this guard "learns its
 * vocabulary from the marked figures and applies it to the unmarked" — and a vocabulary
 * learned that way cannot contain the phrasing of the figure nobody marked. The concurrent
 * session proved it against a live defect: a THIRD stale 24, in a table cell, reported OK by
 * this file. Its measurement status lived in the header row two lines above —
 *
 *     | | Median rounds |
 *     |---|---|
 *     | Six hollow men + three of the column | **24** |     <- the baseline says 25
 *
 * — and the scan read one line at a time, so a bare number in a column the document itself
 * calls "Median rounds" was invisible. Fixed below by reading the header: a cell inherits
 * the measurement status of its column, which is a claim the DOCUMENT makes rather than one
 * this file's vocabulary has to anticipate. That is the narrow repair. The general point
 * stands and is worth keeping in view — see `check-unmarked`, which attacks the same problem
 * from the other end by treating bold as the corpus's own mark of a published figure.
 *
 * So this is the asymmetric counter for the other direction, and the fifth in this repo:
 *
 *   check-cited        reads markers          -> is the figure beside this marker right?
 *   check-figures      reads FIGURES          -> does this figure have a marker at all?
 *
 * THE OPT-IN RULE. A document that uses citations has opted into the regime, and every
 * measurement-shaped figure in it must carry a marker. A document with no markers anywhere
 * has not, and its figures are counted and held by a ratchet rather than failing the build —
 * because turning three unguarded scenarios red is how a guard gets switched off on the day
 * it is written. The ratchet still means they cannot get worse, and the moment such a
 * document gains its first citation it joins the strict regime in full.
 *
 *   node tools/check-figures.mjs            check the corpus
 *   node tools/check-figures.mjs --list     print every figure found, marked or not
 *   node tools/check-figures.mjs --update   re-record the ratchet for opted-out documents
 */
import { readFileSync, writeFileSync, existsSync } from "node:fs";
import path from "node:path";
import { playableFiles } from "./check-scenarios.mjs";

const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")), "..");
const BASELINE = path.join(ROOT, "tools", "figures-baseline.json");
const argv = process.argv.slice(2);
const LIST = argv.includes("--list");
const UPDATE = argv.includes("--update");

/* A number, with the document's own bolding allowed around it. */
const N = String.raw`\*{0,2}(\d+(?:\.\d+)?)\*{0,2}`;

/* THE SHAPES A HARNESS FIGURE TAKES IN THIS CORPUS.
   Deliberately narrow. An earlier draft matched any number within forty-five characters of
   a measurement word and reported 282 candidates, nearly all of them prose — "down 140
   steps", "an engineer on his rounds", "01:06". A guard that cries wolf 282 times is a
   guard nobody runs. These are the phrasings the documents actually use when quoting the
   simulator, and each one was read off a figure that IS cited somewhere. */
/* `d` (hasIndices) so each match reports where its capture actually sits — see numEnd. */
const SHAPES = [
  ["median",      new RegExp(String.raw`median(?:\s+of)?\s+` + N, "gid")],
  ["rounds",      new RegExp(N + String.raw`\s*\*{0,2}\s*rounds\b`, "gid")],
  ["wiped",       new RegExp(N + String.raw`\s*%?\s*\*{0,2}\s*(?:wiped|wipes)\b`, "gid")],
  ["wipes-pct",   new RegExp(String.raw`wipe[sd]?\s+` + N + String.raw`\s*%`, "gid")],
  ["wipe-rate",   new RegExp(String.raw`wipe rate[^.]{0,24}?` + N + String.raw`\s*%`, "gid")],
  ["of-N-hurt",   new RegExp(N + String.raw`\s*\*{0,2}\s*of\s+\d+\s+(?:hurt|down)\b`, "gid")],
  ["deaths",      new RegExp(N + String.raw`\s*\*{0,2}\s*deaths?\b`, "gid")],
  ["pct-of-runs", new RegExp(N + String.raw`\s*%[^.]{0,18}\bruns?\b`, "gid")]
];

/* WHAT IS NOT A MEASUREMENT, each with the case that put it here.

   A DENOMINATOR. "one party in 300 wiped" is a rate written longhand; 300 is the bottom of
   a fraction, not a sample statistic, and THROUGH_TRAIN writes rates that way throughout.

   A THRESHOLD. "Past 15 rounds" is a column header in fight-tail's table — it names the
   bucket the figures below are counted into, and it comes from the tool's own definition
   rather than from a run. Same for "1 in 100 runs past".

   BOTH ARE TESTED AGAINST THE CONTEXT, NOT THE MATCH. The first draft tested the matched
   text alone, which cannot work: the `rounds` shape captures "15 rounds" and the word that
   excuses it — "Past" — is outside the match. It reported a column header as an unheld
   figure, which is the false positive that makes a guard get switched off. */
const NOT_A_MEASUREMENT = [
  [/\b(?:in|of)\s+\*{0,2}\d+(?:\.\d+)?\*{0,2}\s*%?\s*\*{0,2}\s*(?:wiped|wipes)\b/i, "a denominator — 'one party in N wiped' is a rate written longhand"],
  [/\b(?:past|beyond|over|under|at least|fewer than)\s+\*{0,2}\d+(?:\.\d+)?\*{0,2}\s*(?:%|\s*rounds?)?\s*$/i, "a threshold, not a sample — it names a bucket, not a result"]
];

/* FIELDS check-cited REFUSES TO LET ANYBODY CITE, and their values.
   `longest` is a sample maximum: same party, same seeds, same runs, and renaming a config
   moved one from 71 to 90 rounds, because the stream is derived from the id. check-cited
   refuses a citation against it for that reason — but refusing the CITATION while the
   document prints the NUMBER leaves the least stable figure in the suite as the only one
   nothing holds. So a bare figure whose value matches an uncitable field is reported as its
   own kind of problem, with the field named. */
const UNCITEABLE_FIELDS = ["longest"];
const uncitableValues = new Map();
for (const rel of ["tools/pack-tables-baseline.json", "tools/fight-tail-baseline.json"]) {
  const abs = path.join(ROOT, rel);
  if (!existsSync(abs)) continue;
  const walk = (o, trail) => {
    if (o && typeof o === "object") {
      for (const [k, v] of Object.entries(o)) {
        if (UNCITEABLE_FIELDS.includes(k) && typeof v === "number") {
          uncitableValues.set(String(v), `${rel} ${[...trail, k].join(".")}`);
        }
        walk(v, [...trail, k]);
      }
    }
  };
  walk(JSON.parse(readFileSync(abs, "utf8")), []);
}

/* WHAT MAKES A COLUMN A MEASUREMENT, and therefore every number in it a figure.
   Drawn from the baselines' own field names, exactly as the shapes above are. A bare `%` is
   deliberately NOT here: a column of percentages may be skill ratings, and this corpus
   prints plenty of those. */
const MEASURE_HEADER = /\b(median|mean|average|wiped?|wipes|hurt|down|dead|deaths?|swing|rounds?|runs?|rate|odds|chance|share|percentile)\b/i;

/* THE UNION OF TWO WORD LISTS, and both halves were load-bearing. This file could not see
   *wipes* (`wiped?` does not match it) and missed the "Then wipes" column; check-unmarked
   could not see *runs* and missed "1 in 100 runs past", which is the p99 column R-269 added
   because the median is not a plan. Each list had a real gap the other covered, which is a
   better argument for the union than any of the three rates we computed arguing about it.

   NO THRESHOLD EXCLUSION APPLIES TO A HEADER. It was proposed and it is wrong: "Past 15
   rounds" names a bucket and its cells are still measured percentages of runs, so excluding
   the column would drop two correctly-cited figures. The threshold rule belongs where it
   already is, on the cell. */

/** A cell holding prose rather than a value: a sentence break, or simply too many words. */
const isProse = t => /[.!?]\s+\S/.test(t) || t.trim().split(/\s+/).filter(Boolean).length > 8;

/** Split a markdown table row into cells, keeping each cell's offset in the line. */
function cells(line) {
  const out = [];
  let at = line.indexOf("|");
  if (at < 0) return out;
  at += 1;
  for (;;) {
    const end = line.indexOf("|", at);
    if (end < 0) break;
    out.push({ text: line.slice(at, end), start: at });
    at = end + 1;
  }
  return out;
}

/** For every line, the header row of the table it is a body row of — or null. */
function tableHeaders(lines) {
  const owner = new Array(lines.length).fill(null);
  for (let i = 1; i < lines.length; i++) {
    if (!/^\s*\|[\s:|-]+\|\s*$/.test(lines[i])) continue;      /* the |---|---| separator */
    if (!/^\s*\|/.test(lines[i - 1])) continue;
    for (let j = i + 1; j < lines.length && /^\s*\|/.test(lines[j]); j++) owner[j] = lines[i - 1];
  }
  return owner;
}

/* A CITATION MARKER IS FULL OF DIGITS AND NONE OF THEM ARE FIGURES. `packs line.hollow6.hurt`
   holds a 6; `fight-tail cut.over15` holds a 15. Scanning raw cell text made the guard
   report every correctly-cited row in the document as unheld — 130 false positives, on the
   tables that are the best-marked thing in the corpus. Comments are BLANKED rather than
   removed so every offset still points at the right character of the real line. */
const maskComments = line => line.replace(/<!--[\s\S]*?-->/g, m => " ".repeat(m.length));

/* Inline code is quoted material, not the document making a claim — `wiped **8.3%**` in a
   sentence about how a marker is written must not become a finding. Blanked, not stripped,
   for the same reason the comments are: every offset has to keep pointing at the right
   character of the real line, because the marker lookup runs against the unmasked text. */
const maskCode = line => line.replace(/`[^`\n]*`/g, m => " ".repeat(m.length));

/** Figures in a table row, by the header of their own column rather than by phrasing. */
export function cellFiguresIn(line, header) {
  if (!header) return [];
  const heads = cells(header);
  const masked = maskComments(line);
  const out = [];
  for (const [i, cell] of cells(masked).entries()) {
    if (!MEASURE_HEADER.test(heads[i]?.text ?? "")) continue;
    /* A CELL THAT IS A SENTENCE IS NOT A VALUE. THROUGH_TRAIN's "Measured over 300 runs"
       column holds prose — *"2 of 4 hurt, half a party member down, no wipes. The intended
       shape."* — where the bold wraps a clause rather than a figure. The test is on the CELL
       and not on the header's words, because "1 in 100 runs past" and "Measured over 300
       runs" both contain *runs* and only one of them is prose. No edit to a word list can
       separate those two; looking at the cell can. */
    if (isProse(cell.text)) continue;
    const re = /(\d+(?:\.\d+)?)/g;
    let m;
    while ((m = re.exec(cell.text))) {
      /* "3.48 of 6" — the 6 is the party size the mean is out of, not a measurement. */
      if (/\bof\s+$/i.test(cell.text.slice(0, m.index))) continue;
      /* A DURATION IS NOT A HARNESS FIGURE. The Act Two beat table has a column headed
         "Runs" holding `~10 min` — *how long the beat runs*, a different sense of the word
         from the p99 column's "1 in 100 runs past". The suite measures ROUNDS and never
         minutes; this document says so itself, calling three-to-four minutes a round "an
         estimate, not a measurement". So the unit settles it, and the test is on the cell
         because both headers contain *runs* and no word list can tell them apart. */
      if (/^\s*(?:min|mins|minutes?|hrs?|hours?|secs?|seconds?)\b/i.test(cell.text.slice(m.index + m[1].length))) continue;
      const numEnd = cell.start + m.index + m[1].length;
      out.push({
        kind: `column:${(heads[i].text.replace(/[*|]/g, "").trim() || "?").toLowerCase()}`,
        value: m[1],
        text: cell.text.replace(/\s+/g, " ").trim() || m[1],
        at: numEnd,
        numAt: numEnd - m[1].length,
        marked: MARKED_AFTER.test(line.slice(numEnd))
      });
    }
  }
  return out;
}

/* BOLD IS THE CORPUS'S OWN MARK OF A PUBLISHED FIGURE — IN PROSE, AND ONLY THERE.
   The documents bold what they publish and leave ratings plain: `Brawl 55%` is a fact about
   a sheet, `**8.3%**` is a claim about a run. That is a signal from the corpus's habits
   rather than from a guard author's imagination, so it catches phrasings no shape list
   anticipates — the two figures that survived every reader here were `**1.29**` and
   `**48.7%**`, neither in a table and neither matching a shape.

   ⚠ AND IT IS WORTHLESS INSIDE A TABLE, which is the finding that sets this boundary. Nine
   measurement columns in the corpus mix bold with plain, every cell correctly cited. Four
   consecutive rows of the mixed-force table read `0%`, `**8.3%**`, `**30.1%**`, `93.8%` —
   and the two bolded rows are exactly the two the prose beneath singles out. A table bolds
   what it wants READ; prose bolds what it PUBLISHES. Same mark, two conventions, so inside a
   table this pass stays silent and the column header rules alone. */
const BOLD_PUBLISHED = /\*\*\s*(?:[~<>≈]\s*)?(\d[\d,]*(?:\.\d+)?\s*%|\d[\d,]*\.\d+)\s*\*\*/g;

/** Bold figures in a line of prose. Returns nothing for a table row, on purpose. */
export function boldFiguresIn(line) {
  if (/^\s*\|/.test(line)) return [];
  const masked = maskComments(line);
  const out = [];
  for (const m of masked.matchAll(BOLD_PUBLISHED)) {
    const at = m.index + m[0].length;
    out.push({ kind: "bold", value: m[1].replace(/[\s,%]/g, ""), text: m[0].trim(), at,
               numAt: m.index + m[0].indexOf(m[1]),
               marked: MARKED_AFTER.test(line.slice(at)) });
  }
  return out;
}

/* The marker check, deliberately looser than check-cited's CITE. That reader is strict on
   purpose; here, ANY citation-shaped comment beside the figure means somebody marked it and
   check-cited owns the question of whether they marked it correctly. Two guards disagreeing
   about what counts as marked would leave a figure that neither of them holds. */
const MARKED_AFTER = /^[ \t]*(?:%|x)?\**[ \t]*(?:—|-|–)?[ \t]*<!--[ \t]*cite[ \t]*:/i;

/* THE WAIVER, and why it is not a silencer. Some figures have no artifact to resolve
   against — three special/fumble bands out of `resolveBands`, a creature's Dodge rating, an
   opposed pair no countdown row uses. Refusing to mark them leaves the guard red forever and
   a red guard gets switched off, so they carry `<!-- uncited: why -->` instead. It must give
   a reason: an empty waiver is a decision nobody recorded, and it is fatal — the call made
   for the empty cast marker in R-288. Every waiver prints on every green build, so choosing
   to stop checking something stays visible instead of becoming the default. */
const WAIVED_AFTER = /^[ \t]*(?:%|x)?\**[ \t]*(?:—|-|–)?[ \t]*<!--[ \t]*uncited[ \t]*:[ \t]*([^>]*?)[ \t]*-->/i;
const waiverAt = rest => { const m = WAIVED_AFTER.exec(rest); return m ? { reason: m[1] } : null; };

/** Every measurement-shaped figure on one line, with whether it carries a marker. */
export function figuresIn(line) {
  const out = [];
  const seen = new Set();
  for (const [kind, re] of SHAPES) {
    re.lastIndex = 0;
    let m;
    while ((m = re.exec(line))) {
      /* THE CAPTURE'S OWN OFFSET, NOT A SEARCH FOR ITS TEXT. `line.indexOf(m[1], m.index)`
         finds the FIRST copy of the digits at or after the match start, which is not
         necessarily the one that was captured: "the wipe rate of 74 in ten is 74%" matches
         with m[1] = "74", and the search lands on the earlier 74. numEnd then points into
         the middle of the sentence, the marker test reads " in ten is 74%…" and a correctly
         cited figure is reported as bare. Found by a stranger's read of the fold; it needs
         an integer duplicate inside the one shape with a wide gap before its capture, so it
         is contrived — but its failure is the bad direction, a FALSE POSITIVE on good prose,
         which is the class that teaches a reader to stop reading the output.
         The `d` flag gives the capture's real position and there is nothing to search for. */
      const numEnd = m.indices[1][1];
      /* Context, not the match: the word that excuses a figure sits outside it. */
      const before = line.slice(Math.max(0, m.index - 24), numEnd);
      if (NOT_A_MEASUREMENT.some(([re2]) => re2.test(before) || re2.test(m[0]))) continue;
      /* One figure can match two shapes ("2 rounds" inside "median 2 rounds"); the figure is
         the number, so it is counted once at the position it occupies. */
      if (seen.has(numEnd)) continue;
      seen.add(numEnd);
      out.push({ kind, value: m[1], text: m[0].trim(), at: numEnd, numAt: numEnd - m[1].length,
                 marked: MARKED_AFTER.test(line.slice(numEnd)) });
    }
  }
  return out.sort((a, b) => a.text.localeCompare(b.text));
}

/**
 * Every figure in one document, by all three readers. Exported and taking a STRING because
 * a reader tested by editing the corpus proves the corpus, and goes quiet the day somebody
 * rewords the sentence it was anchored to (R-292).
 */
export function scanDocument(label, src) {
  const lines = src.split("\n");
  /* Fenced blocks are the safe harbour, exactly as they are for check-outcomes: a code
     sample or a recorded harness dump is not the document making a claim. */
  const fenced = new Set();
  let inFence = false;
  lines.forEach((ln, i) => {
    if (/^\s*```/.test(ln)) { inFence = !inFence; fenced.add(i); return; }
    if (inFence) fenced.add(i);
  });

  const optedIn = /<!--[ \t]*cite[ \t]*:/i.test(src);
  const cites = (src.match(/<!--[ \t]*cite[ \t]*:/gi) ?? []).length;
  const headers = tableHeaders(lines);
  const rows = [], strict = [], waived = [];
  let unmarked = 0;

  lines.forEach((ln, i) => {
    if (fenced.has(i)) return;
    /* Three readers can find the same number — `**8.3%**` is a bold published figure AND a
       `wipes N%` shape — and they stop at different characters, one after the digits and one
       after the closing asterisks. So the identity of a figure is WHERE ITS NUMBER STARTS,
       not where its marker would go, or the same figure is reported twice. */
    const seen = new Set();
    /* THE PROSE-CELL RULE BINDS THE COLUMN PASS AND NOT THE SHAPE PASS, and the difference is
       what each reader claims. The column pass takes every number in a measurement column on
       the header's authority, so in a cell of narrative it would claim words; the shape pass
       matches a named phrasing — "2 of 4 hurt" is a measured figure whether it sits in a
       sentence or not. Blanking prose cells for both read well and quietly dropped twelve
       real figures out of THROUGH_TRAIN's ratchet, which is coverage this guard already had.
       The exclusion lives in cellFiguresIn, where the claim it guards is made. */
    const scan = maskCode(ln);
    const found = [...figuresIn(scan), ...cellFiguresIn(scan, headers[i] && maskCode(headers[i])),
                   ...boldFiguresIn(scan)]
      .filter(f => !seen.has(f.numAt) && seen.add(f.numAt));
    for (const f of found) {
      rows.push({ label, line: i + 1, ...f, optedIn });
      if (f.marked) continue;

      const w = waiverAt(ln.slice(f.at));
      if (w) {
        if (!w.reason) strict.push(`  ${label}:${i + 1} — "${f.text}" carries an EMPTY `
          + `\`uncited:\` waiver. A waiver with no reason is a decision nobody recorded. Say why `
          + `this figure has no artifact, or cite it.`);
        else waived.push({ label, line: i + 1, text: f.text, reason: w.reason });
        continue;
      }

      unmarked++;
      if (!optedIn) continue;
      const uncitable = uncitableValues.get(f.value);
      strict.push(uncitable
        ? `  ${label}:${i + 1} — "${f.text}" is bare, and ${f.value} is the value of `
          + `${uncitable}, a field check-cited REFUSES to let anybody cite because a sample `
          + `maximum moves by a third on a re-seed. Refusing the citation while printing the `
          + `number leaves the least stable figure in the suite as the only one nothing holds. `
          + `Do not cite it — stop printing it, and lean on the guarantee instead.`
        : `  ${label}:${i + 1} — "${f.text}" carries no citation marker, in a document `
          + `that cites ${cites} other figures. `
          + `Either mark it, or say in words why this number is not a measurement.`);
    }
  });
  return { rows, strict, waived, unmarked, optedIn };
}

/* ── running the guard ─────────────────────────────────────────────────────────────────
   EVERYTHING BELOW RUNS ONLY WHEN THIS FILE IS THE ENTRY POINT, and the reason is not tidiness.
   `scanDocument` is exported so check-behaviour can test the readers on strings (R-292), and
   for one commit importing it ALSO ran the whole guard: a figure defect called `process.exit(1)`
   inside check-behaviour, which then reported check-figures' failure under its own name having
   run ZERO of its 107 tests. A guard that stops another guard from running while appearing to
   participate is the worst version of the fault this file exists to catch. Same idiom as
   step5-split.mjs. */
if (import.meta.main || process.argv[1]?.endsWith("check-figures.mjs")) {
  const strict = [];
  const loose = {};
  const rows = [];
  const waived = [];

  for (const [label, abs] of playableFiles()) {
    const r = scanDocument(label, readFileSync(abs, "utf8"));
    rows.push(...r.rows); strict.push(...r.strict); waived.push(...r.waived);
    if (!r.optedIn) loose[label] = r.unmarked;
  }

  /* ── the ratchet, for documents outside the citation regime ────────────────────────────── */

  const base = existsSync(BASELINE) ? JSON.parse(readFileSync(BASELINE, "utf8")) : null;

  if (UPDATE) {
    writeFileSync(BASELINE, JSON.stringify({
      note: "Unmarked measurement figures in scenarios that use no citations. May fall, never rise. "
          + "Generated by tools/check-figures.mjs --update.",
      uncited: loose
    }, null, 1) + "\n");
    console.log(`check-figures: recorded ${Object.keys(loose).length} document(s) outside the citation regime`);
    process.exit(0);
  }

  const problems = [...strict];

  if (!base) {
    problems.push(`  no ratchet at tools/figures-baseline.json — run: node tools/check-figures.mjs --update`);
  } else {
    for (const [label, n] of Object.entries(loose)) {
      const was = base.uncited?.[label];
      if (was === undefined) {
        problems.push(`  ${label} uses no citations and is not in the ratchet. Re-record with --update, `
          + `or give it its first citation marker and it joins the strict regime.`);
      } else if (n > was) {
        problems.push(`  ${label}: unmarked measurement figures went ${was} -> ${n}. This document cites `
          + `nothing, so the ratchet is all that holds it: the count may fall, never rise.`);
      }
    }
    /* A document that LEAVES the loose set has gained its first citation, which is good news
       and must not be reported as a missing row. A document that vanishes entirely has been
       deleted or reclassified, and that is worth saying out loud. */
    for (const label of Object.keys(base.uncited ?? {})) {
      if (!(label in loose) && !rows.some(r => r.label === label)) {
        problems.push(`  ${label} is in the ratchet but no longer in the corpus. If it was renamed or `
          + `deleted, re-record with --update.`);
      }
    }
  }

  if (LIST) {
    for (const r of rows) {
      console.log(`  ${r.marked ? "cited " : "BARE  "} ${r.label}:${r.line}  [${r.kind}]  ${r.text}`);
    }
    problems.forEach(p => console.log(p));
    process.exit(0);
  }
  if (problems.length) {
    console.error("check-figures: FAILED — measured figures are printed with nothing holding them");
    problems.forEach(p => console.error(p));
    console.error(`  check-cited resolves the markers that exist; it cannot see a figure that has none. `
      + `That is how "a median 24 rounds" survived ten passes against a baseline holding 21.`);
    process.exit(1);
  }
  /* WAIVERS ARE PRINTED ON EVERY GREEN BUILD. A figure nobody checks is the defect this guard
     exists for, and a waived figure is one we have decided to stop checking — so the decision
     stays on screen rather than becoming the default. Six of them is a short list; sixty would
     be a finding. */
  if (waived.length) {
    console.log(`check-figures: ${waived.length} figure(s) waived, each on the record:`);
    for (const w of waived) console.log(`    ${w.label}:${w.line}  ${w.text} — ${w.reason}`);
  }

  const marked = rows.filter(r => r.marked).length;
  const looseTotal = Object.values(loose).reduce((a, b) => a + b, 0);
  console.log(`check-figures: OK — ${rows.length} measurement-shaped figures across ${new Set(rows.map(r => r.label)).size} `
    + `scenarios, ${marked} marked and ${waived.length} waived; ${looseTotal} bare in `
    + `${Object.keys(loose).length} document(s) that cite nothing, held at the ratchet`);
}