clearotron 0.3.2-beta.1 → 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": "4a4575724492736d2333d3bf2faf8027578427f2",
-  "version": "0.3.2-beta.1"
+  "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,11 @@
 # 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

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.1",
+  "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/suite-census.json

@@ -3694,8 +3694,8 @@
           "todos": 0
         },
         "release-pipeline.test.mjs": {
-          "tests": 93,
-          "asserts": 356,
+          "tests": 99,
+          "asserts": 376,
           "skips": 0,
           "todos": 0
         },
@@ -6377,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/mcp-server/CHANGELOG.md

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

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.2-beta.1",
+  "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.1",
+  "version": "0.3.2-beta.2",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/portal-ui/package.json

@@ -2,7 +2,7 @@
   "name": "portal-ui",
   "private": true,
   "type": "module",
-  "version": "0.3.2-beta.1",
+  "version": "0.3.2-beta.2",
   "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/oauth-mcp-bridge/CHANGELOG.md

@@ -1,5 +1,9 @@
 # trademark-oauth-mcp-bridge
 
+## 0.3.2-beta.2
+
+No changes in this release.
+
 ## 0.3.2-beta.1
 
 No changes in this release.

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

@@ -1,6 +1,6 @@
 {
   "name": "trademark-oauth-mcp-bridge",
-  "version": "0.3.2-beta.1",
+  "version": "0.3.2-beta.2",
   "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).",

package/providers/signa/src/core.js

@@ -576,7 +576,35 @@ export function toSignaParams(p = {}) {
   const mode = String(p.match_mode ?? "").trim();
   if (mode === "exact" || mode === "phonetic" || mode === "prefix") out.strategies = [mode];
   else if (mode === "starts_with" || mode === "ends_with" || mode === "contains") out.match = mode;
-  else if (!mode && !p.match && !(Array.isArray(p.strategies) && p.strategies.length)) {
+  // ── `default` IS THE COUNT LANE'S WORD FOR THE SAME UNANCHORED QUERY THE PLAN LANE CALLS `{}` ────
+  //
+  // THE DEFECT. The count lane hands `match_mode: "default"` straight through — that is the word
+  // `COUNT_PREDICATES` gives the CONTAINING predicate, the one whose figure a client reads under
+  // "Filings containing the name". `default` matched none of the branches here, so neither request
+  // shape was selected, and `buildSearchRequest`'s else branch sent `strategies: ["exact"]`. The
+  // containing column therefore printed an exact count, on the axis that most signals how crowded a
+  // field is, and a client was told the field was less busy than it is in a number the report states
+  // as fact. Nothing failed and nothing was logged: a narrower query answers perfectly well, it just
+  // answers a different question.
+  //
+  // The branch below already does exactly this for the plan lane, which reaches here with NO mode at
+  // all. The two lanes mean the same thing by different words; they now take the same shape.
+  else if (mode === "default") {
+    if (typeof out.query === "string" && !out.query.includes("*")) out.match = "contains";
+  }
+  // ── AN UNRECOGNISED MODE REFUSES; IT DOES NOT QUIETLY BECOME A NARROWER SEARCH ──────────────────
+  //
+  // THE CLASS, and it has now bitten twice. This function's own header records `starts_with` falling
+  // through to a plain exact search — "a NARROWER query than the plan asked for, answering as though it
+  // were the one requested" — and `default` has just done the same on a client-facing figure. Both were
+  // fixed by adding the missing word. Adding words one defect at a time leaves the next unmapped mode
+  // to do it a third time, silently, in whichever direction happens to be wrong.
+  //
+  // So a mode this provider cannot express is now NAMED rather than approximated. The caller turns it
+  // into a refused cell, and a refused cell is a disclosed gap a reader can see; a wrong number is not
+  // visible at all. This can only fire where a number would otherwise have been silently wrong.
+  else if (mode) out.unsupported_match_mode = mode;
+  if (!mode && !p.match && !(Array.isArray(p.strategies) && p.strategies.length)) {
     // ── THE `default` PREDICATE, WHICH JUST MADE EXECUTABLE ────────────────────────────────
     // `planPredicateParams` returns {} for the plan's `default` predicate — no match_mode at all —
     // and this branch is the only thing standing between that and `strategies: ["exact"]`. With

package/scripts/release-pre-gate.mjs

@@ -0,0 +1,111 @@
+// 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
+//
+// release-pre-gate.mjs — let a stable cut reach the version script when every note has already been
+// consumed by a pre-release.
+//
+// THE PROBLEM THIS EXISTS FOR, MEASURED. `changesets/action` decides whether to run `version-script` by
+// counting the release notes it can see, and it does that ONCE, at the top of the run, before it touches
+// the working tree. Its reader is `readChangesetState`:
+//
+//     let preState = await readPreState(cwd);
+//     let changesets = await readChangesets(cwd);
+//     if (preState !== undefined && preState.mode === "pre") {
+//       return { preState, changesets: changesets.filter((c) => !c.id.startsWith("pre/")) };
+//     }
+//     return { preState: undefined, changesets };
+//
+// `readChangesets` DOES enumerate `.changeset/pre/`, giving each note an id beginning `pre/`. The filter
+// that hides them applies only while the tree says `mode: "pre"`.
+//
+// A pre-release consumes a note by MOVING it into `.changeset/pre/`, where it waits so the eventual
+// stable can list every change since the last stable. So the ordinary state after cutting a beta is: no
+// notes at the top level, every note under `pre/`, and the flag still saying `pre`. In that state the
+// action counts zero, skips the version script, emits no pull request number, and the stable cut refuses
+// with "Nothing to cut" — a refusal about the wrong thing, because the tree holds a whole release.
+//
+// WHAT THIS DOES, AND WHY IT IS NOT A TRICK. It writes the channel the dispatch asked for into the file
+// the action reads, before the action reads it. A stable cut IS a tree leaving pre-release mode, and the
+// notes under `pre/` ARE the notes that stable will carry; saying so is a true statement about this cut,
+// not a device to get past a check. `release-version.mjs` already states the same principle for the
+// other reader: "the mode a cut needs is a fact about the channel asked for, not about what the last cut
+// happened to do." There are two readers of that fact and they are reached separately.
+//
+// THE WRITE IS DISCARDED, ON PURPOSE, AND THAT IS THE POINT. The action's own first act inside
+// `runVersion` is `git checkout changeset-release/main` followed by `git reset --hard <the run's
+// commit>`, which puts `pre.json` back to `pre`. The version script then runs in that rebuilt tree, finds
+// the tree still in pre mode, and performs the real transition itself with `changeset pre exit` — which
+// is where the transition has to happen, and the reason it was moved there. So this changes what the
+// action COUNTS and nothing about what the cut DOES. Nothing here versions anything, and a tree this
+// touched still produces the same version it would have produced had the gate never been in the way.
+//
+// WHAT IT REFUSES TO DO. It is silent on a beta, on a tree that is not in pre mode, on a tree whose notes
+// are at the top level where the action can already see them, and on a tree with no notes anywhere. That
+// last one matters most: a cut with genuinely nothing to cut must still refuse, and it still does,
+// because this writes nothing when `.changeset/pre/` is empty.
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** A note is a `.md` file that is not the directory's own README. */
+export function countNotes(dir) {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => f.endsWith(".md") && f.toLowerCase() !== "readme.md").length;
+}
+
+/**
+ * PURE. Whether this cut has to restate its channel for the action's counter, and nothing else.
+ *
+ * `null` means leave the tree alone, and every `null` here is a case the action already reads correctly
+ * — including the two that must keep refusing. Only the one state the action cannot see returns a write.
+ *
+ * Kept separate from the file it writes so the decision can be driven against every member of the class
+ * rather than only against the tree that happens to be checked out.
+ */
+export function preGateDecision({ cut, mode, topLevelNotes, preNotes }) {
+  // A beta never restates anything. A beta with no pending notes MUST still refuse, and that refusal is
+  // this function returning null.
+  if (cut !== "stable") return null;
+  // Not in pre mode: the action's filter is not engaged, so whatever is there is already counted.
+  if (mode !== "pre") return null;
+  // The action can see these. Touching the flag here would change the pull request's title for a cut
+  // that never needed help.
+  if (topLevelNotes > 0) return null;
+  // Nothing anywhere. "Nothing to cut" is then the truth, and the refusal downstream is correct.
+  if (preNotes === 0) return null;
+  return { mode: "exit" };
+}
+
+export function main(root = ROOT, argv = process.argv.slice(2)) {
+  const cut = (argv.find((a) => a.startsWith("--cut=")) ?? "").slice("--cut=".length);
+  // `--root` exists so this can be driven against a built tree rather than only against the checkout it
+  // happens to live in. The workflow never passes it: there the script sits in the repository being cut,
+  // which is what ROOT already means.
+  const rootFlag = argv.find((a) => a.startsWith("--root="));
+  if (rootFlag) root = rootFlag.slice("--root=".length);
+  const preJson = join(root, ".changeset", "pre.json");
+  const flag = existsSync(preJson) ? JSON.parse(readFileSync(preJson, "utf8")) : null;
+  const mode = flag?.mode ?? "none";
+  const topLevelNotes = countNotes(join(root, ".changeset"));
+  const preNotes = countNotes(join(root, ".changeset", "pre"));
+
+  const decision = preGateDecision({ cut, mode, topLevelNotes, preNotes });
+  const state = `cut=${cut || "none"}, mode=${mode}, ${topLevelNotes} note(s) pending, ${preNotes} already consumed by the pre-release`;
+  if (!decision) {
+    // SAYS SO EITHER WAY. A step that is silent when it does nothing cannot be told from a step that did
+    // not run, and this one is skipped far more often than it acts.
+    console.log(`release-pre-gate: ${state} — leaving the flag alone.`);
+    return 0;
+  }
+  writeFileSync(preJson, `${JSON.stringify({ ...flag, ...decision }, null, 2)}\n`);
+  console.log(`release-pre-gate: ${state} — the notes this stable carries are all under .changeset/pre/,`
+    + " where the action does not count them while the flag says pre. Writing mode=exit so it counts them."
+    + " The version script performs the real transition after the action rebuilds the tree; this write is"
+    + " discarded by that rebuild and changes no version.");
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exit(main());