clearotron 0.4.0-beta.2 → 0.4.0

package/providers/_shared/term-shape.mjs

@@ -80,7 +80,7 @@ export function termPredicateIssue(term, predicate) {
 // R2b died at fan-in on a plan carrying its own section headings as search terms:
 //
 //   term="**Core (BIOVELTRIN, BIO VELTRIN, BIO-VELTRIN, etc.)**"    predicate=default
-//   term="**Formative root (VELTRIN, DELPHIN, DELPHINUS, etc.)**"   predicate=default
+//   term="**Formative root (VELTRIN, KORPHIN, KORPHINUS, etc.)**"   predicate=default
 //
 // Twenty minutes earlier the same matter on the same commit delivered clean, and the only difference
 // was those two strings. Both happened to be 6 words, so they tripped the >4-word arm below by luck;

package/providers/jx/src/core.js

@@ -120,7 +120,6 @@ export function buildCandidateRequest({ mark, productContext = "", lane = "zh",
     model,
     max_tokens: 2048,   // 8 Han candidates + rationales need headroom; truncation is checked either way
     tools: [CANDIDATE_TOOL],
-    tool_choice: { type: "tool", name: CANDIDATE_TOOL.name },   // FORCED tool answer; shape validated at parse
     messages: [{ role: "user", content: promptFor({ mark: String(mark).trim(), productContext: String(productContext ?? "").trim() }) }],
   };
 }

package/providers/jx/src/judge.js

@@ -79,7 +79,6 @@ export function buildJudgeRequest({ mark, hits, model = DEFAULT_MODEL }) {
     model,
     max_tokens: 4096,   // 40 one-clause judgments fit well inside; truncation checked either way
     tools: [JUDGE_TOOL],
-    tool_choice: { type: "tool", name: JUDGE_TOOL.name },   // FORCED tool answer; shape validated at parse
     messages: [{ role: "user", content: prompt }],
   };
 }

package/providers/jx/src/nativeread.js

@@ -81,7 +81,6 @@ export function buildNativereadRequest({ mark, lane = "zh", payload, model = DEF
     model,
     max_tokens: 4096,   // 12 grounded items with grounds quotes need headroom; truncation checked either way
     tools: [NATIVEREAD_TOOL],
-    tool_choice: { type: "tool", name: NATIVEREAD_TOOL.name },   // FORCED tool answer; shape validated at parse
     messages: [{ role: "user", content: prompt }],
   };
 }

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

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

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

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

