clearotron 0.4.1 → 0.5.0-beta.0

package/driver/coverage-form.mjs

@@ -420,6 +420,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 +434,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 ────────────────────────────────────────

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

@@ -203,8 +203,8 @@ export function narrowingOrderLine(job, profile, inScopeClasses = null) {
       `the major markets (${major.join(", ")})`,
     ].filter(Boolean).join(", else ")}`;
   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; `
+    + `still a crowd, then the markets, ${markets}. 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/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: {

package/driver/findings-model.mjs

@@ -1534,7 +1534,7 @@ function validateNetRequired(f, ord, mode) {
   if (f.ruled_out === true) return;                                      // its ground is ruled_out_reason
   if (!POSITION_REQUIRED_DISPOSITIONS.includes(f.disposition)) return;   // withdrawn — see the const's doc block
   if (typeof f.net === "string" && f.net.trim()) return;
-  throw new Error(`finding_net_missing:${ord} (EVERY finding a reader sees carries the one-clause net — it is the ONLY per-finding summary the report has: the card leads with it, the grouped-negative line states it, the MCP brief lists the finding by it. Name the legal risk driver, then the FACT that conditions it. Length is the renderer's problem, not yours)`);
+  throw new Error(`finding_net_missing:${ord} (EVERY finding a reader sees carries the net — it is the ONLY per-finding summary the report has: the card leads with it, the grouped-negative line states it, the MCP brief lists the finding by it.)`);
 }
 
 // ── requirement 2 — the label follows the argument ───────────────────────────────────────────────
@@ -1734,9 +1734,9 @@ export function netChainMarkers(s) {
 function validateNet(f, ord, mode) {
   if (f.net == null) return;   // absent ⇒ v6 has already thrown; below v6 the card falls back as it always did
   if (typeof f.net !== "string" || !f.net.trim())
-    throw new Error(`finding_net_invalid:${ord} (net is the one-clause read — a non-empty string, or omit it)`);
+    throw new Error(`finding_net_invalid:${ord} (net is a non-empty string, or omit it)`);
   if (PRESCRIPTION_RE.test(f.net))
-    throw new Error(`finding_net_prescriptive:${ord} (the one-clause read carries FACTS AND ASSESSMENT, never an action prescription — the reader is a lawyer who layers their own advice on top; state the risk and the fact that conditions it, and let the typed actions register carry what a human must do)`);
+    throw new Error(`finding_net_prescriptive:${ord} (the read carries FACTS AND ASSESSMENT, never an action prescription — the reader is a lawyer who layers their own advice on top; let the typed actions register carry what a human must do)`);
   validateNetShape(f, ord, mode);
   f.net = f.net.trim();
 }
@@ -1805,7 +1805,7 @@ function validateNetShape(f, ord, mode) {
   if (!POSITION_REQUIRED_DISPOSITIONS.includes(f.disposition)) return;   // withdrawn — see above
   const markers = netChainMarkers(f.net);
   if (!markers.length) return;
-  throw new Error(`findings_net_chained:${ord} (the finding sentence is a CONCLUSION, not a chain — this net carries ${markers.join(" and ")}. Answer the one question a reader asks of this finding: is this a problem for me. Name the parties and the territory and state the outcome as a likelihood ("Veltra Labs' registered VELTRA is more likely than not to prevail against VELTRA PHARMA in the United States."). Then MOVE the chain's clauses — territories, the goods paraphrase, the owner's business, status and use history — into legal_position and practical_position, in full: this is a relocation, never a compression, and a net that got shorter because the reasoning got thinner is the wrong fix. There is no length cap)`);
+  throw new Error(`findings_net_chained:${ord} (the finding sentence is a CONCLUSION, not a chain — this net carries ${markers.join(" and ")}. Answer the one question a reader asks of this finding: is this a problem for me. Name the parties and the territory and state the outcome as a likelihood. Then MOVE the chain's clauses — territories, the goods paraphrase, the owner's business, status and use history — into legal_position and practical_position, in full: this is a relocation, never a compression, and a net that got shorter because the reasoning got thinner is the wrong fix.)`);
 }
 
 // The framework's own inputs, where it states a method. A finding with a band is a rated conflict and
@@ -2642,3 +2642,15 @@ export function blankForeignRecordLinks(doc, origins) {
   });
   return { doc: { ...doc, findings }, blanked, kept };
 }
