clearotron 0.4.0 → 0.4.1-beta.1

package/providers/_shared/enumerate.mjs

@@ -54,7 +54,7 @@
 import {
   BATCH_SCREEN_CHUNK, chunk, classifyStatus, isAllClass, normalizeBrandRow, screenVerdict,
 } from "./screen.mjs";
-import { makeCountProbe, parseToolText, isToolError } from "./count.mjs";
+import { makeCountProbe, parseToolText, isToolError } from "./count.mjs"; import { floorOf, moreThan } from "../../shared/register-floor.mjs";
 import { guardCountCall, guardToolCall } from "./transport-guard.mjs";
 import { clipProviderText } from "./provider-text.mjs";   // — keep the discriminator
 
@@ -220,6 +220,13 @@ export function makeEnumerate(deps) {
     // against the tuned ceiling below and can only ever narrow it — `CLEAROTRON_ENUMERATE_CEILING` cannot
     // raise a band past a window the vendor answers with an HTTP 400.
     ceilingFor = null,
+    // ── HOW MANY NAMES ONE REQUEST CARRIES, WHEN THAT IS A PROPERTY OF THE QUERY ──────────────────
+    //
+    // `namesChunkDefault` models a provider with one width for every names band. A register can take a
+    // list for one kind of question and not another — signa takes up to 100 exact spellings as one ranked
+    // list, and one term per request for everything else. `(params) => number|null`; `null` means the
+    // shape declares nothing and the default (or `CLEAROTRON_ENUMERATE_NAMES_CHUNK`) stands.
+    namesChunkFor = null,
   } = deps;
 
   // ── the I/O seam: a network REJECTION degrades like a 503, it does not abort the stage ────────────
