clearotron 0.4.0-beta.2 → 0.4.0-beta.3

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 `

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)]++;