+
+/**
+ * THE TOP-LEVEL KEYS A FINDINGS DOCUMENT OF THIS schema_version MAY CARRY — the ladder the parsers hold it to,
+ * read off the version as they read it. Exported for the synthesis transport, which reads a correction's
+ * list-less findings object as registers only where every key it carries is on the STORED record's own ladder:
+ * a key that ladder does not allow is refused either way, and it must meet the refusal it always met. Derived
+ * from the ladder above, never copied, for the reason FINDING_KEYS_CURRENT is.
+ */
+export function topKeysForVersion(schemaVersion) {
+  const v = typeof schemaVersion === "number" ? schemaVersion : 1;
+  return [...topKeysFor({ v4: v >= 4, v5: v >= 5, v6: v >= 6, v7: v >= 7 })];
+}

package/driver/floor-duty.mjs

@@ -244,6 +244,15 @@ export function floorDutyBlock(artifact, { armed = false } = {}) {
   };
 }
 
+/**
+ * THE FLOOR'S GAP POSITIVELY CLOSED, judged as `floorDutyBlock` judges it: the floor is armed, its account was
+ * computed, and no floor is left undischarged. An account that is absent, unreadable or not computable is no proof
+ * that the gap closed, so it is false here, where `floorDutyBlock` is null for the same account. PURE.
+ */
+export function floorDutyClosed(artifact, { armed = false } = {}) {
+  return armed === true && artifact?.computable === true && !((artifact?.undischarged_by_seat ?? 0) > 0);
+}
+
 export const FLOOR_DUTY_EVENT_FIELDS = ["floors", "accounted", "named_without_ground", "unanswered"];
 
 /** The run.jsonl row. `computable:false` carries its reason and NO counts — a zero here would read as

package/driver/gate-metrics.mjs

@@ -148,6 +148,10 @@ export function scoredFetched(runDir) {
   // un-normalised join here would miss ALL of them, not some — and a total miss reads as a clean
   // `fetched: 0`, which is this metric's alert, not its absence.
   const lines = readJson(join(runDir, "register-hit-list.json"))?.lines;
+  // NOT COMPUTED WHERE THE CODES ARE NOT THERE. The reading step is not asked for fate codes, and a list whose
+  // lines carry none says nothing about what judgment opened: read as a measurement, every scored finding would
+  // count as unfetched, an alarm about nothing. It says it could not be computed instead.
+  if (Array.isArray(lines) && lines.length && !lines.some((l) => l?.fate != null)) return { notComputed: "the hit list carries no fate codes" };
   if (Array.isArray(lines)) {
     // THREE STATES, NOT TWO, and the third is the one an earlier cut of this got wrong. A line the run
     // deliberately did not open (`NOT_PICKED`) leaves the denominator. A line whose fate this file does
@@ -292,7 +296,9 @@ export function computeGateMetrics(runDirs) {
   for (const d of runDirs) {
     const dr = deferralsRendered(d); if (dr) { agg.deferralsRendered.num += dr.rendered; agg.deferralsRendered.den += dr.total; }
     const sk = skepticConsumed(d);  if (sk) { agg.skepticConsumed.num += sk.consumed; agg.skepticConsumed.den += sk.total; }
-    const sf = scoredFetched(d);    if (sf) { agg.scoredFetched.num += sf.fetched;   agg.scoredFetched.den += sf.total; }
+    const sf = scoredFetched(d);
+    if (sf?.notComputed) agg.scoredFetched.notComputed = (agg.scoredFetched.notComputed ?? 0) + 1;
+    else if (sf) { agg.scoredFetched.num += sf.fetched;   agg.scoredFetched.den += sf.total; }
     const ct = clientTierMatch(d);  if (ct) { agg.clientTierMatch.num += ct.match;   agg.clientTierMatch.den += ct.total; }
     const lt = lintFirstPassTax(d); if (lt) { lintTaxRuns++; lintTaxFailures += lt.initialFailures; if (!lt.initialFailures) lintCleanFirstPass++; }
     const dg = documentGrowth(d);   if (dg) { growthRuns++; growthTrips += dg.count; }

package/driver/gateway.mjs

@@ -36,7 +36,7 @@ import { MODEL_FILE as FRAME_DIFF_MODEL_FILE, PROSE_FILE as FRAME_DIFF_PROSE_FIL
 import { MATTER_CONTEXT_FILE } from "./matter-frame-record.mjs";
 import { MODEL_FILE as VARIANT_MODEL_FILE, PROSE_FILE as VARIANT_PROSE_FILE } from "./clearance-variants-record.mjs";
 import { PROSE_FILE as REPORT_OVERVIEW_FILE } from "./report-overview-record.mjs";
-import { NARRATIVE_FILE, FINDINGS_FILE, refusalsFor } from "./synthesis-record.mjs";
+import { NARRATIVE_FILE, FINDINGS_FILE, refusalsFor, synthesisCallPaths } from "./synthesis-record.mjs";
 import { FINDINGS_FILE as REGISTER_FINDINGS_FILE, refusalsFor as registerDigestRefusalsFor } from "./register-digest-record.mjs";
 
 // artifact basename -> the tool that is now its only writer. A repair for one of these is a CALL, never a
@@ -2277,7 +2277,7 @@ export function correctiveMessage(baseMessage, attempt, lastFail, expectFile, {
       `\n\nCORRECTION: ${budget}${requiredFileClause(inner, { names, toolWritten })}`;
   return baseMessage +
     `\n\nCORRECTION: your previous attempt failed file validation (${inner}). ${budget}Re-do the task and make sure ` +
-    `${correctionHint(inner, { gridLedgerName: gridLedgerNameFor(expectFile), supplementalLane, undispatchable: frameDiffUndispatchable(expectFile, inner) })}. ` +
+    `${correctionHint(inner, { gridLedgerName: gridLedgerNameFor(expectFile), supplementalLane, undispatchable: frameDiffUndispatchable(expectFile, inner), heldRecord: heldSynthesisRecord(files) })}. ` +
     requiredFileClause(inner, { names, toolWritten });
 }
 
@@ -2362,7 +2362,22 @@ export function frameDiffUndispatchable(expectFile, lastFail = "framediff_direct
 // clearance writer's.
 const CLEARANCE_FINDINGS_TOKEN_RE = /(?<!knockout_|knockoutassess_)findings?_/;
 
-export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.json", supplementalLane = false, undispatchable = [], toolWritten = null } = {}) {
+// THE WRITER'S RETRY, WHEN THE DRIVER HOLDS ITS RECORD. A save the tool accepted can still fail the stage's own check
+// of the written files, and the driver then holds the record that save left: the retry sends only the change, in the
+// patch the follow-ups above it ask for. A record nobody saved yet, or one whose version is being replaced, still
+// takes the complete save.
+const HELD_RECORD_RETRY = "Fix exactly that in ONE `record_synthesis` PATCH call, sending only the change: `findings_patch` carrying the complete corrected finding object(s), each with the `ordinal` it replaces, and `findings` carrying any register you corrected, complete, and never a `findings[]` list; leave the narrative prose unchanged";
+const VERSION_FAILURE_RE = /finding_legacy_scale_forbidden|schema_version/;
+/**
+ * Does the driver hold an accepted synthesis record for the run these files belong to? Read from either of the files
+ * the writer's call renders: the stage's own expected file is the narrative, and a caller may name the findings.
+ */
+export const heldSynthesisRecord = (files) => {
+  const f = (Array.isArray(files) ? files : [files]).find((x) => typeof x === "string" && [NARRATIVE_FILE, FINDINGS_FILE].includes(basename(x)));
+  return Boolean(f) && existsSync(synthesisCallPaths(dirname(f)).accepted);
+};
+
+export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.json", supplementalLane = false, undispatchable = [], toolWritten = null, heldRecord = false } = {}) {
   // The repair act, for the hints that name one. Kept to a single sentence and a single decision so a
   // new hint has one thing to append rather than a branch to reproduce.
   const resaveClause = toolWritten
