clearotron 0.4.0-beta.2 → 0.4.0

package/driver/pipeline.mjs

@@ -10,7 +10,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, copyFil
 import { createHash } from "node:crypto";
 import { join, dirname, basename, resolve } from "node:path";   // resolve: the resume line must work from any cwd
 import { driverDir, driverRel, ensureDriverDir } from "../shared/driver-dir.mjs";
-import { REVIEWER_OPEN_QUESTIONS_FILE, reviewerOpenPointsForEmail } from "./reviewer-open-points.mjs";   // the run-record file the reviewer's open points go to   // — one definition of where `_driver/` is
+import { REVIEWER_OPEN_QUESTIONS_FILE } from "./reviewer-open-points.mjs";   // the run-record file the reviewer's open points go to, and the only thing that reads them now
 import { goodsOf } from "./queue-markers.mjs";   // — one reading of "does this job name goods", shared with the intake gate
 import { terminalClampDecision, orderClausesForLede, clientConditions, clauseForDefect } from "./terminal-clamp.mjs";   // — deliver and clamp, never withhold
 import { recordSpan } from "./attributed-span.mjs";   // — driver work the decomposition can attribute
@@ -47,6 +47,7 @@ import { readRegisterTaint, readActiveTaintAxes } from "./register-taint.mjs";
 import { parseNamedBand, mergeNamedBands, findCollapsedBands, quarantineUnknownStates, taintQuarantineCleanBlocks, bandRecords } from "./named-band.mjs";
 import { recordOriginsFor } from "./record-origins.mjs";
 import { REGISTER_PROVIDER } from "./driver.config.mjs";
+import { noteRegisterServed, registersServedFrom, providerUsageCaveat } from "./register-served.mjs";   // which registers actually served this run — noted eagerly from the dispatch's own resolver, and reconciled at publish against the ledger rows, which carry the vendor per call
 import { FACTS_FILE as DIGEST_FACTS_FILE, ACCOUNTING_STAMP as DIGEST_ACCOUNTING_STAMP, recordedFindingUris,
   digestAccountingGap, digestBatchBrief, batchesOf } from "./register-digest-record.mjs";   // conversion 11 — the render's facts sidecar and the accounting era stamp
 import { buildBandShape, dominantElementComposites, deriveRegisterPositions, floorTierByMark, floorMarkKey } from "./band-shape.mjs";   // PR-8 — the deterministic reading layer; P2-A — candidates + positions
@@ -94,7 +95,7 @@ import { deriveScopeFacts } from "./scope-facts.mjs";
 import { documentGrowth } from "./gate-metrics.mjs";
 import { editRepairTail, abbrev } from "./repair-contract.mjs";
 import { repairFollowup } from "./repair-composers.mjs";
-import { seedRunStatus, recordTransition, writeRunStatus, rollupStatus, atomicWrite, finalStepFields, terminalRunState, signoffPatch, readSignoff } from "./progress.mjs";
+import { seedRunStatus, recordTransition, writeRunStatus, readRunStatus, rollupStatus, atomicWrite, finalStepFields, terminalRunState, signoffPatch, readSignoff } from "./progress.mjs";
 import { batchMarkName } from "./mark-name.mjs";
 import { writeOutboxPacket } from "./outbox.mjs";
 import { publishReport, composeEmailHtml, deliverySubject } from "./publish/index.mjs";
@@ -208,8 +209,21 @@ const CL_SUPP_TAGS = ["closure"];
 // body) under the un-namespaced sessionKey we pass, so the row prefix-matches this run and the assembled
 // record set picks it up on re-assembly. Credential = the provider's own env var (already in the driver's
 // systemd EnvironmentFile); absence is a named mechanical cause. One provider is active per run.
