clearotron 0.3.2-beta.0 → 0.3.2-beta.2

package/.env.example

@@ -480,6 +480,25 @@ CLEAROTRON_CUT_REF=
 # effect: tuning
 CLEAROTRON_RELEASE_WAIT_MS=
 
+# A GitHub token carrying Actions read and write. The release workflow supplies it from a repository
+# secret so that a cut does not wait for a person to approve the version pull request's parked CI run:
+# that run is authored by the repository's own Actions bot, and GitHub parks bot-authored runs as
+# `action_required`. The built-in token cannot approve a run — self-approval is blocked deliberately —
+# which is why this is a second, separate credential.
+#
+# NEVER SET THIS ON A DEPLOYMENT. No installed instance reads it and no clearance run reaches it. It is
+# written down here because shipped code reads it, and every name shipped code reads has a row; the
+# catalogue is the contract, not a list of things you are expected to set.
+#
+# UNSET IS THE ORDINARY CASE AND NOT A MISCONFIGURATION. The script names the absent token on stdout
+# and exits successfully, and the version run then waits for a person exactly as it did before the
+# token existed. Nothing fails and no run changes its conclusion.
+#
+# It carries no effect declaration because the closed vocabulary has no class that is true of it: the
+# credential class claims a run refuses at preflight when the name is absent, and this one does not
+# refuse at all. Read by scripts/release-approve-parked.mjs.
+ACTIONS_APPROVE_TOKEN=
+
 # The trickle floor: the fewest output tokens per second of ACTIVE time (elapsed minus tool wait) a
 # model turn may produce before it is stopped as a stall. Unset uses 1. A stage streaming a token every
 # few seconds holds off both other clocks — the stall clock resets on any byte, and the no-progress

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "0bc01b5d6cda940a40dc2fb7da2ae5f83caf3f5b",
-  "version": "0.3.2-beta.0"
+  "commit": "8393489759f73ec4177b2fce74005780b7b4a567",
+  "version": "0.3.2-beta.2"
 }

package/docs/architecture/04-configuration-reference.md

@@ -296,6 +296,7 @@ because the rule is about what PRODUCT CODE reads, not about what a run reads.
 | `CLEAROTRON_UPDATER_STAMP` | `_updater-identity.json` beside the update script, in the directory the updater runs from | The full path of the file in which the updater that deploys this box records which copy of itself ran. The updater writes it and deploy health reads it under this one name, so a box that moves the stamp sets it once for both. On a box with no updater unit, setting it says an updater exists elsewhere and is to be judged. Effect class `deployment`. |
 | `CLEAROTRON_CUT_REF` | `HEAD` | Which ref the cut decision reads the version from. **Read only by the release workflow, never set on a deployment.** The jobs that ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref and `HEAD` there is that ref rather than the branch they are deciding about. A job that asks the wrong subject gets a confident wrong answer. |
 | `CLEAROTRON_RELEASE_WAIT_MS` | 25 minutes | How long a requested cut waits for the version pull request to merge itself before giving up. **Read only by the release workflow.** A rehearsal sets it to `0` so the wiring is exercised without holding a runner. Giving up is a quiet success by design — the scheduled run underneath catches a cut whose wait expired — so this budget failing shows up as a slow job rather than a red one. |
+| `ACTIONS_APPROVE_TOKEN` | unset | A GitHub token with Actions read and write, used to approve the version pull request's parked CI run so a cut does not wait for a person. **Read only by the release workflow, never set on a deployment.** The built-in token cannot approve a run — GitHub blocks self-approval — so this is a second, separate credential. Unset is the ordinary case and not an error: the script names the absent token and exits successfully, and the version run waits for a person as it did before. Actions write is broader than approval alone — it also dispatches workflows, cancels any run in the repository and deletes run logs. |
 | `CLEAROTRON_AGENT_MCP_URL` | unset (⇒ `null`) | The API-key MCP door advertised to a signed-in client. Null until that door is deployed, and the UI keeps its honest empty state rather than inventing a URL. |
 | `CLEAROTRON_AGENTS` | derived | Comma-separated agent ids for `scripts/purge-runs.mjs` to sweep. |
 | `CLEAROTRON_E2E_DIR` | **none — the script refuses without it** | The config repo's `e2e/` directory. There is one suite and it is not in this repo (ruling 2026-08-07), so the comparison script names the variable rather than defaulting anywhere. |

package/docs/architecture/05-config-governance.md

@@ -495,7 +495,15 @@ origin; all portal config lives server-side in portal-service.
 
 These are read by the release workflow and by nothing a deployment runs. They are listed here because a
 name absent from this register is a name nobody can look up, not because an operator has any reason to set
-one — and setting either on a box does nothing at all.
+one — and setting any of them on a box does nothing at all.
+
+`ACTIONS_APPROVE_TOKEN` (unset) — a GitHub token with Actions read and write, used to approve the
+version pull request's parked CI run so that a cut does not wait for someone to click. That run is
+authored by the repository's own Actions bot and GitHub parks bot-authored runs; the built-in token
+cannot release one, because self-approval is blocked deliberately. Unset is the ordinary case: the
+script names the absent token and exits successfully, and the run waits for a person as before.
+Actions write is wider than approving — it also dispatches workflows, cancels any run in the
+repository and deletes run logs — so it is worth rotating on the same schedule as a deploy key.
 
 `CLEAROTRON_CUT_REF` (default `HEAD`) — which ref the cut decision reads the version from. The jobs that
 ask about `main` set it to `origin/main` explicitly, because their checkout is pinned to the run's own ref