@@ -2457,8 +2472,9 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
       `composite/level/dispute_type are RETIRED and forbidden), owner.registrations[] (ONE entry per ` +
       `registration — never overwrite or transpose another's facts; a finding with no fetched record → []), the four ` +
       `meters as {token, basis} (basis = verified-from-record | inferred-from-signal), quadrant {x,y} in [0,1], a ` +
-      `typed source, a disposition, and a unique 1-based ordinal. The failed check was: ${tok}.${extra} Fix exactly that, re-save ` +
-      `the COMPLETE findings.json, and leave the narrative prose unchanged`;
+      `typed source, a disposition, and a unique 1-based ordinal. The failed check was: ${tok}.${extra} ` +
+      (heldRecord && !VERSION_FAILURE_RE.test(lastFail) ? HELD_RECORD_RETRY
+        : `Fix exactly that, re-save the COMPLETE findings.json, and leave the narrative prose unchanged`);
   } else if (/coverage_status_offenum/.test(lastFail)) {
     // D1 — the off-enum PROSE Status cell (distinct from coverage_status_invalid, which is the JSON
     // mirror's token): the defect lives in register-findings.md's own Coverage-ledger table, so the
@@ -2827,8 +2843,7 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
       ? diagnosis +
         `On this run the TOOLS own every band block: if the collapsed slice belongs to a DICTATED plan entry ` +
         `(it carries a qid from the frozen plan), close it by calling register_execute_plan ONCE with the exact ` +
-        `{"plan_path", "axis", "output_path"} from your stage instructions — that is the tool's whole call form ` +
-        `(it takes no per-qid argument); it re-runs this axis's dictated entries and refreshes their blocks, ` +
+        `{"plan_path", "axis", "output_path"} from your stage instructions; it re-runs this axis's dictated entries and refreshes their blocks, ` +
         `qid-stamped. If the collapsed slice ` +
         `was a judgment addition, RE-PROPOSE that EXACT slice through register_propose_supplemental with the same ` +
         `predicate, term(s), nice_classes and regions — the tool re-executes it and merges the corrected block ` +
@@ -2878,9 +2893,8 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
       `the bridge killed it, so the band was never written. This is NOT a missing-structure defect and ` +
       `NOT something you did wrong. Call register_execute_plan ONCE more with the exact ` +
       `{"plan_path", "axis", "output_path"} from your stage instructions. If it is killed again, do ` +
-      `NOT author band blocks by hand and do NOT narrate coverage you did not get — record the timeout ` +
-      `in your .md, state the scope you attempted, and flag CROSS-CHECK REQUIRED. That note is the ` +
-      `correct answer to a tool that will not return, and it is what the reader needs`;
+      `NOT author band blocks by hand and do NOT narrate coverage you did not get — the driver's own call ` +
+      `log records that the call never returned`;
   } else if (/named_band_missing/.test(lastFail)) {
     // 2026-07-14 (copper-keystone): the unit's .md narrated success but the band file was NEVER WRITTEN —
     // the model skipped its one register_execute_plan call and fabricated the narrative. Unlike the
@@ -3516,7 +3530,7 @@ export function warmPatchMessage(lastFail, expectFile, { supplementalLane = fals
     const band = join(dirname(files[0]), basename(files[0]).replace(/\.md$/i, "-band.json"));
     return `You are RESUMING your own session for this stage — your prior work and inputs are already in your context. Do NOT redo your digest prose (${names} already passed validation).\n` +
       `Your register tool call WAS MADE and never returned — it was still running when the bridge killed it, so ${band} was never written. Nothing about your turn was wrong. Call register_execute_plan ONCE more with the exact {"plan_path", "axis", "output_path"} from your original stage instructions (output_path = ${band}), then stop.\n` +
-      `If it is killed again: do NOT author band blocks by hand and do NOT narrate coverage you did not obtain. Record the timeout in your .md, state the scope you attempted, and flag CROSS-CHECK REQUIRED. That is the correct answer to a tool that will not return.`;
+      `If it is killed again: do NOT author band blocks by hand and do NOT narrate coverage you did not obtain. The driver's own call log records that the call never returned.`;
   }
   // Sibling-JSON defects (WS-A coverage mirror / common-law grid): the FINDINGS file already passed
   // its prose checks — telling the model to rewrite it "in full" on a patch turn risks degrading
@@ -3616,7 +3630,7 @@ export function warmPatchMessage(lastFail, expectFile, { supplementalLane = fals
       ? `Do NOT redo the work from scratch. This stage's own output is the driver's — it is rendered from your \`${outIsToolWritten.tool}\` call and you hold no tool that writes it, so there is nothing there for you to rewrite or protect.`
       : `Do NOT redo the work from scratch, and do NOT rewrite ${names || "the findings file"} (it already passed validation).`;
     return `You are RESUMING your own session for this stage — your prior work and inputs are already in your context. ${standsClause}\n` +
-      `Your saved ${sibling} failed validation (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { gridLedgerName: gridLedgerNameFor(files), supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail) })}.\n` +
+      `Your saved ${sibling} failed validation (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { gridLedgerName: gridLedgerNameFor(files), supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail), heldRecord: heldSynthesisRecord(files) })}.\n` +
       `Re-save the COMPLETE corrected JSON at ${sib}. Do not stop until it exists and is valid.`;
   }
   // — A BLIND-FRAME REPAIR IS A TOOL CALL, NOT A FILE WRITE, and this branch is what stops the two
@@ -3668,7 +3682,7 @@ export function warmPatchMessage(lastFail, expectFile, { supplementalLane = fals
         // DIRECTIVES again, which is the 2026-07-29 reopen loss. Caught by frame-diff-model.test.mjs's
         // cardinality pin, which asserts the warm path carries the full list without the caller passing
         // anything.
-        : `What you sent did not pass (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail), toolWritten: toolWritten.tool })}.\n`) +
+        : `What you sent did not pass (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail), toolWritten: toolWritten.tool, heldRecord: heldSynthesisRecord(files) })}.\n`) +
       `Call \`${toolWritten.tool}\` with the values from the work already in your context — never by writing or editing any file. ` +
       `Do not stop until the tool accepts the call.`;
   }
@@ -3688,7 +3702,7 @@ export function warmPatchMessage(lastFail, expectFile, { supplementalLane = fals
   }
   const defective = failingTarget(lastFail, files) ?? files[0] ?? null;
   return `You are RESUMING your own session for this stage — your prior work and inputs are already in your context. Do NOT redo the work from scratch.\n` +
-    `Your saved ${defective ? rel(defective) : names || "output"} failed validation (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { gridLedgerName: gridLedgerNameFor(files), supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail) })}.\n` +
+    `Your saved ${defective ? rel(defective) : names || "output"} failed validation (${lastFail}). Fix exactly this: ensure ${correctionHint(lastFail, { gridLedgerName: gridLedgerNameFor(files), supplementalLane, undispatchable: frameDiffUndispatchable(files, lastFail), heldRecord: heldSynthesisRecord(files) })}.\n` +
     editRepairTail(defective || names || "the stage output");
 }