@@ -182,6 +182,52 @@ export function rememberableAnswer(method, status, body, parseError) {
 // answering as though it were the one requested.
 const DETERMINISTIC_MATCH = new Set(["similar", "exact", "starts_with", "ends_with", "contains"]);
 
+// ── THE RANKED STRATEGIES, AS SIMILARITY CHANNELS ────────────────────────────────────────────────
+//
+// The register retired `strategies` in favour of `similarity` and retired `query` in favour of `q`, both
+// on the same date, and says so in `search_meta.deprecations` on every response that still uses the old
+// names. This is that migration.
+//
+// THE TABLE IS NOT A RENAME, and assuming it was is the way to lose coverage quietly. Each old strategy
+// expands to a SET of channels, and the sets are not the strategy's own name: `fuzzy` alone applies four.
+// Every row below was read off the register's own `similarity_applied` for the old parameter — so the
+// register derived this table, not us — and each was then confirmed by sending the new form and comparing
+// what came back against the old form's answer, on a neutral term, not by reading the names across:
+//
+//   strategy   similarity channels
+//   exact      identical, lookalike
+//   phonetic   identical, phonetic
+//   fuzzy      identical, fuzzy, embedded, lookalike
+//   prefix     identical, embedded
+//
+// For `exact` the comparison was of the returned SETS, paged to exhaustion both ways and compared by
+// record, not of the totals — two totals agreeing is not two sets agreeing. Several strategies in one call
+// UNION their channels, confirmed on a combination the same way. The figures, the date and the term they
+// were taken on are on the tracker: this directory is public and vendor measurements do not live here.
+//
+// `similarity` REFUSES ANYTHING ELSE — "similarity must be one of: identical, fuzzy, embedded, phonetic,
+// lookalike" — which is why `prefix` has no channel of its own and why an unknown strategy must not be
+// forwarded verbatim: it would 4xx the call rather than narrow it, but only at run time and only for the
+// plan that asked. Unknown names map to the exact channels and the caller's word is kept in the request's
+// own record by the plan, not invented here.
+const SIMILARITY_FOR = Object.freeze({
+  exact: ["identical", "lookalike"],
+  phonetic: ["identical", "phonetic"],
+  fuzzy: ["identical", "fuzzy", "embedded", "lookalike"],
+  prefix: ["identical", "embedded"],
+});
+const SIMILARITY_CHANNELS = Object.freeze(["identical", "fuzzy", "embedded", "phonetic", "lookalike"]);
+
+/** The channels a list of ranked strategies asks for: the union of each one's, in the register's own order. */
+export function similarityFor(strategies) {
+  const want = new Set();
+  const list = Array.isArray(strategies) && strategies.length ? strategies : ["exact"];
+  for (const s of list) {
+    for (const c of (SIMILARITY_FOR[String(s ?? "").trim().toLowerCase()] ?? SIMILARITY_FOR.exact)) want.add(c);
+  }
+  return SIMILARITY_CHANNELS.filter((c) => want.has(c));
+}
+
 // ── filters: ONE builder, because the two shapes drifting apart is how `status` survived ───────────
 //
 // `filters.status` was sent by both branches below and NO SUCH KEY EXISTS. The API rejects unknown
@@ -227,12 +273,27 @@ export function buildSearchRequest(p) {
   // serializes away anyway, but writing it conditionally is what makes the owner-only shape legible here
   // rather than an accident of JSON.stringify.
   const body = {};
-  if (String(p.query ?? "").trim()) body.query = p.query;
+  // ── `q` CARRIES ONE TERM, AND AN ARRAY HERE WOULD BE A DIFFERENT SEARCH ────────────────────────
+  //
+  // A scalar `q` is a RANKED query: the similarity channels below apply to it. A LIST in the same field
+  // is not a wider ranked query — it is an exact-text filter, and the register refuses to combine it with
+  // similarity at all ("a list is an exact-text filter, not a ranked query"). Measured: the ranked form
+  // returns a live mark the register itself tiers `identical` via its lookalike channel, and the list form
+  // does not, because that mark's text does not contain the term. So an array reaching this line would
+  // silently drop look-alike coverage while answering 200 — a narrowed query wearing a complete answer,
+  // the failure this connector already refuses a multi-term stack to prevent.
+  //
+  // It is refused rather than joined or first-element-picked, for the same reason the stack is.
+  if (Array.isArray(p.query))
+    throw new Error("[signa] `query` reached the request builder as a list. A list in `q` is an exact-text "
+      + "filter on this register and cannot carry the similarity channels a ranked band asks for, so it "
+      + "would drop look-alike matches while answering 200. Send one term per request.");
+  if (String(p.query ?? "").trim()) body.q = p.query;
   const match = typeof p.match === "string" ? p.match.trim() : "";
   if (match && DETERMINISTIC_MATCH.has(match)) {
-    body.match = match;   // sending strategies alongside is a 4xx, not a preference
+    body.match = match;   // sending similarity alongside is a 4xx, not a preference
   } else {
-    body.strategies = Array.isArray(p.strategies) && p.strategies.length ? p.strategies : ["exact"];
+    body.similarity = similarityFor(p.strategies);
   }
   const filters = buildFilters(p);
   if (Object.keys(filters).length) body.filters = filters;
@@ -319,7 +380,14 @@ export function normalizeRecord(rec, officeHint = null) {
     registrationNumber: rec.registration_number ?? rec.ir_number ?? null,
     applicationDate: toIso(rec.filing_date),
     registrationDate: toIso(rec.registration_date),
-    expiryDate: toIso(rec.expiry_date),
+    // — THE OFFICE'S DATE FIRST, THEN SIGNA'S OWN (their 27 September release). That release split what
+    // an office published from what Signa computes: `expiry_date` now carries only the published date and
+    // is EMPTY on USPTO records, where the computed one moved to `derived.expiry_date`. Read one and the
+    // field goes quietly null on every US record — measured on the record bodies of the run that
+    // straddled the release: 4 of 9 US records carried it only under `derived`, and all 4 normalised to
+    // null here. Where both are present they are identical (12 of 12 on that run), so the office's value
+    // first costs nothing and keeps the published date authoritative when there is one.
+    expiryDate: toIso(rec.expiry_date ?? rec.derived?.expiry_date),
     statusClass: statusClassOf(rec),   // live | dead | unknown — authoritative for the gates
     statusText: pickStatusText(rec),
     markText: rec.mark_text ?? null,
@@ -353,16 +421,31 @@ export function normalizeRecord(rec, officeHint = null) {
     // "absent from the register", and `nativeScriptIndex` is settled from the record, not from this.
     markTextScript: rec.mark_text_script ?? null,
     markTextLanguage: rec.mark_text_language ?? null,
-    renewalDueDate: toIso(rec.renewal_due_date),
+    // The same split as `expiryDate` above, and the vendor names both fields in it. UNEXERCISED ON THE
+    // DATA WE HOLD: of the 22 record bodies from the run that straddled the release, none carried a
+    // renewal date in either place, so the fallback recovers nothing we can point at. It is here because
+    // the register says this field moved with expiry, and reading one place is how the expiry loss
+    // happened; the arm for it is therefore synthetic and says so.
+    renewalDueDate: toIso(rec.renewal_due_date ?? rec.derived?.renewal_due_date),
     publicationDate: toIso(rec.publication_date),
     priorityDate: toIso(rec.priority_date),
     terminationDate: toIso(rec.termination_date),
-    // Opposition data IS on the record now: `opposition_window` rides every search row and
-    // `proceedings_count` the full record. The per-proceeding detail behind
-    // GET /v1/trademarks/{id}/proceedings is still an unwired tool — so the window and the count are
-    // reported, and the absence of detail is stated rather than left to look like an absence of
-    // proceedings.
-    oppositionWindow: rec.opposition_window ?? null,
+    // Opposition data IS on the record, and NOT where this used to look. The register reports the window
+    // under its computed object, and as an OBJECT rather than a scalar:
+    // `{supported, window_opens, window_closes, …}`, or `{supported: false, reason, rule_id}` where the
+    // stage cannot be opposed. `proceedings_count` is still the office's own, top-level.
+    //
+    // THE OLD READ RETURNED NULL ON EVERY RECORD WE HOLD, and the comment here asserted otherwise — that
+    // the window "rides every search row". Measured over all four saved runs on this register: 0 of 6,
+    // 0 of 5, 0 of 7 and 0 of 22 bodies carried it top-level, and 6, 3, 7 and 22 carried it under the
+    // computed object. So the earliest evidence we have already reads the new place, eleven days before
+    // the release the register attributes the move to. Which of the two dates is right does not change
+    // what to read; it does mean this was not reported missing for as long as it was missing.
+    //
+    // The per-proceeding detail behind GET /v1/trademarks/{id}/proceedings is still an unwired tool, so
+    // the window and the count are reported and the absence of detail is stated rather than left to look
+    // like an absence of proceedings.
+    oppositionWindow: rec.opposition_window ?? rec.derived?.opposition_window ?? null,
     proceedingsCount: rec.proceedings_count ?? null,
     oppositions: null,
     _provenance: { opposition: rec.proceedings_count != null ? `count=${rec.proceedings_count} from the record; per-proceeding detail via /proceedings, tool not wired` : "per-proceeding detail via /proceedings, tool not wired" },
@@ -466,6 +549,30 @@ export function normalizeSearchResponse(body, echoQuery) {
     strategies_used: meta.strategies_used ?? [],
     match: meta.match ?? null,
     search_id: meta.search_id ?? null,
+    // ── THE REGISTER'S OWN WARNINGS, CARRIED WHOLE ──────────────────────────────────────────────
+    //
+    // Passed through as the register sent them rather than filtered to the codes we happen to know. A
+    // recorder keyed to a fixed list of codes looks like coverage and is an empty column the day the
+    // register adds one, and there is no way to tell those two apart from the outside. An empty array is
+    // the ordinary case: a clean response carries no `warnings` key at all.
+    //
+    // TWO CODES ARE KNOWN TO ARRIVE HERE, and they behave oppositely — which is the reason to keep the
+    // list whole rather than reason about either one.
+    //
+    // `mixed_script` is emitted on the exact-text filter path and NOT on the ranked path, because a
+    // ranked query folds look-alike letters through its own similarity channel and so has nothing to
+    // warn about. Every sweep this connector sends is ranked, so this code will not appear, and an
+    // empty list is NOT evidence that a query carried no mixed-script risk. Whatever guards that on the
+    // ranked path still has to.
+    //
+    // `expanded_fallback` DOES arrive on requests this connector sends. Measured: it fires on
+    // `offices` together with `nice_classes`, and on `goods_services_text`, which rides every
+    // goods-narrowed question. It says the grouped view cannot serve that filter, so the answer comes
+    // back one row per RECORD instead of one row per MARK — and the register's own note says that
+    // inflates the total. The total is what the enumerate ceiling reads to call a band a crowd, so a
+    // band can be declared a crowd on a number that counts designations rather than marks. This field
+    // is what makes that visible; it does not yet make it safe.
+    warnings: Array.isArray(meta.warnings) ? meta.warnings : [],
     // The corpus total when the vendor counted it exactly; null when it did not answer, when the
     // total was not requested, and when the figure it returned is an approximation. NEVER the page
     // size — `data.length` is `count`, and conflating the two is how a page reads as a corpus.
@@ -485,8 +592,8 @@ export function normalizeSearchResponse(body, echoQuery) {
 //
 // THIS HEADER USED TO ADVERTISE AN ENVIRONMENT VARIABLE, `CLAWDI_SIGNA_MOCK`. There was never such a
 // variable: two occurrences in the whole tree, both comments, zero reads. Following the line produced a
-// run that died at preflight in seconds, and it cost a real investigation (, found by e2e looking
-// for a credential-free register lane for fault injection).
+// run that died at preflight in seconds, and it cost a real investigation — found while looking for a
+// register path that needs no credential, to inject faults into.
 //
 // The lane below is real and works. What does not exist is a way to REACH it from a run: `doSearch`,
 // `doRecordFetch` and `doEnumerate` each take `{ mock = false }`, the capability wrappers pass
@@ -494,10 +601,11 @@ export function normalizeSearchResponse(body, echoQuery) {
 // (driver.config.mjs) call these functions with no options object at all. So the only callers that
 // enable it are this provider's own tests, and that is the whole of it.
 //
-// AND IT STAYS THAT WAY DELIBERATELY, rather than for want of wiring. offered to wire it; the
-// acceptance that comes with wiring is "preflightCredentials must not demand SIGNA_API_KEY when the
-// mock lane is on", and that produces a clearance run with no register credential, reaching the
-// register stage, answering from ten in-repo fixtures. ADR-0003's first table row rules exactly that
+// AND IT STAYS THAT WAY DELIBERATELY, rather than for want of wiring. Wiring it was offered and
+// declined; the acceptance that comes with wiring is "preflightCredentials must not demand
+// SIGNA_API_KEY when the mock path is on", and that produces a clearance run with no register
+// credential, reaching the register stage, answering from ten in-repo fixtures. ADR-0003's first
+// table row rules exactly that
 // out: the register REFUSES at preflight, by name, because "an unconfigured register that answered
 // 'no conflicts found' is the most dangerous output this system can produce".
 //

package/scripts/e2e-first-time.mjs

@@ -163,10 +163,18 @@ export const NOT_COUNTED_EVENTS = {
     "jx-aim-consumed", "jx-candidate-fold", "jx-nativeread", 
     "jx-serp-grid", "jx-serp-grid-overflow", "jx-serp-grid-spec", "jx-slices-stated",
     "knockout-published", "knockout-receipts", 
-    "knockout-register-records", "knockout-sweep-skipped", "knockout-sweep-start",
-    // The sweep's cost line: marks, calls, cells, the largest place list any one name carried, the minutes
-    // and the target they are read against. A RECORD, never a failure — nothing about it is a step that
-    // went wrong, a question re-asked or an attempt repeated, so it does not bear on "first time" (515).
+    "knockout-register-records",
+    // The run's own span against the ten-minute target, written at delivery because that is the first
+    // point at which the run's span is known. Same class as the sweep's line below: a RECORD, never a
+    // failure. `overBar: null` on it means the span could not be measured, which is a gap in the record
+    // and still not a retry (515).
+    "knockout-run-total",
+    "knockout-sweep-skipped", "knockout-sweep-start",
+    // The sweep's cost line: marks, calls, cells, the largest place list any one name carried, and the
+    // sweep's own elapsed minutes. A RECORD, never a failure — nothing about it is a step that went
+    // wrong, a question re-asked or an attempt repeated, so it does not bear on "first time" (515).
+    // The target moved off this line to the run's own, above: the bar is about a run and this span is
+    // one stage of it.
     "knockout-sweep-total", "level-scope-note",
     "named-band-merged", "one-shot-stamp-settled", "order-probe", "output-snapshot", "owner-screen-derived",
     "placement-borderline", "placement-form-written", "plan-execution", "plan-execution-census",

package/scripts/e2e-scenario-ops.mjs

@@ -282,17 +282,40 @@ export function narrowingNamesItsCrowd(a, runDir) {
   const exec = readJson(driverDir(runDir, "plan-execution.json"));
   if (!exec) return { ok: false, saw: "_driver/plan-execution.json absent, so no question's count can be read" };
   const counts = executedCounts(exec);
-  const crowdMissing = [], crowdUncounted = [], narrowingUncounted = [];
+  // A QUESTION ASKED OFF THE PLAN IS DISPOSITIONED, NOT OMITTED, and this op had no branch for it.
+  //
+  // The plan record carries an `unplanned` bucket: the engine asked something the plan did not contain
+  // and said so. Such an entry is on the record with a disposition and carries no executed count, and
+  // this check used to render that as "carries no count of its own" — which describes a silent omission.
+  // On the run that surfaced it, that ONE narrowing was the whole failure: 35 of 36 carried their own
+  // count, all 14 crowds were on the record, and neither crowd branch fired.
+  //
+  // IT IS NAMED, NOT COUNTED AGAINST THE ENGINE. The rule this op states is that the crowd a narrowing
+  // replaced is on the record with a count. An off-plan question satisfies the first half and cannot
+  // satisfy the second, because no count exists to read — and whether the engine ought to record one for
+  // a question it asked off-plan is a question about the RECORD, not about this narrowing. That belongs
+  // to the lane that writes the record; this op says what it found and declines to invent a verdict.
+  const offPlanQids = new Set(list(exec.unplanned).map((e) => text(e?.qid)).filter(Boolean));
+  const crowdMissing = [], crowdUncounted = [], narrowingUncounted = [], narrowingOffPlan = [];
   for (const n of narrowings) {
     const crowd = text(n.narrows);
     if (!byQid.has(crowd)) crowdMissing.push(`${n.qid} → ${crowd}`);
     else if (!counts.has(crowd)) crowdUncounted.push(`${n.qid} → ${crowd}`);
-    if (!counts.has(text(n.qid))) narrowingUncounted.push(text(n.qid));
+    if (!counts.has(text(n.qid))) {
+      if (offPlanQids.has(text(n.qid))) narrowingOffPlan.push(text(n.qid));
+      else narrowingUncounted.push(text(n.qid));
+    }
   }
   const parts = [`${plural(narrowings.length, "narrowing")} naming ${new Set(narrowings.map((n) => text(n.narrows))).size} crowd(s)`];
   if (crowdMissing.length) parts.push(`${crowdMissing.length} name a crowd that is not on the record${sample(crowdMissing)}`);
   if (crowdUncounted.length) parts.push(`${crowdUncounted.length} name a crowd with no count${sample(crowdUncounted)}`);
   if (narrowingUncounted.length) parts.push(`${narrowingUncounted.length} carry no count of their own${sample(narrowingUncounted)}`);
+  // Said whether or not anything failed, because it is the difference between a question the engine
+  // never answered and one it asked outside the plan — and a reader cannot tell those apart from a
+  // count's absence alone.
+  if (narrowingOffPlan.length) parts.push(`${narrowingOffPlan.length} asked OFF THE PLAN: on the record`
+    + ` in plan-execution's \`unplanned\` bucket with a disposition and no executed count, so this check`
+    + ` has no count to read rather than a count that is missing${sample(narrowingOffPlan)}`);
   if (parts.length === 1) parts.push("each crowd and each narrowing on the record with its count");
   return { ok: !crowdMissing.length && !crowdUncounted.length && !narrowingUncounted.length, saw: parts.join("; ") };
 }