+/**
+ * Note the adapter's own id against this run, and hand the adapter straight back.
+ *
+ * RECORDED WHERE IT IS RESOLVED, so the run's record says what SERVED it rather than what was configured
+ * at launch. Noting is idempotent per run and writes only when the set changes, so a run fetching a
+ * thousand records pays one write. A null run directory notes nothing: a call outside a run has no record
+ * to carry the field, and inventing one is the guess this field exists to replace.
+ */
+function noteAdapter(ctx, adapter) {
+  noteRegisterServed(ctx?.run?.runDir ?? ctx?.paths?.runDir ?? null, adapter?.id);
+  return adapter;
+}
+
 async function defaultRecordFetcher(uri, ctx) {
-  return activeProvider().recordFetch(uri, ctx);
+  return noteAdapter(ctx, activeProvider()).recordFetch(uri, ctx);
 }
 
 /**
@@ -2399,7 +2413,7 @@ async function verifyAndRecordHouseElement(ctx, opts = {}) {
     const caps = registerCapabilities();
     const { regions } = resolvePlanRegions(registerJurisdictions(ctx.job, ctx.profile), caps);
     const rec = resolveRecordExecutor({
-      lister: opts?.recordLister ?? null, adapter: activeProvider(),
+      lister: opts?.recordLister ?? null, adapter: noteAdapter(ctx, activeProvider()),
       agentId: ctx.agentId ?? null, sessionKey: `clearance-${ctx.run.slug}-${ctx.run.codename}`,
       recordLog: runRecordLogPath(P.runDir),
       fixtureDir: ctx.job?.registerFixtures?.records ?? null,
@@ -7671,9 +7685,27 @@ export function buildOnlyYouSection(actions, findings, { nowMs = Date.now(), wit
   // addressed TO the reader; monitoring and filing-routine are standing items. Same tags as before, so
   // a reader who knows the old list reads the new one unchanged, one level down.
   const ASK_KINDS = new Set(["client-fact", "commercial-decision"]);
+  // ── THE KINDS THAT DO NOT REACH A CLIENT SURFACE ────────────────────────────────────────────────
+  //
+  // Owner ruling, 2026-10-01, on the clearance emails production sent in the preceding day: the
+  // "[Open question]" rows are non-critical and confuse, and they come OUT of the client's report and
+  // email. They are not reworded and nothing replaces them.
+  //
+  // THE FILTER IS HERE AND NOT ON `advisories` ABOVE, which is the whole care in this change. That list
+  // also feeds `actionDates`, so dropping a kind from it would silently take a declared deadline out of
+  // the date set three predelivery checks key on — a client-facing removal quietly changing a date
+  // check. Filtering at the point of RENDERING removes the rows from the document and touches nothing
+  // else: the register in findings.json is unchanged, the kind stays valid, an advisory still never
+  // conditions reliance, and the verdict and its bound read from the register rather than from these
+  // lines.
+  //
+  // So the row is gone from what the client reads and the fact is still on the run, which is what the
+  // ruling asks for.
+  const NOT_FOR_CLIENT = new Set(["client-fact"]);
   const advisoryLine = (a) => `- **${ADVISORY_TAG[a.kind]}** ${askLine(a)}${a.deadline?.date ? ` (by ${a.deadline.date})` : ""}`;
-  const askLines = advisories.filter((a) => ASK_KINDS.has(a.kind)).map(advisoryLine);
-  const watchLines = advisories.filter((a) => !ASK_KINDS.has(a.kind)).map(advisoryLine);
+  const forClient = (a) => !NOT_FOR_CLIENT.has(a.kind);
+  const askLines = advisories.filter((a) => ASK_KINDS.has(a.kind)).filter(forClient).map(advisoryLine);
+  const watchLines = advisories.filter((a) => !ASK_KINDS.has(a.kind)).filter(forClient).map(advisoryLine);
   const groups = [
     ["Before you can rely on this result", conditionLines],
     ["We need an answer from you", askLines],
@@ -9173,7 +9205,7 @@ async function pipelineInner(job, opts = {}) {
     // which is the same bug in the other direction.
     const planExec = opts.planExecutor
       ?? (envGateOn("CLEAROTRON_PLAN_DISPATCH") && activeProvider().executePlan
-        ? (args, c) => activeProvider().executePlan(args, c) : null);
+        ? (args, c) => noteAdapter(c ?? ctx, activeProvider()).executePlan(args, c) : null);
     // Kill switch CLEAROTRON_SATPROBE_CODESIDE=0 (the inline `!== "0"` pattern): legacy mock harnesses
     // opt out — their scenarios pre-date the code-side member and script the AGENT path (and an armed
     // real executor lane would dial the provider from a test). Production default is ON.
@@ -10841,6 +10873,13 @@ async function pipelineInner(job, opts = {}) {
           let regArm = null;
           const regSwept = new Set();
           const regDeferReason = new Map();
+          // — WHAT THE FOLD REFUSED, AND WHICH KIND OF REFUSAL IT WAS. Read by the remedy accounting
+          // below, which otherwise requires every minted qid to land and so records a term as
+          // dispatch-failed when the fold refused its slice as a duplicate of a question the plan had
+          // already asked and answered. A fold-refused qid can never land, by construction — the
+          // re-attempt above deliberately filters it out — so only the accounting was still waiting
+          // for it. qid -> { kind, twin }.
+          const regFoldRefusals = new Map();
           // Partial mints must not read as full sweeps: when SOME of a directive's remedy proposals mint
           // and a sibling is refused by the shape lint, the directive can still verify-closed on the
           // minted subset — the refusal is disclosed per directive (receipt `partials` row on a close,
@@ -10974,9 +11013,25 @@ async function pipelineInner(job, opts = {}) {
               // belief about two screens agreeing, and the day they stop agreeing this is the only place
               // that would say so.
               if (refused.length) {
+                for (const r of refused) if (r?.qid) regFoldRefusals.set(r.qid, { kind: r.kind ?? null, twin: r.twin ?? null });
+                // THE REASON THE FOLD GAVE IS LOGGED, not just the qid it refused. The fold is the only
+                // place that knows WHY, and for a duplicate it knows WHICH plan row already holds the
+                // answer. Logging the qid alone threw that away: recovering it on one run meant
+                // re-deriving the twin from a shared identity hash by hand, and a receipt that cannot
+                // say why a slice is missing reads as an engine fault whatever the cause was.
                 runLog(run.runDir, { event: "frame-reopen-fold-refused", refused: refused.length,
-                  qids: refused.map((r) => r.qid).slice(0, 6) });
-                note(`frame-reopen: ${refused.length} minted entr${refused.length === 1 ? "y" : "ies"} REFUSED at the fold — the mint screen and the fold screen disagree, which is a wiring finding`);
+                  qids: refused.map((r) => r.qid).slice(0, 6),
+                  kinds: refused.reduce((a, r) => { const k = r.kind ?? "unstated"; a[k] = (a[k] ?? 0) + 1; return a; }, {}),
+                  rows: refused.slice(0, 6).map((r) => ({ qid: r.qid, kind: r.kind ?? null, twin: r.twin ?? null, issue: r.issue ?? null })) });
+                // ONE NOTE PER KIND, because they are three different findings and only one of them is a
+                // wiring fault. A duplicate-question refusal is the fold working: the question is already
+                // in the plan and its existing row carries the coverage. An identity collision or a
+                // malformed term IS the mint screen and the fold screen disagreeing, because the mint
+                // runs entryTermIssues and should have caught it.
+                const dupes = refused.filter((r) => r.kind === "duplicate-question");
+                const faults = refused.filter((r) => r.kind !== "duplicate-question");
+                if (dupes.length) note(`frame-reopen: ${dupes.length} minted entr${dupes.length === 1 ? "y" : "ies"} refused at the fold as already-asked — the plan row${dupes.length === 1 ? "" : "s"} ${dupes.map((r) => `"${r.twin ?? "(twin unstated)"}"`).join(", ")} carr${dupes.length === 1 ? "ies" : "y"} that coverage; the term is answered, not unsearched`);
+                if (faults.length) note(`frame-reopen: ${faults.length} minted entr${faults.length === 1 ? "y" : "ies"} REFUSED at the fold (${[...new Set(faults.map((r) => r.kind ?? "unstated"))].join(", ")}) — the mint screen and the fold screen disagree, which is a wiring finding`);
               }
               // Dispatch → derive band → VERIFY per directive (qid-landed + non-collapse + class-scope).
               // A byte-changed band with only a wrong-scope/empty/error block closes NOTHING.
@@ -11306,6 +11361,7 @@ async function pipelineInner(job, opts = {}) {
               terms: termRows,
               blocksByQid: regLastJoin?.blocksByQid ?? new Map(),
               executedQids: regLastJoin?.executedQids ?? new Set(),
+              foldRefusals: regFoldRefusals,
               outOfScope,
             });
           } catch (e) {
@@ -15136,8 +15192,37 @@ async function pipelineInner(job, opts = {}) {
     try {
       const provider = activeProvider().id;
       const usage = tallyRegisterCalls(DEFAULT_LEDGER_PATH, `clearance-${run.slug}-${run.codename}-`);
-      runLog(run.runDir, { event: "provider-usage", provider, ...usage });
-      writeRunStatus(ctx, { providerUsage: { [provider]: usage } });
+      // ── A WHOLE-RUN TALLY FILED UNDER ONE REGISTER SAYS SO WHEN THE RUN SERVED MORE THAN ONE ──────
+      //
+      // This label is resolved HERE, at publish, while the tally it labels spans the whole run. On a run
+      // whose register changed part-way that key is whichever register happened to be active at publish,
+      // and every call is filed under it — the confident-and-wrong shape the served field exists to end.
+      //
+      // The key's SHAPE is untouched because a ledger reads this map. What is added is the caveat, in the
+      // same record, so the two register fields in one status cannot silently disagree: the served list
+      // says two, and this says the tally covers both and could only be filed under one. Splitting the
+      // tally by register is a second question and is not answered here.
+      // ── THE LEDGER IS WHAT KNOWS, SO ASK IT BEFORE READING THE RECORD ───────────────────────────
+      //
+      // `registersServed` was written from ONE place: the adapter wrapper the record fetcher, the record
+      // lister and a gated plan executor pass through. A clearance that takes counts and never fetches a
+      // record went through none of them and recorded no register at all — the run could not say which
+      // vendor answered it, and `registersServedFrom` returned [] for a run that had called a register
+      // hundreds of times.
+      //
+      // Every one of those calls wrote a ledger row, and every row carries the vendor that produced it, so
+      // the tally just computed already holds the answer per call. Noting them here is not a second source
+      // of truth competing with the first: it is the same memoised setter, which unions and writes only on
+      // change, so the eager note during the run and this reconciliation at publish cannot disagree.
+      //
+      // WHY NOT `activeProvider()` HERE. That resolves the register active at publish, which is the
+      // confident-and-wrong answer this whole field exists to end — and on a run that changed register it
+      // would name one vendor while the rows name two. The rows are per call; the resolver is per moment.
+      for (const id of usage.providers) noteRegisterServed(run.runDir, id);
+      const served = registersServedFrom(readRunStatus(run.runDir));
+      const spans = providerUsageCaveat(served);
+      runLog(run.runDir, { event: "provider-usage", provider, ...(served.length > 1 ? { spans: served } : {}), ...usage });
+      writeRunStatus(ctx, { providerUsage: { [provider]: usage }, ...spans });
       providerTally = { [provider]: usage };
       // AD-4: the line prints the complete by_tool census, not a hand-picked subset — the R2 run printed
       // "search=0" while 286 execute_plan calls carried the whole register workload, and the subset read
@@ -15201,7 +15286,14 @@ async function pipelineInner(job, opts = {}) {
     // rule still forbids is the ENGINE'S OWN WORDS getting there: composeEmailHtml enumerates
     // predelivery-lint's code-owned projection (deliveryFlagLines), never the checks' raw `detail` —
     // this mail is addressed to job.forwarderEmail, which on a client-principal run is the client.
-    emailVerdictOpts.reviewerOpenPointsMd = reviewerOpenPointsForEmail(job, dirname(P.report));   writeFileSync(P.emailBody, composeEmailHtml(P.report, published.url, published.auditFile, emailNames, deliveryForRun(ctx), emailVerdictOpts));
+    // THE REVIEWER'S OPEN POINTS NO LONGER RIDE THE EMAIL (owner ruling, 2026-10-01). This line read them
+    // out of the run record and handed them to the cover, which is how the sentence naming the independent
+    // reviewer reached a client after the 2026-09-24 ruling had already taken it off the report page: the
+    // section stopped being spliced into the body and started being posted to the email instead. Measured
+    // on the last thirty days of production, the report carries neither the heading nor that sentence since
+    // that ruling, and the email carries both. The record is still written beside the report for the
+    // reviewing lawyer; nothing reads it onto a client surface.
+    writeFileSync(P.emailBody, composeEmailHtml(P.report, published.url, published.auditFile, emailNames, deliveryForRun(ctx), emailVerdictOpts));
     // ctx.verdict is set BEFORE the packet is composed, because the packet's copy reads it.
     ctx.verdict = verdict;
     // DELIVERY (Phase 2). The driver writes a self-contained delivery packet and leaves

package/driver/progress.mjs

@@ -153,7 +153,12 @@ export function atomicWrite(file, text) {
 
 function statusPath(runDir) { return join(runDir, "status.json"); }
 
-function readRunStatus(runDir) {
+/**
+ * The run's own status as last written. `{}` when it cannot be read, which callers must treat as an
+ * absence rather than as an empty run — exported so a lane can read the run's own `startedAt` without
+ * a second copy of where status.json lives.
+ */
+export function readRunStatus(runDir) {
   try { return JSON.parse(readFileSync(statusPath(runDir), "utf8")); }
   catch { return {}; }
 }

