clearotron 0.4.1 → 0.5.0-beta.1

package/driver/corrective-arm.mjs

@@ -9,17 +9,20 @@
 //
 // ── WHY THIS IS NOT SIMPLY "ALLOW THE WORD" ─────────────────────────────────────────────────────────
 //
-// The production corrective pass is a WARM followup: it resumes the synthesis session and sends only
-// `correctionsExtra`'s blocks. An experiment arm always builds a fresh key and dispatches into a sandbox,
-// so it cannot resume anything — and resuming the REAL session from a sandbox was rejected outright,
-// because "canonical run untouched" is the arm's whole contract and an arm that breaks its contract to
-// gain fidelity is measuring with a broken instrument.
+// The production corrective pass is a FOLLOWUP dispatch of the synthesis stage, on the run's own key with
+// the winning attempt's model and thinking, and its message is `correctionsExtra`'s blocks. It does not
+// resume the synthesis session: no engine resumes by session key (stages-followup.test.mjs pins it), so
+// the followup's first attempt is a fresh turn handed the corrections and the stage's inputs to read. An
+// experiment arm always builds a fresh key and dispatches into a sandbox — and dispatching on the REAL run's
+// key from a sandbox was rejected outright, because "canonical run untouched" is the arm's whole contract and
+// an arm that breaks its contract to gain fidelity is measuring with a broken instrument.
 //
 // So an arm carries the corrective pass's INPUTS on a COLD turn, composed by the same function production
-// uses. That reaches the seam nothing else reaches without a two-hour run. It is NOT the warm pass, and
-// the receipt says so in a word rather than leaving it to be inferred:
+// uses. That reaches the seam nothing else reaches without a two-hour run. It is NOT production's
+// dispatch, and the receipt says so in a word rather than leaving it to be inferred. The production word
+// is a recorded value and stays as it is, though the followup it names never resumes the synthesis session:
 //
-//   dispatched-warm            production only — the resumed followup
+//   dispatched-warm            production only — the followup on the run's own key
 //   dispatched-cold            the arm — the same blocks, a fresh turn
 //   refused-no-corrective-state  neither — this run has no corrective pass to reproduce
 //

package/driver/coverage-form-io.mjs

