clearotron 0.4.0-beta.2 → 0.4.0

package/driver/register-served.mjs

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// register-served.mjs — which register actually served this run, as a field in the run's own record.
+//
+// THE KNOCKOUT LANE ALREADY RECORDS THIS and the clearance lane recorded nothing equivalent, so the same
+// question about a clearance run had no answer to look up. What stood in for the field was searching for a
+// register's NAME as a substring inside three artifacts that happen to mention it — and measured on the
+// archived runs that instrument could not attribute more than half of two scenarios' runs to any register
+// at all. Those are runs whose register is unknown to the record, not runs that used none, and nothing in
+// the record said which.
+//
+// WHAT SERVED, NOT WHAT WAS CONFIGURED. The value is taken from the same resolver the dispatch itself goes
+// through, at the moment a register is used, rather than from the frozen settings the run started on. The
+// per-run settings sidecar is deliberately NOT the home for it: that file exists to freeze what the run
+// was sold, so a resume runs on what it started on, and a register recorded there would be the launch
+// value presented with a frozen file's authority. A run whose provider changed under it would read wrong
+// and confident, which is the failure this field exists to end rather than to relocate.
+//
+// A LIST, BECAUSE ONE IS A LIST OF ONE. A run that used two registers says two rather than naming the
+// first, and a reader never has to know whether the field is a value or a set.
+//
+// BEST-EFFORT AND SILENT, like every other telemetry write in this lane: a field that cannot be recorded
+// must never fail a register call. An absence is then the honest answer — this run's register is unknown
+// to the record — which is exactly the state the archive is full of and the reason nothing here guesses.
+import { readRunStatus, writeRunStatus } from "./progress.mjs";
+
+/** The status key. One name, so the writer and every reader cannot drift. */
+export const REGISTERS_SERVED = "registersServed";
+
+// Per-process memo so the common case — every call of a run resolving the same register — costs one read
+// and one write for the whole run rather than one of each per call. Keyed by run directory because a
+// process can carry more than one (a resume, a batch).
+const seen = new Map();
+
+/**
+ * Note that `id` served this run, and return the run's full list. Writes only when the set changes.
+ * `id` is the resolver's own answer, never a raw environment read. PURE apart from the run's record.
+ */
+export function noteRegisterServed(runDir, id) {
+  const register = String(id ?? "").trim().toLowerCase();
+  if (!runDir || !register) return null;
+  let set = seen.get(runDir);
+  if (!set) {
+    // A RESUME READS WHAT THE EARLIER PROCESS RECORDED, so a run that changed register across a resume
+    // says both rather than only the half this process saw.
+    set = new Set(registersServedFrom(readRunStatus(runDir)));
+    seen.set(runDir, set);
+  }
+  if (set.has(register)) return [...set];
+  set.add(register);
+  const registers = [...set];
+  try { writeRunStatus(null, { [REGISTERS_SERVED]: registers }, runDir); }
+  catch { /* telemetry must never break a register call */ }
+  return registers;
+}
+
+/** The registers a run's status records, or [] when it records none. PURE. */
+export function registersServedFrom(status) {
+  const v = status?.[REGISTERS_SERVED];
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim()) : [];
+}
+
+/**
+ * One line for a reader, three-valued rather than two: the register, the registers, or the absence NAMED
+ * as an absence. "not recorded" is not "none served" and a reader must never have to guess which.
+ * PURE.
+ */
+export function registerServedLine(status) {
+  const r = registersServedFrom(status);
+  if (!r.length) return "NOT RECORDED — this run's record carries no register, which is not the same fact as using none";
+  return r.length === 1 ? r[0] : `${r.length} registers served this run: ${r.join(", ")}`;
+}
+
+/**
+ * The caveat a whole-run provider tally needs when the run served more than one register: `{}` when the
+ * tally's single key cannot be wrong, and the spanning list when it can. PURE.
+ *
+ * A TALLY'S KEY IS RESOLVED AT PUBLISH and the tally spans the whole run, so on a run whose register
+ * changed part-way every call is filed under whichever was active at the end. That is the shape the
+ * served field exists to end, and until the field existed nothing could contradict it. This does not
+ * split the tally — attributing a whole-run count to one of two registers is a different question — it
+ * stops the two register fields in one record disagreeing in silence.
+ */
+export function providerUsageCaveat(served) {
+  const r = Array.isArray(served) ? served.filter((x) => typeof x === "string" && x.trim()) : [];
+  return r.length > 1 ? { providerUsageSpans: r } : {};
+}
+
+/** Test seam: forget the per-process memo, so an arm can drive a second run in the same process. */
+export function forgetRegistersServed() { seen.clear(); }

package/driver/remedy-accounting.mjs