package/driver/provider-usage.mjs

@@ -115,6 +115,14 @@ function emptyTally() {
     // confused with "the ledger used a name this module doesn't know" again.
     by_tool: {},
     unclassified: 0,
+    // WHICH VENDORS ACTUALLY ANSWERED THIS RUN, read off the rows rather than resolved from the
+    // environment. Every ledger row carries a `provider` discriminator (providers/_shared/ledger.mjs), so
+    // the set of vendors a run used is a fact the ledger already holds — and it is the ONLY place that
+    // holds it per call. A label resolved at publish instead names whichever register happened to be
+    // active then, which is wrong for a run whose register changed part-way; this cannot be, because each
+    // row says who produced it. Empty is a real answer and means the ledger carried no row for this run,
+    // which the four `ledger.*` provenance facts below then explain.
+    providers: [],
     // …and the PROVENANCE of the zeros above. Same house rule, the last place in this module still broken
     // by it: a ledger that is missing, mis-pointed or unreadable returned a clean all-zero tally that was
     // indistinguishable from "the run made no provider calls", and the note line printed `total=0 ((none))`
@@ -163,6 +171,7 @@ export function tallyRegisterCalls(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix)
   out.ledger.readable = true;
 
   const firstFetchSession = new Map(); // record_fetch target → the session that first (network-)fetched it
+  const providersSeen = new Set();     // the vendors this run's rows name, in the order the ledger names them
 
   for (const line of text.split("\n")) {
     if (!line.trim()) continue;
@@ -179,6 +188,11 @@ export function tallyRegisterCalls(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix)
     const isCacheHit = row.cache_hit === true;
     if (isCacheHit) out.cache_hits++;
 
+    // Collected for EVERY matching row, whatever tool it rode — a count-only run rides `count`-shaped
+    // rows and no record fetch, and that is exactly the run whose register went unrecorded before.
+    const rowProvider = typeof row.provider === "string" ? row.provider.trim().toLowerCase() : "";
+    if (rowProvider) providersSeen.add(rowProvider);
+
     const toolName = typeof row.tool === "string" && row.tool ? row.tool : "(none)";
     out.by_tool[toolName] = (out.by_tool[toolName] ?? 0) + 1;
     if (KINDS.includes(row.tool)) out[row.tool]++;
@@ -221,6 +235,8 @@ export function tallyRegisterCalls(ledgerPath = DEFAULT_LEDGER_PATH, runPrefix)
       }
     }
   }