@@ -149,7 +149,8 @@ export function coverageFormInput(runDir) {
   const orderedTerritories = Array.isArray(plan.ordered_jurisdictions) ? plan.ordered_jurisdictions : [];
   return { input: { skeleton: exec.skeleton, plan, bandBlocksByAxis, deferredReasons, activeAxes,
     bandsUnreadable, orderedTerritories, capabilities, unknownAxisUnits,
-    awaiting: Array.isArray(exec.awaiting) ? exec.awaiting : [], withheld: readWithheldFamilies(runDir) }, absent: null };
+    awaiting: Array.isArray(exec.awaiting) ? exec.awaiting : [], withheld: readWithheldFamilies(runDir),
+    mainMarkets: Array.isArray(exec.main_markets) ? exec.main_markets : [] }, absent: null };
 }
 
 /**

package/driver/coverage-form.mjs

@@ -31,7 +31,7 @@
 import { REGISTER_AXES, COVERAGE_STATUSES, normalizeAxis, CROWD_RULING_TOKEN,
   CROWD_RULING_UNIT_GRAMMAR } from "./coverage-ledger.mjs";
 import { shortId } from "./connotation-search.mjs";
-import { openBlocksByAxis } from "./register-plan.mjs";
+import { openBlocksByAxis, crowdNarrowing, blocksByQidOf } from "./register-plan.mjs";
 import { territoryLayerReport, unsearchedLayerReason } from "./binding-layers.mjs"; import { goodsTermsList } from "../providers/_shared/term-shape.mjs";
 
 const STATUS_SET = new Set(COVERAGE_STATUSES);
@@ -344,8 +344,17 @@ export function blockOpenBecause(b, narrowings = []) {
  */
 export function coverageFormRows({ skeleton = [], activeAxes = null, plan = null,
   bandBlocksByAxis = {}, deferredReasons = {}, bandsUnreadable = [],
-  orderedTerritories = [], capabilities = null, awaiting = [], withheld = {} } = {}) {
+  orderedTerritories = [], capabilities = null, awaiting = [], withheld = {}, mainMarkets = [] } = {}) {
   const skel = Array.isArray(skeleton) ? skeleton.filter((s) => s && typeof s === "object") : [];
+  // WHAT WAS RETRIEVED UNDER EACH CROWD (register-plan.mjs, crowdNarrowing), worked out from the same blocks these rows
+  // are built from and carried on its row as data: a narrowed list retrieved in full (and which), none, or for the
+  // identical mark whether retrieved lists cover every class in every main market (and the cells they do not). The
+  // row stays open either way: reading the lists and deciding the crowd are the reading step's.
+  const narrowingByQid = new Map(crowdNarrowing(plan, blocksByQidOf(bandBlocksByAxis), { mainMarkets }).rows.map((r) => [String(r.qid), r]));
+  const endingOf = (qid) => {
+    const r = narrowingByQid.get(String(qid));
+    return r ? { narrowing: r.narrowing, ...(r.lists?.length ? { lists: r.lists } : {}), ...(r.not_covered?.length ? { not_covered: r.not_covered } : {}) } : {};
+  };
   const entriesByQid = new Map((plan?.entries ?? []).map((e) => [e.qid, e]));
   const open = openBlocksByAxis(skel, bandBlocksByAxis, plan);
   // Axis order is the run's, not a set's iteration order: the plan-execution skeleton first (the order
@@ -393,6 +402,7 @@ export function coverageFormRows({ skeleton = [], activeAxes = null, plan = null
         ...(Number.isInteger(b.total_hits) ? { total_hits: b.total_hits } : {}),
         ...(b.unaccounted?.length ? { unaccounted_terms: b.unaccounted } : {}),
         ...(b.unaccounted_classes?.length ? { unaccounted_classes: b.unaccounted_classes } : {}),
+        ...endingOf(b.qid),
         // The block's OWN row is the naming the deleted join required. A clean claim HERE is the
         // silent swallow; a clean claim on a sibling slice never discharged this block and does not now.
         open: true,
@@ -420,6 +430,8 @@ export function coverageFormRows({ skeleton = [], activeAxes = null, plan = null
     // it was not asked. The row arrives settled when the turn recorded that, and open when nobody did,
     // so an unjudged family is an obligation the digest's gate refuses to pass. `family` rows stay out of
     // the ledger the report is built from; the reason is the run's record and the audit workbook's.
+    // A row that arrives settled names the record its judgment came from (`reason_from`), so the union can keep
+    // that judgment the row's own: a later digest may add its reading beside it, never in place of it.
     for (const f of (Array.isArray(awaiting) ? awaiting : [])) {
       const qid = String(f?.qid ?? "").trim();
       if (!qid || String(f?.axis ?? "").trim() !== axis) continue;
@@ -432,6 +444,7 @@ export function coverageFormRows({ skeleton = [], activeAxes = null, plan = null
         open: true,
         open_because: "a waiting family the reading turn did not ask — it was never searched, and its only judgment is withheld-by-judgment with the reason it was not asked",
         status: w?.reason ? "withheld-by-judgment" : null, reason: w?.reason ? String(w.reason) : null,
+        ...(w?.reason ? { reason_from: `_driver/withheld-families-${String(w.axis ?? axis)}.json` } : {}),
       });
     }
     // ── AN OFFICE THIS DEPLOYMENT COULD NOT REACH ────────────────────────────────────────
@@ -1031,6 +1044,8 @@ function briefRow(r) {
     r.unaccounted_classes?.length ? `classes unaccounted: ${r.unaccounted_classes.join(", ")}` : "",
     r.unaccounted_terms?.length ? `terms unaccounted: ${r.unaccounted_terms.join(", ")}` : "",
     r.receipt_reason ? `receipt: ${String(r.receipt_reason).slice(0, 160)}` : "",
+    // what was retrieved under the crowd (register-plan.mjs, crowdNarrowing), as data beside the counts it rests on
+    r.narrowing ? `narrowing: ${r.narrowing}${r.lists?.length ? ` (${r.lists.slice(0, 6).join(", ")})` : ""}${r.not_covered?.length ? `; not covered: ${r.not_covered.slice(0, 12).join(", ")}` : ""}` : "",
   ].filter(Boolean).join("; ");
   const settled = String(r.status ?? "").trim() ? ` [settled: ${String(r.status).trim()}]` : "";
   return `  ${r.row_id}  (${r.kind}) ${r.unit}${facts ? ` — ${facts}` : ""}${r.open === true ? " — OPEN: never confirmed-clean" : ""}${settled}`;

package/driver/coverage-union.mjs

@@ -104,8 +104,17 @@ export function unionCoverageForm(prior, submitted, input, { parkedIds = null }
     const p = findPrior(row), s = findSubmitted(row);
     const sOk = s && rowIsSettled(s, row), pOk = p && rowIsSettled(p, row), dOk = rowIsSettled(row, row);
     let fields;
-    if (sOk) fields = seatFields(s);
-    else if (pOk) fields = seatFields(p); else if (dOk) fields = seatFields(row);   // a judgment the driver row arrived with (a family the reading turn withheld)
+    // A FAMILY THE READING TURN WITHHELD ARRIVES SETTLED WITH THE TURN'S OWN JUDGMENT, and that judgment stays the
+    // row's. Every later reader is told the row carries the turn's decision, so a digest that re-words it would
+    // make that untrue: its own reading is kept beside the turn's, as `digest_reason`, and never replaces it. A
+    // release takes the family out of the turn's record, so the next pass builds the row without that judgment
+    // and the digest settles it as any row.
+    if (row.kind === "family" && row.reason_from && dOk) {
+      fields = seatFields(row);
+      const theirs = sOk ? seatFields(s).reason : (p?.digest_reason ?? null);
+      if (theirs && theirs !== fields.reason) row.digest_reason = theirs;
+    } else if (sOk) fields = seatFields(s);
+    else if (pOk) fields = seatFields(p); else if (dOk) fields = seatFields(row);   // a judgment the driver row arrived with
     else {
       const sf = seatFields(s ?? {}), pf = seatFields(p ?? {});
       fields = { status: sf.status || pf.status, reason: sf.reason || pf.reason };

package/driver/digest-queue.mjs

@@ -156,7 +156,7 @@ export const DIGEST_OWN_PASS_EXEMPTIONS = Object.freeze([
 // The standard digest-resume preamble every warm re-digest opens with (verbatim from the legacy
 // escalation/envelope/frame-reopen followups — shared so the OFF path stays byte-identical).
 export const DIGEST_RESUME_PREAMBLE =
-  "You are RESUMING your earlier register-digest session — your prior digest and all unit files are already in your context. Do NOT redo it from scratch.";
+  "This is a fresh session: your earlier register-digest work is not in your context, and the unit files are among the inputs listed below. Your prior digest is the findings file named below. Do NOT redo it from scratch.";
 
 /**
  * The standard settlement repair contract: every consolidated flush ends with THIS.

package/driver/disposition-call.mjs

@@ -881,7 +881,7 @@ export function callAnswer({ accepted, refused, overflow }, outstanding) {
     const owed = !r.evidence_owed ? ""
       : r.evidence_unsatisfiable === true
         ? " — this row CANNOT be evidenced: no passage on its candidates is long enough to quote from, so no `fragment` will ever bind. Do not keep re-sending it. Rule it and send `obstacle` saying the snippet carries nothing quotable."
-        : (r.ruled ? " — RULED, but this row now also needs `segment_index` (the number of the passage you relied on, from the ruled receipt's numbered passages) and `fragment` (a few characters copied exactly out of that passage)"
+        : (r.ruled ? " — RULED, but this row now also needs `segment_index` (the number of the passage you relied on, from the ruled receipt's numbered passages)"
                    : " — needs `segment_index` (the number of the passage you rely on, from the ruled receipt's numbered passages) and `fragment` (a few characters copied exactly out of that passage)");
     lines.push(`  ${name(r)}${owed}`);
   }

package/driver/document-coverage.mjs

@@ -94,8 +94,9 @@ export function renderDocumentCoverageSection(summary) {
       : `**Registry documents were retrieved for this search:** ${s.recordsWithBody} record`
         + `${s.recordsWithBody === 1 ? "" : "s"}${s.recordsTotal != null && s.recordsTotal !== s.recordsWithBody
           ? ` of the ${s.recordsTotal} held for this matter` : ""} carr${s.recordsWithBody === 1 ? "ies" : "y"} `
-        + "the document itself, so the goods and services behind those rights were read as written rather "
-        + "than inferred from their class numbers.");
+        // Holding a record is not reading it: a judging step opens few of the records a register holds, so the
+        // sentence says what was retrieved and claims no reading (the owner's approved wording, 2026-10-18).
+        + "the document itself.");
   if (s.findingsOnRecord != null && s.recordsWithBody !== 0)
     parts.push(s.findingsOnRecord === 0
       ? "No finding in this report rests on wording read from a retrieved document; where a specification "

package/driver/effective-scope.mjs

@@ -192,19 +192,24 @@ export function orderTerritories(job, profile) {
 /**
  * THE NARROWING ORDER, as the register reading step is told it (ruled 2026-09-26): goods and class
  * first, then the markets in turn, with the markets the driver knows filled in. One line. PURE.
+ *
+ * ONE MARKET LIST, the one that applies: the order's countries; else the customer's priority markets; else the
+ * markets the customer's field and brand point to, with the major markets as their fallback. The line used to
+ * print all three as a chain of "else", and the reading step was left to pick among them. Each step keeps the
+ * limits before it, and a crowd still a crowd after the markets is recorded with its count: the narrowing ends.
  */
 export function narrowingOrderLine(job, profile, inScopeClasses = null) {
   const { scope, priorities, major } = narrowingMarkets(job, profile);
   const markets = scope.length
     ? `one question per market of the order's scope (${scope.join(", ")}); nothing outside it was ordered`
-    : `one question per market: ${[
-      priorities.length ? `the customer's priority markets (${priorities.join(", ")})` : "",
-      "the markets the customer's field and brand point to (judge them from the matter frame)",
-      `the major markets (${major.join(", ")})`,
-    ].filter(Boolean).join(", else ")}`;
+    : priorities.length
+      ? `one question per market: the customer's priority markets (${priorities.join(", ")})`
+      : `one question per market: the markets the customer's field and brand point to (judge them from the matter frame), else the major markets (${major.join(", ")})`;
   return `NARROWING A CROWD, in this order: first the goods and the classes, the client's goods words in `
-    + `${inScopeClasses ? `the order's classes [${inScopeClasses}]` : "the order's classes"}, then the classes the crowding owners `
-    + `file in; still a crowd, then the markets, ${markets}. From the narrowed lists, read what a lawyer would raise. `
+    + `${inScopeClasses ? `the order's classes [${inScopeClasses}]` : "the order's classes"}, then one of those classes at a time, `
+    + `each step keeping the limits before it and stopping at the first list you can read; `
+    + `still a crowd, then the markets, ${markets}. Still a crowd after the markets: record it with its count. `
+    + `From the narrowed lists, read what a lawyer would raise. `
     + `What was counted and not read stays on its coverage row with its count: set aside, never clean.`;
 }
 

package/driver/engine/mcp/band-server.mjs

@@ -21,10 +21,12 @@ import { join, dirname } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { serve } from "./stdio-server.mjs";
 import { answerBudget, quotedBytes } from "../../../shared/answer-parts.mjs";
-import { classifyRecord, prepareTargets, SHAPE_TIERS, isLiveRecord, niceClassKey, PLACEMENT_GROUP_ORDERS } from "../../band-shape.mjs";
+import { classifyRecord, prepareTargets, SHAPE_TIERS, isLiveRecord, niceClassKey, withoutPlacementOrders } from "../../band-shape.mjs";
 import { recordQids } from "../../named-band.mjs";
 import { normalizeRecordUri } from "../../registry-fidelity.mjs";
-import { bandGoodsIndex, goodsFor, goodsWordCounter, goodsWordsMatched, rawGoodsCarried, untaggedIsEnglish } from "../../record-goods.mjs";
+import { bandGoodsIndex, goodsFor, goodsWordCounter, goodsWordsMatched, rawGoodsCarried, untaggedIsEnglish, rowGoods } from "../../record-goods.mjs";
+import { recordGoodsEvidence, heldRecordProvenance, recordFetchOutcomes, readRunCallRows, goodsFromLabel } from "../../goods-evidence.mjs";
+import { DEFAULT_LEDGER_PATH } from "../../provider-usage.mjs";
 
 const RUN_DIR = process.env.CLEAROTRON_BAND_RUN_DIR || "";
 const SESSION = process.env.CLEAROTRON_GATHER_SESSION_KEY || "";
@@ -299,14 +301,31 @@ const shapeGoodsTest = () => {
   testCache = { words, matched: goodsWordsMatched(words, { stems: true }) };
   return testCache;
 };
-// The record's body first; a row that carries goods of its own stands in where the run holds no body.
-const goodsOfRow = (r) => goodsFor(goodsIndex(), r)
+// The record's body first; where the run holds none, the statements the row carries, as the shape reads them
+// (`rowGoods`, a statement the register cut marked so); a row that carries its goods as one string stands in last.
+const goodsOfRow = (r) => goodsFor(goodsIndex(), r) ?? rowGoods(r)
   ?? (typeof r?.goods === "string" && r.goods.trim() ? [{ classes: [], text: r.goods.trim(), ...(untaggedIsEnglish(r?.record_id) ? {} : { en: false }) }] : null);
+// WHAT A RECORD'S GOODS REST ON, from the run's own files and its fetches, by the shared reader's one rule
+// (goods-evidence.mjs `recordGoodsEvidence`): the supporting evidence the record holds, never the last call made
+// for it. A fetch counts as failed only where the register's call ledger records it so; missing telemetry is not a
+// recorded failure. Read once per server, as the band and the goods index are.
+let evidenceCache = null;
+const runEvidence = () => evidenceCache ??= (() => {
+  let prefix = null;
+  try { const st = loadJson(join(RUN_DIR, "status.json")); if (st?.slug && st?.codename) prefix = `clearance-${st.slug}-${st.codename}-`; } catch { prefix = null; }
+  const calls = prefix ? readRunCallRows(DEFAULT_LEDGER_PATH, prefix) : { rows: [], error: "no run prefix" };
+  return { held: heldRecordProvenance(RUN_DIR), fetches: calls.error ? null : recordFetchOutcomes(calls.rows, { runPrefix: prefix }) };
+})();
+const evidenceOfRow = (r) => {
+  const { held, fetches } = runEvidence();
+  return recordGoodsEvidence(r, { goods: { of: goodsOfRow, held: (x) => goodsFor(goodsIndex(), x) != null }, held, fetches });
+};
 const withGoods = (r) => {
   const { words, matched } = shapeGoodsTest();
   const m = words.length ? matched(goodsOfRow(r)) : null;
   const { goods: _text, ...row } = project(r);   // a row's own goods text stands in for the test, and is not served
-  return { ...row, goods_words: m == null ? null : `${m.length} of ${words.length}${m.length ? `: ${m.join(", ")}` : ""}` };
+  return { ...row, goods_words: m == null ? null : `${m.length} of ${words.length}${m.length ? `: ${m.join(", ")}` : ""}`,
+    goods_from: goodsFromLabel(evidenceOfRow(r)) };
 };
 
 // A GROUP, PAGED AS THE SHAPE LISTS IT. The shape lists a group of a thousand records or more by its first
@@ -525,14 +544,59 @@ function bandRecord(params = {}) {
   // It stays an error, it stays in the reading audit with the reason that made it one, and it still says
   // what IS on file: the deferral this tool reports must stay visible for the real failures, or a dead
   // document reads back as a record that never had one.
-  logRead("band_record", { record_id: uri }, { ok: false, reason: hit.miss });
   // The uri grammar is the same one screen-gate reads, and it does not cover every segment shape (a
   // 7+ character office segment parses nowhere). So this message never tells the model its uri is
   // wrong: it says what the resolver could not do, and what to do about it either way.
-  const why = hit.miss === "unparsable-uri"
+  //
+  // WHAT IS ON FILE INSTEAD. Where the register's search answer listed goods for the record, they are served here
+  // with the miss, each statement with its source and completeness, in parts as an official record's text is: a
+  // whole statement on the search answer can decide a line's group, and no other tool serves its text. A fetch
+  // that the register's call ledger records as failed is said to have failed; nothing else is.
+  // A cite without its leading slash resolves on a hit; the miss reads it the same way, or it would lose the failed
+  // fetch and the search answer's goods that the cite's record has.
+  const parsed = hit.miss !== "unparsable-uri";
+  const key = normalizeRecordUri(uri) || normalizeRecordUri(`/${String(uri ?? "").trim().replace(/^\/+/, "")}`);
+  const bandRow = parsed && key ? bandRowFor(key) : null;
+  const statements = bandRow ? rowGoods(bandRow) : null;
+  const fetched = parsed ? runEvidence().fetches : null;
+  const fetch = fetched && key ? (fetched.get(key) ?? fetched.get(key.split("/").pop())) : null;
+  const failed = Boolean(fetch?.failed && !fetch.ok);
+  const why = !parsed
     ? `"${uri}" did not parse as a record reference (expected /mark/<cc>/<id> — a full provider URL carrying one is fine) and no archived record matches it exactly. If the uri IS right, its shape is outside this tool's grammar: state the gap, never read it as a clean.`
-    : `No official record fetched for "${uri}" this run.`;
-  return { isError: true, text: `${why} ${available.length ? `Records on file (${available.length}): ${available.slice(0, 40).join(", ")}${available.length > 40 ? ", …" : ""}.` : "No records fetched yet."} This tool is read-only — it never fetches; a record you need but do not have is an honest gap to state, not a reason to guess.` };
+    : statements
+      ? `${failed ? `No official record is on file for "${uri}": a fetch of it failed this run.` : `No official record is on file for "${uri}".`} The register's search answer listed these goods. Their source and completeness are shown with each statement.`
+      : failed ? `No official record is on file for "${uri}": a fetch of it failed this run.` : `No official record fetched for "${uri}" this run.`;
+  const rest = `${available.length ? `Records on file (${available.length}): ${available.slice(0, 40).join(", ")}${available.length > 40 ? ", …" : ""}.` : "No records fetched yet."} This tool is read-only — it never fetches; a record you need but do not have is an honest gap to state, not a reason to guess.`;
+  if (!statements) {
+    logRead("band_record", { record_id: uri }, { ok: false, reason: hit.miss, ...(failed ? { fetch_failed: true } : {}) });
+    return { isError: true, text: `${why} ${rest}` };
+  }
+  const goodsLines = statements.map((g) => JSON.stringify({ class: g.classes.join(",") || null, text: g.text,
+    goods_from: g.cut ? "search answer, cut by the register" : g.unknown ? "search answer, completeness not established" : "search answer" }));
+  const text = [why, ...goodsLines, rest].join("\n");
+  const parts = splitAtLines(text, RESPONSE_CHARS);
+  const wanted = Number(params.part ?? 1);
+  const part = Number.isInteger(wanted) && wanted >= 1 && wanted <= parts.length ? wanted : 1;
+  logRead("band_record", { record_id: uri }, { ok: false, reason: hit.miss, served: "search-answer-goods", bytes: text.length,
+    ...(parts.length > 1 ? { part, parts: parts.length } : {}), ...(failed ? { fetch_failed: true } : {}) });
+  if (parts.length === 1) return { isError: true, text };
+  return { isError: true, text: `[record ${uri} — part ${part}/${parts.length}]\n` + parts[part - 1]
+    + (part < parts.length ? `\n[end of part ${part}/${parts.length} — call band_record again with {"record_id": "${uri}", "part": ${part + 1}}]` : "") };
+}
+
+// The band row a record id names, from the band file, read once per server. null where the band holds none.
+let bandRowsCache = null;
+function bandRowFor(uri) {
+  if (!bandRowsCache) {
+    bandRowsCache = new Map();
+    try {
+      for (const r of loadJson(bandPath())?.enumerated ?? []) {
+        const k = normalizeRecordUri(r?.record_id);
+        if (k && !bandRowsCache.has(k)) bandRowsCache.set(k, r);
+      }
+    } catch { /* no band on file: nothing to serve beside the miss */ }
+  }
+  return bandRowsCache.get(normalizeRecordUri(uri)) ?? null;
 }
 
 // THE SHAPE'S GROUP PAGES ARE PLACEMENT'S. Placement owes every line a group lists a fate, so it is offered the
@@ -543,10 +607,10 @@ function bandRecord(params = {}) {
 // arrives anyway is served as before: the offer changes, not what the tool answers.
 const GROUP_PAGES = process.env.CLEAROTRON_BAND_GROUPS === "1";
 // The same holds for the shape's own orders under the groups: placement reads them, and every other stage is
-// served the shape without them (Krzys's ruling, 2026-10-14). Each is removed with the space before it, inside
+// served the shape without them (the owner's ruling, 2026-10-14). Each is removed with the space before it, inside
 // its line, so no line moves and the line each listed mark is printed on, which `linesByPart` reads, still holds.
-const withoutPlacementOrders = (text) => PLACEMENT_GROUP_ORDERS.reduce((t, order) => t.split(` ${order}`).join("").split(order).join(""), text);
-const LOOKUP_DESCRIPTION = "Look up enumerated records in this run's frozen register band (read-only; logged to the reading audit). Filters AND together: record_id (exact uri), owner (substring), nice_class, tier (identical|near-identical|same-family|other|unclassifiable — classified against the shape's frozen targets), qid (exact plan-entry id — the plan-execution ledger join; a record surfaced by several slices matches under EVERY one of them), query (the _query slice that surfaced the record), text (substring of mark_text), status (substring), live_only, goods (words: records whose goods contain any of them, as whole words, singular or plural; a record with no goods on file matches too), group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), limit (default 20, max 100), offset (default 0: where in the matching records or lines to start — a capped answer names the next offset, so a large band or group is read page by page). On each record served, `goods_words` gives the client's goods words its goods hold, as the shape tests them (k of N: the words), or null where its goods cannot be read; the goods text is in band_record. Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.";
+// (band-shape.mjs `withoutPlacementOrders` removes them, with the shape's other placement-only orders and its group-page commands.)
+const LOOKUP_DESCRIPTION = "Look up enumerated records in this run's frozen register band (read-only; logged to the reading audit). Filters AND together: record_id (exact uri), owner (substring), nice_class, tier (identical|near-identical|same-family|other|unclassifiable — classified against the shape's frozen targets), qid (exact plan-entry id — the plan-execution ledger join; a record surfaced by several slices matches under EVERY one of them), query (the _query slice that surfaced the record), text (substring of mark_text), status (substring), live_only, goods (words: records whose goods contain any of them, as whole words, singular or plural; a record with no goods on file matches too), group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), limit (default 20, max 100), offset (default 0: where in the matching records or lines to start — a capped answer names the next offset, so a large band or group is read page by page). On each record served, `goods_words` gives the client's goods words its goods hold, as the shape tests them (k of N: the words), or null where its goods cannot be read; `goods_from` says what those goods rest on: official record; official record, cut by the register; official record, completeness not established; official record, no goods listed; search answer; search answer, cut by the register; search answer, completeness not established; fetch failed; or nothing held. The goods text is in band_record. Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.";
 const LOOKUP_GROUP_CLAUSE = "group (a, b, c, d, rest or no_goods: that list's lines in the shape's order, one per mark of an owner), ";
 const LOOKUP_OFFSET_GROUPS = "offset (default 0: where in the matching records or lines to start — a capped answer names the next offset, so a large band or group is read page by page)";
 const LOOKUP_OFFSET_BAND = "offset (default 0: where in the matching records to start — a capped answer names the next offset, so a large band is read page by page)";
@@ -579,7 +643,7 @@ serve({
     },
     {
       name: "band_record",
-      description: "The OFFICIAL registry record the driver fetched into this run's _records/ for a given record_id (/mark/... uri) — the fetched document itself, for detail the band row does not carry. Cite the uri in whatever form the band, the findings or the provider gave you: case, a wrapping provider URL and the registration-instance suffix are all resolved to the same document. Read-only: it never fetches; an unfetched record returns an honest miss listing what is on file, and a record that IS on file but cannot be opened says so — both are gaps to state, never records without documents. Every call is logged to the reading audit.",
+      description: "The OFFICIAL registry record the driver fetched into this run's _records/ for a given record_id (/mark/... uri) — the fetched document itself, for detail the band row does not carry. Cite the uri in whatever form the band, the findings or the provider gave you: case, a wrapping provider URL and the registration-instance suffix are all resolved to the same document. Read-only: it never fetches. An unfetched record returns an honest miss listing what is on file, with the goods the register's search answer listed for it where it listed any; a record that IS on file but cannot be opened says so — both are gaps to state, never records without documents. Every call is logged to the reading audit.",
       inputSchema: { type: "object", required: ["record_id"], properties: { record_id: { type: "string", description: "the /mark/<cc>/<id> uri" }, part: { type: "number", description: "1-based part number when an oversize record is served in parts (default 1)" } } },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: bandRecord,

package/driver/engine/mcp/dispositions-server.mjs

@@ -128,7 +128,7 @@ serve({
   name: "dispositions", version: "0.1.0",
   tools: [{
     name: "record_dispositions",
-    description: "Record your meaning rulings. Send VALUES, not a file: one entry per row, and the driver writes the document. You type NO identifier of any kind: give `row_index`, the NUMBER printed beside that obligation in the obligations block, and `receipt_index`, the POSITION of the candidate in that row's own list — the driver resolves both. Rows are validated against THAT row as they arrive, so you learn what to fix inside this turn; rows that validate are kept even when others in the same call are refused. The answer names every obligation still outstanding and which of them still owe proof of reading — a `segment_index` and a `fragment`.",
+    description: "Record your meaning rulings. Send VALUES, not a file: one entry per row, and the driver writes the document. You type NO identifier of any kind: give `row_index`, the NUMBER printed beside that obligation in the obligations block, and `receipt_index`, the POSITION of the candidate in that row's own list — the driver resolves both. Rows are validated against THAT row as they arrive, so you learn what to fix inside this turn; rows that validate are kept even when others in the same call are refused. The answer names every obligation still outstanding and which of them still owe proof of reading — a `segment_index`.",
     inputSchema: { type: "object", required: ["grid_spec_path", "rows"], properties: {
       grid_spec_path: { type: "string", description: "Absolute path to the driver-written grid spec — the same one the grid tool was given." },
       rows: {
@@ -156,7 +156,7 @@ serve({
           // — THE HONEST EXIT. Declared here because a seat can only take an exit it can see: the
           // one row that killed a production run was refused 217 times by a seat that had no way to say
           // it could not rule, and the schema is the half its tool-calling binds to.
-          obstacle: { type: "string", description: "ONLY when this receipt supports no ruling at all: one line naming what in it blocks a ruling. Send this INSTEAD of `ruling` — never both. The row is then recorded as undecided, with your sentence shown to the reviewing lawyer in place of a ruling, and the stage completes rather than stalling on it. Prefer a ruling whenever you can give one; this is not a way past a hard row." },
+          obstacle: { type: "string", description: "ONLY when this receipt is genuinely impossible to evidence — every passage an elision marker, nothing quotable in any of them: one line saying what stops you. Send this ALONGSIDE your `ruling` and `note`, never instead of them. The row is then recorded as undecided, with your sentence shown to the reviewing lawyer in place of proof, and the stage completes rather than stalling on it. This is not a way past a hard row: `obstacle` is for the receipt that offers nothing, not the awkward one." },
         } },
       },
     } },

package/driver/engine/mcp/held-answers.mjs

@@ -0,0 +1,128 @@
+// 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
+//
+// held-answers.mjs — ONE ANSWER PER QUESTION PER RUN, ACROSS EVERY WORKER AND PASS.
+//
+// The register workers run in parallel and do not see each other's questions, so the same question was put to the
+// register again by another worker: on a test run of a crowded matter, 178 follow-up proposals held 167 distinct
+// questions, and the 11 copies cost 49 calls. A question the run has already answered now gets the held answer, and
+// one the run has already decided not to ask (a family withheld by judgment, or a follow-up the run's safety net
+// refused) gets that decision. Nothing is asked again and no call is made.
+//
+// WHAT MAKES TWO QUESTIONS THE SAME: every field that changes what the register is asked — the predicate, the term
+// or terms, their romanised forms, the classes, the markets, the goods words, the owner and the kind of answer —
+// and none that only records where a question came from. A question with no markets is asked to the plan's, so it
+// is the same as one naming them. Owner names are compared as written, never merged. A different scope is a
+// different question, and an earlier answer that failed is no answer: both are asked again.
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { driverDir } from "../../../shared/driver-dir.mjs";
+import { OUTSTANDING_REASON } from "../../../providers/_shared/follow-up-searches.mjs";
+import { awaitsReadingTurn } from "../../../providers/_shared/plan-guards.mjs";
+import { releasedFamilyQids } from "../../withheld-families.mjs";
+
+const QUESTION_FIELDS = ["predicate", "term", "terms", "romanizedTerms", "term_literal", "nice_classes", "regions", "goods_text", "owner", "expected_kind"];
+const sorted = (v) => [...v].map((x) => String(x)).sort();
+
+/** The question an entry asks, as a key. `planRegions` fills an entry that names no markets. PURE. */
+export function questionKey(e, planRegions = []) {
+  const o = {};
+  for (const k of QUESTION_FIELDS) {
+    let v = e?.[k];
+    if (k === "predicate") v = String(v ?? "default");
+    if (k === "expected_kind") v = String(v ?? "enumerate");
+    if (k === "regions" && !(Array.isArray(v) && v.length)) v = planRegions;
+    if (v === undefined || v === null || v === false || (Array.isArray(v) && !v.length) || v === "") continue;
+    o[k] = Array.isArray(v) ? (k === "terms" || k === "romanizedTerms" ? v.map(String) : sorted(v)) : v;
+  }
+  return JSON.stringify(o);
+}
+
+// A band file is read once per change: the propose tool is called many times in a turn, and a primary sweep's band
+// runs to tens of megabytes. Keyed on the path, its size and its modification time. Only what a held answer hands
+// back is kept, the first records among it, so a worker's process does not hold every band whole.
+const BAND_CACHE = new Map();
+const HELD_RECORDS = 25;
+function readBlocks(path) {
+  let st;
+  try { st = statSync(path); } catch { return []; }
+  const stamp = `${st.size}:${st.mtimeMs}`;
+  const hit = BAND_CACHE.get(path);
+  if (hit && hit.stamp === stamp) return hit.blocks;
+  let blocks = [];
+  try {
+    const j = JSON.parse(readFileSync(path, "utf8"));
+    blocks = (Array.isArray(j) ? j : []).filter((b) => b?.qid).map((b) => ({
+      qid: b.qid, state: b.state ?? null, error: b.error === true, total_hits: b.total_hits ?? null,
+      count: b.count ?? (Array.isArray(b.records) ? b.records.length : null),
+      records: Array.isArray(b.records) ? b.records.slice(0, HELD_RECORDS) : [],
+    }));
+  } catch { blocks = []; }
+  BAND_CACHE.set(path, { stamp, blocks });
+  return blocks;
+}
+
+/**
+ * Refuse the minted entries whose question the run has already answered on another row, the way the fold refuses a
+ * question the plan already holds: `duplicate-question`, with the row that answered it as the twin. Second framing's
+ * re-sweep calls this before its fold, because the fold sees only the plan's rows on the re-sweep's own axis, and a
+ * question another worker answered is not asked again. Only an answer settles: a withheld family has its own refusal,
+ * and a follow-up the safety net did not send would not be sent again. PURE.
+ * @returns {{ kept: object[], refused: {qid: string, term: string, kind: "duplicate-question", twin: string}[] }}
+ */
+export function refuseHeldQuestions(entries, held, planRegions = []) {
+  const kept = [], refused = [];
+  for (const e of Array.isArray(entries) ? entries : []) {
+    const h = held?.get?.(questionKey(e, planRegions));
+    if (e?.qid && h?.decision === "answered" && h.qid && String(h.qid) !== String(e.qid))
+      refused.push({ qid: e.qid, term: String(e.term ?? e.terms?.[0] ?? ""), kind: "duplicate-question", twin: String(h.qid) });
+    else kept.push(e);
+  }
+  return { kept, refused };
+}
+
+/**
+ * The run's held answers and decisions, by question key. IMPURE (reads the run's register files).
+ * @returns {Map<string, { qid: string, axis: string, decision: "answered"|"withheld"|"outstanding", block?: object }>}
+ */
+export function heldAnswers(runDir, { planRegions = [], withheld = {}, released = null } = {}) {
+  // A FAMILY WAITING FOR THE READING TURN IS ANSWERED ONLY ONCE IT IS RELEASED AND RUN, the plan join's own rule: until
+  // then it was not asked, whatever block its qid may carry, and a question repeating it is asked as the join expects.
+  let releasedQids = released;
+  if (!(releasedQids instanceof Set)) { try { releasedQids = releasedFamilyQids(runDir); } catch { releasedQids = new Set(); } }
+  const held = new Map();
+  const units = join(runDir, "register-units");
+  const blocksByQid = new Map();
+  const plans = [];
+  try { plans.push({ axis: null, plan: JSON.parse(readFileSync(driverDir(runDir, "register-plan.json"), "utf8")) }); } catch { /* no frozen plan */ }
+  let files = [];
+  try { files = readdirSync(units); } catch { files = []; }
+  for (const f of files) {
+    if (f.endsWith("-band.json")) for (const b of readBlocks(join(units, f))) if (b?.qid) blocksByQid.set(String(b.qid), b);
+    if (f.endsWith("-supplemental-plan.json")) {
+      try { plans.push({ axis: f.slice(0, -"-supplemental-plan.json".length), plan: JSON.parse(readFileSync(join(units, f), "utf8")) }); } catch { /* torn: skipped */ }
+    }
+  }
+  for (const { plan } of plans) {
+    for (const e of Array.isArray(plan?.entries) ? plan.entries : []) {
+      if (!e?.qid) continue;
+      const key = questionKey(e, planRegions);
+      if (held.has(key)) continue;
+      if (awaitsReadingTurn(e.when) && !releasedQids.has(String(e.qid))) {
+        if (withheld?.[e.qid]) held.set(key, { qid: e.qid, axis: e.axis, decision: "withheld" });
+        continue;
+      }
+      const b = blocksByQid.get(String(e.qid));
+      if (b && b.error !== true) held.set(key, { qid: e.qid, axis: e.axis, decision: "answered", block: b });
+      else if (withheld?.[e.qid]) held.set(key, { qid: e.qid, axis: e.axis, decision: "withheld" });
+    }
+    // A follow-up the run's safety net did not send is a decision too: proposed again, it would not be sent again.
+    for (const r of Array.isArray(plan?.rejected) ? plan.rejected : []) {
+      if (r?.issue !== OUTSTANDING_REASON || !r?.proposal) continue;
+      const key = questionKey(r.proposal, planRegions);
+      if (!held.has(key)) held.set(key, { qid: null, axis: null, decision: "outstanding" });
+    }
+  }
+  return held;
+}

package/driver/engine/mcp/recording-server.mjs

@@ -1082,7 +1082,7 @@ serve({
         findings_patch: {
           type: "array",
           description:
-            "A TARGETED CORRECTION, and the shape the repair prompts ask for. Send the complete corrected finding object(s), each carrying the `ordinal` of the finding it replaces, and send NOTHING else — no `findings`, no `narrative` unless you also corrected a section. The driver is holding every value you already sent and re-renders both files from them, so what you do not name comes back byte-identical. It cannot remove a finding: an ordinal names one to replace, and there is no way to express a deletion. Sending the whole `findings` document instead REPLACES the record, which is how fifteen findings were lost once — if you mean to correct four findings, send four rows here, not a document containing four.",
+            "A TARGETED CORRECTION, and the shape the repair prompts ask for. Send the complete corrected finding object(s), each carrying the `ordinal` of the finding it replaces, and send NOTHING else — no `findings[]` list, no `narrative` unless you also corrected a section, and a `findings` object only to carry the registers you changed or the \"corrections\" marker. The driver merges this patch into the last accepted record, keeps the values the patch does not replace, and renders both files. It cannot remove a finding: an ordinal names one to replace, and there is no way to express a deletion. Sending a `findings` document that carries its `findings[]` list instead REPLACES the record, which is how fifteen findings were lost once — if you mean to correct four findings, send four rows here, not a document containing four.",
           items: {
             type: "object",
             required: ["ordinal"],
@@ -1109,7 +1109,11 @@ serve({
         narrative: {
           type: "object",
           description: "The cross-finding read, as sections. This is the material no other artifact on the run holds — NOT a second write-up of each finding, which lives on the report card. On a first call, send it complete. On a correction, send only the sections you changed — the rest are held.",
-          required: ["spine", "verdict"],
+          // NO `required` HERE EITHER. It refused a correction that sent only the sections it changed — the save
+          // this description and every repair prompt ask for — before the save code saw the call, and such a
+          // refusal left no call file, only a line in the server's log. The save code still refuses a FIRST
+          // call without the spine or the verdict, by name (`synthesis_spine_missing`, `synthesis_verdict_missing`),
+          // and a patch keeps the held ones.
           properties: {
             spine: { type: "string", description: "The dominant-element spine: what carries these marks and what a register would weigh. The core of the product." },
             verdict: { type: "string", description: "The verdict prose — what the findings together mean for this client." },
@@ -1133,7 +1137,7 @@ serve({
         findings: {
           type: "object",
           description:
-            "The findings document — schema_version, rated_under_framework, findings[], coverage[], ask_answers[] and the other top-level registers. Already typed values; it arrives here instead of being written as a file so the joins below can run, and it is validated through the shipped parser, which names its own defect tokens. " +
+            "The findings document — schema_version, rated_under_framework, findings[], coverage[], ask_answers[] and the other top-level registers. On a first call, send it whole. To correct part of the record, send no `findings[]` list (a finding is corrected through `findings_patch`) and only the registers you changed, each complete, with the \"corrections\" marker when the repair asks for it: every register you do not send is held. A `findings` object that carries a `findings[]` list replaces the whole record; so does one that changes `schema_version` or `rated_under_framework`, which must then carry its list. Already typed values; it arrives here instead of being written as a file so the joins below can run, and it is validated through the shipped parser, which names its own defect tokens. " +
             "TWO OF ITS FIELDS ALSO RENDER INTO THE NARRATIVE, which is why they are here and not on `narrative`: `coverage[]` becomes the readable coverage list (rows are {area, state, note}; `confirmed-clean` ASSERTS a search ran and is joined to this run's plan-execution receipt, so a clean claim over a slice that did not run is refused — name the area as the receipt names the slice, and the honest alternatives are coverage-limited and not-searched), and `ask_answers[]` becomes the labelled answer lines ({ask, answer}: the ask VERBATIM because the driver joins on it, and the ANSWER ALONE starting at its first word — the driver writes the \"- You asked: <ask> → \" label, so an answer that repeats the ask ships the question to the client twice).",
         },
       },
@@ -1165,7 +1169,7 @@ serve({
         chunkSummary: {
           type: "string",
           description:
-            "2–5 sentences covering THIS chunk's marks, as markdown narrative. EVERY chunk emits one: " +
+            "The cross-mark read covering THIS chunk's marks: a short opening line for what the batch as a whole shows, then one \"## <MARK NAME>\" sub-header per mark with its band and the one or two things that drive it, bullets where they help. EVERY chunk emits one: " +
             "the whole-batch executive summary is composed in code by concatenating them, so a chunk " +
             "without one vanishes from the summary a client reads.",
         },
@@ -1207,7 +1211,7 @@ serve({
               registerEstimate: { type: "string" },
               parodyNote: { type: ["string", "null"] },
               crowdedField: { type: "boolean" },
-              purpleNotes: { type: "array", items: { type: "string" }, description: "Internal notes — removed on export, never client-facing." },
+              purpleNotes: { type: "array", items: { type: "string" }, description: "Reviewer notes appear on the report page and are removed on export." },
               // — DECLARED HERE OR IT IS FOLKLORE.
               //
               // Both fields were built end to end for — instructed in the dispatch,
@@ -1409,7 +1413,7 @@ serve({
             inUseAs: { type: "string", description: "The kinds of use off the register that could conflict in this client's field, as one phrase completing \"Is this name already in use as …?\". The places the batch is searched on include the sites where these uses are listed." },
             places: {
               type: "array", items: { type: "string" },
-              description: "The 2 to 4 places every spelling is searched on: \"web\" for the whole web, and the client's stores and the sites where the kinds of use are listed, each a bare host. A host covers its subdomains.",
+              description: "THE PLACES ARE PER NAME (task 2d) and go on each mark, not here.",
             },
             umbrellaBrandNote: { type: "string", description: "A note where an umbrella brand is in play, or omit it." },
             executionOrder: {