@@ -249,6 +256,10 @@ export function makeEnumerate(deps) {
     // error on the count probe rather than as a countable total. Optional: a provider that does not
     // declare one keeps the previous behaviour exactly.
     cardinalityRefusal = null,
+    // — the provider's own words for refusing a LIST of spellings it would answer one by one (a ranked list
+    // judged too complex to run). Such a list is asked again one spelling at a time, as it was before lists
+    // were sent at all, never reported as a search that could not be made. Optional: absent, nothing changes.
+    listRefusal = null,
   } = capabilities;
 
   if (countProbe === "endpoint" && typeof count !== "function") {
@@ -258,8 +269,7 @@ export function makeEnumerate(deps) {
     throw new Error('[enumerate-kernel] capabilities.screenSource === "search-row" requires a rowScreen() dependency');
   }
 
-  const crowdReason = (total, ceiling) =>
-    `total_hits ${total} exceeds the enumerate ceiling ${ceiling} — this is a CROWD, not a named exact/near band. Record it as a count+sample descriptor and hand it up to judgment; the funnel does NOT narrow-and-retry a crowd here. Whether a narrower NAMED enumeration is warranted, and whether this slice is material, is judgment's call (Layer B) — never accept it as clean.`;
+  const crowdReason = (total, ceiling) => `total_hits ${total} exceeds the enumerate ceiling ${ceiling} — ${CROWD_IS}`;
 
   // ── count-first per-term rescue ───────────────────────────────────────────────────────────────────
   // A multi-name OR-stack that crowds over the ceiling used to return ONE blind `incomplete` — a rare
@@ -288,19 +298,19 @@ export function makeEnumerate(deps) {
   // asks a register "how many", so the two can never drift. `null` on any failure is preserved
   // exactly: a term whose probe failed is dispositioned `error`, never `verified-zero`.
   const countHits = makeCountProbe({ search, count, capabilities: { countProbe }, cheapCountParams });
-  const probeTermCount = async (auth, params, term, tctx) => {
-    const c = await countHits(auth, { ...params, [namesKey]: [term] }, tctx);
-    return c.ok ? c.total : null;
-  };
 
-  async function countFirstRescue(auth, params, names, ceiling, stackTotal, tctx, incomplete) {
+  // `floor` is the register's "at least N" when it answered the whole stack with one instead of a count
+  // (shared/register-floor.mjs): the stack's total then stays null and the figure rides beside it.
+  async function countFirstRescue(auth, params, names, ceiling, stackTotal, tctx, incomplete, floor = null) {
     const term_counts = {};
     for (const t of names) {
-      const n = await probeTermCount(auth, params, t, tctx);
-      if (n == null) { term_counts[t] = { total_hits: null, disposition: "error" }; continue; }
-      if (n === 0) term_counts[t] = { total_hits: 0, disposition: "verified-zero" };
-      else if (n > ceiling) term_counts[t] = { total_hits: n, disposition: "crowd" };
-      else term_counts[t] = { total_hits: n, disposition: "unenumerated" };
+      const probe = await countHits(auth, { ...params, [namesKey]: [t] }, tctx);
+      const n = probe.ok ? probe.total : null;
+      const said = countsOf(probe);   // what this spelling's own count counts, when the register said
+      if (n == null) { term_counts[t] = floorCount(probe) ?? { total_hits: null, disposition: "error" }; continue; }
+      if (n === 0) term_counts[t] = { total_hits: 0, disposition: "verified-zero", ...said };
+      else if (n > ceiling) term_counts[t] = { total_hits: n, disposition: "crowd", ...said };
+      else term_counts[t] = { total_hits: n, disposition: "unenumerated", ...said };
     }
     const records = [];
     const tally = { "verified-zero": 0, enumerated: 0, crowd: 0, unenumerated: 0, error: 0 };
@@ -317,13 +327,14 @@ export function makeEnumerate(deps) {
     // the identical question, that is the best case a matter can have (a mark nobody has registered)
     // producing a run that searches almost nothing. The ordinary search path has always returned
     // `enumerated` for a zero-record answer; this rescue path was the one place that did not.
-    if (unresolved === 0) {
+    // A stack the register answered with a floor is never a complete zero, whatever its spellings say.
+    if (unresolved === 0 && floor === null) {
       // every term verified zero ⇒ nobody has filed any of these names: a complete band whose answer is zero.
       return { type: "text", text: JSON.stringify({ state: "enumerated", total_hits: stackTotal, count: records.length, records, term_counts }, null, 2) };
     }
-    return incomplete(stackTotal, records.length, records,
-      `stack total_hits ${stackTotal} exceeds the enumerate ceiling ${ceiling}; each spelling was counted and none was read (${names.length} terms: ${tally["verified-zero"]} verified-zero, ${tally.unenumerated} counted and not read, ${tally.crowd} crowd, ${tally.error} error). term_counts carries each spelling's count: which to read, narrow or leave is the reading step's decision, and a populated term is never recorded 0.`,
-      { term_counts, records });
+    return incomplete(floor === null ? stackTotal : null, records.length, records,
+      `stack total_hits ${floor === null ? stackTotal : moreThan(floor)} exceeds the enumerate ceiling ${ceiling}; each spelling was counted and none was read (${names.length} terms: ${tally["verified-zero"]} verified-zero, ${tally.unenumerated} counted and not read, ${tally.crowd} crowd, ${tally.error} error). term_counts carries each spelling's count: which to read, narrow or leave is the reading step's decision, and a populated term is never recorded 0.`,
+      { term_counts, records, ...floorStamp(floor) });
   }
 
   // ── count-first per-CLASS rescue ──────────────────────────────────────────────────────────────────
@@ -338,26 +349,27 @@ export function makeEnumerate(deps) {
   // a populated class can never be recorded 0 — it is in `class_counts`, and if tractable its records
   // are carried. NOTE a record filed in several classes sits in each leg's enumeration; the merge
   // dedupes it, so per-class totals may legitimately sum past the stack total.
-  async function classSplitRescue(auth, params, classes, ceiling, stackTotal, tctx, incomplete) {
+  async function classSplitRescue(auth, params, classes, ceiling, stackTotal, tctx, incomplete, floor = null) {
     const class_counts = {};
     const tractable = [];
     for (const c of classes) {
       const probe = await countHits(auth, { ...params, nice_classes: [c] }, tctx);
       const n = probe.ok ? probe.total : null;
-      if (n == null) { class_counts[c] = { total_hits: null, disposition: "error" }; continue; }
-      if (n === 0) class_counts[c] = { total_hits: 0, disposition: "verified-zero" };
-      else if (n > ceiling) class_counts[c] = { total_hits: n, disposition: "crowd" };
-      else tractable.push({ c, n });
+      const said = countsOf(probe);   // what this class's own count counts, when the register said (ruling 712)
+      if (n == null) { class_counts[c] = floorCount(probe) ?? { total_hits: null, disposition: "error" }; continue; }
+      if (n === 0) class_counts[c] = { total_hits: 0, disposition: "verified-zero", ...said };
+      else if (n > ceiling) class_counts[c] = { total_hits: n, disposition: "crowd", ...said };
+      else tractable.push({ c, n, said });
     }
     tractable.sort((a, b) => a.n - b.n); // cheapest first — maximizes fully-enumerated legs under the budget
     const merged = new Map();
-    for (const { c, n } of tractable) {
-      if (merged.size + n > ceiling) { class_counts[c] = { total_hits: n, disposition: "unenumerated" }; continue; }
+    for (const { c, n, said } of tractable) {
+      if (merged.size + n > ceiling) { class_counts[c] = { total_hits: n, disposition: "unenumerated", ...said }; continue; }
       const r = await enumerate(auth, { ...params, nice_classes: [c] }, tctx);
       const parsed = isToolError(r) ? null : parseToolText(r);
-      if (!parsed) { class_counts[c] = { total_hits: n, disposition: "error" }; continue; }
+      if (!parsed) { class_counts[c] = { total_hits: n, disposition: "error", ...said }; continue; }
       if (parsed.state === "enumerated") {
-        class_counts[c] = { total_hits: n, disposition: "enumerated" };
+        class_counts[c] = { total_hits: n, disposition: "enumerated", ...said };
         for (const rec of (parsed.records ?? [])) {
           const k = recordKeyOf(rec);
           if (!merged.has(k)) merged.set(k, rec);
@@ -365,7 +377,7 @@ export function makeEnumerate(deps) {
       } else {
         // drifted past the probe count (provider re-count) or hit the provider window — honest per-leg state
         const m = parsed.total_hits ?? n;
-        class_counts[c] = { total_hits: m, disposition: m > ceiling ? "crowd" : "error" };
+        class_counts[c] = { total_hits: m, disposition: m > ceiling ? "crowd" : "error", ...(Number.isFinite(parsed.total_hits) ? countsOf(parsed) : said) };
       }
     }
     const records = [...merged.values()];
@@ -374,14 +386,14 @@ export function makeEnumerate(deps) {
     const unresolved = Object.values(class_counts).filter(isUnresolvedCount).length;
     // Same rule, same reason, same correction as the OR-stack rescue above: a stack in which every class
     // came back a verified zero is a complete band whose answer is zero, not a question nobody answered.
-    if (unresolved === 0) {
+    if (unresolved === 0 && floor === null) {
       // every class resolved to verified-zero or fully-enumerated ⇒ the union of per-class enumerations
       // IS the complete stack (every record carries ≥1 in-filter class) — a true band, the class rescue.
       return { type: "text", text: JSON.stringify({ state: "enumerated", total_hits: stackTotal, count: records.length, records, class_counts }, null, 2) };
     }
-    return incomplete(stackTotal, records.length, records,
-      `owner-scoped total_hits ${stackTotal} exceeds the enumerate ceiling ${ceiling}; count-first per-CLASS rescue ran (${classes.length} classes: ${tally["verified-zero"]} verified-zero, ${tally.enumerated} enumerated with records carried, ${tally.crowd} crowd, ${tally.unenumerated} unenumerated on budget, ${tally.error} error). Saturated class legs stay a CROWD descriptor for judgment; class_counts is the per-class truth — a populated class leg is never recorded 0 and never "unopened".`,
-      { class_counts, records });
+    return incomplete(floor === null ? stackTotal : null, records.length, records,
+      `owner-scoped total_hits ${floor === null ? stackTotal : moreThan(floor)} exceeds the enumerate ceiling ${ceiling}; count-first per-CLASS rescue ran (${classes.length} classes: ${tally["verified-zero"]} verified-zero, ${tally.enumerated} enumerated with records carried, ${tally.crowd} crowd, ${tally.unenumerated} unenumerated on budget, ${tally.error} error). Saturated class legs stay a CROWD descriptor for judgment; class_counts is the per-class truth — a populated class leg is never recorded 0 and never "unopened".`,
+      { class_counts, records, ...floorStamp(floor) });
   }
 
   // ── A QUESTION SLOWER THAN THE REGISTER'S GATEWAY WAITS IS ASKED AGAIN IN REGION HALVES ───────────────
@@ -399,7 +411,7 @@ export function makeEnumerate(deps) {
   // half's own reason, as a names window does: a clean never ships over a part that did not run.
   // `region_split` rides the answer, naming the timeout that started it and the size of every part that
   // answered, so a reader can see the question was asked in pieces and where.
-  async function regionHalves(auth, params, tctx, { ceiling, incomplete, cause }) {
+  async function regionHalves(auth, params, tctx, { ceiling, incomplete, cause, hear = () => {} }) {
     const regions = params.regions;
     const mid = Math.ceil(regions.length / 2);
     const halves = [regions.slice(0, mid), regions.slice(mid)];
@@ -435,9 +447,10 @@ export function makeEnumerate(deps) {
       // A half that timed out while its sibling answered is the one place fewer regions may help: it is
       // halved in turn, under the same rule.
       const r = timedOut({ r: first })
-        ? await regionHalves(auth, { ...params, regions: half }, tctx, { ceiling, incomplete, cause: parseToolText(first)?.reason ?? cause })
+        ? await regionHalves(auth, { ...params, regions: half }, tctx, { ceiling, incomplete, cause: parseToolText(first)?.reason ?? cause, hear })
         : first;
       const parsed = isToolError(r) ? null : parseToolText(r);
+      hear(parsed);
       const which = `the ${half.length}-region half ${half[0]}${half.length > 1 ? `…${half[half.length - 1]}` : ""}`;
       // A stall from a deeper split keeps its own reason, stall first, so the executor reads it however
       // deep the split went and however short the reason is later cut.
@@ -464,8 +477,22 @@ export function makeEnumerate(deps) {
       ...(screenLift ? { screen_lift: screenLift } : {}), region_split: { cause, parts } }, null, 2) };
   }
 
-  async function enumerate(auth, params, tctx, { split = true } = {}) {
+  // ── WHAT THE TOTAL COUNTS, STATED ONCE FOR THE WHOLE ANSWER ────────────────────────────────────────
+  //
+  // A register can say that a total counts records, one per country a mark covers, rather than marks
+  // (`total_counts` on a provider's parsed answer). The answer to the question states it, whichever of the
+  // exits below produced it: the page loop, the name windows, the region halves and the rescues each tell
+  // the question what they heard, and it is stamped here, on the one way out. Recorded only: the ceiling
+  // still reads the register's own number (ruled 2026-10-02). An answer with no `total_counts` is one whose
+  // register said nothing about it, never a count of marks.
+  async function enumerate(auth, params, tctx, opts = {}) {
+    const said = { totalCounts: null };
+    return stampTotalCounts(await enumerateQuestion(auth, params, tctx, opts, said), said.totalCounts);
+  }
+
+  async function enumerateQuestion(auth, params, tctx, { split = true, oneByOne = false } = {}, said = { totalCounts: null }) {
     if (!hasAnyElement(params)) return { type: "text", text: missingElementError };
+    const hear = (p) => { if (typeof p?.total_counts === "string") said.totalCounts = p.total_counts; };
 
     // The tuned ceiling, then narrowed by any window the QUERY SHAPE imposes. Min, never max:
     // a shape window is a vendor limit, and a band that pages past it does not return more records, it
@@ -499,7 +526,9 @@ export function makeEnumerate(deps) {
     // descriptor total — `count` is the deduped truth); the resource ceiling applies to the RUNNING total
     // so a crowd still returns an incomplete descriptor. ANY chunk error/incomplete makes the WHOLE slice
     // incomplete — a clean can never ship over a partially-executed slice.
-    const namesChunk = envInt("CLEAROTRON_ENUMERATE_NAMES_CHUNK", namesChunkDefault);
+    const shapeChunk = oneByOne ? 1 : typeof namesChunkFor === "function" ? namesChunkFor(params) : null;
+    const namesChunk = Number.isFinite(shapeChunk) && shapeChunk >= 1
+      ? Math.floor(shapeChunk) : envInt("CLEAROTRON_ENUMERATE_NAMES_CHUNK", namesChunkDefault);
     const allNames = Array.isArray(params[namesKey]) ? params[namesKey].filter(Boolean) : null;
     if (allNames && allNames.length > namesChunk) {
       const merged = new Map();
@@ -507,6 +536,9 @@ export function makeEnumerate(deps) {
       const rescueNotes = [];           // per-window rescue summaries for the final descriptor
       const enumeratedWindowTerms = []; // terms whose whole window enumerated cleanly (per-term truth by superset)
       let totalSum = 0;
+      // The largest floor a window answered with ("at least N"): the slice's total is then unknown, never a
+      // sum that leaves the floor out, and the figure rides as the slice's own floor.
+      let floorMax = null;
       const chunks = Math.ceil(allNames.length / namesChunk);
       const mergeRecs = (recs) => {
         for (const rec of (recs ?? [])) {
@@ -518,6 +550,7 @@ export function makeEnumerate(deps) {
         const part = allNames.slice(i * namesChunk, (i + 1) * namesChunk);
         const r = await enumerate(auth, { ...params, [namesKey]: part }, tctx);
         const parsed = parseToolText(r);
+        hear(parsed);
         if (isToolError(r) || !parsed) {
           return incomplete(totalSum, merged.size, [...merged.values()],
             `chunk ${i + 1}/${chunks} (${part.length} names) failed: ${String(r?.text ?? "unparseable").slice(0, 140)}`,
@@ -527,6 +560,7 @@ export function makeEnumerate(deps) {
           // A rescued window (term_counts attached) carries its per-term truth — aggregate and CONTINUE so
           // the remaining windows still get their accounting; the slice stays incomplete either way, but a
           // partial abort here would leave later windows' terms unaccounted and the clean-gate blind.
+          if (Number.isFinite(parsed.total_floor)) floorMax = Math.max(floorMax ?? 0, parsed.total_floor);
           if (countFirst && parsed.term_counts && typeof parsed.term_counts === "object") {
             Object.assign(termCounts, parsed.term_counts);
             totalSum += parsed.total_hits ?? 0;
@@ -534,9 +568,10 @@ export function makeEnumerate(deps) {
             rescueNotes.push(`chunk ${i + 1}/${chunks}: ${String(parsed.reason ?? "").slice(0, 140)}`);
             continue;
           }
-          return incomplete(totalSum + (parsed.total_hits ?? 0), merged.size + (parsed.fetched ?? 0),
+          return incomplete(floorMax === null ? totalSum + (parsed.total_hits ?? 0) : null, merged.size + (parsed.fetched ?? 0),
             [...merged.values(), ...(parsed.sample ?? [])],
-            `chunk ${i + 1}/${chunks} (${part.length} names) ${parsed.state}: ${String(parsed.reason ?? "").slice(0, 180)}`);
+            `chunk ${i + 1}/${chunks} (${part.length} names) ${parsed.state}: ${String(parsed.reason ?? "").slice(0, 180)}`,
+            floorStamp(floorMax));
         }
         totalSum += parsed.total_hits ?? 0;
         mergeRecs(parsed.records);
@@ -555,9 +590,9 @@ export function makeEnumerate(deps) {
         for (const t of enumeratedWindowTerms) {
           if (!(t in termCounts)) termCounts[t] = { total_hits: null, disposition: "enumerated" };
         }
-        return incomplete(totalSum, merged.size, [...merged.values()],
+        return incomplete(floorMax === null ? totalSum : null, merged.size, [...merged.values()],
           `count-first per-term rescue ran in ${rescueNotes.length}/${chunks} name chunks — saturated terms stay CROWD descriptors for judgment; term_counts is the per-term truth (a populated term is never recorded 0). ${rescueNotes.join(" · ")}`.slice(0, 900),
-          { term_counts: termCounts, records: [...merged.values()] });
+          { term_counts: termCounts, records: [...merged.values()], ...floorStamp(floorMax) });
       }
       return { type: "text", text: JSON.stringify({ state: "enumerated", total_hits: totalSum, count: merged.size, records: [...merged.values()], ...(Object.keys(termCounts).length ? { term_counts: termCounts } : {}) }, null, 2) };
     }
@@ -599,10 +634,11 @@ export function makeEnumerate(deps) {
             + `Provider's own words: ${clipProviderText(c?.reason ?? "", COUNT_PROBE_BUDGET)}`,
             { crowd_basis: "provider-refused-count", count_unavailable: true });
         }
-        if (splittable && isGatewayTimeout(c?.reason)) return regionHalves(auth, params, tctx, { ceiling, incomplete, cause: String(c.reason) });
+        if (splittable && isGatewayTimeout(c?.reason)) return regionHalves(auth, params, tctx, { ceiling, incomplete, cause: String(c.reason), hear });
         return incomplete(0, 0, [],
           `provider error on the count probe before enumeration: ${String(c?.reason ?? "count unavailable")}`, timeoutMark(c?.reason));
       }
+      hear(c);
       total = Number.isFinite(c.total) ? c.total : 0;
       probeTotal = total;
       if (total > ceiling) {
@@ -625,11 +661,15 @@ export function makeEnumerate(deps) {
     for (let page = 0; ; page += 1) {
       const r = await search(auth, { ...params, ...pageParams(page, pageSize, prevParsed) }, tctx);
       if (isToolError(r)) {
-        if (splittable && isGatewayTimeout(r.text)) return regionHalves(auth, params, tctx, { ceiling, incomplete, cause: String(r.text) });
+        if (page === 0 && !oneByOne && allNames && allNames.length > 1 && listRefusal?.test(String(r.text ?? ""))) {
+          return enumerateQuestion(auth, params, tctx, { split, oneByOne: true }, said);
+        }
+        if (splittable && isGatewayTimeout(r.text)) return regionHalves(auth, params, tctx, { ceiling, incomplete, cause: String(r.text), hear });
         return incomplete(total, results.length, results, `provider error during enumeration (page ${page}): ${String(r.text ?? "")}`, timeoutMark(r.text));
       }
       const parsed = parseToolText(r);
       if (!parsed) return incomplete(total, results.length, results, `unparseable search response during enumeration (page ${page})`);
+      hear(parsed);
       // ── the number the completeness claim rests on must BE a number ────────────────────────────────
       // On the "cheap" seam the page response IS the count — the ceiling is tested off `total_hits` and
       // nothing else. A response that parsed but carries no usable total therefore cannot support a
@@ -638,6 +678,24 @@ export function makeEnumerate(deps) {
       // where the "enumerated" verdict is actually minted, so it cannot depend on every future adapter
       // remembering. total_hits rides out NULL — unknown — never a fabricated 0.
       if (countProbe === "cheap" && !Number.isFinite(parsed.total_hits)) {
+        // A FLOOR IS AN ANSWER (ruled 2026-10-02). A register that says "at least 10,000" counted, and gave a
+        // floor instead of a figure: the search ran and is too large to read. So it is a crowd, with the
+        // register's own figure beside a total that stays null. Never a provider error, which would ask it
+        // again for the same answer and write a 0 in its place.
+        const floor = floorOf(parsed);
+        if (floor !== null) {
+          // AS FOR ANY CROWD OVER THE CEILING (the page-0 branch below): a stack of spellings, or an owner's
+          // classes, is counted part by part first, so a rare spelling never vanishes inside the floor.
+          if (page === 0 && countFirst && allNames && allNames.length > 1) {
+            return countFirstRescue(auth, params, allNames, ceiling, null, tctx, incomplete, floor);
+          }
+          if (page === 0 && countFirst && splitClasses.length > 1) {
+            return classSplitRescue(auth, params, splitClasses, ceiling, null, tctx, incomplete, floor);
+          }
+          return incomplete(null, results.length + (parsed.results?.length ?? 0), [...results, ...(parsed.results ?? [])],
+            `the register answered "${moreThan(floor)}" for this question: a floor, not a count, so the set is too large to read. ${CROWD_IS[0].toUpperCase()}${CROWD_IS.slice(1)}`,
+            floorStamp(floor));
+        }
         return incomplete(null, results.length, results,
           `provider error during enumeration (page ${page}): the search response carried no usable total_hits, and on this provider the response IS the count — so the enumerate ceiling could not be tested and this band cannot be read as either a completed enumeration or a sanctioned crowd. The total is UNKNOWN (null, never 0).`);
       }
@@ -811,3 +869,29 @@ export function makeEnumerate(deps) {
 
   return { enumerate, countFirstRescue, classSplitRescue };
 }
+
+/** The stamps a crowd carries when the register answered with a floor: the figure, and why the total is null. */
+function floorStamp(floor) {
+  return floor === null ? {} : { crowd_basis: "register-floor", total_floor: floor };
+}
+
+/** A part the register answered with a floor is itself a crowd with the register's figure, never an error. */
+function floorCount(probe) {
+  return Number.isFinite(probe?.floor) ? { total_hits: null, total_floor: probe.floor, disposition: "crowd" } : null;
+}
+
+/** `{ total_counts }` from a probe or a parsed answer that carries it, else nothing to spread. PURE. */
+function countsOf(p) {
+  return typeof p?.total_counts === "string" ? { total_counts: p.total_counts } : {};
+}
+
+/** The answer with what its total counts stated on it; an error, or nothing heard, passes unchanged. */
+function stampTotalCounts(r, totalCounts) {
+  if (!totalCounts || isToolError(r)) return r;
+  const parsed = parseToolText(r);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return r;
+  return { ...r, text: JSON.stringify({ ...parsed, total_counts: totalCounts }, null, 2) };
+}
+
+// What a crowd is, in the words every crowd's reason ends with: a band the funnel hands up, never a clean.
+const CROWD_IS = "this is a CROWD, not a named exact/near band. Record it as a count+sample descriptor and hand it up to judgment; the funnel does NOT narrow-and-retry a crowd here. Whether a narrower NAMED enumeration is warranted, and whether this slice is material, is judgment's call (Layer B) — never accept it as clean.";

package/providers/_shared/execute-plan.mjs

@@ -16,7 +16,7 @@
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { nativeScriptIndexGap } from "./script-form.mjs";
+import { nativeScriptIndexGap } from "./script-form.mjs"; import { floorOf, moreThan } from "../../shared/register-floor.mjs";
 import { entryTermIssues, goodsTermsList } from "./term-shape.mjs";
 import { awaitsReadingTurn, releasedFamiliesFile } from "./plan-guards.mjs";
 import { faultText, guardToolCall } from "./transport-guard.mjs";
@@ -500,8 +500,16 @@ export function makeExecutePlan(deps) {
           && Number.isFinite(parsed.total_hits) && Number(parsed.total_hits) === 0
           && parsed.owner_resolution != null && !ownerNameResolved(parsed.owner_resolution);
         const counted = !!parsed && !ownerUnverified;
+        // A floor ("at least 10,000") is the register's answer: the total stays null and its figure rides beside
+        // it, never a 0 (ruled 2026-10-02; shared/register-floor.mjs). An answer that carried no number at all
+        // keeps a null total as well. `?? 0` wrote it down as a counted zero, which read as an empty field and
+        // hid it from the band shape's uncountable-slice reading. A call that failed keeps the 0 it always had
+        // beside error:true, the placeholder every refused slice carries.
+        const floor = floorOf(parsed);
+        const untotalled = counted && !Number.isFinite(parsed.total_hits);
         blocks.push({ state: "incomplete", ...base,
-          total_hits: ownerUnverified ? null : (parsed?.total_hits ?? 0), fetched: parsed?.results?.length ?? 0,
+          total_hits: ownerUnverified || floor !== null || untotalled ? null : (parsed?.total_hits ?? 0), fetched: parsed?.results?.length ?? 0,
+          ...(floor !== null ? { total_floor: floor, crowd_basis: "register-floor" } : {}),
           sample: (parsed?.results ?? []).slice(0, 5),
           ...(counted ? {} : { error: true }),
           ...(countGap || ownerUnverified ? { deferred: true } : {}),
@@ -509,6 +517,8 @@ export function makeExecutePlan(deps) {
           // the resolution the sweep actually ran on, verbatim — a reader must be able to see WHICH
           // applicant styling was asked for, on a verified zero as much as on an unverified one.
           ...(parsed?.owner_resolution ? { owner_resolution: parsed.owner_resolution } : {}),
+          // what the counted total counts, when the register said (enumerate.mjs, "what the total counts")
+          ...(counted && typeof parsed?.total_counts === "string" ? { total_counts: parsed.total_counts } : {}),
           reason: ownerUnverified ? unresolvedOwnerCountReason(e.term ?? (e.terms ?? [])[0], coveredBy)
             : parsed ? descriptorReason
             : `provider error on the count probe (after one in-tool retry): ${clipProviderText(r?.text ?? "", 100)}` });
@@ -643,7 +653,8 @@ export function makeExecutePlan(deps) {
     // EACH SPELLING'S COUNT, IN THE REPLY. A crowded stack comes back counted and unread, and the reading
     // step decides which spellings to read, narrow or leave (ruled 2026-09-26), so it is handed the counts
     // here rather than left to find them in the band file: a number for a spelling counted and not read,
-    // 0 for a verified zero, "crowd N" for one over the ceiling, "error" for a count that failed.
+    // 0 for a verified zero, "crowd N" for one over the ceiling, "error" for a count that failed. A spelling the
+    // register answered with a floor reads "crowd more than 10,000", its figure as every page prints it.
     //
     // THE GATE IS "ANYTHING LEFT TO DECIDE", not one disposition, and that is the whole of this block's
     // correctness. Keyed on `unenumerated` alone it dropped the two stacks the rule exists for: one where
@@ -659,7 +670,7 @@ export function makeExecutePlan(deps) {
     const spellingCounts = Object.fromEntries(blocks
       .filter((b) => b?.term_counts && Object.values(b.term_counts).some(isUnresolvedCount))
       .map((b) => [b.qid, Object.fromEntries(Object.entries(b.term_counts).map(([t, v]) => [t,
-        v?.disposition === "crowd" ? `crowd ${v.total_hits}` : v?.disposition === "error" ? "error" : (v?.total_hits ?? "error")]))]));
+        v?.disposition === "crowd" ? `crowd ${Number.isFinite(v.total_floor) ? moreThan(v.total_floor) : v.total_hits}` : v?.disposition === "error" ? "error" : (v?.total_hits ?? "error")]))]));
     return { type: "text", text: JSON.stringify({
       written: outPath, blocks: blocks.length + preserved.length, executed: blocks.length, preserved: preserved.length, skipped,
       states: Object.fromEntries([...stateByQid].filter(([q]) => !seeded.has(q))),

package/providers/corsearch/src/capabilities.js

@@ -38,7 +38,7 @@ export const CAPABILITIES = Object.freeze({
   countStatusFilter: "none",
   // HTTP-414 URI guard: the whole query is a GET query string, so ~80 backtick-quoted names (≈2–4KB
   // encoded) is the safe OR-stack. This MIRRORS the executor's ENUMERATE_NAMES_CHUNK_DEFAULT — the
-  // planner must never dictate an OR-stack the executor would have to chunk-rescue (Wilderness 414).
+  // planner must never dictate an OR-stack the executor would have to chunk-rescue (Open Country 414).
   maxOrWidth: 80,
   // `nice-class` clauses ride the same query string (implicit OR within the field) — one call, no fan-out.
   classFilter: "native",

package/providers/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-oauth-mcp-bridge
 
+## 0.4.1-beta.1
+
+No changes in this release.
+
+## 0.4.1-beta.0
+
+No changes in this release.
+
 ## 0.4.0
 
 No changes in this release.

package/providers/oauth-mcp-bridge/package.json

@@ -1,13 +1,13 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.4.0",
+  "version": "0.4.1-beta.1",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "OAuth 2.1 MCP stdio bridge used by the engine's case-law gather stage (courtlistener / legaldatahunter).",
   "type": "module",
   "main": "bridge.mjs",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.31.0"
   },
   "engines": { "node": ">=22.13.0" }
 }

package/providers/signa/src/capabilities.js

@@ -120,9 +120,36 @@ export const CAPABILITIES = Object.freeze({
   // NOTE the key. `filters.status` does not exist and the API rejects unknown filter keys outright
   // (`HTTP 400 Unrecognized key: status`) — which is what core.js was sending until this issue.
   countStatusFilter: "native",
-  // The request carries ONE `query` string. There is no OR-stack surface at all — an N-name band is N
-  // calls, so the planner must emit one term per entry.
+  // The request carries ONE `query` string for every predicate but one, so the general OR width stays 1:
+  // a phonetic, wildcard or owner band is one call per term, and anything that reads this width as
+  // "no OR at all" (the supplemental batch's one-question-per-name split) keeps reading it that way.
   maxOrWidth: 1,
+  // ── THE ONE PREDICATE THAT TAKES A LIST: exact spellings, up to 100 per request ─────────────────
+  //
+  // A list in `q` is a ranked search over every spelling through the channels the request names, and
+  // each record says which spellings found it (`match.terms`). The register takes up to 100 spellings
+  // when the channels are only `identical` and `lookalike` — which is exactly what an exact question
+  // sends — and 10 otherwise. Measured live against one search per spelling, by record id and paged to
+  // exhaustion: the same records on the exact band at 32 and at 100 spellings, look-alike-only records
+  // included, with every record's `match.terms` naming exactly the spellings that found it alone. The
+  // figures are on the tracker. The one documented difference — a list skips the word-by-word fuzzy
+  // retry — belongs to a channel the exact question does not send.
+  //
+  // So the planner stacks an exact spelling band at this width, and the kernel sends each stack as one
+  // request (`namesChunkFor` in core.js); every other predicate stays at `maxOrWidth`.
+  exactOrWidth: 100,
+  // ── THE SOUND-ALIKE BAND TAKES A LIST TOO, UP TO 10 SPELLINGS AND 30 WORDS ─────────────────────────
+  //
+  // The register takes up to 10 spellings, and 30 words in all, when a channel other than `identical`
+  // and `lookalike` is asked. On the sound-alike channels (`identical`, `phonetic`) it answers a list of
+  // 10 with the same records, by id, as one search per spelling, and each record's `match.terms` names the
+  // spellings that found it alone (ruled 2026-10-09).
+  //
+  // The typo channels (`identical`, `fuzzy`, `embedded`, `lookalike`) stay one spelling per request. The
+  // register refuses some typo lists of 10 as "too complex to run" where each spelling alone answers, and
+  // which lists it refuses depends on the spellings, so no fixed width is safe there.
+  phoneticOrWidth: 10,
+  listWordBudget: 30,
   // filters.nice_classes[] is a top-level OR filter — one call, no fan-out.
   classFilter: "native",
   // ── THE GOODS-AND-SERVICES TEXT FILTER ──────────────────────────────────────────────────────────
@@ -395,6 +422,9 @@ export const CAPABILITIES = Object.freeze({
     pageGuard: 60,
     ceilingDefault: 600,
     namesChunkDefault: 1,
+    // A ranked list the register will not run (HTTP 400, "The search query is too complex to run."). Which
+    // lists it refuses depends on the spellings, so a refused one is asked again one spelling at a time.
+    listRefusal: /too complex to run/i,
     providerWindow: "cursor window; exact total via options.include_total (approximate totals saturate at 10000 and are reported UNKNOWN, never as a count)",
   }),
 });