+  // Sorted so two runs with the same vendors compare equal whatever order the ledger happened to append in.
+  out.providers = [...providersSeen].sort();
   return out;
 }
 

package/driver/publish/index.mjs

@@ -1712,9 +1712,13 @@ export function composeEmailHtml(reportMdPath, url, auditFile, names = [], deliv
   const { fm, secs } = parseReport(reportMdPath);
   const auditUrl = auditUrlFor(url, auditFile);
 
-  // 1) internal review headline — short: the bottom line + any "Reviewer's open questions" already in # Summary.
-  // Heading-neutral match: accept the new "Reviewer's open questions" and the legacy "Open questions for the reviewer".
-  const oq = (secs['Summary'] || '').match(/\*\*(?:Reviewer's open questions|Open questions for the reviewer)[\s\S]*?(?=\n\n[^*\d])/i);
+  // 1) internal review headline — short: the bottom line, and nothing of the reviewer's own notes.
+  //
+  // THE SCRAPE THAT STOOD HERE IS GONE (owner ruling, 2026-10-01). It lifted a "Reviewer's open questions"
+  // block out of the report's own # Summary and reprinted it on the cover. Two ways that reached a client:
+  // a report that still carried an authored section of that name, and any archived report re-rendered
+  // later. Removing the producer is not enough while something downstream goes looking for the text, so
+  // this goes with it.
   // The report link rides HIGH — right under the bottom line in the headline, not buried below the table.
   const reportLink = hrefAttr(url)
     ? `<p style="margin:0 0 10px"><a href="${hrefAttr(url)}" style="color:#1a4fd6;font-weight:bold;font-size:12pt;text-decoration:none">▶ Open the full report</a>`
@@ -1826,8 +1830,10 @@ export function composeEmailHtml(reportMdPath, url, auditFile, names = [], deliv
     // second rung on any shipped build. Nothing renders a failover note into a report.
     // B5b checkpoint 4 — a customer named after the analysis was written ships as a delivery note, never silently.
     + (fm.late_bind_note ? `<p style="margin:0 0 8px;color:#7a2b12"><b>Applicant named mid-run:</b> ${cell(fm.late_bind_note)}</p>` : '')
-    + (oq ? `<div style="margin:0 0 8px">${mdBlock(oq[0])}</div>` : '')   // …and the reviewer's open points from the run record (opts.reviewerOpenPointsMd), never from the report
-    + (opts.reviewerOpenPointsMd ? `<div style="margin:0 0 8px">${mdBlock(String(opts.reviewerOpenPointsMd).replace(/^#+\s*(.+)$/m, '**$1**'))}</div>` : '')
+    // The reviewer's open points stood here, from the run record. They do not ride the cover any more
+    // (owner ruling, 2026-10-01): the sentence naming the independent reviewer reads as a human declining
+    // to sign, and the points themselves are the engine's own vocabulary. Both stay on the run, beside the
+    // report, for the reviewing lawyer. Nothing is reworded and nothing replaces them.
     // wp50: the two-bucket # Actions list no longer rides the email — it renders on the report itself
     // (the single master document); the cover keeps only the headline, link, and surviving flags.
     + `</div>`;

package/driver/publish/knockout.mjs

@@ -475,16 +475,26 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
   // Depth 2's sidecar, read from the RUN DIR rather than taken on trust from the caller: the
   // publisher renders what the driver measured and wrote, and a republish of an archived run picks up
   // the same file. An absent sidecar publishes exactly today's knockout.
+  // AN UNREADABLE SIDECAR IS NOT AN ABSENT ONE, and until now both arrived here as null. The
+  // instructed-scope load eight lines down has told the two apart since it was written; these two had
+  // the same catch and neither flag. A run whose counts file is present but corrupt therefore published
+  // the sentence for a run that never took any counts.
+  //
+  // `registerCountsUnreadable` HAS NO CONSUMER YET, deliberately. The page's line for an absent counts
+  // file says none could be taken, and there is no shipped sentence for a file that could not be read —
+  // writing one is a decision about what a client is told, not a defect fix. The distinction is recorded
+  // here so the decision has something to key on when it is made.
+  let registerCountsUnreadable = false;
   if (!registerCounts) {
     try { registerCounts = JSON.parse(readFileSync(driverDir(runDir, 'register-counts.json'), 'utf8')); }
-    catch { registerCounts = null; }
+    catch { registerCounts = null; registerCountsUnreadable = existsSync(driverDir(runDir, 'register-counts.json')); }
   }
   // part 5 — the filings sidecar, read the same way and for the same reason: the publisher renders
   // what the driver measured and wrote, and a republish of an archived run picks up the same file. An
   // absent sidecar publishes exactly the counts-only knockout, with no filings section anywhere.
-  let registerRecords = null;
+  let registerRecords = null, registerRecordsUnreadable = false;
   try { registerRecords = JSON.parse(readFileSync(driverDir(runDir, 'register-records.json'), 'utf8')); }
-  catch { registerRecords = null; }
+  catch { registerRecords = null; registerRecordsUnreadable = existsSync(driverDir(runDir, 'register-records.json')); }
   // The owner lookups this run made, read the same tolerant way as the records above:
   // an archived run that predates the lane has no file, and its cards then render exactly as they were
   // delivered. The source line the report prints comes from HERE, not from anything the seat typed.
@@ -699,6 +709,9 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
     const markBand = single ? overall : worstBand(framework, [m]);
     writeRO(file, renderKnockoutHtml(one, framework, {
       runId, overall: markBand, issued, auditFile, probeRan, registerCounts, registerRecords, ownerChecks, instructedScope, identity, matter: runId,
+      // Carried as its own value rather than folded into `registerRecords`, because three sites PRINT
+      // `registerRecords.unavailable` and a marker invented here would become client-facing wording.
+      registerRecordsUnreadable,
       // — an invented mark says so on its own report. Resolved ONCE above the loop:
       // the answer is a property of the run, and asking per mark would let a multi-mark demo mark some
       // documents and not others if the roster moved mid-publish.

package/driver/publish/render-knockout.mjs

@@ -1377,16 +1377,16 @@ function firstRef(marks, framework) {
   return '';
 }
 
-// — THE REGISTER SENTENCE IS THE RENDERER'S, and it is the whole reason this function exists.
+// — THE REGISTER SENTENCE IS THE RENDERER'S, and it is the whole reason the two clauses below exist.
 //
 // A live run printed "the register overlay has not been run" in model prose directly under a table of
 // register counts the same run had taken. The model was not lying: it cannot see the count lane, it is
 // deliberately never shown the figures (register-count.mjs rule 1), and it filled the gap with the only
 // thing it had. The fix is not a better prompt — it is that nobody who cannot see the machinery gets to
-// describe it. The validator forbids the model from saying anything about register coverage; this
-// function says it, from the artifacts.
+// describe it. The validator forbids the model from saying anything about register coverage; these
+// clauses say it, from the artifacts.
 //
-// It reads the SIDECARS, never the prose: the counts entry for this mark, and whether the product bought
+// They read the SIDECARS, never the prose: the counts entry for this mark, and whether the product bought
 // the probe at all. Four states, four sentences, and none of them is a judgment.
 //
 // — AND IT NOW STATES THE POSITION, NOT ONLY THE COVERAGE. Coverage alone ("hit-counts were taken
@@ -1394,10 +1394,12 @@ function firstRef(marks, framework) {
 // STANDS on the register for this name. That sentence is appended by registerPositionClause below and
 // it is present in every state, including the state where the answer is "nothing does" — an absence is
 // a finding and must be said out loud, never left as a silence over a table of numbers.
-function registerLine(mark, registerCounts, probeRan, registerRecords = null, cards = []) {
-  return [coverageClause(mark, registerCounts, probeRan),
-    registerPositionClause(mark, registerCounts, registerRecords, cards)].filter(Boolean).join(' ');
-}
+//
+// THE FUNCTION THAT COMPOSED THE PAIR IS GONE, and removing it was the point rather than tidiness. It
+// was called from nowhere in the tree, and its call to `registerPositionClause` was the one that did NOT
+// pass the unreadable-sidecar flag — so anybody reviving it would have revived exactly the defect that
+// flag closes, silently, with nothing at the call site to say so. The live composition is inline in
+// `renderKnockoutHtml`, which passes it. Found independently twice before being removed once.
 
 /**
  * Where the name STANDS on the register that was searched. Six states, and they are six because
@@ -1421,12 +1423,22 @@ function registerLine(mark, registerCounts, probeRan, registerRecords = null, ca
 // unconditionally, which was true while the clause was drawn under the cards. It is drawn under the
 // COUNTS now — the numbers it qualifies — and the cards are below it, so a fixed word would send a
 // reader the wrong way up the page. The caller knows the order; this function does not guess it.
-function registerPositionClause(mark, registerCounts, registerRecords, cards = [], where = 'above') {
+// The one sentence for a listing whose answer this run cannot state, whether the lister refused or the
+// sidecar itself would not parse. Held once so the two callers below cannot drift: they are the same fact
+// to a reader, and two copies of a sentence are two sentences waiting to differ.
+const FILINGS_NOT_LISTED = 'The filings behind the counts could not be listed on this run, so nothing here says whether one stands.';
+
+function registerPositionClause(mark, registerCounts, registerRecords, cards = [], where = 'above', recordsUnreadable = false) {
   if (!registerRecords) {
+    // AN UNREADABLE SIDECAR IS NOT AN ABSENT ONE. Absent means the listing was never taken, and the page
+    // says so. Unreadable means it WAS taken and this run cannot say what it found. The second sentence
+    // was already written, for the lister's own refusal, and was simply unreachable from a republish:
+    // a file that would not parse arrived as null, and null reads here as absent.
+    if (recordsUnreadable) return FILINGS_NOT_LISTED;
     return registerCounts ? 'The filings behind those counts were not listed on this run.' : '';
   }
   if (registerRecords.unavailable) {
-    return 'The filings behind the counts could not be listed on this run, so nothing here says whether one stands.';
+    return FILINGS_NOT_LISTED;
   }
   const entry = recordsForMark(registerRecords, mark?.name);
   const provider = registerRecords.providerLabel ?? registerRecords.provider ?? 'the register';
@@ -1775,6 +1787,11 @@ const CAVEAT_LEAD = 'This screen also carries the following limits:';
 export function renderKnockoutHtml(findings, framework, {
   runId, overall, issued = null, auditFile = null, probeRan = false, registerCounts = null,
   registerRecords = null,
+  // — was the filings sidecar PRESENT but unreadable? Defaults to false, so every existing caller — the
+  // unit fixtures and both render-check scripts, none of which pass one — renders exactly as it did. It
+  // is its own value rather than a marker on `registerRecords`, because three sites PRINT
+  // `registerRecords.unavailable` and anything invented for it would become client-facing wording.
+  registerRecordsUnreadable = false,
   // The driver's own record of the owner lookups it ran. Defaults to [] so an
   // archived run that predates the lane renders exactly as it was delivered.
   ownerChecks = [],
@@ -1853,7 +1870,7 @@ export function renderKnockoutHtml(findings, framework, {
   // promoted, and the clause would name refs no card carries.
   const cardsByMark = new Map(marks.map((m) => [m?.name, registerCardViews(m, framework, registerRecords).cards]));
   const positions = marks.map((m) => {
-    const clause = registerPositionClause(m, registerCounts, registerRecords, cardsByMark.get(m?.name) ?? [], 'below');
+    const clause = registerPositionClause(m, registerCounts, registerRecords, cardsByMark.get(m?.name) ?? [], 'below', registerRecordsUnreadable);
     if (!clause) return '';
     return marks.length > 1 && m?.name ? `${m.name}: ${clause}` : clause;
   }).filter(Boolean).join(' ');
@@ -2220,6 +2237,16 @@ export function knockoutReportData(findings, framework, { runId, codename, overa
             line: recordsLine(listed),
             fetched: listed.fetched ?? (listed.records ?? []).length,
             capped: Boolean(listed.capped),
+            // THE CAP THE RUN RECORDED, beside the flag that says it bit. `capped: true` on its own cannot
+            // tell a listing truncated at fifty from one a cap of zero stopped before it began: the first
+            // is a register outcome and the second is a configuration, and a consumer reading the flag
+            // alone reports them the same way. The run has always written `cap` per mark; nothing read it.
+            //
+            // NULL IS NOT ZERO and the two are kept apart all the way out, the way the portal's allowance
+            // contract keeps them. Null is a sidecar that recorded no cap at all, which is every run
+            // archived before the field existed; zero is a cap that was set to zero. Folding them together
+            // would put an archived run and a misconfigured one on the same line.
+            cap: Number.isFinite(listed.cap) ? listed.cap : null,
             records: (listed.records ?? []).map((r) => ({
               mark: r.mark, owner: r.owner, status: r.status, classes: r.classes ?? [],
               territory: r.territory, matchedForm: r.matchedForm, matchedBasis: r.matchedBasis,

package/driver/record-carry.mjs

@@ -567,6 +567,21 @@ export function traceRecordCarry({ bandRecords = [], placements = [], registerFi
   // and the one that run shipped without stating, so it is counted separately and never folded
   // into an ordinary drop total.
   const upstreamAbsent = rows.filter((r) => /:stage-incomplete$/.test(String(r.reason ?? "")));
+  // Records the step PASSED OVER: it ran, it reached them, and it recorded no ground of its own, so the
+  // driver's own literal stands as the reason. A reason, so not `unreasoned` — the same distinction
+  // `upstreamAbsent` above is drawn on, and counted separately for the same reason.
+  //
+  // WHY IT HAS TO BE IN `totals` AND NOT ONLY IN `by_reason_source`. This module's own header says a
+  // reader who opens the file and sees `unreasoned: 0` must be able to tell that from "nothing was
+  // dropped anywhere in this run". On R18 of 2026-09-27 the totals block read `unreasoned: 0` beside
+  // 5,760 records the step passed over — the count was in `by_reason_source` and not in the block a
+  // reader opens first, so the loudest fact about that run was one level down from the answer.
+  //
+  // `unreasoned` IS NOT REDEFINED, deliberately. A shipped Machine QC check passes only on
+  // `unreasoned === 0` and that row reaches a client's workbook; folding these in would turn a green
+  // into a red on every run with a silent exit, which is a decision about what a client is told rather
+  // than a correction to a record.
+  const stepSilent = rows.filter((r) => r.reason_source === "step-silent");
   const incompleteStages = Object.values(outcomes ?? {}).filter((o) => o && o.completed !== true).map((o) => o.stage);
   const slices = untraceableSlices({ crowds, planExecution });
   const deliveredFindings = Array.isArray(findings) ? findings.length : 0;
@@ -601,6 +616,7 @@ export function traceRecordCarry({ bandRecords = [], placements = [], registerFi
       finding: byReach.finding ?? 0,
       dropped: rows.length - (byReach.finding ?? 0),
       unreasoned: unreasoned.length,
+      step_silent: stepSilent.length,
       upstream_absent: upstreamAbsent.length,
       untraceable_slices: slices.length,
       // — THE SUM STATES ITS OWN INCOMPLETENESS. `n + s.untraced` coerced a null to 0, so a
@@ -886,7 +902,7 @@ export function statedDivergenceFindings({ reconciliation = null, carryRows = nu
   //   statedDivergenceFindings   checked=5 matched=5 diverged=0   ← should have named two marks
   //
   // The reconciliation names five finding-ended positions and they are five OTHER marks — VELTRIN
-  // bioenergetische Kosmetik, KORPHIC HSE, KORPHI, DELPHIN & EMERENCE, KORPHI DIAGNOSTICS. The two that
+  // bioenergetische Kosmetik, KORPHIC HSE, KORPHI, KORPHIN & ACME, KORPHI DIAGNOSTICS. The two that
   // were lost sit in the CARRY rows and the reconciliation never mentions them:
   //
   //   HALVER KORPHI  reach=placed stopped_at=digest reason_source=step-stated reason=digest:reasoned-negative

package/driver/reference-strip-signatures.mjs

@@ -66,8 +66,18 @@ export const RULE_DEFINITIONS = [
 ];
 
 /** Files worth scanning: prose-bearing, tracked, not generated, and not this rule's own definition. */
+// `.js` IS IN THE LIST BECAUSE IT WAS THE HOLE. The extensions here were the ones the driver is written
+// in, and the register adapters are not: 26 tracked `.js` files, every one carrying the same kind of
+// header prose as the rest of the tree, scanned by nothing. The strip ran over them like everywhere
+// else, and one of its casualties sat in an adapter header for as long as this check has existed,
+// under a table reading zero. A floor that cannot see a whole file extension reports a repaired tree.
+//
+// It costs one row, and the row is NOT residue: an adapter header names a list separator as
+// `(, ; / etc)`, which is a parenthesis opening on a comma and is also correct English about
+// punctuation. `notes` in the backlog table records why that row is there, so the next reader meets an
+// explanation rather than a number that will not fall.
 export const isScannable = (f) =>
-  /\.(mjs|md|yml|ts)$/.test(f) && !f.startsWith("portal-ui/dist/") && !RULE_DEFINITIONS.includes(f);
+  /\.(mjs|js|md|yml|ts)$/.test(f) && !f.startsWith("portal-ui/dist/") && !RULE_DEFINITIONS.includes(f);
 
 /**
  * Count both signatures per file across `files`.

package/driver/register-plan.mjs

@@ -2079,7 +2079,7 @@ export function foldSupplementalEntries(plan, entries) {
     const eTerm = String(e.term ?? e.terms?.[0] ?? "");
     if (inBatch.has(e.qid) && inBatch.get(e.qid) === eTerm) continue;   // the same row twice — one refusal
     if (inBatch.has(e.qid)) {
-      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""),
+      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""), kind: "identity-collision",
         issue: planRowRefusal({ qid: e.qid, issue:
           `a different term ("${inBatch.get(e.qid)}") already minted this identity in the same batch, so `
           + `one of the two would be dropped with nothing recorded. Two DIFFERENT terms sharing one qid is `
@@ -2098,7 +2098,7 @@ export function foldSupplementalEntries(plan, entries) {
     e = kept;
     const issues = entryTermIssues(e);
     if (issues.length) {
-      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""),
+      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""), kind: "malformed-term",
         issue: planRowRefusal({ qid: e.qid, issue: issues[0].issue }) });
       continue;
     }
@@ -2107,7 +2107,11 @@ export function foldSupplementalEntries(plan, entries) {
     const key = entryQuestionKey(e, plan);
     const twin = key ? asked.get(key) : undefined;
     if (twin) {
-      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""),
+      // THE TWIN IS A FIELD, NOT ONLY A PHRASE IN THE PROSE. This row is the only place that knows the
+      // question is already asked, and by which plan row. A reader could parse it back out of the
+      // sentence; a caller cannot be asked to. The remedy accounting reads it to tell a duplicate
+      // refusal (answered elsewhere) from the other two kinds (genuinely unasked).
+      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""), kind: "duplicate-question", twin,
         issue: planRowRefusal({ qid: e.qid, issue:
           `it asks the same question as plan row "${twin}" once regions are resolved (an entry with no `
           + `regions of its own inherits the plan's, so an empty list is the WIDEST scope, not a narrower `