clearotron 0.4.1-beta.4 → 0.4.1-beta.6

package/driver/clearance-variants-record.mjs

@@ -151,6 +151,7 @@ export function renderClearanceVariants(model, scopeRows) {
   // The prose copy restates exactly what the structured sibling holds — a reader of the manifest must
   // be able to see which words the register search was narrowed to without opening the JSON.
   if (model.goods_words?.length) out.push("### Goods words the register search is narrowed to", "", ...model.goods_words.map((w) => `- ${w}`), "");
+  if (model.product_words?.length) out.push("### The client's product words", "", ...model.product_words.map((w) => `- ${w}`), "");
   // — the search floor, on the human surface because a reader auditing the run has to see what was
   // obliged as well as what was done. Rendered ONLY when designated: an empty section would read as a
   // floor of nothing rather than as no floor, and those are the two states this mechanism must keep apart.
@@ -178,7 +179,7 @@ export function renderClearanceVariants(model, scopeRows) {
  */
 /** The shape this tool declares, at every depth — what the ACCEPTOR enforces. */
 const DECLARED = Object.freeze({
-  "": ["mark", "dominant_element", "elements", "variants", "incumbent_classes", "search_floor", "watchlist_owners", "goods_words", "scope_ledger"],
+  "": ["mark", "dominant_element", "elements", "variants", "incumbent_classes", "search_floor", "watchlist_owners", "goods_words", "product_words", "scope_ledger"],
   elements: ["value", "kind", "famous_mark_flag"],
   variants: ["value", "category", "rationale", "romanization"],
   scope_ledger: ["layer", "item", "status", "reason", "reopen_trigger"],
@@ -218,6 +219,7 @@ export function mergeClearanceVariantsCall(stored, received) {
     // correct one part, and a seat that sends only that part, would otherwise delete the goods words
     // — and the loss reads as "this matter has none" rather than as a partial call.
     goods_words: keepIfAbsent(received?.goods_words, base.goods_words),
+    product_words: keepIfAbsent(received?.product_words, base.product_words),
   };
 }
 
@@ -234,6 +236,8 @@ export function acceptClearanceVariants(params) {
     // back a key nothing in this chain declares: the tool's schema offers the slot, and this is what
     // moves the answer from the call into the manifest the compiler reads.
     goods_words: params?.goods_words,
+    // — the client's product words, the particular goods the band shape groups on (ruled 2026-10-12).
+    product_words: params?.product_words,
     // — the search-floor axes. Validated by the model parser (closed against REGISTER_AXES), not
     // here, so there is ONE definition of what a floor may name.
     search_floor: params?.search_floor,

package/driver/close-verify.mjs

@@ -59,6 +59,18 @@ export function blockCollapsed(block) {
   return state === "enumerated" && Number.isFinite(total) && total > 0 && recs === 0;
 }
 
+/**
+ * The plan row that answers a minted slice: the slice itself, or, where the fold refused it as already-asked, the
+ * row it duplicates. Such a slice is never frozen into the plan and never runs; its question was asked by the twin.
+ * ONLY THE DUPLICATE KIND RESOLVES: an identity collision or a malformed term asked a question nothing else asked.
+ * `foldRefusals` maps a refused qid to `{kind, twin}`, as `foldSupplementalEntries` records it. One rule for the
+ * directive below and the remedy term ledger (remedy-accounting.mjs), so the two cannot read a slice apart. PURE.
+ */
+export function answeredAs(qid, foldRefusals) {
+  const r = foldRefusals?.get?.(qid);
+  return r && r.kind === "duplicate-question" && r.twin ? String(r.twin) : qid;
+}
+
 /**
  * Verify a register frame-reopen directive was actually SEARCHED as intended (Part B, arm #1). A directive
  * is closed ONLY if EVERY minted qid clears three checks:
@@ -70,22 +82,29 @@ export function blockCollapsed(block) {
  *      wrong-scope 0/0). Indeterminate pins fall through to 1+2 — a strict tightening over byte-diff, never
  *      a new false deferral.
  * PURE. `executedQids` is a Set of joinPlanToBands.executed qids; `blocksByQid` maps qid → band block.
- * @returns {{closed: boolean, reason: string|null}}
+ *
+ * A slice the fold refused as already-asked is checked on the row that answered it (`answeredAs`), on the same
+ * three checks, and a directive closed that way names each such row in `answered_by`.
+ * @returns {{closed: boolean, reason: string|null, answered_by?: {qid: string, twin: string}[]}}
  */
-export function verifyRegisterDirectiveClose({ qids, intendedClasses = [], executedQids, blocksByQid } = {}) {
+export function verifyRegisterDirectiveClose({ qids, intendedClasses = [], executedQids, blocksByQid, foldRefusals = new Map() } = {}) {
   const list = qids ?? [];
   if (!list.length) return { closed: false, reason: "no-slice-dispatched" };
   const want = [...new Set((intendedClasses ?? []).map(String))];
   const executed = executedQids ?? new Set();
   const byQid = blocksByQid ?? new Map();
+  const answeredBy = [];
   for (const qid of list) {
-    if (!executed.has(qid)) return { closed: false, reason: `slice-not-landed:${qid}` };
-    const b = byQid.get(qid);
-    if (!b) return { closed: false, reason: `no-band-block:${qid}` };
-    if (blockCollapsed(b)) return { closed: false, reason: `collapsed-slice:${qid}` };
+    const q = answeredAs(qid, foldRefusals);
+    const as = q === qid ? qid : `${qid} (answered by ${q})`;
+    if (!executed.has(q)) return { closed: false, reason: `slice-not-landed:${as}` };
+    const b = byQid.get(q);
+    if (!b) return { closed: false, reason: `no-band-block:${as}` };
+    if (blockCollapsed(b)) return { closed: false, reason: `collapsed-slice:${as}` };
     const searched = blockSearchedClasses(b);
     if (want.length && searched.length && !want.every((c) => searched.includes(c)))
-      return { closed: false, reason: `wrong-scope:${qid} searched[${searched.join(",")}]⊉intended[${want.join(",")}]` };
+      return { closed: false, reason: `wrong-scope:${as} searched[${searched.join(",")}]⊉intended[${want.join(",")}]` };
+    if (q !== qid) answeredBy.push({ qid, twin: q });
   }
-  return { closed: true, reason: null };
+  return { closed: true, reason: null, ...(answeredBy.length ? { answered_by: answeredBy } : {}) };
 }

package/driver/contract-vocabulary.mjs

@@ -213,6 +213,8 @@ export const VOCABULARY = [
   { token: "placement_unjudged", stages: ["placement-inquiry"], site: "driver/verify.mjs placementAccountVerdict" },
   { token: "placement_register_unrendered", stages: ["placement-inquiry"], site: "driver/verify.mjs placementAccountVerdict" },
   { token: "placement_form_unreadable", stages: ["placement-inquiry"], site: "driver/verify.mjs placementAccountVerdict" },
+  { token: "placement_floors_without_fate", stages: ["placement-inquiry"], site: "driver/verify.mjs placementSaidBackVerdict" },
+  { token: "placement_refused", stages: ["placement-inquiry"], site: "driver/verify.mjs placementSaidBackVerdict" },
   { token: "placement", stages: ["placement-inquiry"], site: "driver/verify.mjs validators.placement → checkSiblingJson → checkJson", family: "driver/placement-model.mjs (`placement_*` and `placements_*`)", dynamic: "D3" },
 
   // ── case-law / narrative-refutation ────────────────────────────────────────────────────────────────

package/driver/degraded-parts.mjs

@@ -131,6 +131,9 @@ const stageEnded = (runDir, stage) => {
 
 // The register's own steps, each of which the run survives without: the band's shape (the floors and the
 // full cards read it), the mechanical form floor, the owner screen, and the digest's folding in of re-runs.
+// And the dominant-element crowd the blind frame comparison flagged and the reopen pass did not close: the
+// clamp keeps that reason on the run record alone (ruled 2026-10-13), so the audit records the part here,
+// read from the reopen's receipt as delivery found it.
 function register(runDir, log) {
   const part = { part: "register", name: PART_NAMES.register, reason: NOT_COMPLETED };
   const steps = [
@@ -140,6 +143,10 @@ function register(runDir, log) {
     ["digest-flush", "digest-flush-failed", "the digest flush"],
   ];
   const failed = steps.map(([ok, bad, what]) => [failedStep(log, ok, bad), what]).filter(([e]) => e);
+  let reopen = null;
+  try { reopen = JSON.parse(readFileSync(driverDir(runDir, "frame-reopen.json"), "utf8")); } catch { reopen = null; }
+  if (reopen?.dominant_element_gap === true && reopen?.domClosed !== true)
+    failed.push([{ fail: "the omission the blind frame comparison flagged was not closed by the reopen pass" }, "the dominant-element crowd"]);
   if (!failed.length) return null;
   return { ...part, cause: failed.map(([e, what]) => `${what}: ${e.fail ?? e.reason ?? e.event}`).join("; ") };
 }

package/driver/effective-scope.mjs

@@ -34,7 +34,7 @@
 // those origins rather than re-deriving them, so it cannot disagree about which layer supplied a value.
 
 import { withRunPlatforms, derivedFloor } from "./profiles.mjs";
-import { recognizedTerritories } from "./territory-tiers.mjs";   // — a staff free-text field must not reach a prompt unchecked
+import { recognizedTerritories, territoryKey } from "./territory-tiers.mjs";   // — a staff free-text field must not reach a prompt unchecked
 
 /**
  * Human-readable provenance, shown to clients.
@@ -163,6 +163,32 @@ export function narrowingMarkets(job, profile) {
   return { scope: [], priorities: defaultTerritoryState(profile).kept, major: [...MAJOR_MARKETS] };
 }
 
+/**
+ * THE CLIENT'S MARKETS, as the band shape sorts by them (840 decision 7): the account's default markets,
+ * else the major markets, plus every market the order names. Codes as the territory vocabulary writes
+ * them, compared with a record's own jurisdictions. PURE.
+ */
+export function clientMarkets(job, profile) {
+  // A sort key, not a scope: an order the ladder cannot read leaves the sort without markets rather than
+  // the band without a shape.
+  try {
+    const { scope } = narrowingMarkets(job, profile);
+    const defaults = defaultTerritoryState(profile).kept;
+    return [...new Set([...scope, ...(defaults.length ? defaults : MAJOR_MARKETS)].map((t) => territoryKey(t)).filter(Boolean))];
+  } catch { return []; }
+}
+
+/**
+ * THE ORDER'S TERRITORIES, as the band shape scopes its lists (ruled 2026-10-12): the countries a
+ * territorial order names, or the account's defaults filling an absent one; empty for a worldwide order.
+ * A ladder that cannot read the order leaves the lists unscoped rather than the band without a shape. PURE.
+ */
+export function orderTerritories(job, profile) {
+  // Folded as the territory vocabulary folds them: an order that names "Switzerland" is CH, never a name
+  // that matches no register.
+  try { return [...new Set(narrowingMarkets(job, profile).scope.map((t) => territoryKey(t)).filter(Boolean))]; } catch { return []; }
+}
+
 /**
  * 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.

package/driver/engine/anthropic-agent.mjs

@@ -16,6 +16,7 @@
 // watchdog heartbeat (--include-partial-messages).
 
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
@@ -594,6 +595,9 @@ export const anthropicAgentEngine = {
       child.stdin.on("error", () => {});
       try { child.stdin.write(input); child.stdin.end(); } catch { /* child gone — handled by close/error */ }
       let buf = "", stderr = "", resultEvent = null, killed = false, stallKill = false, settled = false;
+      // A CHUNK IS NOT A CHARACTER: a character split across two chunks of a pipe is held by its stream's decoder
+      // until the rest arrives (common.mjs `runStreamingChild` says why). The raw sink still takes the bytes.
+      const outText = new StringDecoder("utf8"), errText = new StringDecoder("utf8");
       let noProgressKill = false;               // the no-progress ceiling fired (a stall discriminator, see noProgressMs)
       let trickleKill = false;                  // the token-rate floor fired (a stall discriminator, see minTokensPerSec)
       let overflow = false;                     // A3: stdout/stderr exceeded maxBuffer — force a nonzero fail, never parse the truncated tail
@@ -1091,7 +1095,7 @@ export const anthropicAgentEngine = {
         prevChunkAt = Date.now();
         lastMove = Date.now();   // ANY streamed byte = liveness → resets the stall clock
         sink.write(d);           // the raw stream, byte for byte, before anything parses it
-        buf += d.toString();
+        buf += outText.write(d);
         let nl;
         while ((nl = buf.indexOf("\n")) >= 0) { parseLine(buf.slice(0, nl)); buf = buf.slice(nl + 1); }
         if (buf.length > maxBuffer) { buf = buf.slice(0, maxBuffer); overflowKill(); }
@@ -1109,7 +1113,7 @@ export const anthropicAgentEngine = {
         // The diagnostic follows the same rule deliberately. `firstByteMs=NEVER` now means "never spoke
         // its protocol", which is the question the no-progress specimen is actually asking — a number
         // that came from a stderr line would have answered a different one.
-        stderr += d.toString();
+        stderr += errText.write(d);
         if (stderr.length > maxBuffer) { stderr = stderr.slice(0, maxBuffer); overflowKill(); }
       });
       // error + close can BOTH fire for a single failure (Node) → settle EXACTLY once (no double clearInterval/resolve).
@@ -1125,7 +1129,7 @@ export const anthropicAgentEngine = {
         // settlement must never wait on a pipe some straggler keeps open (the group SIGKILL reaps the tree).
         try { child.stdout.destroy(); } catch { /* stream gone */ }
         try { child.stderr.destroy(); } catch { /* stream gone */ }
-        if (!overflow) { parseLine(buf); }   // B1: flush the final, un-terminated line (the result event) — but NEVER the truncated overflow tail
+        if (!overflow) { buf += outText.end(); stderr += errText.end(); parseLine(buf); }   // B1: flush the final, un-terminated line (the result event) — but NEVER the truncated overflow tail
         const stream = sink.close();   // after the flush: every byte the program wrote is in it, or the record says why not
         buf = "";
         // ONE SAMPLE OF THE CLOCK, and both quantities below are derived from it. Two `Date.now()` calls

package/driver/engine/common.mjs

@@ -19,6 +19,7 @@
 // the engines it serves.
 
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { recordEngineChild, clearEngineChild } from "./child-record.mjs";   //
@@ -190,6 +191,10 @@ export function runStreamingChild({
     try { child.stdin.write(input ?? ""); child.stdin.end(); } catch { /* child gone — handled by close/error */ }
 
     let buf = "", stdoutAll = "", stderr = "";
+    // A CHUNK IS NOT A CHARACTER. A pipe hands the output over in chunks, and a character of two or more bytes can
+    // straddle two of them: decoded one chunk at a time, its halves read as replacement characters. One decoder per
+    // stream holds a split character's first bytes until the rest arrive.
+    const outText = new StringDecoder("utf8"), errText = new StringDecoder("utf8");
     let killed = false, stallKill = false, overflow = false, settled = false;
     let lastMove = Date.now();
     // — false until the child's FIRST byte on EITHER stream. Not "first liveness byte": a
@@ -248,7 +253,7 @@ export function runStreamingChild({
       if (settled || overflow) return;
       sawOutput = true; firstOutputAt ||= Date.now();        // — the child has spoken; startup is over
       lastMove = Date.now();   // ANY streamed byte = liveness → resets the stall clock
-      const s = d.toString();
+      const s = outText.write(d);
       buf += s; stdoutAll += s;
       let nl;
       while ((nl = buf.indexOf("\n")) >= 0) { emitLine(buf.slice(0, nl)); buf = buf.slice(nl + 1); }
@@ -258,7 +263,7 @@ export function runStreamingChild({
       if (settled || overflow) return;
       sawOutput = true; firstOutputAt ||= Date.now();        // — spoken is spoken, whether or not this stream counts as liveness
       if (stderrIsLiveness) lastMove = Date.now();   // codex progress lives on stderr → it is liveness too
-      stderr += d.toString();
+      stderr += errText.write(d);
       if (stderr.length > maxBuffer) { stderr = stderr.slice(0, maxBuffer); overflowKill(); }
     });
 
@@ -282,7 +287,9 @@ export function runStreamingChild({
       // settlement must never wait on a pipe some straggler keeps open (the group SIGKILL reaps the tree).
       try { child.stdout.destroy(); } catch { /* stream gone */ }
       try { child.stderr.destroy(); } catch { /* stream gone */ }
-      if (!overflow) emitLine(buf);   // B1: flush the final, un-terminated line — but NEVER the truncated overflow tail
+      // B1: flush the final, un-terminated line — but NEVER the truncated overflow tail. The decoders give up
+      // what they held: a character the program never finished reads as a replacement character, once.
+      if (!overflow) { const tail = outText.end(); buf += tail; stdoutAll += tail; stderr += errText.end(); emitLine(buf); }
       buf = "";
       resolve({
         rawCode: typeof code === "number" ? code : null,

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

@@ -20,10 +20,11 @@ import { readFileSync, readdirSync, appendFileSync, existsSync, mkdirSync } from
 import { join, dirname } from "node:path";
 import { driverDir } from "../../../shared/driver-dir.mjs";   //
 import { serve } from "./stdio-server.mjs";
-import { answerBudget } from "../../../shared/answer-parts.mjs";
-import { classifyRecord, prepareTargets, SHAPE_TIERS, isLiveRecord } from "../../band-shape.mjs";
+import { answerBudget, quotedBytes } from "../../../shared/answer-parts.mjs";
+import { classifyRecord, prepareTargets, SHAPE_TIERS, isLiveRecord, niceClassKey, PLACEMENT_GROUP_ORDERS } 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";
 
 const RUN_DIR = process.env.CLEAROTRON_BAND_RUN_DIR || "";
 const SESSION = process.env.CLEAROTRON_GATHER_SESSION_KEY || "";
@@ -107,7 +108,8 @@ const SHAPE_PART_CHARS = 70000;   // step 3 — was a knob; no environment ever
 // band_lookup of 100 fat records or a pathological official record could exceed the engine's
 // per-tool-output token cap and error the call — killing the reading path exactly where the record
 // volume is highest. band_lookup TRIMS records (the full match count always survives, with an
-// honest note); band_record serves PARTS like band_shape (a record is a document — never trimmed).
+// honest note); band_record serves PARTS like band_shape (a record is a document — never trimmed of anything it
+// says; a goods list it says twice is served once, at `recordAsServed`).
 // Given an answer size and no band size of its own, the band answers in five sixths of it: the rest is room
 // for the quotes and line breaks a printout adds (up to 13% on band answers) and for a banner, so a band
 // answer is never split a second time (shared/answer-parts.mjs). 37,500 on Claude, 30,000 on codex.
@@ -122,15 +124,27 @@ const RESPONSE_CHARS = Math.max(4096, Number(process.env.CLEAROTRON_BAND_RESPONS
 // so a larger answer size cannot push a part past Claude's limit; with no size set, nothing changes.
 const SHAPE_PART_SERVED = Math.min(SHAPE_PART_CHARS, RESPONSE_CHARS);
 
-/** Split text into parts of ≤ budget chars, cutting only at line boundaries (an over-budget single
- *  line still ships whole — never cut mid-line). Concatenating the parts with "\n" restores the
- *  input byte-for-byte. */
+// The answer size is in bytes, counted as a quoted string (shared/answer-parts.mjs), and characters are not
+// bytes: a page of marks and owners in a script of three bytes a character, trimmed to the character size,
+// came to about three times the answer size and was split a second time. So every answer and every part is
+// held to the bytes as well, with room in a part for its banner. Latin text meets the character size first,
+// so it is served as before.
+const RESPONSE_BYTES = answerBudget();
+const PART_ROOM = 512;
+const fits = (text) => text.length <= RESPONSE_CHARS && (!RESPONSE_BYTES || quotedBytes(text) <= RESPONSE_BYTES);
+
+/** Split text into parts of ≤ budget chars and, given an answer size, ≤ its bytes less a banner's room,
+ *  cutting only at line boundaries (an over-budget single line still ships whole — never cut mid-line).
+ *  Concatenating the parts with "\n" restores the input byte-for-byte. */
 function splitAtLines(text, budget) {
+  const bytes = RESPONSE_BYTES ? RESPONSE_BYTES - PART_ROOM : Infinity;
   const parts = [];
-  let cur = null;
+  let cur = null, curBytes = 0;
   for (const line of String(text).split("\n")) {
-    if (cur !== null && cur.length + 1 + line.length > budget) { parts.push(cur); cur = line; }
-    else cur = cur === null ? line : cur + "\n" + line;
+    const lineBytes = RESPONSE_BYTES ? quotedBytes(line) : 0;
+    if (cur !== null && (cur.length + 1 + line.length > budget || curBytes + 2 + lineBytes > bytes)) { parts.push(cur); cur = line; curBytes = lineBytes; }
+    else if (cur === null) { cur = line; curBytes = lineBytes; }
+    else { cur += "\n" + line; curBytes += 2 + lineBytes; }
   }
   parts.push(cur ?? "");
   return parts;
@@ -224,35 +238,119 @@ function resolveRecordFile(dir, uri) {
   return { miss: "not-fetched", files };
 }
 
+// WHAT A PART OF THE SHAPE HOLDS. A group's row is checked against the lines the step READ, so each md part
+// served logs the listed lines printed in it, found through the md line the shape's data records for each
+// (`md_lines`), and which parts hold each group, so a refusal can name the parts left unread. The json form
+// is the machine shape: reading it serves no line. A shape with no recorded lines logs none.
+function linesByPart(parts) {
+  let shape = null;
+  try { shape = loadJson(shapeJsonPath()); } catch { shape = null; }
+  const at = shape?.md_lines && typeof shape.md_lines === "object" ? shape.md_lines : {};
+  const ends = [];
+  let line = 0;
+  for (const p of parts) { line += p.split("\n").length; ends.push(line - 1); }
+  const partOf = (n) => ends.findIndex((end) => n <= end);
+  const keys = parts.map(() => []);
+  for (const [key, n] of Object.entries(at)) { const i = partOf(n); if (i >= 0) keys[i].push(key); }
+  const groupParts = {};
+  for (const g of ["a", "b", "c", "d", "rest", "no_goods"]) {
+    const ps = new Set((shape?.groups?.[g]?.list ?? []).map((l) => at[l.key]).filter((n) => n != null).map((n) => partOf(n) + 1));
+    if (ps.size) groupParts[g] = [...ps].sort((x, y) => x - y);
+  }
+  return { keys, groupParts };
+}
+
 function bandShape(params) {
   const format = params?.format === "json" ? "json" : "md";
   const p = format === "json" ? shapeJsonPath() : shapeMdPath();
   if (!RUN_DIR) { logRead("band_shape", { format }, { ok: false }); return { isError: true, text: "ERROR: CLEAROTRON_BAND_RUN_DIR not set — band tools are wired per run by the driver." }; }
   if (!existsSync(p)) { logRead("band_shape", { format }, { ok: false }); return { isError: true, text: `ERROR: ${p} not found — the driver derives it after the register fan-in; if the band exists but the shape does not, report this as a driver defect (do NOT slice the raw band instead).` }; }
-  const text = readFileSync(p, "utf8");
+  const text = format === "md" && !GROUP_PAGES ? withoutPlacementOrders(readFileSync(p, "utf8")) : readFileSync(p, "utf8");
   const parts = splitAtLines(text, SHAPE_PART_SERVED);
   const total = parts.length;
+  const read = format === "md" ? linesByPart(parts) : null;
   if (total === 1) {                                    // the common case — served verbatim, no banner
-    logRead("band_shape", { format }, { ok: true, bytes: text.length });
+    logRead("band_shape", { format }, { ok: true, bytes: text.length, ...(read ? { part: 1, parts: 1, served_lines: read.keys[0], group_parts: read.groupParts } : {}) });
     return text;
   }
   const part = Math.min(Math.max(1, Math.floor(Number(params?.part)) || 1), total);
-  logRead("band_shape", { format, part, parts: total }, { ok: true, bytes: parts[part - 1].length, total_bytes: text.length });
-  const head = `[band_shape part ${part}/${total} — this shape exceeds one tool response, so it is served in ${total} parts` +
-    ` split at line boundaries (every floor row is intact). The shape is COMPLETE only once ALL ${total} parts are read` +
-    `${format === "json" ? "; concatenate the parts before parsing the JSON" : ""} — never reason from a partial shape.]`;
+  logRead("band_shape", { format, part, parts: total }, { ok: true, bytes: parts[part - 1].length, total_bytes: text.length,
+    ...(read ? { served_lines: read.keys[part - 1], group_parts: read.groupParts } : {}) });
+  const head = format === "json"
+    ? `[band_shape part ${part}/${total} of the json; concatenate the parts before parsing it.]`
+    : `[band_shape part ${part}/${total}. Read each group by the size sentence at its head; the next part continues the groups.]`;
   const tail = part < total
     ? `\n[end of part ${part}/${total} — call band_shape again with {"part": ${part + 1}} for the next part]`
-    : `\n[end of part ${total}/${total} — the shape is complete once parts 1..${total} are all read]`;
+    : `\n[end of the shape]`;
   return head + "\n" + parts[part - 1] + tail;
 }
 
+// THE GOODS ON THE ROW, AS THE SHAPE TESTS THEM. Each record served carries the goods words its goods
+// hold, "k of N: the words", tested on the same words and stems the shape grouped on (its `goods_test`),
+// from the records the register already logged to this run (record-goods.mjs). The goods text is one
+// `band_record` away; a row never carries it. A record whose goods cannot be read says so with null.
+let goodsCache = null;
+const goodsIndex = () => (goodsCache ??= bandGoodsIndex(RUN_DIR));
+let testCache = null;
+const shapeGoodsTest = () => {
+  if (testCache) return testCache;
+  let words = [];
+  try { words = loadJson(shapeJsonPath()).groups?.goods_test?.words ?? []; } catch { words = []; }
+  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)
+  ?? (typeof r?.goods === "string" && r.goods.trim() ? [{ classes: [], text: r.goods.trim(), ...(untaggedIsEnglish(r?.record_id) ? {} : { en: false }) }] : null);
+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(", ")}` : ""}` };
+};
+
+// A GROUP, PAGED AS THE SHAPE LISTS IT. The shape lists a group of a thousand records or more by its first
+// page; the rest of its lines are served here, one compact line per mark of an owner, in the group's own
+// order. A group's row is refused until every line was read (placement-union.mjs), so the step can always
+// reach every line it is asked to answer for. Each answer logs the lines it served.
+const GROUP_LINE_LIMIT = 200;
+function groupLookup(params) {
+  const g = String(params.group ?? "").trim().toLowerCase();
+  let groups;
+  try { groups = loadJson(shapeJsonPath()).groups; } catch { groups = null; }
+  if (!groups?.[g]?.list) { logRead("band_lookup", params, { ok: false, reason: "no-group" }); return { isError: true, text: `ERROR: the band shape lists no group "${g}" — one of a, b, c, d, rest, no_goods.` }; }
+  const lines = groups[g].list;
+  const total = groups.goods_words_total || 0;
+  const limit = Math.max(1, Math.min(Number(params.limit) || GROUP_LINE_LIMIT, GROUP_LINE_LIMIT));
+  const offset = Math.max(0, Math.floor(Number(params.offset) || 0));
+  const page = lines.slice(offset, offset + limit).map((l) => ({
+    mark: l.mark, owner: l.owner_name, classes: l.classes, live: `${l.live} of ${l.records}`, territories: l.territories,
+    goods_words: l.goods_words == null ? null : `${l.goods_words.length} of ${total}${l.goods_words.length ? `: ${l.goods_words.join(", ")}` : ""}`,
+    ...(l.goods_words == null && l.goods_on_file != null ? { goods_on_file: l.goods_on_file } : {}),
+    floor: l.floors > 0, record: l.record_id, _key: l.key,
+  }));
+  const body = () => JSON.stringify({
+    group: g, lines_total: lines.length, returned: page.length, ...(offset ? { offset } : {}),
+    ...(lines.length > offset + page.length ? { next_offset: offset + page.length,
+      note: `call again with offset: ${offset + page.length} for the next lines of group ${g}` } : {}),
+    lines: page.map(({ _key, ...l }) => l),
+  }, null, 2);
+  let out = body();
+  while (!fits(out) && page.length > 1) { page.pop(); out = body(); }
+  logRead("band_lookup", params, { ok: true, group: g, returned: page.length, served_lines: page.map((l) => l._key) });
+  return out;
+}
+
 function bandLookup(params = {}) {
   if (!RUN_DIR) return { isError: true, text: "ERROR: CLEAROTRON_BAND_RUN_DIR not set — band tools are wired per run by the driver." };
+  if (params.group != null && String(params.group).trim()) return groupLookup(params);
   if (!existsSync(bandPath())) { logRead("band_lookup", params, { ok: false }); return { isError: true, text: "ERROR: register-named-band.json not found in this run — the band has not been merged yet." }; }
   let band;
   try { band = loadJson(bandPath()); } catch (e) { logRead("band_lookup", params, { ok: false }); return { isError: true, text: `ERROR: band unreadable (${e.message}) — a driver-side defect; report it, never hand-repair the band.` }; }
-  const { record_id, owner, nice_class, tier, qid, query, text, status, live_only = false } = params;
+  const { record_id, owner, nice_class, tier, qid, query, text, status, live_only = false, goods } = params;
+  // Words, as a list or one string. A record whose goods the run does not hold passes: unknown is not a mismatch.
+  const goodsWords = (Array.isArray(goods) ? goods : goods == null ? [] : [goods]).map((w) => String(w ?? "").trim()).filter(Boolean);
+  const goodsCount = goodsWords.length ? goodsWordCounter(goodsWords, { stems: true }) : null;   // the shape's own matcher
   const limit = Math.max(1, Math.min(Number(params.limit) || 20, 100));
   // PAGING. A large band is read page by page from `offset`, in the band's own order, and a capped answer
   // names the next offset. Without it the only way to see every record was to slice the band by owner or
@@ -275,8 +373,8 @@ function bandLookup(params = {}) {
     if (record_id && norm(r?.record_id) !== norm(record_id)) continue;
     if (owner && !norm(r?.owner_name).includes(norm(owner))) continue;
     if (nice_class != null) {
-      const cls = (Array.isArray(r?.classes) ? r.classes : [r?.classes]).map((c) => String(c ?? "").trim());
-      if (!cls.includes(String(nice_class).trim())) continue;
+      const cls = (Array.isArray(r?.classes) ? r.classes : [r?.classes]).map(niceClassKey);   // "09" is class 9
+      if (!cls.includes(niceClassKey(nice_class))) continue;
     }
     if (status && !norm(r?.status ?? r?.screen?.status).includes(norm(status))) continue;
     if (live_only === true && !isLiveRecord(r)) continue;
@@ -288,8 +386,9 @@ function bandLookup(params = {}) {
     if (query && ![...(Array.isArray(r?._queries) ? r._queries : []), r?._query].some((q) => norm(q).includes(norm(query)))) continue;
     if (text && !norm(r?.mark_text).includes(norm(text))) continue;
     if (prepared && classifyRecord(r?.mark_text, prepared).tier !== tier) continue;
+    if (goodsCount && goodsCount(goodsOfRow(r)) === 0) continue;
     matched++;
-    if (matched > offset && hits.length < limit) hits.push(project(r));
+    if (matched > offset && hits.length < limit) hits.push(withGoods(r));
   }
   // matching crowd descriptors ride along (a lookup that lands in an un-enumerated zone must SEE that).
   const crowds = (Array.isArray(band?.crowds) ? band.crowds : []).filter((c) => {
@@ -330,11 +429,32 @@ function bandLookup(params = {}) {
       + (unsizedCrowds ? ` — and ${unsizedCrowds} of them has/have an UNKNOWN SIZE (see "size"): the register stated no total, so how much lies under those slices is unmeasured` : "") } : {}),
   }, null, 2);
   let out = body();
-  while (out.length > RESPONSE_CHARS && hits.length > 1) { hits.pop(); byteCapped++; out = body(); }
-  logRead("band_lookup", params, { ok: true, matched, returned: hits.length, crowds: crowds.length, ...(byteCapped ? { byte_capped: byteCapped } : {}) });
+  while (!fits(out) && hits.length > 1) { hits.pop(); byteCapped++; out = body(); }
+  logRead("band_lookup", params, { ok: true, matched, returned: hits.length, crowds: crowds.length, ...(byteCapped ? { byte_capped: byteCapped } : {}),
+    served: hits.map((h) => h.record_id).filter(Boolean) });
   return out;
 }
 
+// A RECORD'S GOODS ARE SERVED ONCE. A Clarivate record carries the register's raw goods list beside the
+// normalised goods the provider maps from it item for item (record-goods.mjs `rawGoodsCarried`), so every goods
+// statement was read twice. On a crowded test run, 2026-10-13, one synthesis attempt read 10.79 MB of record
+// text in 549 calls; served this way, the same records come to 6.04 MB in 398. Where the normalised goods carry
+// the raw list, the record is served without that list, in the file's own layout and field order, and anything
+// else in the raw goods block stays; where they do not, or the text is not a record, it is served as it
+// stands. The file on disk is never touched, and the reading audit says how much was left out.
+function recordAsServed(text) {
+  let body;
+  try { body = JSON.parse(text); } catch { return { text, audit: {} }; }
+  if (!rawGoodsCarried(body)) return { text, audit: {} };
+  const goods = { ...body._raw.goodsServices };
+  delete goods.intClassDescriptions;
+  const raw = { ...body._raw, goodsServices: goods };
+  if (!Object.keys(goods).length) delete raw.goodsServices;
+  const indent = /^\{\n( +)"/.exec(text)?.[1]?.length ?? 0;
+  const served = JSON.stringify({ ...body, _raw: raw }, null, indent) + (text.endsWith("\n") ? "\n" : "");
+  return { text: served, audit: { raw_goods_left_out: text.length - served.length } };
+}
+
 function bandRecord(params = {}) {
   if (!RUN_DIR) return { isError: true, text: "ERROR: CLEAROTRON_BAND_RUN_DIR not set — band tools are wired per run by the driver." };
   const uri = String(params.record_id ?? "").trim();
@@ -362,21 +482,22 @@ function bandRecord(params = {}) {
     // How the cite resolved rides the log: an `exact` hit is the model quoting the store's own key; any
     // other value is this ladder doing work, and the reading audit says which and to what.
     const resolution = hit.via === "exact" ? {} : { via: hit.via, ...(hit.resolved ? { resolved: hit.resolved } : {}) };
+    const served = recordAsServed(text);
+    text = served.text;
     const parts = splitAtLines(text, RESPONSE_CHARS);
     const total = parts.length;
-    if (total === 1) {                                  // the common case — served verbatim, no banner
-      logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, ...resolution });
+    if (total === 1) {                                  // the common case — one part, no banner
+      logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, ...resolution, ...served.audit });
       return text;
     }
-    // An oversize official record serves in PARTS, same contract as band_shape: line-boundary splits,
-    // byte-identical concatenation, and an explicit "complete only once all parts are read" banner.
+    // An oversize official record serves in PARTS, as band_shape does: line-boundary splits, byte-identical
+    // concatenation, and a banner that says the next part continues it.
     const part = Math.min(Math.max(1, Math.floor(Number(params.part)) || 1), total);
-    logRead("band_record", { record_id: uri, part, parts: total }, { ok: true, bytes: parts[part - 1].length, total_bytes: text.length, ...resolution });
-    const head = `[band_record part ${part}/${total} — this record exceeds one tool response, so it is served in ${total} parts` +
-      ` split at line boundaries. The record is COMPLETE only once ALL ${total} parts are read; concatenate the parts before parsing.]`;
+    logRead("band_record", { record_id: uri, part, parts: total }, { ok: true, bytes: parts[part - 1].length, total_bytes: text.length, ...resolution, ...served.audit });
+    const head = `[band_record part ${part}/${total}. This record is served in ${total} parts; the next part continues it.]`;
     const tail = part < total
       ? `\n[end of part ${part}/${total} — call band_record again with {"record_id": "${uri}", "part": ${part + 1}} for the next part]`
-      : `\n[end of part ${total}/${total} — the record is complete once parts 1..${total} are all read]`;
+      : `\n[end of the record]`;
     return head + "\n" + parts[part - 1] + tail;
   }
   // ── BEFORE CALLING IT A MISS, ASK THE LEDGER — ─────────────────────────────────
@@ -386,15 +507,16 @@ function bandRecord(params = {}) {
   // fetched this run", which is a different claim and was false four times on a delivered round.
   const fromLedger = recordFromLedger(uri);
   if (fromLedger) {
-    const text = JSON.stringify(fromLedger, null, 2);
+    const served = recordAsServed(JSON.stringify(fromLedger, null, 2));
+    const text = served.text;
     const parts = splitAtLines(text, RESPONSE_CHARS);
     if (parts.length === 1) {
-      logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, via: "ledger" });
+      logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, via: "ledger", ...served.audit });
       return { type: "text", text };
     }
     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: true, bytes: text.length, via: "ledger", part, parts: parts.length });
+    logRead("band_record", { record_id: uri }, { ok: true, bytes: text.length, via: "ledger", part, parts: parts.length, ...served.audit });
     return { type: "text", 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}}]` : "") };
   }
@@ -413,23 +535,44 @@ function bandRecord(params = {}) {
   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.` };
 }
 
+// THE SHAPE'S GROUP PAGES ARE PLACEMENT'S. Placement owes every line a group lists a fate, so it is offered the
+// group filter and told that a group is read page by page. No other stage owes the band a read, and a synthesis
+// offered the same paged an exhausted group 2,498 times (measured on a test run, 2026-10-13). The driver sets
+// CLEAROTRON_BAND_GROUPS for placement alone (stages.mjs GROUP_READING_STAGES); every other stage is offered
+// the lookup without `group`, in the words every stage had before group pages existed. A group argument that
+// 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
+// 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.";
+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)";
+/** The lookup's description as a stage is offered it: whole where it reads the groups, without them elsewhere. PURE. */
+const lookupDescription = (groupPages) => (groupPages ? LOOKUP_DESCRIPTION
+  : LOOKUP_DESCRIPTION.replace(LOOKUP_GROUP_CLAUSE, "").replace(LOOKUP_OFFSET_GROUPS, LOOKUP_OFFSET_BAND));
+
 serve({
   name: "band", version: "0.1.0",
   tools: [
     {
       name: "band_shape",
-      description: "The deterministic shape of this run's merged register band: totals, mechanical tiers, the complete floors list (every live in-class identical/near-identical record), class/status/registry/recency census, owner concentrations, crowd descriptors (with crowd-context joins) and blind spots. Read this FIRST, then pull what it names via band_lookup/band_record. A floors-heavy shape is served in PARTS (the response labels itself part N/M and names the next call — read ALL parts; the shape is complete only then, and a partial read is never the shape). Every call is logged to the run's reading audit.",
+      description: "The deterministic shape of this run's merged register band: totals, mechanical tiers, the floors (every live in-class identical/near-identical record), each marked on its line in the band in the lawyer's order, class/status/registry/recency census, owner concentrations, crowd descriptors (with crowd-context joins) and blind spots. Read this FIRST, then pull what it names via band_lookup/band_record. A large shape is served in parts, each naming the next call. Every call is logged to the run's reading audit.",
       inputSchema: { type: "object", properties: { format: { type: "string", enum: ["md", "json"], description: "md (default, readable) or json (machine shape)" }, part: { type: "number", description: "1-based part number when the shape is served in parts (default 1)" } } },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: bandShape,
     },
     {
       name: "band_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, limit (default 20, max 100), 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). Matching un-enumerated crowd descriptors ride along so a lookup can never mistake a counted-only zone for a clean.",
+      description: lookupDescription(GROUP_PAGES),
       inputSchema: { type: "object", properties: {
         record_id: { type: "string" }, owner: { type: "string" }, nice_class: { type: "string" },
         tier: { type: "string", enum: SHAPE_TIERS }, qid: { type: "string" }, query: { type: "string" }, text: { type: "string" },
-        status: { type: "string" }, live_only: { type: "boolean" }, limit: { type: "number" }, offset: { type: "number" },
+        status: { type: "string" }, live_only: { type: "boolean" }, goods: { type: "array", items: { type: "string" } },
+        ...(GROUP_PAGES ? { group: { type: "string", enum: ["a", "b", "c", "d", "rest", "no_goods"] } } : {}),
+        limit: { type: "number" }, offset: { type: "number" },
       } },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: bandLookup,