clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/providers/clarivate/src/core.js

@@ -31,7 +31,8 @@
 //     `register-records.jsonl`; providers/_shared/ledger-path.mjs still resolves the older
 //     `corsearch-*` names on a box that already has them.)
 
-import { makeLedger } from "../../_shared/ledger.mjs";
+import { makeLedger, heldRecordBodies } from "../../_shared/ledger.mjs";
+import { answerKey, compareAnswers, forgetAnswer, noteAnswer, openAnswerMemory, recallAnswer, rememberAnswer } from "../../_shared/answer-memory.mjs";
 import { nonAnswerBodyError, parseJsonBody, unparsedBodyError } from "../../_shared/http-body.mjs";
 import {
   BATCH_SCREEN_CHUNK, chunk, isAllClass, makeClassifyStatus, screenVerdict,
@@ -76,13 +77,36 @@ export function refToOffice(ref) {
 }
 
 // ── HTTP helper (with the metered chokepoint) ──────────────────────────────────────────────────────
-export async function clarivateFetch(apiKey, base, path, { body = null, method = "POST", retries = 1, tctx = null } = {}) {
+//
+// THE RUN MEMORY (providers/_shared/answer-memory.mjs) answers an identical count, search or owner lookup
+// from what this run already asked: the question is the base address, the path and the whole body, never
+// the key. Records are held by id instead (heldRecords, below), because a record is the same whichever
+// search found it. Images and filing dates are not repeated in a run and go to the register every time.
+// With no memory for the run, this is the plain fetch it always was.
+//
+// `ledgerExtra` rides on the call ledger's row: a /text call names the record ids it fetched, which is
+// what lets a run's usage count a record fetched twice (driver/provider-usage.mjs).
+const REMEMBERED_PATHS = new Set(["/count", "/search", "/resolution/company"]);
+
+export async function clarivateFetch(apiKey, base, path, { body = null, method = "POST", retries = 1, tctx = null, ledgerExtra = null } = {}) {
   const url = `${base}${path}`;
   const headers = { "X-ApiKey": apiKey, "Accept": "application/json" };
   const init = { method, headers };
   if (body !== null) { headers["Content-Type"] = "application/json"; init.body = JSON.stringify(body); }
 
   const t0 = Date.now();
+  const mem = REMEMBERED_PATHS.has(path) ? openAnswerMemory(tctx?.recordLog) : null;
+  const key = mem ? answerKey({ base, method, path, body }) : null;
+  const held = mem ? recallAnswer(mem, key) : null;
+  const note = (row) => noteAnswer(mem, { ts: new Date().toISOString(), mode: mem.mode, key, method, path, tool: tctx?.kind ?? null,
+    via: tctx?.recordLog ? "driver" : "tool-server", session: tctx?.sessionKey ?? null, ...row });
+  if (held && mem.mode === "on") {
+    const { body: parsed, parseError } = parseJsonBody(held.raw);
+    const ok = held.status >= 200 && held.status < 300;
+    logCall(tctx, { http_status: held.status, ok, attempts: 0, took_ms: Date.now() - t0, bytes: held.raw.length, cache_hit: true });
+    note({ held: true, served: true, status: held.status });
+    return { status: held.status, ok, url, body: parsed, raw: held.raw, parseError };
+  }
   let attempts = 0;
   let resp;
   try {
@@ -96,17 +120,91 @@ export async function clarivateFetch(apiKey, base, path, { body = null, method =
       await new Promise((r) => setTimeout(r, 1500 * (i + 1)));
     }
   } catch (err) {
-    logCall(tctx, { http_status: 0, ok: false, attempts, took_ms: Date.now() - t0, bytes: 0, cache_hit: false });
+    logCall(tctx, { http_status: 0, ok: false, attempts, took_ms: Date.now() - t0, bytes: 0, cache_hit: false, ...(ledgerExtra ?? {}) });
+    if (mem) note({ held: Boolean(held), status: 0 });
     throw err;
   }
 
   const raw = await resp.text();
   // The parse failure travels on `parseError` instead of being swallowed — providers/_shared/http-body.mjs.
   const { body: parsed, parseError } = parseJsonBody(raw);
-  logCall(tctx, { http_status: resp.status, ok: resp.ok, attempts, took_ms: Date.now() - t0, bytes: raw.length, cache_hit: false });
+  // A FAILED CALL'S BODY IS KEPT WHOLE on its row. Everything downstream shortens it — the error text
+  // quotes 200 characters of it and a band's reason 240 — and a gateway's error body is often the only
+  // sentence that says what happened. A successful body is never written here: the record ledger holds
+  // records, and this row is the call's.
+  logCall(tctx, { http_status: resp.status, ok: resp.ok, attempts, took_ms: Date.now() - t0, bytes: raw.length, cache_hit: false, ...(ledgerExtra ?? {}),
+    ...(resp.ok ? {} : { error_body: raw }) });
+  if (mem) {
+    const summary = rememberableAnswer(path, resp.status, parsed, parseError);
+    const row = { held: Boolean(held), status: resp.status, rememberable: Boolean(summary) };
+    if (held && summary) Object.assign(row, compareAnswers(held.summary, summary));
+    if (summary && !held) row.stored = rememberAnswer(mem, key, { status: resp.status, raw, summary });
+    note(row);
+  }
   return { status: resp.status, ok: resp.ok, url, body: parsed, raw, parseError };
 }
 
+/**
+ * What the run memory may keep from a count, a search or an owner lookup, as the short summary a watch
+ * compares — or null when the question must be asked again next time.
+ *
+ * KEPT: a 200 that parsed into the answer its path gives — `counts{}` for /count, `ids{}` for /search
+ * (isSearchResponseBody), `companies[]` for /resolution/company.
+ *
+ * NEVER KEPT: anything else, the refusals included — a result past the ceiling, a query the service
+ * refused as written, an error envelope served with a 200, a body that did not parse. Those are the
+ * answers this core reports as failures, and remembering one would turn a passing fault into the run's
+ * permanent answer. No answer here points at a next page: /search returns the whole set at once.
+ */
+export function rememberableAnswer(path, status, body, parseError) {
+  if (status !== 200 || parseError || body == null || typeof body !== "object" || Array.isArray(body)) return null;
+  if (path === "/count") {
+    if (!body.counts || typeof body.counts !== "object" || Array.isArray(body.counts)) return null;
+    const entries = Object.entries(body.counts).filter(([, n]) => Number.isFinite(Number(n)));
+    return { total: entries.reduce((t, [, n]) => t + Number(n), 0), ids: entries.map(([o, n]) => `${o}:${Number(n)}`).sort(), next_page: false };
+  }
+  if (path === "/search") {
+    if (!isSearchResponseBody(body)) return null;
+    const ids = Object.entries(body.ids).flatMap(([o, gs]) => (Array.isArray(gs) ? gs : []).map((g) => `${o}/${g}`));
+    return { total: ids.length, ids, next_page: false };
+  }
+  if (path === "/resolution/company") {
+    if (!Array.isArray(body.companies)) return null;
+    const ids = body.companies.map((c) => `${c?.applicantName ?? ""}|${c?.registrationOfficeCode ?? ""}|${c?.confidenceScore ?? ""}`);
+    return { total: ids.length, ids, next_page: false };
+  }
+  return null;
+}
+
+/**
+ * THE RECORDS THIS RUN ALREADY HOLDS, by id, for a /text call about to be made — Map<lowercased guid, raw
+ * record>. Read off the run's record log, which every process that fetches a record for the run writes
+ * to (providers/_shared/ledger.mjs heldRecordBodies), and only while the run memory is `on`.
+ *
+ * The raw vendor record is what comes back, not the normalized one stored beside it, so the caller runs
+ * it through exactly the normalization and screening a fetched record gets, with this request's own office
+ * hint. A held record therefore yields the row a fresh fetch would, and a record whose office segment
+ * differs between two searches is addressed the way this search addresses it.
+ *
+ * Why no watch period (the owner's ruling): across 38 past runs that fetched the same record twice, every
+ * second copy was byte-identical apart from the order of one list inside the vendor's raw record, and
+ * every normalized field matched.
+ */
+function heldRecords(tctx, guids) {
+  const out = new Map();
+  if (openAnswerMemory(tctx?.recordLog)?.mode !== "on") return out;
+  const log = typeof tctx?.recordLog === "string" && tctx.recordLog.trim()
+    ? tctx.recordLog.trim() : String(process.env.CLEAROTRON_REGISTER_RECORD_LOG ?? "").trim();
+  for (const [g, body] of heldRecordBodies(log, guids)) if (body?._raw && typeof body._raw === "object") out.set(g, body._raw);
+  return out;
+}
+
+/** The one ledger row for records served from the run's own store: no call made, none paid for. */
+function logHeldRecords(tctx, held) {
+  if (!held.size) return;
+  logCall({ ...tctx, target: `held:${held.size}` }, { http_status: 200, ok: true, attempts: 0, took_ms: 0, bytes: 0, cache_hit: true, records: [...held.keys()] });
+}
+
 const errText = (r) => r?.body?.errorMessage ?? r?.body?.message ?? (r?.raw ? String(r.raw).slice(0, 200) : "");
 
 // ══ QUERY BUILDING ═════════════════════════════════════════════════════════════════════════════════
@@ -192,7 +290,7 @@ const PHRASE_OPERATOR = "ADJ";
 // once `exact`:
 //   "SLUSH FREEZE, SLUSH ICE, SLUSH POP"                     three terms crammed into one
 //   "TIKTOK / TIK- famous-neighbour family"                  a description of a family, not a name
-//   "TIKE, TIPI one-keystroke neighbours of TIKI"
+//   "WAVU, WAPO one-keystroke neighbours of WAVO"
 //
 // Searched, they return 0 — and a 0 here reads as CLEAN, which is the one outcome this contract must
 // never produce by accident. On that run the `default` twins deferred loudly while the `exact` twins
@@ -305,7 +403,7 @@ export function compilePhraseValue(term, { pre = "", post = "", dropReserved = f
   const last = kept.length - 1;
   const tailWrap = (kept.length > 1 && kept[last].length === 1) ? "" : post;
   // THE WILDCARD PREDICATE CARRIES ITS OWN STAR, so `post` is empty there and the two rules above
-  // cannot reach it: the caller writes `STEAL A*` and the star is part of the token. Same shape, same
+  // cannot reach it: the caller writes `FOLD A*` and the star is part of the token. Same shape, same
   // refusal, so the same subtraction — the star comes off a one-character final token. Nothing else is
   // touched: a longer final token keeps the caller's pattern exactly as written, and a `?` is a
   // single-character class rather than a sub-query, so it is not this.
@@ -561,7 +659,7 @@ export function resolveOffices(regions) {
  * answers the deduplicated union of the deleted 4-call per-class fan-out.
  */
 // ── THE APOSTROPHE IS NOT SEARCHABLE IN APPLICANT_NAME ────────────────────────────────────────────
-// An apostrophe is not searchable: "TRADER VIC'S", "MCDONALD'S CORPORATION" and
+// An apostrophe is not searchable: "TRADER VIC'S", a company's possessive name and
 // "…L'ETAT DU DELAWARE" all answer HTTP 400 — "the following characters are not searchable by
 // themselves" — while the same names without the apostrophe answer 200. It is the character itself,
 // not the elision and not the possessive; an earlier fix narrowed this to elided articles only, on the
@@ -569,7 +667,7 @@ export function resolveOffices(regions) {
 // is exactly what failed next.
 //
 // Dropping the name is the wrong remedy: `?` is a native single-character wildcard on this field, so
-// the apostrophe is EXPRESSIBLE. "MCDONALD?S CORPORATION" returns 27 where the literal returns 400.
+// the apostrophe is EXPRESSIBLE. That possessive name written with "?" returns 27 where the literal returns 400.
 //
 // Emit BOTH spellings OR-joined, because registers hold both: "TRADER VIC?S" matches the apostrophe'd
 // record and "TRADER VICS" the stripped one (probe: 3 records each). One form alone silently loses
@@ -1107,6 +1205,7 @@ export async function doSearch(apiKey, base, params, tctx) {
   if (!isSearchResponseBody(r.body)) {
     return { type: "text", text: nonAnswerBodyError("clarivate_search", r, "a search response (no ids{} — the one key POST /search answers with)", ` query=${String(echo).slice(0, 200)}`) };
   }
+  forgetContradictedAnswers(base, body, r.body, tctx);
   const out = normalizeSearchResponse(r.body, echo, p.match_mode || "default");
   // The resolution note rides on the answer, exactly as it does on the enumerate result: a reader has
   // to be able to see WHICH applicant styling this sweep actually asked for, and a zero over an owner
@@ -1115,6 +1214,22 @@ export async function doSearch(apiKey, base, params, tctx) {
   return { type: "text", text: JSON.stringify(out, null, 2) };
 }
 
+// A SEARCH SHORTER THAN ITS OWN COUNT IS NOT KEPT, AND NEITHER IS THE COUNT. The enumerate kernel reads the
+// shortfall as the register contradicting itself and hands the slice to the repair ladder to ask again
+// (the count/search reconciliation in providers/_shared/enumerate.mjs). Kept, both answers would be served
+// again on every retry, and the slice could not be cured within the attempt. The two share one body, so
+// the count held for this search is found under the same question.
+function forgetContradictedAnswers(base, body, searchBody, tctx) {
+  const mem = openAnswerMemory(tctx?.recordLog);
+  if (!mem) return;
+  const countKey = answerKey({ base, method: "POST", path: "/count", body });
+  const counted = recallAnswer(mem, countKey)?.summary?.total;
+  const returned = rememberableAnswer("/search", 200, searchBody, null)?.total;
+  if (!Number.isFinite(counted) || !Number.isFinite(returned) || returned >= counted) return;
+  forgetAnswer(mem, countKey);
+  forgetAnswer(mem, answerKey({ base, method: "POST", path: "/search", body }));
+}
+
 // ── Count ─────────────────────────────────────────────────────────────────────────────────────────
 // POST /count takes the SAME SearchRequest body as /search, is cheap, works at ANY magnitude and
 // returns PER-OFFICE counts in one call. This is the enumerate
@@ -1269,7 +1384,7 @@ async function fetchText(apiKey, base, group, testMode, tctx) {
   const body = { ids: group };
   if (testMode) body.test = true;
   const target = group.slice(0, 5).join(",") + (group.length > 5 ? `+${group.length - 5}` : "");
-  const r = await clarivateFetch(apiKey, base, "/text", { body, tctx: { ...tctx, target } });
+  const r = await clarivateFetch(apiKey, base, "/text", { body, tctx: { ...tctx, target }, ledgerExtra: { records: group.map((g) => String(g).toLowerCase()) } });
   if (!r.ok) return { ok: false, raw: [], error: `HTTP ${r.status} for a ${group.length}-id chunk: ${errText(r)}` };
   // On this provider /text is the ONLY source of mark text, classes, status and owner (the search
   // returns bare guids), and the kernel's contentFromScreen seam reads a chunk error to decide whether
@@ -1305,21 +1420,31 @@ export async function doRecordFetch(apiKey, base, params, tctx) {
   if (inputs.length === 0) return { type: "text", text: "ERROR: clarivate_record_fetch — record_ids is required (non-empty array of refs or guids)." };
 
   const { officeByGuid, guids } = splitRefs(inputs);
-  const groups = chunk(guids, TEXT_BATCH_MAX);
+  // A record this run already holds is not fetched again (heldRecords); test-mode bodies are obfuscated
+  // and are never held.
+  const held = params.test_mode ? new Map() : heldRecords(tctx, guids);
+  logHeldRecords(tctx, held);
+  const groups = chunk(guids.filter((g) => !held.has(String(g).toLowerCase())), TEXT_BATCH_MAX);
   const records = [];
+  const fetched = [];
   const errors = [];
+  for (const rec of held.values()) { const nr = normalizeRecord(rec, rec?.id ? officeByGuid[rec.id] : null); records.push(nr); fetched.push(nr); }
   for (const group of groups) {
     const { ok, raw, error } = await fetchText(apiKey, base, group, params.test_mode, tctx);
     if (!ok) { errors.push(error); continue; }
-    for (const rec of raw) records.push(normalizeRecord(rec, rec?.id ? officeByGuid[rec.id] : null));
+    for (const rec of raw) { const nr = normalizeRecord(rec, rec?.id ? officeByGuid[rec.id] : null); records.push(nr); fetched.push(nr); }
   }
   if (!records.length && errors.length) {
     return { type: "text", text: `ERROR: clarivate_record_fetch — ${errors.join("; ")}` };
   }
   // A1: persist each normalized record keyed by its synthetic ref so the driver can field-verify
   // registry identifiers and archive the record into the run. (test_mode bodies are obfuscated — skip.)
+  // A HELD RECORD IS WRITTEN TOO, under the address this request gives it. The screen gate matches exact
+  // addresses against this log, and a record first fetched under another office's address was otherwise
+  // absent under this one, so a drop citing it read as a record nobody examined. The log keeps one row per
+  // address (writeRecordOnce), so a held record already logged under this address writes nothing.
   if (!params.test_mode) {
-    for (const nr of records) if (nr?.uri) logRecordBody({ ...tctx, kind: "record_fetch" }, nr.uri, nr);
+    for (const nr of fetched) if (nr?.uri) logRecordBody({ ...tctx, kind: "record_fetch" }, nr.uri, nr);
   }
   return { type: "text", text: JSON.stringify({ count: records.length, records, errors: errors.length ? errors : undefined }, null, 2) };
 }
@@ -1337,15 +1462,21 @@ export async function doBatchScreen(apiKey, base, params, tctx) {
     ? params.in_scope_classes.map(Number).filter(Number.isFinite) : [];
 
   const { officeByGuid, guids } = splitRefs(inputs);
-  const groups = chunk(guids, TEXT_BATCH_MAX);
+  // A record this run already holds is screened from its stored raw copy and not fetched again
+  // (heldRecords); only the rest go to /text. Test-mode bodies are obfuscated and are never held.
+  const held = params.test_mode ? new Map() : heldRecords(tctx, guids);
+  logHeldRecords(tctx, held);
+  const groups = chunk(guids.filter((g) => !held.has(String(g).toLowerCase())), TEXT_BATCH_MAX);
   const rows = [];
   const errors = [];
   const normalized = [];
-  for (const group of groups) {
-    const { ok, raw, error } = await fetchText(apiKey, base, group, params.test_mode, tctx);
+  const answers = held.size ? [{ ok: true, raw: [...held.values()], held: true }] : [];
+  for (const group of groups) answers.push({ ...(await fetchText(apiKey, base, group, params.test_mode, tctx)), held: false });
+  for (const { ok, raw, error } of answers) {
     if (!ok) { errors.push(error); continue; }
     for (const rec of raw) {
       const nr = normalizeRecord(rec, rec?.id ? officeByGuid[rec.id] : null);
+      // A held record is logged as well, under this request's address, for the reason doRecordFetch gives.
       normalized.push(nr);
       const row = {
         uri: nr.uri,
@@ -1398,6 +1529,7 @@ export async function doBatchScreen(apiKey, base, params, tctx) {
   for (const row of rows) verdict_summary[row.screen_verdict] = (verdict_summary[row.screen_verdict] ?? 0) + 1;
   return { type: "text", text: JSON.stringify({
     requested: inputs.length, returned: rows.length, chunks: groups.length,
+    ...(held.size ? { held: held.size } : {}),
     in_scope_classes: inScopeClasses.length ? inScopeClasses : "NOT PROVIDED — live marks fail-safe to surface:in-scope-live (no class-drop)",
     errors: errors.length ? errors : undefined,
     note: "Per-row `screen_verdict` (CLOSED SET) is the keep/drop authority — NOT the mark name or owner. drop:dead = a confidently dead status; drop:out-of-class = live but no in-scope-class overlap and not all_class — these two are batch-screen-authoritative drops. surface:in-scope-live and surface:all-class = a real in-scope candidate: decide it on the record's goods & services (this provider returns them on this very call). deepfetch:ambiguous = status unrecognised, never auto-drop.",
@@ -1645,6 +1777,33 @@ export async function doFilingDate(apiKey, base, params, tctx) {
   return { type: "text", text: JSON.stringify({ count: rows.length, registers: rows }, null, 2) };
 }
 
+// ── ONE OFFICE WITH NO GOODS FIELD REFUSES THE WHOLE REQUEST ─────────────────────────────────────
+// The vendor answers a goods-narrowed request with HTTP 400 "Search field INT_GOODS_SERVICES_DESCRIPTION
+// is not supported for registrationOfficeCode XX" when any one office in it lacks the field, so every
+// other office goes unasked. A retry of the same request cannot change that; the request without that
+// office can. Ask again without it, as often as another office refuses, and name each office left out on
+// the result. No call is added unless an office refuses.
+export function officeRefusingGoodsField(reason) {
+  const m = new RegExp(`Search field ${GOODS_FIELD} is not supported for registrationOfficeCode ([A-Z]{2})\\b`).exec(String(reason ?? ""));
+  return m ? m[1] : null;
+}
+
+export async function withoutOfficesRefusingGoods(params, ask, reasonOf) {
+  const leftOut = [];
+  let p = params;
+  let out = await ask(p);
+  for (let office = officeRefusingGoodsField(reasonOf(out)); office && !leftOut.includes(office); office = officeRefusingGoodsField(reasonOf(out))) {
+    const regions = (Array.isArray(p?.regions) ? p.regions : []).filter((r) => !resolveOffices([r]).codes.includes(office));
+    // The refusing office is not in the request as the caller wrote it, or it is the only one: the
+    // refusal stands as it was given.
+    if (!regions.length || regions.length === (p?.regions ?? []).length) break;
+    leftOut.push(office);
+    p = { ...p, regions };
+    out = await ask(p);
+  }
+  return { out, params: p, leftOut };
+}
+
 // ── Enumerate — WIRED FROM THE SHARED KERNEL ──────────────────────────────────────────────────────
 //
 // The control flow (states, ceilings, the wide-`names` chunking, the count-first per-term rescue) lives
@@ -1685,8 +1844,14 @@ export async function doEnumerate(apiKey, base, params, tctx) {
   const chunked = Array.isArray(p?.names) && p.names.filter(Boolean).length > namesChunk;
 
   const sink = [];
-  let r = await __enumerate({ apiKey, base }, { ...p, __countSink: sink }, tctx);
-  let parsed = parseToolText(r);
+  const asked = await withoutOfficesRefusingGoods(p, async (q) => {
+    sink.length = 0;
+    const rr = await __enumerate({ apiKey, base }, { ...q, __countSink: sink }, tctx);
+    return { rr, parsed: parseToolText(rr) };
+  }, (o) => o.parsed?.reason);
+  p = asked.params;
+  let r = asked.out.rr;
+  let parsed = asked.out.parsed;
   if (!parsed) return r;
 
   // ── the ADDITIVE invariant, ENFORCED AT RUNTIME TOO ─────────────────────────────────────────────
@@ -1711,7 +1876,7 @@ export async function doEnumerate(apiKey, base, params, tctx) {
     // without it the kernel's calls underneath this fallback would re-resolve the very names whose
     // expansion the provider has just rejected — reinstating the stack the fallback exists to drop.
     // The un-resolved sweep has to be genuinely un-resolved, at every seam.
-    const rawOnly = { ...params, resolve_owner: false };
+    const rawOnly = { ...params, regions: p.regions, resolve_owner: false };
     delete rawOnly.owners;
     const sink2 = [];
     const r2 = await __enumerate({ apiKey, base }, { ...rawOnly, __countSink: sink2 }, tctx);
@@ -1732,6 +1897,9 @@ export async function doEnumerate(apiKey, base, params, tctx) {
     }
   }
 
+  // After the owner fallback, which may replace the answer: it asks with the same reduced offices.
+  if (asked.leftOut.length) parsed.offices_without_goods_field = asked.leftOut;
+
   if (parsed.state === "incomplete") {
     // The 30000 ceiling is the provider truthfully reporting a CROWD, not a fault. Restate it as a
     // crowd descriptor — and strip the kernel's generic "provider error" framing, because an
@@ -1750,6 +1918,13 @@ export async function doEnumerate(apiKey, base, params, tctx) {
     if (chunked) {
       parsed.per_office_counts = null;
       parsed.per_office_counts_unavailable = `the ${p.names.length}-name stack was enumerated in windows of ${namesChunk} (the provider's OR-width bound), so no whole-stack per-office count exists — per-window counts would misreport the jurisdictional shape of this crowd.`;
+    } else if (parsed.region_split) {
+      // ASKED IN REGION HALVES after a gateway timeout, so sink[0] may be one half's count. Each count
+      // covers exactly its own offices, and an office's count is the same whichever count asked it, so
+      // the first count that names an office answers for it.
+      const perOffice = {};
+      for (const entry of sink) for (const [office, n] of Object.entries(entry?.per_office ?? {})) if (!(office in perOffice)) perOffice[office] = n;
+      if (Object.keys(perOffice).length) parsed.per_office_counts = perOffice;
     } else if (sink.length && sink[0]?.per_office) {
       parsed.per_office_counts = sink[0].per_office;
     }

package/providers/corsearch/README.md

@@ -13,8 +13,7 @@ a global aggregator, so it declares no enumerable covered office set; see the la
 | `test/` | Characterisation and fault-lane tests |
 
 Environment: `CORSEARCH_SESSION_KEY` is required, and it is a **session cookie**, not a bearer token —
-`core.js` sends it as `Cookie: sessionKey=…`. `src/index.js` will also take it from the gateway's
-`plugins.entries.clawdi-corsearch.config.sessionKey`. There is no base-URL variable: `BASE_SEARCH`,
+`core.js` sends it as `Cookie: sessionKey=…`. There is no base-URL variable: `BASE_SEARCH`,
 `BASE_DETAIL` and `BASE_IMAGE` are constants in `core.js`. The per-call ledger paths come from
 `CLEAROTRON_REGISTER_CALL_LOG` / `CLEAROTRON_REGISTER_RECORD_LOG`, resolved in
 [`../_shared/ledger-path.mjs`](../_shared/ledger-path.mjs) and shared with the other register adapters

package/providers/corsearch/src/core.js

@@ -54,7 +54,7 @@ export const MATCH_MODE_PREFIX = {
 // `provider` discriminator on every row.
 //
 // SECURITY — the ids logged (agentId / sessionKey / sessionId) are the GATEWAY tool-call context
-// (e.g. "clawdi", "clearotron-acme-…"), the per-run attribution. They are NOT the Corsearch `sessionKey`
+// (e.g. "localagent", "clearotron-acme-…"), the per-run attribution. They are NOT the Corsearch `sessionKey`
 // COOKIE (the live credential, which merely shares the name). logCall is only ever handed `tctx`
 // (kind + gateway ids + target) and response metrics — the cookie is never passed in. Keep it so.
 export const { logCall, logRecordBody, tctxOf } = makeLedger("corsearch");
@@ -269,7 +269,7 @@ export function normalizeSearchResponse(body, echoQuery, matchMode) {
 // ── Search (with per-run dedup) ───────────────────────────────────────────────
 // The plugin runs in the long-lived gateway daemon, so this module-level Map persists across tool
 // calls within a run. A run issues the SAME search more than once (~12% of this build's baseline run
-// were exact-duplicate sweeps — name:CLAWDI, the JP and CN transliteration sweeps each issued twice),
+// were exact-duplicate sweeps — the name sweep and the JP and CN transliteration sweeps, each issued twice),
 // invisible to telemetry because the dup counter watched record_fetch only. We cache the normalized
 // result keyed on the GATEWAY session key (per-run, unique → no cross-run collision) + the FULL
 // canonical upstream query tail (so a different page / field-set is NOT a dup). On an exact repeat we

package/providers/jx-subclass/lookup.mjs

@@ -83,7 +83,7 @@ export function subclassesFor(db, { country, term, niceClass }) {
                  cn_goods_code: row.group_code,   // what the 12th says, kept even when the 13th governs
                })),
                source: from13 === ruled.length
-                 ? "NCL 13-2026 concordance — the 13th edition governs the group code (#1391); CNIPA's 区分表 found the good"
+                 ? "NCL 13-2026 concordance — the 13th edition governs the group code; CNIPA's 区分表 found the good"
                  : from13 === 0
                    ? "CNIPA 区分表, 12th edition (2023 text) — the 13th edition holds no group for this good, so there is nothing it disagrees with"
                    : `mixed: ${from13} of ${ruled.length} matched goods take the 13th edition's group, the rest have no 13th-edition group at all`,

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

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

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

@@ -43,11 +43,12 @@ The bridge owns `<creds-dir>/<server>.json` from the moment the recipe below
 writes it, and refreshes are written back there. mcporter's own credential store
 can rotate or clear without affecting the bridge.
 
-**Where `<creds-dir>` is.** `bridge.mjs` reads `--creds-dir`, else
-`OAUTH_BRIDGE_CREDS_DIR`, else `~/.config/trademark-oauth-mcp`. `warm-server.mjs`
-reads `--creds-dir`, else `~/.config/clawdi/oauth-mcp` — it has no env override,
-so a deployment that runs both must pass the same directory to the warm server
-explicitly or keep the credentials where each default looks.
+**Where `<creds-dir>` is.** Both `bridge.mjs` and `warm-server.mjs` read
+`--creds-dir`, else `OAUTH_BRIDGE_CREDS_DIR`, else `~/.config/trademark-oauth-mcp`.
+They disagreed until 2026-09-27 — the warm server defaulted elsewhere and took no
+variable at all, so a deployment running both had to pass the directory explicitly.
+A deployment whose credentials sit in the folder an earlier build used points
+`OAUTH_BRIDGE_CREDS_DIR` at that folder.
 
 ## One-time setup (per remote MCP server)
 
@@ -247,7 +248,7 @@ that way.
 
 Two caveats on "courtlistener is warm", both about WHERE. First, no box runs a unit of
 that name: `driver/unit-inventory.mjs` declares the shipped one an orphan and records the
-live service as `clawdi-courtlistener-mcp`, run from another checkout — so editing
+live service under a name of its own, run from another checkout — so editing
 `warm-server.mjs` or the unit file here changes nothing on the running proxy. Second, the
 clearance engine does not reach the warm service at all: `driver/engine/mcp/gather-config.mjs`
 mounts courtlistener as a per-session `bridge.mjs` spawn, exactly like legaldatahunter, so
@@ -274,7 +275,7 @@ checkout.
 
 **Why this unit does not take `CLEAROTRON_CHECKOUT_DIR` the way the driver units do**: those load
 `EnvironmentFile=%h/.env` and expand `${CLEAROTRON_CHECKOUT_DIR}` in `ExecStart`. This one deliberately
-loads no environment file — it reads the OAuth cache at `~/.config/clawdi/oauth-mcp/courtlistener.json`
+loads no environment file — it reads the OAuth cache under the credentials directory
 and needs nothing else — and on systemd an `EnvironmentFile` **overrides** the unit's own `Environment=`
 lines, so adding one to gain the variable would also let `~/.env` silently replace this unit's `PATH`.
 Editing one line is the smaller cost. Keep `loginctl enable-linger <user>` on if the service must

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

@@ -33,13 +33,13 @@ import { driverDir } from "../../shared/driver-dir.mjs";   //
 import { RefreshLock } from "./refresh-lock.mjs";
 import { exitOnStdinClose } from "./stdin-guard.mjs";
 
-// Creds dir: env-overridable (OAUTH_BRIDGE_CREDS_DIR). An existing deployment migrating from the
-// origin monorepo keeps its credentials by pointing this at the old ~/.config/clawdi/oauth-mcp.
+// Creds dir: env-overridable (OAUTH_BRIDGE_CREDS_DIR). A deployment whose credentials still sit in the
+// folder an earlier build used keeps them by pointing this variable at that folder.
 const DEFAULT_CREDS_DIR = process.env.OAUTH_BRIDGE_CREDS_DIR || path.join(homedir(), ".config", "trademark-oauth-mcp");
 
 // Per-server tool allowlist. Upstream MCP servers may add or rename tools
 // without notice — we explicitly opt in. To add a tool: verify it's read-only
-// (or otherwise intended for clawdi use) against the upstream API docs, then
+// (or otherwise intended for this product's use) against the upstream API docs, then
 // add the unprefixed upstream name below and restart the bridge.
 const ALLOWED_TOOLS = {
   courtlistener: new Set([
@@ -146,7 +146,7 @@ process.on("exit", () => refreshLock.releaseSync());
 // of holding the upstream HTTP transport (and any in-flight upstream call) open forever (see
 // stdin-guard.mjs for the 3.5-day PPID-1 orphan this closes). The 'exit' hook above releases the
 // refresh lock on the way out.
-exitOnStdinClose({ name: `clawdi-oauth-bridge:${serverName}` });
+exitOnStdinClose({ name: `clearotron-oauth-bridge:${serverName}` });
 
 class CachedOAuthProvider {
   constructor(initialCreds) {
@@ -278,6 +278,20 @@ function resultBytes(res) {
   try { return JSON.stringify(res ?? null).length; } catch { return null; }
 }
 
+/**
+ * AN ERROR ANSWER IS A FAILED CALL. Under MCP a tool reports its own failure, a quota or an outage behind
+ * the server, inside its result as `isError: true`, and the call itself returns. Logged as ok, that answer
+ * read as a source that answered: a case-law pass whose every query met a failing source would then read
+ * as having searched and found nothing. Returns the source's words, cut like a thrown error's, or null
+ * for an answer that is not an error.
+ */
+function toolError(res) {
+  if (res?.isError !== true) return null;
+  const said = (Array.isArray(res.content) ? res.content : [])
+    .filter((c) => c?.type === "text").map((c) => String(c.text ?? "")).join(" ").trim();
+  return (said || "the tool answered with an error").slice(0, 200);
+}
+
 function logCall(server, tool, args, result) {
   if (!AUDIT_RUN_DIR) return;
   try {
@@ -341,7 +355,9 @@ async function main() {
     }
     try {
       const res = await upstream.callTool({ name, arguments: req.params.arguments });
-      logCall(serverName, name, req.params.arguments, { ok: true, bytes: resultBytes(res) });
+      const refused = toolError(res);
+      if (refused === null) logCall(serverName, name, req.params.arguments, { ok: true, bytes: resultBytes(res) });
+      else logCall(serverName, name, req.params.arguments, { ok: false, error: refused });
       return res;
     } catch (err) {
       // A FAILED CALL IS LOGGED TOO, and it is the half that matters: without it, "the search ran and

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

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

@@ -5,7 +5,7 @@ After=network-online.target
 Wants=network-online.target
 
 [Service]
-# Reads the OAuth cache at ~/.config/clawdi/oauth-mcp/courtlistener.json (no ~/.env needed).
+# Reads the OAuth cache at <creds-dir>/courtlistener.json (no ~/.env needed).
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
 # ── RESOLVED AT INSTALL (option B) ───────────────────────────────────────────────────────────
 # `@CLEAROTRON_CHECKOUT_DIR@` is substituted by render-units.mjs when it writes the resolved copy.

package/providers/oauth-mcp-bridge/warm-server.mjs

@@ -53,8 +53,19 @@ import { randomUUID } from "node:crypto";
 import http from "node:http";
 import path from "node:path";
 import { listenOrDie } from "../../shared/listen.mjs";   // — a taken port is a sentence, not a stack
+import { warnRetiredEnv } from "../../shared/env-aliases.mjs";
 
-const DEFAULT_CREDS_DIR = path.join(homedir(), ".config", "clawdi", "oauth-mcp");
+// THE REFUSAL ONLY, NO ENVIRONMENT FILE. This process reads one variable and deliberately loads no
+// `.env` — its unit says so and explains why — but an operator who renamed the retired settings in that
+// unit must not have this process silently stop seeing them. Reading the environment is what owes the
+// refusal, and until 2026-09-27 this file read none, which is why it owed nothing.
+warnRetiredEnv();
+
+// Creds dir: env-overridable (OAUTH_BRIDGE_CREDS_DIR), and the same folder `bridge.mjs` already
+// defaults to. The two entry points disagreed — this one named a folder after the old agent id and took
+// no override at all, which is what made an install on the default unable to keep its sign-in. A
+// deployment whose credentials sit in the old folder points the variable at it.
+const DEFAULT_CREDS_DIR = process.env.OAUTH_BRIDGE_CREDS_DIR || path.join(homedir(), ".config", "trademark-oauth-mcp");
 
 // Per-server tool allowlist — upstream servers may add/rename tools without
 // notice, so we explicitly opt in. Kept in sync with bridge.mjs ALLOWED_TOOLS.
@@ -132,7 +143,7 @@ if (!allowedTools) {
 }
 
 const log = (msg) =>
-  process.stderr.write(`[clawdi-warm-mcp:${serverName}] ${msg}\n`);
+  process.stderr.write(`[clearotron-warm-mcp:${serverName}] ${msg}\n`);
 
 async function loadCreds() {
   let raw;
@@ -199,7 +210,7 @@ class WarmOAuthProvider {
   get clientMetadata() {
     return (
       this._creds.clientInfo?.metadata ?? {
-        client_name: "clawdi-oauth-mcp-bridge",
+        client_name: "clearotron-oauth-mcp-bridge",
         grant_types: ["authorization_code", "refresh_token"],
         response_types: ["code"],
         redirect_uris: [],
@@ -279,7 +290,7 @@ function scheduleKeepWarm(expiresInSec) {
 // warm upstream through the serialization mutex, applying the allowlist.
 function makeProxyServer() {
   const server = new Server(
-    { name: `clawdi-warm-${serverName}`, version: "0.1.0" },
+    { name: `clearotron-warm-${serverName}`, version: "0.1.0" },
     { capabilities: { tools: {} } },
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -344,7 +355,7 @@ async function main() {
   const authProvider = new WarmOAuthProvider(creds);
 
   upstream = new Client(
-    { name: "clawdi-warm-mcp-client", version: "0.1.0" },
+    { name: "clearotron-warm-mcp-client", version: "0.1.0" },
     { capabilities: {} },
   );
   const clientTransport = new StreamableHTTPClientTransport(