clearotron 0.3.2 → 0.3.3-beta.0

package/driver/unit-inventory.mjs

@@ -676,7 +676,7 @@ export const CHECKED_TIMERS = Object.freeze(
  * that reports on the service keeps saying `inactive`, which is what it says when the timer is working.
  */
 export function timerVerdict(timers, { probeFailed = null } = {}) {
-  if (probeFailed) return { state: "unknown", stopped: [], absent: [], message: `could not ask systemd about the timers: ${probeFailed}. That is this check failing to look, not a report about them.` };
+  if (probeFailed) return { state: "skip", blocked: true, stopped: [], absent: [], message: `could not ask systemd about the timers: ${probeFailed}. That is this check failing to look, not a report about them.` };
   const rows = timers ?? [];
   if (!rows.length) return { state: "pass", stopped: [], absent: [], message: "no timer is declared for this box" };
   const absent = rows.filter((t) => t.load === "not-found").map((t) => t.unit).sort();
@@ -726,7 +726,7 @@ export function unitInventoryVerdict({
   inventory = UNIT_INVENTORY,
 } = {}) {
   if (!probe.ok) {
-    return { state: "skip", undeclared: [], orphaned: [], absent: [], misdeclared: [],
+    return { state: "skip", blocked: true, undeclared: [], orphaned: [], absent: [], misdeclared: [],
       message: `could not enumerate systemd units, so the inventory was NOT checked — ${probe.why ?? "no reason given"}. `
         + "A failure to look is not a finding about the deployment." };
   }

package/driver/unit-state-verdict.mjs

@@ -100,7 +100,7 @@ export function classifyActiveState(active) {
 export function unitsActiveVerdict({ units, probe }) {
   // — a failure to look is never a finding about the deployment.
   if (!probe?.ok)
-    return { state: "skip", message: `could not enumerate systemd --user units — ${probe?.why ?? "no reason reported"}` };
+    return { state: "skip", blocked: true, message: `could not enumerate systemd --user units — ${probe?.why ?? "no reason reported"}` };
 
   const label = (u) => `${u.unit}=${u.active}`
     + (u.type ? ` (${u.type}${u.since ? `, since ${u.since}` : ""})` : (u.since ? ` (since ${u.since})` : ""));

package/driver/updater-identity.mjs

@@ -111,8 +111,7 @@ export function updaterVerdict({ stamp, now = null, deployClone = null, maxAgeSe
     return { state: "fail", message:
       `no updater identity stamp at ${UPDATER_STAMP_BASENAME}: the copy of the updater that deploys this `
       + "box did NOT say what it is, so whether it is the current one was not established. A copy old "
-      + "enough to predate the stamp writes none, which is itself the stale-updater case. This is a "
-      + "failure to look, never a pass." };
+      + "enough to predate the stamp writes none, which is itself the stale-updater case." };
   }
 
   // — AN UNREADABLE SIDE IS NOT A MISMATCH. A digest that could not be taken arrives as null, and
@@ -128,7 +127,7 @@ export function updaterVerdict({ stamp, now = null, deployClone = null, maxAgeSe
       : !wsha ? "the running copy of the updater could NOT be read as a digest"
       : "the master could NOT be read as a digest";
     const why = stamp.masterCommitError ? ` The updater reported: ${stamp.masterCommitError}` : "";
-    return { state: "fail", message:
+    return { state: "skip", blocked: true, message:
       `the updater stamp is present but ${which}, so the running copy was NOT `
       + `compared against its master.${why} This is a failure to look, never a pass.` };
   }

package/driver/variant-manifest-model.mjs

@@ -176,8 +176,18 @@ export function parseVariantManifestModel(raw) {
   // and refuses it. Each says so in its own capability contract, and the compiler declines to build an
   // entry a register cannot express. Deciding it here would freeze one register's behaviour into a
   // rule about every register.
-  let goods_words = [];
+  // ── AN ABSENT KEY AND AN EMPTY LIST ARE DIFFERENT ANSWERS ───────────────────────────────────────
+  //
+  // `null` means the stage was asked and did not answer. `[]` means it answered: it considered the
+  // goods and there are no words worth narrowing by. They are the same value to a reader who only
+  // checks emptiness, and that is how a production run shipped a narrowing that never ran — the model
+  // could not send the key at all, the manifest carried an empty list, the compiler minted nothing,
+  // and the run looked exactly like a matter that genuinely had no goods words.
+  //
+  // Nothing downstream may treat the two the same. A skipped question is a fact about the run.
+  let goods_words = null;
   if (m.goods_words != null) {
+    goods_words = [];
     if (!Array.isArray(m.goods_words) || !m.goods_words.every((w) => typeof w === "string"))
       throw new Error("variantmodel_goods_words_invalid (an array of single-word strings, or omitted)");
     const seen = new Set();

package/driver/verify.mjs

@@ -16,7 +16,7 @@ import { matterFrameWasRecorded, frameRatifiedForms } from "./matter-frame-recor
 import { findConnotationViolations, parsePrRiskResults, prRiskPopulation,
   CONNOTATION_UNMATCHED_MARK, CONNOTATION_NO_RESEMBLANCE_MARK, MEANING_ANGLES_RE,
   parseDispositionForm, CONNOTATION_UNRULED_REASONS, queryKey } from "./connotation-search.mjs";
-import { formSidecarName, formSidecarPath } from "./disposition-union.mjs";
+import { formSidecarName, formSidecarPath } from "./disposition-union.mjs"; import { coverageStatusAsData } from "./common-law-coverage-status.mjs";
 // B — the transport's own four failure states. The audit reads the run's records; this file locates them.
 import { auditDispositionCalls, CALL_FAILURE_REASONS } from "./disposition-call-audit.mjs";
 import { callRecordPaths } from "./disposition-tool.mjs";
@@ -481,7 +481,7 @@ function commonLawMeaningSeat(p, c) {
 // — the EVIDENCE chain for `validators.commonLaw`, lifted out verbatim so the unavailability
 // veto can wrap it instead of pre-empting it. Every return token is unchanged.
 function commonLawEvidence(p, c) {
-    const structural = commonLawStructural(c);
+    const structural = commonLawStructural(c, p);
     if (!structural.ok) return structural;
     // The dictated grid spec is the SINGLE source of the grid contract when present (the driver wrote it,
     // the plugin ran it, the plugin wrote the ledger from it): the receipts gate joins the ledger against
@@ -596,7 +596,7 @@ function commonLawHalfEvidence(p, c) {
     if (!half) return fail("half_path_unrecognized");
     // — the meaning seat is judged on the meaning work, because that is all it was dictated.
     if (half === MEANING_SEAT) return commonLawMeaningSeat(p, c);
-    const structural = commonLawStructural(c);
+    const structural = commonLawStructural(c, p);
     if (!structural.ok) return structural;
     const gs = readGridSpecHalf(p, half);
     if (gs.invalid) return fail(`grid_spec_unreadable:_driver/grid-spec.half-${half}.json is corrupt or misshapen (driver-written — this is a bug, not a model defect)`);
@@ -664,7 +664,7 @@ function commonLawHalfEvidence(p, c) {
 // adjacent with exactly one separator between them; it stops rejecting a document that HAS the section
 // under the hyphenated compound the skill itself uses. The failure this removes is a false negative, and
 // its cost was a clearance that had already spent an hour.
-function commonLawStructural(c) {
+function commonLawStructural(c, p = null) {
   return all(
     nonEmpty(c),
     needsSection(c, "findings", [/^#{1,4}\s+[^\n]*\bfindings\b/im], "findings-heading"),
@@ -672,7 +672,7 @@ function commonLawStructural(c) {
     needsSection(c, "coverage-ledger", [/coverage[\s-]ledger/i], "coverage-ledger"),
     needsSection(c, "audit-trail", [/audit[\s-]trail/i], "audit-trail"),
     needs(c, [/\|/], "platform matrix"),
-    hasCoverageLedgerRow(c) ? ok() : fail("no_coverage_status_row"),
+    coverageStatusAsData(p) || hasCoverageLedgerRow(c) ? ok() : fail("no_coverage_status_row"),   // the recorded status first, the word as fallback: coverageStatusAsData() in common-law-coverage-status.mjs
   );
 }
 

package/driver/withheld-families.mjs

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// withheld-families.mjs — the reading turn's record of the waiting families it chose not to ask.
+//
+// On a crowded field the wider register families wait in the plan for the reading turn, which asks the
+// ones worth asking. A family it does not ask was never searched, and until this record nothing said
+// so: the turn's reason, when it gave one, sat in its prose note, where nothing reads it. So the turn
+// records each family it leaves unasked as `withheld-by-judgment` with its reason, the coverage form
+// carries a row per waiting family pre-settled from this record, and a family nobody judged is an
+// unsettled row the digest's gate refuses to pass.
+//
+// The reason is the run's record and the audit workbook's, never the report's: the coverage form keeps
+// these rows out of the ledger the report is built from (coverage-form.mjs, `family`).
+//
+// One file per axis, because the reading turn fans out one seat per axis and two seats writing one file
+// would lose each other's calls. The axis is bound by the server, never taken from the payload.
+import { readFileSync, writeFileSync, renameSync, existsSync, readdirSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { driverDir } from "../shared/driver-dir.mjs";
+import { awaitsReadingTurn } from "../providers/_shared/plan-guards.mjs";
+import { entryQuestionKey } from "./register-plan.mjs";
+import { seatBannedTokens } from "./coverage-form.mjs";
+
+export const WITHHELD_REASON_MAX = 600;
+const FILE_RE = /^withheld-families-(.+)\.json$/;
+
+export const withheldFamiliesPath = (runDir, axis) => driverDir(runDir, `withheld-families-${axis}.json`);
+
+const readJson = (p) => { try { return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null; } catch { return null; } };
+
+/** Every axis's record, merged: `{ [qid]: { axis, reason } }`. An unreadable file contributes nothing. */
+export function readWithheldFamilies(runDir) {
+  const out = {};
+  let names = [];
+  try { names = readdirSync(driverDir(runDir)); } catch { return out; }
+  for (const name of names) {
+    const m = FILE_RE.exec(name);
+    if (!m) continue;
+    const doc = readJson(driverDir(runDir, name));
+    for (const [qid, v] of Object.entries(doc?.families ?? {})) {
+      const reason = String(v?.reason ?? "").trim();
+      if (qid && reason) out[qid] = { axis: String(doc?.axis ?? m[1]), reason };
+    }
+  }
+  return out;
+}
+
+/**
+ * The waiting families on one axis, and which of them the reading turn has asked: a waiting row is asked
+ * when a question it did not wait for — a plan entry or one of this axis's supplementals — carries the
+ * same question key. PURE over its inputs.
+ */
+export function waitingFamiliesOn(plan, axis, supplementals = []) {
+  const entries = Array.isArray(plan?.entries) ? plan.entries : [];
+  const askedKeys = new Set([...entries.filter((e) => !awaitsReadingTurn(e?.when)), ...supplementals]
+    .filter((e) => e && !e.unsupported).map((e) => entryQuestionKey(e, plan)).filter(Boolean));
+  const waiting = entries.filter((e) => e?.axis === axis && awaitsReadingTurn(e?.when));
+  return {
+    waiting,
+    unasked: waiting.filter((e) => !askedKeys.has(entryQuestionKey(e, plan))),
+  };
+}
+
+/**
+ * Record families withheld on the bound axis. `families` is `[{ qids: [qid…] | qid, reason }]` — one
+ * reason may cover several families. Each qid must be a waiting family of this axis in the frozen plan;
+ * a reason must be the reader's words, since the audit workbook prints it. Accepts what is valid, names
+ * what it refused, and never throws.
+ */
+export function recordWithheldFamilies(runDir, { axis, families } = {}) {
+  const plan = readJson(driverDir(runDir, "register-plan.json"));
+  if (!plan || !Array.isArray(plan.entries)) return { refused: "no frozen register plan in this run — there are no waiting families to record against" };
+  if (!Array.isArray(families) || !families.length) return { refused: "families must list at least one { qids, reason }" };
+  const supp = readJson(join(runDir, "register-units", `${axis}-supplemental-plan.json`));
+  const { waiting, unasked } = waitingFamiliesOn(plan, axis, Array.isArray(supp?.entries) ? supp.entries : []);
+  const waitingQids = new Set(waiting.map((e) => e.qid));
+  const path = withheldFamiliesPath(runDir, axis);
+  const doc = readJson(path) ?? { axis, families: {} };
+  const recorded = [], rejected = [];
+  for (const item of families) {
+    const qids = (Array.isArray(item?.qids) ? item.qids : [item?.qids ?? item?.qid]).map((q) => String(q ?? "").trim()).filter(Boolean);
+    const reason = String(item?.reason ?? "").replace(/\s+/g, " ").trim();
+    if (!qids.length) { rejected.push({ qid: "", issue: "an item names no qid" }); continue; }
+    if (!reason) { for (const qid of qids) rejected.push({ qid, issue: "no reason — a withheld family is recorded with why it was not asked" }); continue; }
+    if (reason.length > WITHHELD_REASON_MAX) { for (const qid of qids) rejected.push({ qid, issue: `the reason runs to ${reason.length} characters; at most ${WITHHELD_REASON_MAX}` }); continue; }
+    const banned = seatBannedTokens(reason);
+    if (banned.length) { for (const qid of qids) rejected.push({ qid, issue: `the reason names ${banned.join(", ")} — the audit workbook prints it; say it in a lawyer's words` }); continue; }
+    for (const qid of qids) {
+      if (!waitingQids.has(qid)) { rejected.push({ qid, issue: `not a waiting family on axis "${axis}" in the frozen plan` }); continue; }
+      doc.families[qid] = { reason };
+      recorded.push(qid);
+    }
+  }
+  if (recorded.length) {
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ axis, families: doc.families }, null, 2) + "\n");
+      renameSync(tmp, path);
+    } catch (e) { return { write_failed: String(e?.message ?? e).slice(0, 200) }; }
+  }
+  const still = unasked.filter((e) => !doc.families[e.qid]).map((e) => e.qid);
+  return { axis, recorded, rejected, still_to_judge: still, waiting: waiting.length };
+}

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-artifacts-mcp
 
+## 0.3.3-beta.0
+
+No changes in this release.
+
 ## 0.3.2
 
 ### Patch Changes

package/mcp-server/lib/brief.mjs

@@ -92,9 +92,8 @@ export function buildBrief(run) {
   const tail = [product, dateStr ? `run ${dateStr}` : null].filter(Boolean).join(", ");
   lines.push(`**${subject}**${tail ? ` — ${tail}` : ""}.`);
 
-  const caption = clearance
-    ? (clearance.verdict?.statement ?? clearance.caption ?? "")
-    : plainClause(fm.overall_caption ?? "");
+  // The report's own conclusion, verbatim, after the rating (ruled 2026-09-22: the report is the master).
+  const caption = clearance ? (clearance.caption ?? "") : plainClause(fm.overall_caption ?? "");
   if (overall) lines.push(`**Overall risk: ${titleCase(String(overall))}.** ${caption}`.trim());
   if (run.state) {
     // a park is paused, not finished — say so plainly, and name the clock only where one exists
@@ -104,9 +103,8 @@ export function buildBrief(run) {
       : run.state === "recovering" ? ` — auto-recovery backoff, resumes ${run.recoveryResumesAt ? `at ${String(run.recoveryResumesAt).replace("T", " ").slice(0, 16)} UTC` : "on its own"}`
       : run.state === "parked-for-human" ? ` — parked by a runner stop (deploy/restart), resumes on the next runner activation` : "";
     lines.push(`Status: ${run.state}${paused}.`);
-    // The run's own sentence, composed once by the driver and rendered on every client surface. It says
-    // what the gate word used to be reached for, in the words the report itself uses.
-    if (run.statement) lines.push(String(run.statement));
+    // No second summary here: the rating and the report's conclusion above are the run's answer. The
+    // composed statement said "on hold" on runs nothing held.
   }
 
   let source = "none";
@@ -204,7 +202,7 @@ export function buildBrief(run) {
   return {
     runId: run.runId, markName: run.markName ?? clearance?.markName ?? fm.title ?? null,
     product,
-    overall, tier: run.tier ?? null, statement: run.statement ?? null, state: run.state ?? null, date: run.date ?? null,
+    overall, tier: run.tier ?? null, caption: run.caption ?? null, state: run.state ?? null, date: run.date ?? null,
     source, brief: lines.join("\n"),
   };
 }

package/mcp-server/lib/runs.mjs

@@ -102,7 +102,7 @@ function runFromStatusFile(statusFile, agent) {
     // assistant saw the gate's word and nothing beside it, which is the shape this whole item is about.
     // The verdict record holds the band for those runs, so it is read from there.
     state: s.state ?? null,
-    tier: s.tier ?? bandWord(s.verdict) ?? tierFromRecord(runDir), statement: s.statement ?? null, url: s.url ?? null,
+    tier: s.tier ?? bandWord(s.verdict) ?? tierFromRecord(runDir), caption: s.caption ?? null, url: s.url ?? null,   // the report's own conclusion, never a second summary (ruled 2026-09-22)
     markName: s.markName ?? null, ref: s.ref ?? null, classes: s.classes ?? null,
     stepN: s.stepN ?? null, stepLabel: s.stepLabel ?? null, stepTotal: s.stepTotal ?? null,
     failedStage: s.failedStage ?? null, reason: s.reason ?? null,

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3-beta.0",
   "license": "AGPL-3.0-only",
   "private": true,
   "description": "MCP server to interrogate clearotron trademark-clearance runs — list/read artifacts, trace the full decision flow, telemetry/cost, coverage, single-run search, and a gated single-step what-if. Imports the clearotron-driver read-only; touches no driver/template/deploy files.",

package/mcp-server/server.mjs

@@ -207,8 +207,9 @@ function runSummary(run) {
     // once. null where the registry cannot name it — the row says nothing rather than guessing, because
     // a hardcoded fallback is how a knockout once announced itself as a product it provably was not.
     product: productIdentityFor(run),
-    // The band and the run's own sentence; the gate's word stays in the run record (824).
-    state: run.state, location: run.location, tier: run.tier, statement: run.statement, url: run.url,
+    // The band and the report's own conclusion; the gate's word stays in the run record (824), and no
+    // second summary rides beside them (ruled 2026-09-22).
+    state: run.state, location: run.location, tier: run.tier, caption: run.caption, url: run.url,
     markName: run.markName, ref: run.ref, classes: run.classes,
     step: s.stepN ? `${s.stepN}/${s.stepTotal} ${s.stepLabel ?? ""}`.trim() : null,
     startedAt: run.startedAt, updatedAt: run.updatedAt, deliveredAt: run.deliveredAt,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.3.3-beta.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/dist/assets/{index-DMthc7PQ.js → index-GBbbyQxc.js}

@@ -12751,7 +12751,18 @@ function Logo({ markOnly = false }) {
 var ACTIVE_MS = 5e3;
 var IDLE_MS = 3e4;
 var BACKOFF_MS = 6e4;
-function useLoad(fetcher, deps) {
+var startedEarly = new Map();
+function startEarly(key, fetcher) {
+	if (!startedEarly.has(key)) startedEarly.set(key, fetcher());
+}
+function claimEarly(key) {
+	if (!key) return null;
+	const p = startedEarly.get(key);
+	if (!p) return null;
+	startedEarly.delete(key);
+	return p;
+}
+function useLoad(fetcher, deps, early) {
 	const [result, setResult] = (0, import_react.useState)(null);
 	const [loading, setLoading] = (0, import_react.useState)(true);
 	const [nonce, setNonce] = (0, import_react.useState)(0);
@@ -12764,7 +12775,7 @@ function useLoad(fetcher, deps) {
 		if (seenKey.current !== null && seenKey.current !== depsKey) setResult(null);
 		seenKey.current = depsKey;
 		setLoading(true);
-		fetcherRef.current().then((r) => {
+		(claimEarly(early) ?? fetcherRef.current()).then((r) => {
 			if (!live) return;
 			setResult(r);
 			setLoading(false);
@@ -15487,7 +15498,7 @@ function lastFinishedOf(row) {
 }
 var COMPACT_FROM = 5;
 function Home({ ctx }) {
-	const { result, reload } = useLoad(() => api.runsMine(), []);
+	const { result, reload } = useLoad(() => api.runsMine(), [], "runs:mine");
 	const allowanceOwner = ctx.owner ?? (ctx.me.accounts.length === 1 ? ctx.me.accounts[0] : null);
 	const { result: usageRes } = useLoad(() => allowanceOwner ? api.usage(allowanceOwner) : Promise.resolve({ kind: "pickAccount" }), [allowanceOwner]);
 	const allRuns = result?.kind === "ok" ? result.value : [];
@@ -16920,7 +16931,7 @@ function Clearances({ ctx }) {
 	const [query, setQuery] = (0, import_react.useState)("");
 	const [open, setOpen] = (0, import_react.useState)(new Set());
 	const [page, setPage] = (0, import_react.useState)(0);
-	const { result, reload } = useLoad(() => api.runsMine(), []);
+	const { result, reload } = useLoad(() => api.runsMine(), [], "runs:mine");
 	const allRuns = result?.kind === "ok" ? result.value : [];
 	const ownerFilter = ctx.owner;
 	const runs = (0, import_react.useMemo)(() => ownerFilter ? allRuns.filter((r) => runKey(r) === ownerFilter) : allRuns, [allRuns, ownerFilter]);
@@ -26744,6 +26755,13 @@ function screen(id, ctx) {
 		});
 	}
 }
+var EARLY_RUNS_PATHS = [
+	"/portal/home",
+	"/portal/clearances",
+	"/portal"
+];
+var here = window.location.pathname.replace(/[?#].*$/, "").replace(/\/+$/, "") || "/portal";
+if (EARLY_RUNS_PATHS.includes(here)) startEarly("runs:mine", () => api.runsMine());
 var root = document.getElementById("root");
 if (!root) throw new Error("#root is missing from index.html");
 (0, import_client.createRoot)(root).render((0, import_jsx_runtime.jsx)(import_react.StrictMode, { children: (0, import_jsx_runtime.jsx)(AppShell, { render: screen }) }));

package/portal-ui/dist/index.html

@@ -49,7 +49,7 @@
     -->
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700,900&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/portal/assets/index-DMthc7PQ.js"></script>
+    <script type="module" crossorigin src="/portal/assets/index-GBbbyQxc.js"></script>
     <link rel="stylesheet" crossorigin href="/portal/assets/index-5CCwiJG7.css">
   </head>
   <body>

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.3.3-beta.0",
   "license": "AGPL-3.0-only",
   "description": "The unified trademark portal UI. One address, one login: who you are decides what you see. Built as a static bundle, served by driver/portal-service.mjs — the browser never reaches profile-service or recipe-service.",
   "engines": {

package/providers/_shared/count.mjs

@@ -13,8 +13,8 @@
 //
 // SEAM (capabilities.countProbe) — WHERE the number comes from. Same three values enumerate.mjs
 // documents, same meanings:
-//   "endpoint" Clarivate. A real POST /count: cheap, works at ANY magnitude (209012 returned without
-//              complaint), fetches nothing. A true count-only call.
+//   "endpoint" Clarivate. A real POST /count: cheap, works at ANY magnitude, fetches nothing. A true
+//              count-only call.
 //   "cheap"    Corsearch. The count rides page 0 of a normal search (totalHitCount) — so it is one
 //              BILLABLE search with `limit:1 fields:["uri"]`, the smallest response the API will give.
 //              Cheap, not free: every count here is a metered call.

package/providers/_shared/enumerate.mjs

@@ -288,7 +288,18 @@ export function makeEnumerate(deps) {
     const tally = { "verified-zero": 0, enumerated: 0, crowd: 0, unenumerated: 0, error: 0 };
     for (const v of Object.values(term_counts)) tally[v.disposition] += 1;
     const unresolved = tally.crowd + tally.unenumerated + tally.error;
-    if (unresolved === 0 && records.length > 0) {
+    // A FULLY RESOLVED STACK IS A COMPLETE BAND, INCLUDING WHEN THE ANSWER IS ZERO. The comment below
+    // states the rule and the code then demanded a record anyway: `records.length > 0`. So a stack in
+    // which EVERY term resolved to verified-zero — nobody has filed any of these names — fell through
+    // to `incomplete`, which says nobody answered the question. The opposite is true: every term was
+    // asked and every one came back empty.
+    //
+    // It matters beyond the label. An `incomplete` parent is terminal for its when-guarded children, so
+    // a clean zero here held back everything waiting on it — and with the wider families now waiting on
+    // 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) {
       // every term resolved to verified-zero or fully-enumerated ⇒ the union of per-term enumerations IS
       // the complete stack (every record matching ≥1 name sits in some term's enumeration) — a true band.
       return { type: "text", text: JSON.stringify({ state: "enumerated", total_hits: stackTotal, count: records.length, records, term_counts }, null, 2) };
@@ -344,7 +355,9 @@ export function makeEnumerate(deps) {
     const tally = { "verified-zero": 0, enumerated: 0, crowd: 0, unenumerated: 0, error: 0 };
     for (const v of Object.values(class_counts)) tally[v.disposition] += 1;
     const unresolved = tally.crowd + tally.unenumerated + tally.error;
-    if (unresolved === 0 && records.length > 0) {
+    // 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) {
       // 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) };

package/providers/_shared/execute-plan.mjs

@@ -18,6 +18,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { nativeScriptIndexGap } from "./script-form.mjs";
 import { entryTermIssues, goodsTermsList } from "./term-shape.mjs";
+import { awaitsReadingTurn } from "./plan-guards.mjs";
 import { faultText, guardToolCall } from "./transport-guard.mjs";
 import { clipProviderText } from "./provider-text.mjs";   // — keep the discriminator
 
@@ -210,10 +211,13 @@ export function queryMarkTerms(e, query) {
   return Array.isArray(e?.terms) ? e.terms : e?.term != null ? [e.term] : [];
 }
 
+// The goods words ride after the class tag (close-verify reads that tag): a goods-narrowed question shares
+// predicate, term and classes with the identical one, and without them the two read as the same question.
 export const describePlanEntry = (e) =>
   `${e.predicate} ${e.terms ? e.terms.join(" OR ") : e.term}`
   + `${typeof e.owner === "string" && e.owner.trim() && String(e.predicate ?? "") !== "owner" ? ` owner:${e.owner.trim()}` : ""}`
-  + ` [cl ${(e.nice_classes ?? []).join(",")}]`;
+  + ` [cl ${(e.nice_classes ?? []).join(",")}]`
+  + `${goodsTermsList(e).length ? ` goods:${goodsTermsList(e).join(" OR ")}` : ""}`;
 
 // Compile one plan entry + its predicate params into the provider's query params (corsearch shapes by
 // default: names/name/owners/owner + nice_classes + regions).
@@ -576,6 +580,20 @@ export function makeExecutePlan(deps) {
     for (const e of targeted.filter((x) => !x.when)) await runEntry(e);
     const skipped = [];
     for (const e of targeted.filter((x) => x.when)) {
+      // A CROWD IS WHAT HOLDS A CHILD BACK, and only a crowd. `enumerated` is the state of a question
+      // that was answered — with records or with none: the ordinary search path returns it for a
+      // zero-record answer too, so a clean zero has always released its children here.
+      //
+      // Where that stopped being true was the RESCUE paths, and it is fixed there rather than here: a
+      // per-term or per-class stack in which every member came back a verified zero was falling through
+      // to `incomplete`, which says nobody answered. See enumerate.mjs — a fully resolved stack is a
+      // complete band whose answer is zero. `verified-zero` is a per-term DISPOSITION and never a band
+      // state (named-band.mjs BAND_STATES), so a guard testing for it here could never fire.
+      // THE READING-TURN WAIT: a family awaiting the reading turn is never released by a RESULT, so there is no
+      // state to read here and no seeded prior state that could release it on a warm followup either.
+      // The reading turn asks for it by minting a supplemental entry, which arrives as its own
+      // ungated entry — this one stands in the plan as the record of a question not asked.
+      if (awaitsReadingTurn(e.when)) { skipped.push(e.qid); continue; }
       if (stateByQid.get(e.when.runs_if_enumerated) === "enumerated") await runEntry(e);
       else skipped.push(e.qid);   // crowd/failed parent is TERMINAL for the fringe — by design, never an error
     }

package/providers/_shared/plan-guards.mjs

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// plan-guards.mjs — what a register plan entry's `when` guard means, read from one place.
+//
+// THE TWO WAITS A PLAN ENTRY CAN CARRY, and they are different questions.
+//
+//   `runs_if_enumerated: <parent qid>` is a fact about a RESULT: this slice runs if its parent question
+//   came back as a list rather than a crowd. A crowd parent is terminal for it.
+//
+//   `awaits_reading_turn: true` is a fact about JUDGMENT NOT YET MADE (ruled 2026-09-21): this family runs
+//   when the reading turn asks for it, having read the identical mark's own list and found it thin. No
+//   result releases it — not the identical question coming back as a comfortable list, not a clean
+//   zero, nothing. The ask arrives as a supplemental entry, so the guarded entry itself never runs: it
+//   stands in the plan as the record of a question deliberately not asked.
+//
+// WHY THIS IS ITS OWN MODULE, on the provider side, rather than a constant in the compiler. Both the
+// COMPILER (driver/register-plan.mjs, which writes the guard and joins it back to the band) and the
+// EXECUTOR (providers/_shared/execute-plan.mjs, which decides what to dispatch) must agree on what a
+// guard means, and a guard the executor does not recognise is not a guard at all — the entry runs as
+// though it were ungated, which is silently the opposite of what was asked for. The executor cannot
+// import the compiler: nothing under providers/ imports driver/, and inverting that for one predicate
+// would invert it for the whole provider tree. So the meaning lives here, where both sides can read
+// it, and neither side carries a second copy to drift.
+
+/** The guard a decision-10 family carries while it waits for the reading turn. Frozen: entries spread a copy. */
+export const AWAITS_READING_TURN = Object.freeze({ awaits_reading_turn: true });
+
+/** Is this guard the ruling-204 wait — the one no result can release? */
+export const awaitsReadingTurn = (when) => when?.awaits_reading_turn === true;
+
+/**
+ * The parent qid a guard waits on, or null where it waits on no question at all.
+ *
+ * Every caller that resolves a guard against a band, validates it against the plan's qids, or reports
+ * which question held an entry back goes through this. A ruling-204 wait names no qid, and a caller
+ * reading `when.runs_if_enumerated` directly would get `undefined` and then decide something about it
+ * — orphan it, look it up and miss, or print it.
+ */
+export const guardParentQid = (when) => (awaitsReadingTurn(when) ? null : when?.runs_if_enumerated ?? null);

package/providers/clarivate/src/capabilities.js

@@ -97,8 +97,7 @@ export const CAPABILITIES = Object.freeze({
   // fails loud with tooManyResults past 30000. There is no partial mode and no cursor.
   pagination: "single-shot",
   // …which is exactly why the enumerate ceiling must be tested BEFORE the search, via the cheap
-  // POST /count — it works at ANY magnitude (209012 returned without complaint) and returns per-office
-  // counts in one call.
+  // POST /count — it works at ANY magnitude and returns per-office counts in one call.
   countProbe: "endpoint",
   // A count CAN be narrowed to live filings here — queryOptions.activeOnly (buildSearchRequest's
   // `active_only`). Declared because it diverges from corsearch, which has no status clause at all;
@@ -107,7 +106,8 @@ export const CAPABILITIES = Object.freeze({
   countStatusFilter: "live",
   // JSON body, not a URI: the bound is the parser's own document-nesting cap, which the vendor names in
   // the refusal it answers a stack wider than this with. Not a URI length, so widening is not the fix.
-  maxOrWidth: 500,
+  // A 498-term stack is refused at that cap and a 496-term stack is not, so 496 is the declared width.
+  maxOrWidth: 496,
   // ONE call: INT_CLASS_NUMBER value "9 OR 28 OR 41 OR 42" (or "9,28,41,42") = the deduplicated union.
   classFilter: "native",
   // POST /text, EXACTLY 100 ids per call — a longer list is refused — and the call is BILLED: screening an
@@ -239,6 +239,16 @@ export const CAPABILITIES = Object.freeze({
   goodsTextMultiWord: "ordered-phrase",
   // Several goods terms ride ONE clause joined by OR — this register expresses a list natively.
   goodsTextListOr: true,
+  // ── THE SHORTEST TERM THE CONTAINS FORM ACCEPTS: none known, so none declared ───────────────────
+  //
+  // No vendor document available to this repository states one: the vendor publishes no public
+  // reference for this search API, and none was found on 2026-09-22. What is measured is narrower and is
+  // handled in core.js: a ONE-character first or last token inside a phrase chain is refused (HTTP
+  // 500), and two characters are answered. A two-letter `*TERM*` on its own is not recorded either way.
+  //
+  // `null` means the compiler keeps asking the contains form at every length, which is what this
+  // register has always been sent. A declared number must come from the vendor, not from a guess.
+  containsMinLength: null,
   // The operator the goods clause rides. `EQUALS` on WHOLE WORDS: `CONTAINS` is a hard 400 here
   // exactly as it is on APPLICANT_NAME, and so is a mid-word wildcard. Several words are asked for
   // with `OR` inside the value.
@@ -285,7 +295,7 @@ export const CAPABILITIES = Object.freeze({
   // WIRED: providers/clarivate/src/core.js builds its enumerate from
   // makeEnumerate({ capabilities: {...CAPABILITIES.kernel} }) — these values are the LIVE seam settings,
   // no longer a design note. pageGuard is 1 because /search is single-shot: there is no page 2 to
-  // fetch, so the guard can only ever be a backstop. namesChunkDefault = maxOrWidth (500): the kernel
+  // fetch, so the guard can only ever be a backstop. namesChunkDefault = maxOrWidth (496): the kernel
   // chunks a wide OR-stack to the parser's nesting bound before it reaches the wire.
   kernel: Object.freeze({
     countProbe: "endpoint",
@@ -293,7 +303,7 @@ export const CAPABILITIES = Object.freeze({
     pageSize: 100,
     pageGuard: 1,                          // single-shot: there is no page 2
     ceilingDefault: 600,
-    namesChunkDefault: 500,
+    namesChunkDefault: 496,
     providerWindow: "30000-result hard ceiling (tooManyResults, fails loud)",
     // POST /search returns BARE GUIDS — the search row carries no mark text, classes, status or owner.
     // POST /text (the screen call) is therefore the SOLE content source for an enumerated band, which