clearotron 0.4.0-beta.2 → 0.4.0

package/scripts/e2e.mjs

@@ -57,6 +57,7 @@ import { isLiveQueueMarker, isQueueSidecar, liveQueueState, LIVE_QUEUE_STATES, T
 // leave the real one to park tomorrow's re-run as a duplicate. usage-ledger.mjs is a pure leaf too
 // (node:fs + node:path + queue-markers.mjs), so it drags no driver machinery in either.
 import { matterLedgerPath } from "../driver/usage-ledger.mjs";
+import { registerServedLine } from "../driver/register-served.mjs";   // which register a run recorded as having served it
 import { probeWorker } from "../driver/queue-watch-probe.mjs";   // the drain this deployment actually has
 // Teardown asks whether a process is actually producing a run before it rewrites the record that says so.
 import { claimLivenessForCodename, claimForbidsDestruction } from "../driver/claim-liveness.mjs";
@@ -336,6 +337,75 @@ const allScenarios = () => {
     .sort((a, b) => byScenarioNumber(a.id, b.id));
 };
 
+// ── A SCENARIO MAY NAME THE REGISTER ITS NUMBERS WERE MEASURED AGAINST ──────────────────────────────
+//
+// THE DEFECT THIS CLOSES. A scenario's register floors are counts, and a count is an answer one register
+// gave. Run the same scenario against a different register and the floor decides nothing about the
+// engine: measured 2026-09-30 on a knockout whose floors are `identical: 8` and `containing: 300`, the
+// other register answered 2 and 471 for the SAME mark. One floor failed and one passed, in one run, and
+// neither outcome was about the engine. A red like that costs a round: it reads as a regression, it is
+// investigated as one, and the run that produced it is already spent.
+//
+// WHAT THIS DOES NOT DO, deliberately. It does not encode which register returns more. The measurement
+// says the two DISAGREE — 2 against 8 on one predicate and 471 against 300 on another, in opposite
+// directions — and nothing here has established why. A floor per register would need that why, and a
+// harness rule must not smuggle one in. So a scenario states which register its numbers came from, and
+// the harness refuses to spend the run anywhere else.
+//
+// OPTIONAL BY CONSTRUCTION, because the store is a DIFFERENT REPO. A scenario that declares nothing
+// behaves exactly as it does today. There is no ordering problem to manage and no day on which this
+// harness refuses a store that has not caught up.
+//
+// WHY THIS DOES NOT ASK THE DRIVER. `driver.config.mjs` resolves the provider, and this file may not
+// import it — its unset-env defaults are PRODUCTION, which is the rule stated at four points above. The
+// variable is read here directly and with no fallback: unset stays unset, and unset is reported as its
+// own state rather than resolved to anything.
+//
+// CONFIGURED, NOT SERVED, and the difference is a live gap. What a run was configured for is the
+// launch value; what actually served it is a separate record the runs do not yet carry (measured
+// 2026-09-30: absent on all four runs of a round, on both the knockout and the clearance path). When
+// that record exists, an assertion could read what served. Until then this is a PRE-RUN refusal on the
+// configured value, which is the honest instrument available — and it is placed before the spend, where
+// being approximately right still saves the money.
+export const REGISTER_ENV = "CLEAROTRON_DATABASE";
+
+/** The registers a scenario declares its numbers were measured against, lowercased. `[]` when it declares none. PURE. */
+export function registersDeclaredBy(sc) {
+  const v = sc?.register;
+  const list = Array.isArray(v) ? v : v == null ? [] : [v];
+  return list.map((x) => String(x ?? "").trim().toLowerCase()).filter(Boolean);
+}
+
+/** The register this process is configured for, or `null` when the variable names none. No default, ever. PURE apart from the read. */
+export function configuredRegister(env = process.env) {
+  return String(env?.[REGISTER_ENV] ?? "").trim().toLowerCase() || null;
+}
+
+/**
+ * The refusal text for running `sc` here, or `null` when there is nothing to refuse. PURE.
+ *
+ * Three cases, and the middle one is the reason this returns text rather than a boolean: a scenario that
+ * declares a register and an environment that names none is NOT a match and NOT a mismatch. Running it
+ * would spend against whatever the driver defaults to, which this file is not allowed to ask about, so
+ * the refusal says exactly that rather than guessing either way.
+ */
+export function registerRefusal(sc, env = process.env) {
+  const want = registersDeclaredBy(sc);
+  if (!want.length) return null;
+  const have = configuredRegister(env);
+  const declares = want.length === 1 ? want[0] : `one of ${want.join(", ")}`;
+  if (!have) {
+    return `${sc.id} states that its numbers were measured against ${declares}, and ${REGISTER_ENV} names no register `
+      + `on this instance. This harness does not resolve a default — the module that would is the one it may not import. `
+      + `Set ${REGISTER_ENV} to ${declares} and run again.`;
+  }
+  if (want.includes(have)) return null;
+  return `${sc.id} states that its numbers were measured against ${declares}, and this instance is configured for ${have}. `
+    + `What one register answered is not what another answers, so here this scenario would judge the register `
+    + `and not the engine — and a red read as a regression arrives on a run that is already spent. `
+    + `Set ${REGISTER_ENV} to ${declares}, or run a scenario whose numbers were measured against ${have}.`;
+}
+
 // ── — the store is the input to the most expensive thing this repo does ─────────────────────────
 //
 // Every job block in the store, through BOTH admission gates, against the outcome the scenario declares.
@@ -439,6 +509,20 @@ export function lintScenarios(scenarios) {
     for (const f of sc.expect?.artifacts ?? []) {
       if (/^\/|\.\./.test(f)) wrong.push(`${label}: artifact ${JSON.stringify(f)} must be a plain run-relative name`);
     }
+    // ── `register`, IF STATED, MUST BE STATABLE ────────────────────────────────────────────────────
+    //
+    // SHAPE ONLY, AND NOT THE NAME. Checking the value against the known providers would mean importing
+    // `driver.config.mjs`, which this file may not do. That is not a hole worth patching another way: a
+    // misspelled register never runs anywhere, and the refusal it produces prints the scenario's word
+    // and the instance's word side by side, which is a typo shown rather than described. What IS worth
+    // refusing is a value nothing can compare at all — an empty string, a number, an empty list — since
+    // that would declare a register and then silently compare against nothing.
+    if (Object.prototype.hasOwnProperty.call(sc, "register")) {
+      const raw = Array.isArray(sc.register) ? sc.register : [sc.register];
+      const bad = raw.length === 0 || raw.some((x) => typeof x !== "string" || !x.trim());
+      if (bad) wrong.push(`${label}: \`register\` is ${JSON.stringify(sc.register)} — it must be a non-empty register name, or a non-empty list of them. `
+        + `A scenario states this when its numbers are counts one register returned, so that a run against another is refused before it spends.`);
+    }
     const allAsserts = [...(sc.expect?.assert ?? []), ...(sc.cases ?? []).flatMap((c) => c.expect?.assert ?? [])];
     for (const a of allAsserts) {
       if (/^_driver\/scope-ledger\.json/.test(String(a.path ?? ""))) {
@@ -1213,6 +1297,11 @@ export function outboxPackets({ runId = null, runIds = [], queueBase = null } =
   return { packets: [...hit].sort(), unreadable: null };
 }
 
+// WITHHELD UNLESS ASKED, and the default is off so nothing has to remember to turn it on. Set once from
+// argv; `evalAssertion` takes it as an option so a test can drive both paths without touching argv.
+export let REPORT_NAMES = false;
+export const setReportNames = (v) => { REPORT_NAMES = Boolean(v); };
+
 // ── assertions ───────────────────────────────────────────────────────────────────────────────────────
 // Every op is implemented or explicitly reported UNIMPLEMENTED. An op that silently passes because
 // nobody wrote it is the exact failure mode this whole suite exists to prevent.
@@ -1339,7 +1428,70 @@ function bandShapeUnder(full, file, field) {
   return { doc, unread, shallow, verdict };
 }
 
-function evalAssertion(a, runDir) {
+/**
+ * A quotation from a RUN, or where to find it.
+ *
+ * WHY THIS EXISTS. `report` is the cheap instrument — free, re-runnable, and the doctrine tells a lane to
+ * re-run it rather than re-run the clearance — so it is the one most often pointed at a real matter, in a
+ * session that records whatever it prints. Its INVESTIGATE rows earned their usefulness by showing the
+ * sentence they object to, and that sentence is the engine's own words about a client's matter.
+ *
+ * A LOCATION IS AS ACTIONABLE AS A QUOTE AND CARRIES NOTHING. "sentence 14 of knockout-findings.md" sends
+ * a reader to the same words, in the file that already holds them, without copying them anywhere else.
+ * The one job that needs them on the page — reading a surprising row against the text — asks with
+ * `--names`, the same flag the scorer takes for the same reason.
+ *
+ * The count is never withheld. How many claims exceeded their evidence is the finding; which words they
+ * used is the detail.
+ */
+/**
+ * One door's refusal line.
+ *
+ * A DOOR'S REFUSAL TEXT IS THE DOOR'S, NOT OURS, and that is the reason to gate it rather than a reason
+ * not to. Measured across every receipt on this box — 397 door answers, 213 refusals, 113 distinct
+ * reasons — not one echoes the order: they carry an HTTP status and the server's own error envelope, or
+ * a socket error. So this guards a case that has not happened, and it is worth one line, because the
+ * half of these that CAN echo is structural: an `initialize` refusal is sent before any order exists and
+ * cannot carry one, a `tools/call` refusal is sent after and can. Which it does is the door's own
+ * error-message discipline, which nothing here governs and no clipping saves — an echoing server puts
+ * the mark near the front, well inside the 160 characters this used to print.
+ *
+ * A MISSING REASON IS NOT A WITHHELD ONE. "(no reason recorded)" is a fact about the receipt and says so
+ * plainly; offering to print it with `--names` would promise words that do not exist.
+ */
+export function doorReasonLine(r, names = REPORT_NAMES) {
+  if (r?.reason == null || String(r.reason).trim() === "") return "(no reason recorded)";
+  return fromTheRun({ names, quotes: [String(r.reason)],
+    where: "the door's own words are in the round receipt, at rounds[].cases[].answers[].reason" });
+}
+
+function fromTheRun({ names, quotes, where }) {
+  // THE LOCATION IS KEPT WHEN THE WORDS ARE SHOWN. It costs one clause beside the quotation it stands in
+  // for, and a reader chasing a surprising row wants to go and read around it rather than only at it.
+  if (names) return `${quotes.map((q) => `"${String(q).slice(0, 160)}"`).join(" · ")} (${where})`;
+  return `${where} — run again with --names to read them here`;
+}
+
+/**
+ * The row that fires when a listing does not hold the mark an assertion asked for.
+ *
+ * It is the WIDEST row in either floor op: it printed the name asked for and every name the listing did
+ * hold, in clear, with no flag involved, and it fires precisely when somebody is investigating — a mark
+ * is absent, so a reader is reading the report. It exists twice, once per floor op, with one verb each.
+ *
+ * The COUNT is never withheld. A listing that held nothing is a different defect from one that held four
+ * other marks, and that distinction is the finding.
+ */
+function noSuchMark({ names, field, marks, file, verb }) {
+  const listed = (marks ?? []).map((x) => x?.name).filter((x) => typeof x === "string");
+  return { ok: false, saw: `the asked-for mark is not in ${file}, which ${verb} ${listed.length} mark(s)`
+    + (listed.length
+      ? ` — ${fromTheRun({ names, quotes: [field, ...listed],
+          where: `the name asked for is the field of this assertion's path, and the names ${verb} are the "marks" array of ${file}` })}`
+      : "") };
+}
+
+function evalAssertion(a, runDir, { names = REPORT_NAMES } = {}) {
   const [file, field] = String(a.path ?? "").split(":");
   const full = join(runDir, file || "");
 
@@ -1566,13 +1718,19 @@ function evalAssertion(a, runDir) {
     const held = recordsFile
       ? (recordsFile.marks ?? []).reduce((n, m) => n + (m.records ?? []).length, 0)
       : null;
-    const bad = sentences.filter((s) => aboutRegister.test(s) && !staysInside.test(s)
+    // Carried WITH ITS POSITION, because the index is what a withheld row prints instead of the words.
+    // `indexOf` on the sentence would be wrong the moment a document repeats one: both rows would send
+    // the reader to the first copy, and a run that says the same thing twice is exactly the run somebody
+    // is reading the report about.
+    const badAt = sentences.map((s, i) => ({ s, i })).filter(({ s }) => aboutRegister.test(s) && !staysInside.test(s)
       && (exceedsACount.test(s) || (singularAbsence.test(s) && !(held > 0))));
+    const bad = badAt.map(({ s }) => s);
     const basis = held === null
       ? "_driver/register-records.json is absent or unreadable, so this is as strict as a run holding zero records — identical verdict, different reason: one is a fact about the search, this is a fact about the check's own evidence"
       : `the run holds ${held} register record(s), so a status read off one is supported and only a claim over the field is not`;
     return { ok: bad.length === 0,
-      saw: bad.length ? `${bad.length} register claim(s) wider than the records this run holds — ${bad.slice(0, 2).map((s) => `"${s.slice(0, 120)}"`).join(" · ")} (${basis})`
+      saw: bad.length ? `${bad.length} register claim(s) wider than the records this run holds — `
+        + `${fromTheRun({ names, quotes: bad.slice(0, 2), where: `sentence ${badAt.slice(0, 2).map(({ i }) => i + 1).join(" and ")} of ${file}` })} (${basis})`
         : `${sentences.filter((s) => aboutRegister.test(s)).length} register sentence(s), each a count, a labelled expectation, or a status the records support — ${basis}` };
   }
   // `survivor-not-clear` — a mark this lane did not knock out is a SURVIVOR, never a clear. The two words
@@ -1712,7 +1870,7 @@ function evalAssertion(a, runDir) {
     const want = field ? String(field).trim().toLowerCase() : null;
     if (!want) return { ok: false, saw: "no mark given (path must be <file>:<MARK NAME>)" };
     const m = (doc.marks ?? []).find((x) => String(x?.name ?? "").trim().toLowerCase() === want);
-    if (!m) return { ok: false, saw: `no mark ${JSON.stringify(field)} in ${file} — it counted ${(doc.marks ?? []).map((x) => JSON.stringify(x?.name)).join(", ") || "nothing"}` };
+    if (!m) return noSuchMark({ names, field, marks: doc.marks, file, verb: "counted" });
     const floors = a.value && typeof a.value === "object" ? a.value : null;
     if (!floors) return { ok: false, saw: "value must be an object of predicate floors, e.g. {\"identical\": 45}" };
     const saw = [], short = [], untaken = [];
@@ -1720,7 +1878,12 @@ function evalAssertion(a, runDir) {
       const cell = m.counts?.[pred];
       if (!cell) { untaken.push(`${pred}: no such predicate on this run's sidecar`); continue; }
       if (!Number.isFinite(cell.total)) {
-        untaken.push(`${pred}: NOT TAKEN — ${String(cell.unavailable ?? "no reason recorded").slice(0, 160)}`);
+        // THE SAME FIELD AND THE SAME PROVENANCE as the `unavailable` twenty lines below, which is
+        // withheld — this one is the engine's own prose about why a count could not be taken, out of the
+        // run's sidecar. Withheld with it, and located by the predicate it belongs to.
+        untaken.push(`${pred}: NOT TAKEN — ${cell.unavailable === undefined || cell.unavailable === null
+          ? "no reason recorded"
+          : fromTheRun({ names, quotes: [String(cell.unavailable)], where: `the reason is counts.${pred}.unavailable of ${file}` })}`);
         continue;
       }
       saw.push(`${pred}=${cell.total} (floor ${floor})`);
@@ -1744,11 +1907,14 @@ function evalAssertion(a, runDir) {
     if (!existsSync(full)) return { ok: false, saw: `${file} absent — the filings lane wrote nothing, not even its refusal` };
     const doc = readJson(full);
     if (!doc) return { ok: false, saw: `${file} present but unparseable` };
-    if (doc.unavailable) return { ok: false, saw: `the filings were never listed — ${String(doc.unavailable).slice(0, 200)}. A listing that was refused is not a register that holds nothing.` };
+    if (doc.unavailable) return { ok: false, saw: `the filings were never listed — `
+      + `${fromTheRun({ names, quotes: [String(doc.unavailable)], where: `the reason is the "unavailable" field of ${file}` })}. `
+      + `A listing that was refused is not a register that holds nothing.` };
     const want = field ? String(field).trim().toLowerCase() : null;
     if (!want) return { ok: false, saw: "no mark given (path must be <file>:<MARK NAME>)" };
-    const m = (doc.marks ?? []).find((x) => String(x?.name ?? "").trim().toLowerCase() === want);
-    if (!m) return { ok: false, saw: `no mark ${JSON.stringify(field)} in ${file} — it listed ${(doc.marks ?? []).map((x) => JSON.stringify(x?.name)).join(", ") || "nothing"}` };
+    const markIndex = (doc.marks ?? []).findIndex((x) => String(x?.name ?? "").trim().toLowerCase() === want);
+    const m = markIndex === -1 ? null : doc.marks[markIndex];
+    if (!m) return noSuchMark({ names, field, marks: doc.marks, file, verb: "listed" });
     const floors = a.value && typeof a.value === "object" ? a.value : {};
     const minRecords = Number.isFinite(floors.records) ? floors.records : 1;
     const minOffices = Number.isFinite(floors.offices) ? floors.offices : 1;
@@ -1756,8 +1922,15 @@ function evalAssertion(a, runDir) {
     const offices = [...new Set(records.map((r) => String(r?.territory ?? "").trim().toLowerCase()).filter(Boolean))];
     // A term the register refused is REDUCED COVERAGE, and it is named whichever way the floor goes: met,
     // it qualifies what was proved; missed, it says the shortfall may be the fetch rather than the register.
-    const failed = (m.terms ?? []).filter((t) => t?.ok !== true)
-      .map((t) => `${t?.term ?? "?"}: ${String(t?.reason ?? "no reason recorded").slice(0, 120)}`);
+    // A TERM IS A SPELLING OF A MARK and the reason is the engine's own prose, so both are withheld by
+    // default; the INDEX still says which of the run's terms to go and read.
+    const failedRows = (m.terms ?? []).map((t, i) => ({ t, i })).filter(({ t }) => t?.ok !== true);
+    const failed = names
+      ? failedRows.map(({ t }) => `${t?.term ?? "?"}: ${String(t?.reason ?? "no reason recorded").slice(0, 120)}`)
+      // NAMED BY POSITION IN THE FILE, both coordinates. `term 2 of knockout-filings.json` is ambiguous
+      // the moment the listing holds more than one mark, and it always does — so the row would send a
+      // reader to a term belonging to a different mark and read just as confidently.
+      : failedRows.map(({ i }) => `term ${i + 1} of mark ${markIndex + 1} of ${file}`);
     const met = records.length >= minRecords && offices.length >= minOffices;
     const body = `${records.length} record(s) (floor ${minRecords}) across ${offices.length} office(s) [${offices.join(", ") || "none"}] (floor ${minOffices})`;
     if (met) return { ok: true, saw: failed.length ? `${body} — floor met, but ${failed.length} term(s) were refused and this run covered less than it asked for: ${failed.join(" · ")}` : body };
@@ -2095,7 +2268,11 @@ export function provenanceLines(cost, today = new Date()) {
 
 function cmdList() {
   console.log("\nE2E scenarios — each is one complete clearance unless marked $0");
-  console.log(`store: ${storeLine(STORE)}\n`);
+  console.log(`store: ${storeLine(STORE)}`);
+  // WHAT THIS INSTANCE IS CONFIGURED FOR, once at the top, because it decides which of the scenarios
+  // below `run` will start. Printed even when nothing declares a register: a reader choosing a scenario
+  // needs to know the variable names none BEFORE the refusal tells them.
+  console.log(`register: ${configuredRegister() ?? `${REGISTER_ENV} names none`}\n`);
   sweepStoreOrDie();
   for (const s of allScenarios()) {
     const cost = s.cost?.measured ? `~${s.cost.wallMinutes} min` : "UNMEASURED";
@@ -2110,6 +2287,16 @@ function cmdList() {
     // all, and an absent benchmark is not a met one.
     for (const l of turnaroundVerdict(bandForScenario(s)).lines) console.log(`      ${l}`);
     for (const l of provenanceLines(s.cost)) console.log(`      ${l}`);
+    // WHETHER `run` WOULD START THIS ONE HERE, at a glance, so the choice is made in the list rather
+    // than discovered one scenario at a time. The refusal's own words, not a second wording of them.
+    {
+      const declared = registersDeclaredBy(s);
+      if (declared.length) {
+        const no = registerRefusal(s);
+        console.log(`      register: measured against ${declared.join(", ")} — ${no ? "WOULD REFUSE HERE" : "runnable here"}`);
+        if (no) console.log(`        ${no}`);
+      }
+    }
     // — which scenarios prove the register HIT path, at a glance. Unconditional, and an
     // unstated label prints as loudly as a stated one.
     {
@@ -2173,6 +2360,13 @@ async function cmdRun(id) {
   // Which store this came from, on the record before the run spends. The synthetic and the real scenario
   // share an ID, so the ledger afterwards cannot tell you which one ran unless the run says so now.
   console.log(`store: ${storeLine(STORE)}`);
+  // BEFORE THE SPEND, because that is the only place this check is worth anything: a scenario whose
+  // floors were measured against another register produces a red that reads as an engine regression,
+  // and by then the run is paid for. `die` rather than a warning — a warning printed above a three-hour
+  // run is a warning nobody reads until the verdict.
+  { const no = registerRefusal(s); if (no) die(`REFUSING: ${no}`); }
+  console.log(`register: ${configuredRegister() ?? `${REGISTER_ENV} names none`}${
+    registersDeclaredBy(s).length ? ` — the scenario states its numbers were measured against ${registersDeclaredBy(s).join(", ")}` : ""}`);
   // Every scenario spends, R0 included — so every scenario refuses on stale code. R0 was exempted here
   // on the belief that it is refused at the door before any model call, which its own `why` also claimed.
   // It is not: R0d's FIRST submission is expected to admit (that is how it produces a duplicate to
@@ -3091,6 +3285,10 @@ async function cmdReport(id, { round: requestedToken = null } = {}) {
       // — the handover's "commit SHA on test" field, READ rather than reconstructed. An absence
       // is printed as itself: a run that predates the stamp has none, and inventing one from a reflog
       // is the reconstruction this replaces.
+      // — WHICH REGISTER SERVED IT, beside the engine build because it is the same class of fact: what
+      // this run actually ran against, read as a field rather than searched for as a substring. An absence
+      // prints as itself, because "not recorded" is not "none served" and a reader must not have to guess.
+      console.log(`         register: ${registerServedLine(readJson(join(run.runDir, "status.json")))}`);
       const eb = engineBuildOf(run.runDir);
       if (!eb) console.log(`         engine build: NOT RECORDED — this run predates the run-start stamp (#1423); any attribution for it is a reflog reconstruction`);
       else {
@@ -3177,7 +3375,7 @@ async function cmdReport(id, { round: requestedToken = null } = {}) {
           notProbed.push(`${ref}: the doors refused, but this receipt records no REASON — re-run with the current e2e.mjs to check expect.reasonMatches`);
           console.log(`  reason: NOT RECORDED by the round that wrote this receipt — not a pass`);
         } else {
-          for (const r of refusal.reasons) console.log(`      [${r.door}] ${String(r.reason ?? "(no reason recorded)").slice(0, 160)}`);
+          for (const r of refusal.reasons) console.log(`      [${r.door}] ${doorReasonLine(r)}`);
           if (refusal.wantReason && refusal.missed.length)
             toInvestigate.push(`${ref}: refused, but ${refusal.missed.join(", ")} did not say "${refusal.wantReason}" — a refusal for the wrong reason reads exactly like the right one`);
           else if (refusal.wantReason) console.log(`  [ ok ] every door's reason carries "${refusal.wantReason}"`);
@@ -3392,8 +3590,27 @@ async function cmdReport(id, { round: requestedToken = null } = {}) {
       // A multi-name knockout stamps NO single url BY DESIGN: one address would be the first
       // name standing for the batch, so the packet carries `reports[{mark, url}]` instead. Read it —
       // from the run dir, or from the pool meta once the run dir is archived — and probe every per-mark
-      // address exactly as the single-url arm does. Only a delivered run with neither a url nor a
-      // reports[] list is the CLEAROTRON_REPORTS_URL absence this arm was written for.
+      // address exactly as the single-url arm does.
+      //
+      // ── WHAT THE TWO ABSENCE ARMS BELOW MEASURE, AND WHAT THEY CANNOT SEE ───────────────────────────
+      //
+      // They measure one thing: no entry carries a url. They used to REPORT a second thing they never
+      // looked at — that CLEAROTRON_REPORTS_URL is unset — and the row said it flatly, as a fact about
+      // the instance.
+      //
+      // IT IS NOT ALWAYS TRUE, measured on a test instance 2026-09-30: the variable was present and
+      // non-empty both in the instance's env file and in the worker process's own environment, and the
+      // run's eight report entries each carried a `url` KEY WITH AN EMPTY VALUE. The stamp had run and
+      // produced nothing. On that run the stated cause was simply wrong, and the cause of the empty
+      // stamp is still unknown.
+      //
+      // WHAT IT COSTS TO STATE A CAUSE YOU DID NOT MEASURE: acting on the row, the obvious repair is to
+      // restore the variable from a backup — overwriting a working value with an older one and calling
+      // it a fix. That was nearly done here.
+      //
+      // So the row states the measurement and the investigate line keeps the hypothesis, marked as one.
+      // A reader who wants the cause reads the variable on the instance and the stamp's own output; this
+      // check is not in a position to tell them.
       const batchReports = (() => {
         try { return JSON.parse(readFileSync(driverDir(runDir, "delivery.json"), "utf8")).reports ?? []; } catch { /* archived or pre-batch */ }
         try { return JSON.parse(readFileSync(join(poolDir, "meta.json"), "utf8")).reports ?? []; } catch { /* no pool entry */ }
@@ -3411,13 +3628,14 @@ async function cmdReport(id, { round: requestedToken = null } = {}) {
           else if (error) { failures++; toInvestigate.push(`${ref}: could not probe ${r.mark}'s report URL (${error}) — ${r.url}`); }
         }
       } else if (batchReports.length) {
-        console.log(`  [FAIL] the run's stamped URL resolves\n           delivered as a batch of ${batchReports.length}, but no report entry carries a url — CLEAROTRON_REPORTS_URL is unset on this instance`);
-        failures++; toInvestigate.push(`${ref}: batch delivered with no per-report URL stamped (CLEAROTRON_REPORTS_URL unset?)`);
+        console.log(`  [FAIL] the run's stamped URL resolves\n           delivered as a batch of ${batchReports.length}, and not one of those entries carries a url`);
+        failures++; toInvestigate.push(`${ref}: batch delivered with no per-report URL stamped — cause NOT measured here; read CLEAROTRON_REPORTS_URL on the instance AND what the stamp wrote, because a set variable can still stamp empty`);
       } else {
-        // A delivered run with no URL at all is the same absence one step earlier: CLEAROTRON_REPORTS_URL unset
-        // makes publishReport stamp null, and the handoff packet then carries no address for anyone to open.
-        console.log(`  [FAIL] the run's stamped URL resolves\n           delivered, but status.json carries no url — CLEAROTRON_REPORTS_URL is unset on this instance`);
-        failures++; toInvestigate.push(`${ref}: delivered with no report URL stamped (CLEAROTRON_REPORTS_URL unset?)`);
+        // A delivered run with no URL at all is the same absence one step earlier, and the same limit
+        // applies: this arm sees that the record carries no address, never why. The handoff packet then
+        // carries no address for anyone to open, whatever produced that.
+        console.log(`  [FAIL] the run's stamped URL resolves\n           delivered, and status.json carries no url`);
+        failures++; toInvestigate.push(`${ref}: delivered with no report URL stamped — cause NOT measured here; read CLEAROTRON_REPORTS_URL on the instance AND what the stamp wrote, because a set variable can still stamp empty`);
       }
     }
 
@@ -4040,7 +4258,7 @@ function cmdTeardown(id) {
 // stamp can never disagree about whether a round is done.
 // adds `SCENARIO_FILE` — the ONE filename pattern, exported so the test that pins the widening
 // reads the same regex `list` and the sweep read, rather than a copy that agrees today.
-export { evalAssertion, OPS, queueDrainState, DOORS, runLedger, investigate, brief, secs, queueOutcomes,
+export { evalAssertion, fromTheRun, OPS, queueDrainState, DOORS, runLedger, investigate, brief, secs, queueOutcomes,
   TERMINAL_BY_SUFFIX, TERMINAL_BY_SUFFIX_RAN, SCENARIO_FILE };
 
 // ── main ─────────────────────────────────────────────────────────────────────────────────────────────
@@ -4064,6 +4282,10 @@ if (invokedDirectly) {
     if (a === "--round") {
       requestedRound = raw[++i] ?? null;
       if (!requestedRound || requestedRound.startsWith("--")) die("--round needs a round TOKEN: e2e.mjs report <ID> --round <token>\n  The token is on `run`'s output and in the ROUNDS block of any report.");
+    } else if (a === "--names") {
+      // The words the run wrote, on the page. Off by default because `report` is the cheap instrument and
+      // is pointed at real matters in sessions that record what they print.
+      setReportNames(true);
     } else if (a.startsWith("--round=")) {
       requestedRound = a.slice("--round=".length);
       if (!requestedRound) die("--round= needs a round TOKEN: e2e.mjs report <ID> --round=<token>");
@@ -4071,13 +4293,13 @@ if (invokedDirectly) {
   }
   const [cmd, arg, ...extra] = positional;
   if (extra.length) die(`unexpected argument "${extra[0]}"\n`
-    + "usage: e2e.mjs list | run <ID> [--stale] | status | report <ID> [--round <token>] | teardown <ID> [--waive-unread]");
+    + "usage: e2e.mjs list | run <ID> [--stale] | status | report <ID> [--round <token>] [--names] | teardown <ID> [--waive-unread]");
   switch (cmd) {
     case "list": cmdList(); break;
     case "run": if (!arg) die("usage: e2e.mjs run <ID> [--stale]"); await cmdRun(arg); break;
     case "status": cmdStatus(); break;
-    case "report": if (!arg) die("usage: e2e.mjs report <ID> [--round <token>]"); await cmdReport(arg, { round: requestedRound }); break;
+    case "report": if (!arg) die("usage: e2e.mjs report <ID> [--round <token>] [--names]"); await cmdReport(arg, { round: requestedRound }); break;
     case "teardown": if (!arg) die("usage: e2e.mjs teardown <ID> [--waive-unread]"); cmdTeardown(arg); break;
-    default: die("usage: e2e.mjs list | run <ID> [--stale] | status | report <ID> [--round <token>] | teardown <ID> [--waive-unread]");
+    default: die("usage: e2e.mjs list | run <ID> [--stale] | status | report <ID> [--round <token>] [--names] | teardown <ID> [--waive-unread]");
   }
 }

package/scripts/mint-reference-strip-backlog.mjs

@@ -36,17 +36,51 @@ if (p.laid) console.log(`mint-reference-strip-backlog: ${p.laid} tracked path(s)
 const tracked = p.files;
 const minted = censusOf(ROOT, tracked, publishedReader(ROOT, (f) => readFileSync(join(ROOT, f), "utf8")));
 
+// ── EVERY ROW IS EXPLAINED, OR THE TABLE IS A NUMBER NOBODY CAN ACT ON ────────────────────────────
+//
+// A count on its own tells a reader a file has residue in it. It does not tell them whether the line is
+// residue at all — and once the table reached zero, the next row to appear is either a regression to
+// repair or a known-good the scanner cannot tell from one. The first `.js` row is the second kind: an
+// adapter header names a list separator as `(, ; / etc)`, which matches the third signature and is also
+// correct English about punctuation. Without a sentence beside it that row is a number that will never
+// fall, and a floor with one of those in it stops being read.
+//
+// So notes are carried by the minter rather than typed into the artifact: a re-mint keeps the note for a
+// file that still has rows, drops it for a file that no longer does (a repair takes its explanation with
+// it), and says which rows are still unexplained. It never invents one — an unexplained row is reported,
+// and the arm that reads this table refuses it.
+const NOTES = {
+  "providers/clarivate/src/core.js":
+    "NOT residue — the header names a list separator as `(, ; / etc)`. It matches the third signature "
+    + "and is correct English about punctuation, so it is recorded rather than repaired.",
+};
+const notesFor = (files) => Object.fromEntries(
+  Object.keys(files).filter((f) => NOTES[f]).map((f) => [f, NOTES[f]]).sort(([a], [b]) => a < b ? -1 : 1));
+const unexplained = (files) => Object.keys(files).filter((f) => !NOTES[f]).sort();
+
 if (process.argv.includes("--check")) {
   const have = JSON.parse(readFileSync(TABLE, "utf8"));
   const a = JSON.stringify(have.files), b = JSON.stringify(minted.files);
+  if (JSON.stringify(have.notes ?? {}) !== JSON.stringify(notesFor(minted.files))) {
+    console.error("reference-strip backlog: the committed notes do not match this tree's rows.");
+    console.error("  re-mint with: node scripts/mint-reference-strip-backlog.mjs");
+    process.exit(1);
+  }
   if (a !== b || have.total !== minted.total) {
     console.error("reference-strip backlog is STALE against the tree.");
     console.error(`  committed total ${have.total}, tree has ${minted.total}`);
     console.error("  re-mint with: node scripts/mint-reference-strip-backlog.mjs");
     process.exit(1);
   }
-  console.log(`reference-strip backlog: current — ${minted.total} line(s) still to repair`);
+  const open = unexplained(minted.files);
+  const held = Object.keys(minted.files).length - open.length;
+  console.log(`reference-strip backlog: current — ${minted.total} matching line(s); `
+    + `${open.length} file(s) to repair, ${held} recorded as not residue`);
 } else {
-  writeFileSync(TABLE, JSON.stringify({ signatures: SIGNATURES.map((s) => s.name), ...minted }, null, 2) + "\n");
+  writeFileSync(TABLE, JSON.stringify({ signatures: SIGNATURES.map((s) => s.name), ...minted,
+    notes: notesFor(minted.files) }, null, 2) + "\n");
   console.log(`minted ${TABLE}: ${minted.total} line(s) across ${Object.keys(minted.files).length} file(s)`);
+  const open = unexplained(minted.files);
+  if (open.length) console.log(`mint-reference-strip-backlog: ${open.length} file(s) carry rows with no note — `
+    + `each is a line to repair, or a note to add here if it is not residue:\n  ${open.join("\n  ")}`);
 }