@@ -136,15 +136,40 @@ function material(block) {
  *      `unaccounted` when there is no reason either — a legacy receipt states neither, and inventing
  *      "not dispatched" from silence would be the same guess in a new place);
  *   2. ANY slice that did not land clean ⇒ `dispatch-failed`, naming the first such qid. Every slice
- *      must land, exactly as verifyRegisterDirectiveClose requires of a directive — one convention;
+ *      must land, exactly as verifyRegisterDirectiveClose requires of a directive — one convention. A
+ *      slice the FOLD refused as already-asked is read through the twin it duplicates first, because that
+ *      slice cannot land and the twin is where its question was answered;
  *   3. all landed, ANY slice material ⇒ `found`;
  *   4. all landed, EVERY slice a counted zero ⇒ `searched-empty`;
  *   5. otherwise ⇒ `unaccounted`, with the shape that defeated the join stated.
  * PURE.
  */
-export function classifyRemedyTerm(row, { blocksByQid = new Map(), executedQids = new Set() } = {}) {
+export function classifyRemedyTerm(row, { blocksByQid = new Map(), executedQids = new Set(), foldRefusals = new Map() } = {}) {
   const qids = (Array.isArray(row?.qids) ? row.qids : []).filter(Boolean);
-  const slices = qids.map((q) => sliceRow(q, blocksByQid.get(q), executedQids.has(q)));
+  // — A SLICE THE FOLD REFUSED AS ALREADY-ASKED IS ANSWERED BY THE ROW IT DUPLICATES.
+  //
+  // The fold refuses a minted qid when the plan already holds a row asking the same question, and hands
+  // back the twin's qid. Such a slice can NEVER land: it was never frozen into the plan, and the reopen's
+  // own re-attempt filters it out on purpose. Requiring it to land anyway made rule 2 below fire on it and
+  // return before rules 3-5 could look at the rest, so a term whose question HAD been asked and answered
+  // was recorded `dispatch-failed` — which reads as an engine fault a re-run would fix, where the truth is
+  // that the coverage is already on the plan's own row. Measured on a delivered breadth run: one term, its
+  // twin enumerated with 71 records, the dominant-element gap left open and clamped on that basis.
+  //
+  // ONLY THE DUPLICATE KIND RESOLVES. An identity collision or a malformed term is a genuine fault and
+  // stays `dispatch-failed`: nothing else asked those questions, so nothing else answers them.
+  const resolve = (q) => {
+    const r = foldRefusals.get?.(q);
+    return r && r.kind === "duplicate-question" && r.twin ? String(r.twin) : q;
+  };
+  const landsAs = new Map(qids.map((q) => [q, resolve(q)]));
+  const blockFor = (q) => blocksByQid.get(landsAs.get(q) ?? q);
+  const ranAs = (q) => executedQids.has(landsAs.get(q) ?? q);
+  const slices = qids.map((q) => {
+    const via = landsAs.get(q);
+    const slice = sliceRow(q, blockFor(q), ranAs(q));
+    return via && via !== q ? { ...slice, answered_by: via, refused_at_fold: "duplicate-question" } : slice;
+  });
   if (!qids.length) {
     const reason = String(row?.dispatch_reason ?? "").trim();
     return reason
@@ -152,16 +177,16 @@ export function classifyRemedyTerm(row, { blocksByQid = new Map(), executedQids
       : { class: "unaccounted", basis: "no-mapping", reason: "the receipt records no slice and no reason for this term — the join cannot say whether it was searched", slices };
   }
   for (const q of qids) {
-    const b = blocksByQid.get(q);
-    if (sliceLanded(b, executedQids.has(q))) continue;
-    const why = !executedQids.has(q) ? "slice-not-landed"
+    const b = blockFor(q);
+    if (sliceLanded(b, ranAs(q))) continue;
+    const why = !ranAs(q) ? "slice-not-landed"
       : !b ? "no-band-block"
         : b.deferred === true ? "capability-gap-deferral"
           : b.error === true ? "provider-error"
             : "collapsed-slice";
     return { class: "dispatch-failed", basis: why, reason: `${why}:${q}${b?.reason ? ` — ${clip(b.reason, 200)}` : ""}`, slices };
   }
-  const blocks = qids.map((q) => blocksByQid.get(q));
+  const blocks = qids.map((q) => blockFor(q));
   if (blocks.some(material)) return { class: "found", basis: "band-block", reason: null, slices };
   if (blocks.every(countedZero)) return { class: "searched-empty", basis: "counted-zero", reason: null, slices };
   const odd = blocks.find((b) => !countedZero(b));
@@ -186,14 +211,18 @@ const emptyTotals = () => {
  * `out_of_scope` carries the directives that have no term unit (source-layer channels), with the reason
  * — counted and named, never silently absent.
  *
+ * `foldRefusals` maps a minted qid the FOLD refused to `{ kind, twin }`, as `foldSupplementalEntries`
+ * recorded it. It is how a term whose slice was refused as already-asked reads through the plan row that
+ * answered it instead of counting as a slice that failed to land.
+ *
  * Deterministic; no timestamps (the caller stamps `ts`), no IO, no judgment. PURE.
  */
-export function accountRemedyTerms({ terms = [], blocksByQid = new Map(), executedQids = new Set(), outOfScope = [] } = {}) {
+export function accountRemedyTerms({ terms = [], blocksByQid = new Map(), executedQids = new Set(), foldRefusals = new Map(), outOfScope = [] } = {}) {
   const totals = emptyTotals();
   const byDirective = {};
   const rows = [];
   for (const t of Array.isArray(terms) ? terms : []) {
-    const c = classifyRemedyTerm(t, { blocksByQid, executedQids });
+    const c = classifyRemedyTerm(t, { blocksByQid, executedQids, foldRefusals });
     const directive = String(t?.directive ?? "");
     totals.terms++;
     totals[key(c.class)]++;

package/driver/reviewer-open-points.mjs

@@ -3,31 +3,28 @@
 //
 // reviewer-open-points.mjs — where the reviewer's open points are kept, and how the audit workbook reads them.
 //
-// Owner ruling, 2026-09-24: reviewer notes never reach the client page. The pipeline still builds the
-// section from the review and the corrective observation (buildReviewerOpenPointsSection) and writes it to
-// the run record under `_driver/`, for the reviewing lawyer. Nothing a client can open carries it: not the
-// report, and not the audit workbook, whose link rides the cover note a client principal receives.
+// Owner ruling, 2026-09-24: reviewer notes never reach the client page. Owner ruling, 2026-10-01: they do
+// not reach the email either, on any run. The pipeline still builds the section from the review and the
+// corrective observation (buildReviewerOpenPointsSection) and writes it to the run record under `_driver/`,
+// beside the report, for the reviewing lawyer who opens the run. Nothing sends it anywhere.
 //
-// One module owns the file's name and its reading, so the pipeline that writes it and the email that reads
-// it cannot disagree about where it is, and the reader does not import the pipeline to learn a file name.
-
-import { readFileSync, existsSync } from "node:fs";
-import { driverDir } from "../shared/driver-dir.mjs";
+// WHAT THE SECOND RULING REMOVED, and why it is not a narrowing of the first. The first took the section off
+// the report page and left it on the email, gated on whether the run's forwarder was the client. The email
+// then carried the sentence naming the independent reviewer — which reads as a human declining to sign a
+// report — and carried the points in the engine's own vocabulary. Measured over the thirty days to
+// 2026-10-01: the report page carries neither since the first ruling, and the email carried both. So the
+// gate was holding a door open that is now shut: nothing reads this file onto a surface that is sent.
+//
+// One module owns the file's name, so the pipeline that writes it and the workbook reader that skips it
+// cannot disagree about where it is, and a reader does not import the pipeline to learn a file name.
 
 /** The run-record file the reviewer's open points are written to, under the run's `_driver/`. */
 export const REVIEWER_OPEN_QUESTIONS_FILE = "reviewer-open-questions.md";
 
-/**
- * The recorded open points for the email the run sends, or null where that email could reach a client.
- *
- * The run's email goes to the job's forwarder, and on a client-started run (`clientPrincipal`) that address
- * is the client itself. There the open points stay in the run record alone. Everywhere else the recipient
- * is the reviewing lawyer, who reads them in the email's review headline, in the record's own words.
- * Null too when the run recorded none: the reviewer signed and nothing is open.
- */
-export function reviewerOpenPointsForEmail(job, runDir) {
-  if (job?.clientPrincipal === true || !runDir) return null;
-  const file = driverDir(runDir, REVIEWER_OPEN_QUESTIONS_FILE);
-  if (!existsSync(file)) return null;
-  try { return readFileSync(file, "utf8").trim() || null; } catch { return null; }
-}
+// THE EMAIL READER IS GONE (owner ruling, 2026-10-01). It returned this file's text for a run whose
+// forwarder was not the client, and the pipeline handed that to the email cover. Both halves are removed:
+// the reader here, and the hand-off there. A gate on the recipient is not what the ruling asked for — the
+// points leave every surface that is sent, so there is no recipient to test.
+//
+// NOT LEFT IN PLACE UNUSED. An exported reader with no caller is the shape somebody wires back up, and the
+// thing that made this reachable in the first place was a function that existed and looked safe to call.