package/driver/CHANGELOG.md

@@ -1,5 +1,18 @@
 # clearotron-driver
 
+## 0.3.2-beta.2
+
+### Patch Changes
+
+- 8642064: Fixed: On one register the "Filings containing the name" figure counted only identical filings. A report could therefore show a field as far less crowded than it really is. That column now asks the register the question its label promises. Where a register cannot answer a given kind of search, the figure is reported as unavailable rather than filled in from a narrower one.
+
+## 0.3.2-beta.1
+
+### Patch Changes
+
+- 2a81abc: New: A report can now show how much was searched to reach its answer. It records the names read and cleared, the records read in each country, and the checks made. Countries where nothing was found are included.
+- 2a81abc: Fixed: The conditions listed on a report are now written in plain legal English, matching the summary line above them. One condition could previously appear as an internal engine note with counts and identifiers in it.
+
 ## 0.3.2-beta.0
 
 ### Patch Changes

package/driver/contract-e3-backlog.mjs

@@ -638,7 +638,7 @@ export const E3_BACKLOG = [
     where: "driver/stages.mjs:3470",
     surface: "stage-message",
     evidence: "EVERY \"Grounded profile\" section MUST start its body with the line \"- ord: <N>\" naming which finding it grounds (use the ordinal from this list; a profile that grounds no listed finding omits the line)",
-    reparsedBy: "driver/publish/parse.mjs:339 parseCaseLawProfiles (\"the optional '- ord: <N>' first body line … gives an EXACT join\"); driver/findings-model.mjs:273 /^-\\s*ord:\\s*(\\d+)\\s*$/m; driver/publish/index.mjs:776",
+    reparsedBy: "driver/publish/parse.mjs:339 parseCaseLawProfiles (\"the optional '- ord: <N>' first body line … gives an EXACT join\"); driver/findings-model.mjs:273 /^-\\s*ord:\\s*(\\d+)\\s*$/m; driver/publish/index.mjs:778 runOrigins",
     removedByMove: "NOTHING ON THE #850 PLAN REMOVES THIS",
   },
   {

package/driver/driver.config.mjs

@@ -1184,8 +1184,16 @@ export const PROVIDERS = {
         // modes, not strategies, and the API rejects them in the strategies array. These wrappers
         // hand-built the vendor shape and so were untouched by that fix — the translator is the one
         // place that knows which mode rides which request shape, and every caller must go through it.
-        const r = await core.doCountHits(process.env.SIGNA_API_KEY, base,
-          core.toSignaParams({ name, match_mode: matchMode || "exact", nice_classes: classes, regions }),
+        // A MODE THIS PROVIDER CANNOT EXPRESS REFUSES THE CELL, rather than being answered by a
+        // different predicate's number. The translator names it; this turns it into an honest unknown,
+        // which the count kernel already treats as a disclosed gap. The alternative is what this
+        // issue was: a narrower query answering under the wider query's label, invisibly.
+        const signaParams = core.toSignaParams({ name, match_mode: matchMode || "exact", nice_classes: classes, regions });
+        if (signaParams.unsupported_match_mode) {
+          return { ok: false, total: null, unsupported: true,
+            cause: `this register provider cannot express the "${signaParams.unsupported_match_mode}" match mode, so this count is UNKNOWN — it is not answered with a different predicate's number` };
+        }
+        const r = await core.doCountHits(process.env.SIGNA_API_KEY, base, signaParams,
           { kind: "count", agentId, sessionKey, sessionId: null, recordLog });
         const text = typeof r?.text === "string" ? r.text : "";
         if (text.startsWith("ERROR")) return { ok: false, cause: text.slice(0, 200) };
@@ -1207,8 +1215,16 @@ export const PROVIDERS = {
       catch (e) { return { ok: false, records: null, reason: `plugin core unavailable: ${e.message}` }; }
       const base = process.env.SIGNA_BASE_URL || core.DEFAULT_BASE;
       try {
+        // The listing takes the same refusal as the count above, and for the same reason one level on:
+        // a narrower search here returns FEWER records under the wider query's name, so the listing
+        // would under-report and read as complete.
+        const signaListParams = core.toSignaParams({ name, match_mode: matchMode || "exact", nice_classes: classes, regions });
+        if (signaListParams.unsupported_match_mode) {
+          return { ok: false, records: null,
+            reason: `this register provider cannot express the "${signaListParams.unsupported_match_mode}" match mode, so this listing was not taken — it is not answered with a narrower search` };
+        }
         const r = await core.doSearch(process.env.SIGNA_API_KEY, base,
-          { ...core.toSignaParams({ name, match_mode: matchMode || "exact", nice_classes: classes, regions }), limit },
+          { ...signaListParams, limit },
           { kind: "search", agentId, sessionKey, sessionId: null, recordLog });
         const text = typeof r?.text === "string" ? r.text : "";
         if (text.startsWith("ERROR")) return { ok: false, records: null, reason: text.slice(0, 200) };

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.2-beta.0",
+  "version": "0.3.2-beta.2",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/partial-payload-baseline.json

@@ -56,7 +56,7 @@
         "methodology",
         "handling_note"
       ],
-      "why": "a caption-only call renders 149B, clears the 120-char floor, and ships a SECTION OF THE CLIENT'S ONE REPORT without the 'Checks we ran' bullets, the methodology or the handling note. Traced: report-overview.md is the head of report.md (assembleReportMd() in pipeline.mjs) which renders to the HTML (publish/index.mjs:648). The 'Only you can close these' register is NOT lost — it is code-built from findings.json under spec 64's 'code wins' ruling."
+      "why": "a caption-only call renders 149B, clears the 120-char floor, and ships a SECTION OF THE CLIENT'S ONE REPORT without the 'Checks we ran' bullets, the methodology or the handling note. Traced: report-overview.md is the head of report.md (assembleReportMd() in pipeline.mjs) which renders to the HTML (publish/index.mjs:649 publishReport). The 'Only you can close these' register is NOT lost — it is code-built from findings.json under spec 64's 'code wins' ruling."
     },
     {
       "tool": "record_prelim_variants",

package/driver/pipeline.mjs

@@ -10,7 +10,7 @@ import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, copyFil
 import { createHash } from "node:crypto";
 import { join, dirname, basename, resolve } from "node:path";   // resolve: the resume line must work from any cwd
 import { driverDir, driverRel, ensureDriverDir } from "../shared/driver-dir.mjs";   // — one definition of where `_driver/` is
-import { terminalClampDecision, orderClausesForLede } from "./terminal-clamp.mjs";   // — deliver and clamp, never withhold
+import { terminalClampDecision, orderClausesForLede, clientConditions } from "./terminal-clamp.mjs";   // — deliver and clamp, never withhold
 import { recordSpan } from "./attributed-span.mjs";   // — driver work the decomposition can attribute
 import { fileURLToPath } from "node:url";
 import { runStage, correctionHint, gridLedgerNameFor, draftCarryEligible, toolWrittenArtifact, selectEngine } from "./gateway.mjs";
@@ -13006,7 +13006,7 @@ async function pipelineInner(job, opts = {}) {
       const statement = riskStatement({ tier: derived.tier, verdict, reasons: reasonsOut, clauses: orderedClauses,
         basis: isRegisterOnly(ctx.searchPolicy) ? "register-only" : null });
       const tmp = driverDir(run.runDir, "verdict.json.tmp");
-      writeFileSync(tmp, JSON.stringify({ ts: new Date().toISOString(), verdict, reasons: reasonsOut, kinds: kindsOut,
+      writeFileSync(tmp, JSON.stringify({ ts: new Date().toISOString(), verdict, reasons: reasonsOut, clauses: orderedClauses, kinds: kindsOut,
         tier: derived.tier, badge: derived.badge, gaugeIndex: derived.gaugeIndex, maxComposite: derived.maxComposite,
         band: derived.band ?? null, statement, stance: verdictStance(verdict) }, null, 2));
       renameSync(tmp, driverDir(run.runDir, "verdict.json"));
@@ -14859,7 +14859,7 @@ async function pipelineInner(job, opts = {}) {
     let emailVerdictOpts = { productName: emailProductName ?? undefined };
     // SPREAD, never reassign: this used to replace the whole object, which would now drop productName
     // above on every run that has a verdict sidecar — i.e. on every healthy run, and on no test.
-    try { const v = JSON.parse(readFileSync(driverDir(run.runDir, "verdict.json"), "utf8")); emailVerdictOpts = { ...emailVerdictOpts, verdict: v.verdict, conditions: v.reasons, tier: v.tier, statement: v.statement ?? null }; } catch { /* legacy path — no row */ }
+    try { const v = JSON.parse(readFileSync(driverDir(run.runDir, "verdict.json"), "utf8")); emailVerdictOpts = { ...emailVerdictOpts, verdict: v.verdict, conditions: clientConditions(v), tier: v.tier, statement: v.statement ?? null }; } catch { /* legacy path — no row */ }
     // wp50 — thread the findings too: the table overlay's rating cells are code-bound to the canonical
     // ratings (joinFindingToBlock), never the summary's own words.
     try { emailVerdictOpts.findings = parseFindingsJsonLenient(readFileSync(P.findings, "utf8"))?.findings ?? undefined; } catch { /* no findings — table falls back to the summary words */ }

package/driver/portal-families.mjs

@@ -9,7 +9,7 @@
 //
 // ── why this is a sidecar and not a field in meta.json ────────────────────────────────────────────────
 //
-// The same reason `archive-tags.json` is one, recorded at publish/index.mjs:338: "meta.json is rewritten
+// The same reason `archive-tags.json` is one, recorded at publish/index.mjs:377 ARCHIVE_TAGS_FILE: "meta.json is rewritten
 // on every republish so a flag there would be lost." That is not hypothetical here — a `rerender-all`
 // pass over the pool is a live plan, and a family written into meta would be erased by the very operation
 // meant to bring old reports up to date. Curation state that a person entered by hand must outlive a

package/driver/predelivery-lint.mjs

@@ -32,6 +32,7 @@ import { writeUpViolations, writeUpMessage } from "./narrative-write-ups.mjs";
 import { findRegistryArithmeticIssues, findRegistryViolations, splitBlocks } from "./registry-fidelity.mjs";
 import { CLIENT_TIER_BY_COMPOSITE, joinFindingToBlock, parseBlockOrd, worstLiveBand, NO_RATED_CONFLICTS, deriveActionConditions, isUnconditionalProceed, verdictStance, joinAskToAnswer, projectAssessmentField, POSITION_REQUIRED_DISPOSITIONS, OFF_FIELD_GROUNDS, FINDINGS_SCHEMA_VERSION, netChainMarkers, STATEMENT_CLAUSE_MAX } from "./findings-model.mjs";
 import { normalizeBand } from "./framework.mjs";
+import { clientConditions, ENGINE_TOKEN_RE } from "./terminal-clamp.mjs";   // the reader's clause per condition, and the token shape it may never carry
 import { knockoutNoteView, REQUEST_NOTE_WORDS, REQUEST_SUBJECT_WORDS } from "./findings-model.mjs";   // one reader for where a note prints
 import { isEngineAppendedCaveat } from "./verify-knockout.mjs";   // ONE derivation for "the engine appended this caveat, not a seat"
 
@@ -1961,6 +1962,26 @@ export function verdictActionsCoherenceChecks({ actionsRegister, findings, verdi
 // the conditional FORM riskStatement composes ("<Tier> — conditional on: <facts>"), never a wording
 // regex. Legacy sidecars (no stance) get the tier + unconditional-proceed checks only — judged
 // against the wording THEIR era composed (the retired-phrase exemption below), never the new form.
+// ── THE CONDITIONS A CLIENT READS SPEAK A LAWYER'S NOUNS ────────────────────────────────────────────
+// The sidecar carries two texts per condition — a run-record `reason` that may name tokens, counts and
+// record ids, and the reader's `clause`. `clientConditions` is the one reader of that pair, so this
+// check asks the question over what a surface actually renders rather than over either array.
+//
+// IT FIRES ON A LEGACY SIDECAR, DELIBERATELY. A run recorded before clauses were persisted has none, so
+// every condition falls back to its run-record reason and a token-bearing one flags here. That is the
+// honest reading: the delivered page for that run does carry the token, and re-generating the run is
+// what clears it. A flag, never a withholding — the report ships and the operator sees where the gap is.
+export function clientConditionVoiceChecks({ verdictDoc }) {
+  if (!verdictDoc) return [];
+  const carrying = clientConditions(verdictDoc)
+    .map((c) => ({ c, m: String(c).match(ENGINE_TOKEN_RE) }))
+    .filter((x) => x.m);
+  return [check("client-condition-voice", "verdict", "report", carrying.length === 0,
+    carrying.length
+      ? `${carrying.length} delivered condition${carrying.length === 1 ? "" : "s"} carr${carrying.length === 1 ? "ies" : "y"} an engine identifier, so the client's "conditional on:" list reads the run record rather than the reader's sentence: ${carrying.slice(0, 3).map((x) => `"${x.m[0]}"`).join(", ")}${carrying.length > 3 ? ` (+${carrying.length - 3} more)` : ""}. The clause exists at the clamp site; persist it and this list takes it. A sidecar written before clauses were persisted flags until the run is re-generated.`
+      : "")];
+}
+
 export function statementCoherenceChecks({ verdictDoc }) {
   if (!verdictDoc?.statement) return [];
   const st = String(verdictDoc.statement), tier = String(verdictDoc.tier ?? "");
@@ -2292,7 +2313,8 @@ export function runLint({ depth, commonLawGrid, matterContext, clientPartyName,
   if (findings && clientSummaryMd) checks.push(...clientTierChecks({ clientSummaryMd, findings, manifest }));   // A2 (doc 50: band words via the frozen manifest)
   if (verdictDoc?.tier && reportMd) checks.push(...overallTierChecks({ reportMd, verdictDoc }));         // wp50/wi2
   checks.push(...verdictActionsCoherenceChecks({ actionsRegister, findings, verdictDoc }));              // spec 64
-  checks.push(...statementCoherenceChecks({ verdictDoc }));                                              // spec 64
+  checks.push(...statementCoherenceChecks({ verdictDoc }));
+  checks.push(...clientConditionVoiceChecks({ verdictDoc }));                                         // — the reader's clause, not the run record                                              // spec 64
   checks.push(...conditionalTextCoherenceChecks({ reportMd, clientSummaryMd, verdictDoc }));             // qw/verdict-text-coherence — CONDITIONAL badge vs clean-outcome prose
   checks.push(...prescriptionProseChecks({ reportMd, clientSummaryMd, findings, fourAnswers }));         // PR-3 report voice — facts that condition, never advice; flag-only (P5: the findings-derived prose is a delivered surface too)
   checks.push(...onlyYouRegisterChecks({ actionsRegister, findings, reportMd }));                        // spec 64

package/driver/publish/index.mjs

@@ -16,6 +16,7 @@ import { buildAudit } from './xlsx.mjs';
 import { parseFindingsJson, parseFindingsJsonLenient, deriveDisplayVerdict, joinFindingToBlock, CLIENT_TIER_BY_COMPOSITE, projectCoverageJudgment } from '../findings-model.mjs';
 import { readStore, requiredAbsent, nonClosingAbsences } from './publish-inputs.mjs';   // — and why an absence did not close
 import { clearanceReportData } from './report-data.mjs';
+import { searchDepthRecord } from './search-depth.mjs';   // how much was read to reach the answer, as counts and tokens
 import { parseFrameworkManifest } from '../framework.mjs';
 import { rollupTokens } from '../tokens.mjs';
 import { reportIdentityFor, productCoverageNote, isRegisterOnly } from '../search-policy.mjs';
@@ -1053,7 +1054,29 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
   // worse demo than no toggle.
   const reportNav = siteNav(poolRoot, 'report', null, '../', { anon: false });
   // `demoData` is resolved above the report.md write — one answer, every surface.
-  writeRO('report.html', renderHtml(parsed, findings, coverage, { demoData, productName, depthNote, scopeBasis, auditFile: auditFile || undefined, runId, delivery: deliv, recordsByUri, contextNotes, coverageJudgment: coverageJudgmentDisplay, markAssessment, fourAnswers, homeHref: '../index.html', nav: reportNav, chromeHref: '../assets/chrome.css', issued, asOf, verdictInfo, framework, searchedJurisdictions, caseLawByOrdinal, caseLawNotice, enforcerSignals, recordOrigin, recordOrigins: runOrigins, recordCitation: runProviderConf?.recordCitation ?? null, recordLinks: officeLinks?.byUri ?? null, providerLabel, seniorRights, findingsSchemaVersion }));
+  // ── HOW MUCH WAS READ TO REACH THE ANSWER ──────────────────────────────────────────────────────
+  // Derived here rather than in a stage so a REPUBLISH of an archived run picks the fields up with no
+  // re-run: every source below is something the run already wrote. Best-effort per source, in the house
+  // pattern — a run with no grid or no case-law layer still gets its register counts, and the absent
+  // ones report themselves as zero or `not-in-scope` rather than as a gap nobody can see.
+  let searchDepth = null;
+  try {
+    const runBase = runDir ?? dirname(reportMd);
+    const recDir = join(runBase, '_records');
+    const rdText = (p2) => { try { return readFileSync(p2, 'utf8'); } catch { return ''; } };
+    const rdJson = (p2) => { try { return JSON.parse(readFileSync(p2, 'utf8')); } catch { return null; } };
+    searchDepth = searchDepthRecord({
+      auditMd: (auditMd && existsSync(auditMd)) ? rdText(auditMd) : '',
+      recordIndex: recordsByUri ?? {},
+      recordFileNames: existsSync(recDir) ? readdirSync(recDir) : [],
+      commonLawGrid: rdJson(join(runBase, 'common-law-grid.json')),
+      caseLawText: rdText(join(dirname(reportMd), 'case-law-findings.md')),
+      registerPlan: rdJson(driverDir(runBase, 'register-plan.json')),
+    });
+    writeRO('search-depth.json', JSON.stringify(searchDepth, null, 2));
+  } catch { /* the depth record is additive — a publish never fails for want of it */ }
+
+  writeRO('report.html', renderHtml(parsed, findings, coverage, { demoData, productName, depthNote, scopeBasis, auditFile: auditFile || undefined, runId, delivery: deliv, recordsByUri, contextNotes, coverageJudgment: coverageJudgmentDisplay, markAssessment, fourAnswers, homeHref: '../index.html', nav: reportNav, chromeHref: '../assets/chrome.css', issued, asOf, verdictInfo, framework, searchedJurisdictions, caseLawByOrdinal, caseLawNotice, enforcerSignals, recordOrigin, recordOrigins: runOrigins, recordCitation: runProviderConf?.recordCitation ?? null, recordLinks: officeLinks?.byUri ?? null, providerLabel, seniorRights, findingsSchemaVersion, searchDepth }));
   // ONE report (spec 2026-07-30 §5): report.client.html is no longer written. The knockout lane's own
   // collapse note is the precedent: "two renderings of one run is how the wrong link gets sent". The
   // client host serves the same report.html through the portal's readReport() (cleaning built in) — its

package/driver/publish/report-data.mjs

@@ -32,6 +32,7 @@
 // testable offline and a republished archived run reproduces its file deterministically.
 import { stripInternal, dropLabelledInternals, stripEngineInternals } from './parse.mjs';
 import { DISPOSITION_GROUP, deriveActionConditions, projectAssessmentField } from '../findings-model.mjs';
+import { clientConditions } from '../terminal-clamp.mjs';   // the reader's clause per condition — one definition, shared with the email
 
 // The client scrub choke point: the three existing rules, in the order the client HTML applies them.
 // Structural values (uris, enum tokens, dates, numbers) do not route through here — they carry no prose.
@@ -101,7 +102,7 @@ export function clearanceReportData({
       badge: verdictInfo.badge ?? null,
       band: verdictInfo.band ?? null,
       statement: clientText(verdictInfo.statement),
-      conditions: (Array.isArray(verdictInfo.reasons) ? verdictInfo.reasons : []).map(clientText).filter(Boolean),
+      conditions: clientConditions(verdictInfo).map(clientText).filter(Boolean),
     } : null,
     caption: clientText(caption),
     jurisdiction: clientText(jurisdiction),

package/driver/publish/search-depth.mjs

@@ -0,0 +1,178 @@
+// 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
+//
+// ── HOW MUCH WAS READ TO REACH THE ANSWER, AS MACHINE FIELDS ────────────────────────────────────────
+//
+// A deeper search reads more and finds no more, and until now the report could not say so: a run that
+// read 1,455 register records and cleared 432 near-names delivered a page showing 13 findings and
+// nothing of the rest. The negative evidence — the work that came back clean — existed only in the
+// audit workbook, in the engine's own working voice.
+//
+// This module derives that body of negative evidence from artifacts the run has ALREADY written. It
+// starts no search, asks no model and composes no sentence: every field here is a count, a token, or a
+// fact copied from a record. That is the whole design constraint, and it is why this lives at publish
+// time rather than in a stage — a republish of an archived run picks the fields up with no re-run.
+//
+// THE GROUP KEY IS THE PART THAT COULD HAVE GONE WRONG. Each cleared near-name is grouped by WHY it was
+// cleared, and the honest source is the register providers' closed screening vocabulary, which every
+// provider computes identically: `drop:dead` (a confidently dead status), `drop:out-of-class` (live but
+// no in-scope-class overlap), `surface:in-scope-live` / `surface:all-class` (a real in-scope candidate),
+// `deepfetch:ambiguous` (status unrecognised). A verdict and the record's own status are facts. The
+// engine's `result` paragraph is not a fact about the record, it is prose about the reasoning, and
+// classifying on it is how a report ends up asserting a reason the record does not support.
+//
+// SO THIS EMITS THREE GROUPS, NOT FOUR, AND THAT IS DELIBERATE. `dead-filing` and `different-goods` fall
+// straight out of the vocabulary. Everything else is `other` — read, in scope, and cleared on judgment.
+// A fourth group, "different word", cannot be derived from a screening verdict or a status: a name
+// cleared because it reads as a different word was `surface:in-scope-live` like any other real
+// candidate, and only the reasoning says otherwise. Splitting it would mean either reading that prose
+// or inventing a similarity rule here, and a wrong group on a client page is worse than a coarse
+// honest one. Recorded on the issue rather than guessed at.
+//
+// BREAK MATRIX:
+//   · a dead status groups as dead-filing            → break: drop the status arm, arm 1 red
+//   · an out-of-class verdict groups as goods        → break: map it to other, arm 2 red
+//   · an in-scope live name groups as other          → break: classify on the result prose, arm 3 red
+//   · a per-country count names every country read   → break: count only countries with a finding, arm 5 red
+//   · court decisions distinguishes four states      → break: collapse none-found into not-checked, arm 6 red
+
+/** The closed set a group key may take. The renderer's headings are keyed on these, never on prose. */
+export const CLEARED_GROUPS = Object.freeze(["dead-filing", "different-goods", "other"]);
+
+/** Statuses a register reports for a filing that is no longer live. Surfaced by the provider, never date-cut. */
+const DEAD_STATUS_RE = /^(?:CANCELLED|CANCELED|EXPIRED|ABANDONED|WITHDRAWN|REFUSED|DEAD|LAPSED|INVALID|SURRENDERED)\b/i;
+
+/**
+ * Why this near-name was cleared, from the two fields the engine records per name. PURE.
+ *
+ * @param {{screenVerdict?: string, status?: string}} a
+ * @returns {"dead-filing"|"different-goods"|"other"}
+ */
+export function groupForCleared({ screenVerdict, status } = {}) {
+  const v = String(screenVerdict ?? "").trim().toLowerCase();
+  const s = String(status ?? "").trim();
+  if (v.startsWith("drop:dead") || DEAD_STATUS_RE.test(s)) return "dead-filing";
+  if (v.startsWith("drop:out-of-class")) return "different-goods";
+  return "other";
+}
+
+/** One `## NRn` block's `- key: value` lines. The audit is written by a deterministic builder, so this is a contract. */
+const field = (block, key) => (block.match(new RegExp(`^- ${key}:\\s*(.*)$`, "m")) || [])[1]?.trim() ?? "";
+const noteField = (notes, key) => (notes.match(new RegExp(`${key}=([^;]+)`)) || [])[1]?.trim() ?? "";
+
+/**
+ * Every near-name the run read and cleared, register and web, as facts. PURE.
+ *
+ * The register rows carry no sentence: mark, owner, country, class, status, group and the record URI.
+ * The reasoning stays in the audit workbook, where the engine already wrote it — the owner ruled against
+ * a second client-facing sentence per name (2026-09-16), so this deliberately does not carry `result`.
+ *
+ * @param {string} auditMd            the run's `audit.md`
+ * @param {Record<string, object>} recordIndex  fetched records by URI, for the fuller mark and owner
+ */
+export function clearedNames(auditMd, recordIndex = {}) {
+  const out = { register: [], web: [] };
+  for (const block of String(auditMd ?? "").split(/^## /m).slice(1)) {
+    const title = block.split("\n")[0].trim();
+    const layer = field(block, "source_layer");
+    if (/^NR\d+/.test(title) && /register/i.test(layer)) {
+      const notes = field(block, "notes");
+      const uri = (notes.match(/URI (\S+?);/) || [])[1] ?? "";
+      const screenVerdict = noteField(notes, "screen_verdict");
+      const status = noteField(notes, "status");
+      const classes = noteField(notes, "class");
+      const country = ((uri.match(/^\/mark\/([a-z]{2})\//) || [])[1] ?? "").toUpperCase();
+      const rec = recordIndex[uri] ?? {};
+      out.register.push({
+        term: field(block, "search_term"),
+        mark: rec.markText || rec.mark || field(block, "search_term"),
+        owner: rec.owner ?? "", country, classes: rec.classes || classes,
+        status: rec.statusText || status,
+        group: groupForCleared({ screenVerdict, status: rec.statusText || status }),
+        uri,
+      });
+    } else if (!/^NR\d+/.test(title) && /common-law/i.test(layer) && !/^\(none/i.test(title)) {
+      out.web.push({ title, url: field(block, "url"), type: field(block, "type") });
+    }
+  }
+  return out;
+}
+
+/**
+ * Register records read, per country, from the run's own `_records/` listing. PURE.
+ *
+ * EVERY COUNTRY THE RUN READ, including the ones that came back clean — those are the whole point. A
+ * count keyed off the findings would list only countries with a conflict, which is the gap this closes.
+ *
+ * @param {string[]} recordFileNames  the `_records/` directory listing, named `<cc>-<id>.json`
+ */
+export function recordsByCountry(recordFileNames = []) {
+  const out = {};
+  for (const name of recordFileNames) {
+    const cc = (String(name).match(/^([a-z]{2})-/i) || [])[1];
+    if (cc) out[cc.toUpperCase()] = (out[cc.toUpperCase()] ?? 0) + 1;
+  }
+  return out;
+}
+
+/** Marketplace, web, reputation and meaning checks, from the deterministic grid the tools wrote. PURE. */
+export function sweepCounts(commonLawGrid, auditMd = "") {
+  const cells = Array.isArray(commonLawGrid?.cells) ? commonLawGrid.cells : [];
+  const counts = {
+    checks: cells.length,
+    platforms: new Set(cells.map((c) => c?.platform).filter(Boolean)).size,
+    spellings: new Set(cells.map((c) => c?.term).filter(Boolean)).size,
+    reputation: Array.isArray(commonLawGrid?.extras?.pr_risk) ? commonLawGrid.extras.pr_risk.length : 0,
+  };
+  // A run old enough to predate the grid has no machine record; its per-term log is the audit's own
+  // common-law rows. Not a fallback masking a defect — those runs have nothing else to read.
+  if (!counts.checks && auditMd) counts.checks = (String(auditMd).match(/^- source_layer: Common-law/gm) || []).length;
+  return counts;
+}
+
+/**
+ * What the court-decisions pass came back with, as one token. PURE.
+ *
+ * FOUR STATES, BECAUSE THREE OF THEM MEAN DIFFERENT THINGS TO A READER. "None found" is a result and
+ * "could not be checked" is a gap; collapsing them would let an unreachable source read as a clean
+ * negative, which is the one thing a clearance may never do. "Not in scope" is neither — the product
+ * offers the pass on a full country search only.
+ *
+ * @returns {"found"|"none-found"|"not-checked"|"not-in-scope"}
+ */
+export function courtDecisionsState(caseLawText) {
+  const t = String(caseLawText ?? "");
+  if (!t.trim()) return "not-in-scope";
+  if (/source unreachable|could not be reached|CONNECTION_CLOSED|not reachable|quota/i.test(t)) return "not-checked";
+  if (/No on-point precedent found|none found|no decisions found/i.test(t)) return "none-found";
+  return "found";
+}
+
+/** Was the name searched in a non-Latin script? Read off the plan's own terms, never asserted. PURE. */
+export function localScriptSearched(registerPlan) {
+  const entries = Array.isArray(registerPlan?.entries) ? registerPlan.entries : [];
+  return entries.some((e) => /[^\x00-\x7F]/.test(String(e?.term ?? "")));
+}
+
+/**
+ * The whole record, composed from what the run holds. PURE — every argument is already-written material.
+ *
+ * @returns {{schemaVersion: number, cleared: object, counts: object}}
+ */
+export function searchDepthRecord({ auditMd = "", recordIndex = {}, recordFileNames = [], commonLawGrid = null, caseLawText = "", registerPlan = null } = {}) {
+  const cleared = clearedNames(auditMd, recordIndex);
+  const groups = {};
+  for (const key of CLEARED_GROUPS) groups[key] = 0;
+  for (const c of cleared.register) groups[c.group] += 1;
+  return {
+    schemaVersion: 1,
+    cleared: { register: cleared.register, web: cleared.web, groups },
+    counts: {
+      recordsByCountry: recordsByCountry(recordFileNames),
+      recordsRead: recordFileNames.length,
+      sweep: sweepCounts(commonLawGrid, auditMd),
+      localScriptSearched: localScriptSearched(registerPlan),
+      courtDecisions: courtDecisionsState(caseLawText),
+    },
+  };
+}

package/driver/suite-census.json

@@ -141,6 +141,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-client-condition-never-carries-an-engine-token.test.mjs": {
+          "tests": 6,
+          "asserts": 10,
+          "skips": 0,
+          "todos": 0
+        },
         "a-codex-login-survives-its-own-refresh.test.mjs": {
           "tests": 4,
           "asserts": 18,
@@ -1643,7 +1649,7 @@
         },
         "coverage-is-disclosed-never-refused.test.mjs": {
           "tests": 10,
-          "asserts": 38,
+          "asserts": 40,
           "skips": 0,
           "todos": 0
         },
@@ -3688,8 +3694,8 @@
           "todos": 0
         },
         "release-pipeline.test.mjs": {
-          "tests": 93,
-          "asserts": 356,
+          "tests": 99,
+          "asserts": 376,
           "skips": 0,
           "todos": 0
         },
@@ -5001,6 +5007,12 @@
           "skips": 1,
           "todos": 0
         },
+        "the-report-can-say-how-much-was-read.test.mjs": {
+          "tests": 8,
+          "asserts": 23,
+          "skips": 0,
+          "todos": 0
+        },
         "the-report-carries-what-the-assessment-wrote.test.mjs": {
           "tests": 10,
           "asserts": 41,
@@ -5979,7 +5991,7 @@
         },
         "home.test.ts": {
           "tests": 56,
-          "asserts": 196,
+          "asserts": 197,
           "skips": 0,
           "todos": 0
         },
@@ -6365,6 +6377,12 @@
           "skips": 0,
           "todos": 0
         },
+        "providers/signa/test/match-mode-is-not-approximated.test.mjs": {
+          "tests": 4,
+          "asserts": 11,
+          "skips": 0,
+          "todos": 0
+        },
         "providers/uspto-local/test/backfile-window.test.mjs": {
           "tests": 6,
           "asserts": 11,

package/driver/terminal-clamp.mjs

@@ -106,3 +106,44 @@ export function orderClausesForLede(clauses, reasons, guardSet) {
   const ordered = [...aligned.filter((x) => !guardSet?.has?.(x.c)), ...aligned.filter((x) => guardSet?.has?.(x.c))];
   return { clauses: ordered.map((x) => x.c), reasons: ordered.map((x) => x.r) };
 }
+
+/**
+ * THE CLIENT'S CONDITION LIST, from a verdict sidecar. PURE.
+ *
+ * TWO TEXTS, NEVER ONE — stated at the top of this module, and until now honoured at only one of the
+ * two ends. Every clamp site composes a run-record `reason` (token, counts, record ids) and a reader
+ * `clause` (the same fact in a lawyer's nouns), and `terminalClampDecision` refuses a clause that
+ * carries an engine identifier. The sidecar then persisted `reasons` alone and threw the clauses away,
+ * so every client surface had only the run-record text to render. A delivered report's conditions
+ * opened with `floor_duty_undischarged:4 of 430 floor row(s)…` while the SAME run's risk statement, one
+ * line above, read the clean clause: `riskStatement` already prefers `clauses`, so the page contradicted
+ * its own headline. This function is the other end of that rule.
+ *
+ * THE CLAUSE WINS WHERE THERE IS ONE, and the fallback is not politeness. Three machinery sites push
+ * the reason AS the clause ("machinery reasons ARE factual open-states"), so for those entries the two
+ * texts are one string and this returns it unchanged — correctly, because no second text exists to
+ * prefer. A legacy sidecar written before this change carries no `clauses` key at all and falls back
+ * entirely, which is what keeps archived runs republishable.
+ *
+ * ALIGNMENT IS BY INDEX AND THE REASONS ARE THE COUNT AUTHORITY. `orderClausesForLede` pairs the two
+ * arrays and reorders them together; a BLOCKING verdict then appends its grounds to the reasons alone,
+ * so `clauses` is legitimately SHORTER. Mapping over reasons and reaching for `clauses[i]` is what
+ * makes that safe — never `clauses.map`, which would silently drop the appended grounds.
+ *
+ * BREAK MATRIX:
+ *   · a clause replaces its token-bearing reason   → break: return reasons unchanged, arm 1 red
+ *   · a clean reason with no clause survives       → break: return "" for a missing clause, arm 2 red
+ *   · a legacy sidecar still yields its conditions  → break: require the clauses key, arm 3 red
+ *   · clauses shorter than reasons loses nothing    → break: map over clauses, arm 4 red
+ *
+ * @param {{reasons?: string[], clauses?: string[]}} sidecar  the parsed `_driver/verdict.json`
+ * @returns {string[]} one condition per reason, in the sidecar's own order
+ */
+export function clientConditions({ reasons, clauses } = {}) {
+  const rs = Array.isArray(reasons) ? reasons : [];
+  const cs = Array.isArray(clauses) ? clauses : [];
+  return rs.map((r, i) => {
+    const clause = typeof cs[i] === "string" ? cs[i].trim() : "";
+    return clause || String(r ?? "").trim();
+  }).filter(Boolean);
+}

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-artifacts-mcp
 
+## 0.3.2-beta.2
+
+No changes in this release.
+
+## 0.3.2-beta.1
+
+No changes in this release.
+
 ## 0.3.2-beta.0
 
 No changes in this release.

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.2-beta.0",
+  "version": "0.3.2-beta.2",
   "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/package.json

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