clearotron 0.3.3 → 0.4.0-beta.1

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,86 @@ 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 });
+  logCall(tctx, { http_status: resp.status, ok: resp.ok, attempts, took_ms: Date.now() - t0, bytes: raw.length, cache_hit: false, ...(ledgerExtra ?? {}) });
+  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 +285,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 +398,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.
@@ -1107,6 +1200,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 +1209,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 +1379,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 +1415,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 +1457,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 +1524,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.",

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.1
+
+No changes in this release.
+
+## 0.4.0-beta.0
+
+No changes in this release.
+
 ## 0.3.3
 
 No changes in this release.

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

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

@@ -337,6 +337,30 @@ export const CAPABILITIES = Object.freeze({
   // search rows therefore finds no scripts anywhere and reads as "the index holds none" — which is
   // how this probe failed on its first attempt, and it failed by returning an empty set, not an error.
   nativeScriptIndex: true,
+  // ── A TERM THAT MIXES ALPHABETS IS NOT SEARCHED AS WRITTEN ──────────────────────────────────────
+  //
+  // A term mixing Latin letters with Greek or Cyrillic ones, such as `τιmbεr`, is answered as if the
+  // non-Latin letters were absent: the rows that come back share only the Latin remainder, so none of
+  // them is the spelling asked for. The form band's whole-word look-alike swap writes exactly these
+  // terms, because it leaves every letter without a Greek or Cyrillic twin in Latin, and on a common
+  // remainder the unrelated rows arrive as a crowd that a report then reads as unread coverage.
+  //
+  // `false` says so. driver/form-neighbourhood.mjs then leaves those spellings out of the form band on
+  // this register and lists them there as not searched. A wholly Greek or Cyrillic term is a different
+  // question, answered by `nativeScriptIndex` above, and still goes out.
+  //
+  // OPTIONAL, like `queryableStatuses`: a provider that does not declare it keeps sending these terms,
+  // as every provider did before the field existed.
+  mixedScriptQuery: false,
+  // ── A KNOCKOUT'S LISTING ALREADY HOLDS ITS COUNT ─────────────────────────────────────────────────
+  //
+  // The knockout listing asks the count lane's exact question (the same term, classes and territories)
+  // and `include_total` puts the register's own total on the answer. So a knockout lists first and takes
+  // the identical and close counts from those totals (driver/register-count.mjs listingAnswers), rather
+  // than asking each of them twice. A term the listing did not answer is counted as before.
+  //
+  // OPTIONAL: a provider that does not declare it counts first and lists second, as before.
+  listingAnswersCount: true,
   // Opposition data IS on the record, and in three places: `opposition_window` on every search row,
   // `proceedings_count` on the full record, and the filters `has_proceedings`,
   // `opposition_status` and `opposition_closes_before/after`. GET /v1/trademarks/{id}/proceedings

package/providers/signa/src/core.js

@@ -27,6 +27,7 @@ import { goodsTermsList } from "../../_shared/term-shape.mjs";   // the shared r
 
 import { makeLedger } from "../../_shared/ledger.mjs";
 import { nonAnswerBodyError, parseJsonBody, unparsedBodyError } from "../../_shared/http-body.mjs";
+import { answerKey, compareAnswers, noteAnswer, openAnswerMemory, recallAnswer, rememberAnswer } from "../../_shared/answer-memory.mjs";
 import { makeEnumerate, isOwnerScoped } from "../../_shared/enumerate.mjs";
 import { makeExecutePlan } from "../../_shared/execute-plan.mjs";
 import CAPABILITIES, { SIGNA_OFFICE_KEYS, OWNER_SCOPED_WINDOW } from "./capabilities.js";
@@ -76,6 +77,11 @@ export function refToOffice(ref) {
 }
 
 // ── HTTP helper (Bearer auth + the metered chokepoint) ─────────────────────────────────────────────
+//
+// THE RUN MEMORY sits here because every request this provider makes passes through here — see
+// providers/_shared/answer-memory.mjs. The question is the base address, the method, the path and the
+// whole body, and never the credential; the base is in it so a test server and the register never share
+// an answer. With no memory for the run (the default), this is the plain fetch it always was.
 export async function signaFetch(apiKey, base, path, { method = "GET", body = null, retries = 1, tctx = null } = {}) {
   const url = `${base}${path}`;
   const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
@@ -83,6 +89,26 @@ export async function signaFetch(apiKey, base, path, { method = "GET", body = nu
   if (body !== null) { headers["Content-Type"] = "application/json"; init.body = JSON.stringify(body); }
 
   const t0 = Date.now();
+  const mem = openAnswerMemory(tctx?.recordLog);
+  const key = mem ? answerKey({ base, method, path, body }) : null;
+  const recalled = mem ? recallAnswer(mem, key) : null;
+  // A held answer too old to trust its next-page cursor is not used, and is replaced by the fresh one.
+  const held = recalled && !recalled.stale ? recalled : null;
+  // `via` says which kind of process asked: the driver hands its calls the run's record log, and a tool
+  // server a stage spawned finds the run through its environment. The watch log must show both, because a
+  // memory only one of them can find removes only half the repeats.
+  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,
+    ...(recalled?.stale ? { held_stale: true, held_age_ms: recalled.age_ms } : {}), ...row });
+  if (held && mem.mode === "on") {
+    // Served from the memory: nothing goes to the register. The ledger still gets its line, marked as a
+    // cache hit, so the run's usage shows the request was made and was not paid for.
+    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, resp;
   try {
     for (let i = 0; i <= retries; i++) {
@@ -93,15 +119,55 @@ export async function signaFetch(apiKey, base, path, { method = "GET", body = nu
     }
   } catch (err) {
     logCall(tctx, { http_status: 0, ok: false, attempts, took_ms: Date.now() - t0, bytes: 0, cache_hit: false });
+    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 });
+  if (mem) {
+    // In `watch` every request reaches this line, held or not, and the line says what the memory would
+    // have done. The FIRST answer is the one kept: a later identical request is compared against it
+    // and never replaces it, so every comparison in a run is against the answer that would be served.
+    const summary = rememberableAnswer(method, 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 (recalled?.stale && summary) Object.assign(row, compareAnswers(recalled.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, as the short summary a watch compares — or null when the answer must
+ * be asked again next time.
+ *
+ * KEPT: a search page that is a whole answer (it parsed, it carries `data[]` — isSearchResponseBody —
+ * and it carries its total); a record that parsed and names itself; and a `validation_error`, which is
+ * the register saying the question itself is malformed and will say so every time.
+ *
+ * NEVER KEPT: a body that did not parse, a 200 without `data[]`, an authentication, payment, permission
+ * or rate refusal, a cursor refusal, a server error, and anything else. Those are exactly the answers
+ * doSearch and doRecordFetch refuse or report as failures, and remembering one would turn a passing
+ * fault into the run's permanent answer.
+ */
+export function rememberableAnswer(method, status, body, parseError) {
+  if (parseError || body == null || typeof body !== "object" || Array.isArray(body)) return null;
+  if (status === 200 && method === "POST") {
+    if (!isSearchResponseBody(body) || !Number.isFinite(body.pagination?.total_count)) return null;
+    return { total: body.pagination.total_count, ids: body.data.map((row) => row?.id ?? null), next_page: body.has_more === true };
+  }
+  if (status === 200 && method === "GET") {
+    const rec = body.data ?? body;
+    if (!rec || typeof rec !== "object" || Array.isArray(rec) || !rec.id) return null;
+    return { total: null, ids: [rec.id], next_page: false };
+  }
+  if (status === 400 && body.error?.type === "validation_error") return { total: null, ids: [], next_page: false, refusal: "validation_error" };
+  return null;
+}
+
 // ── Search-request assembly ────────────────────────────────────────────────────────────────────────
 // THE TWO MATCH SHAPES ARE MUTUALLY EXCLUSIVE, and the live specification is explicit:
 // "Deterministic modes require a query and disallow strategies/ranking_profile."

package/scripts/deprecate-below.mjs

@@ -2,9 +2,11 @@
 // 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
 //
-// deprecate-below.mjs — put one warning on every published version below a named stable.
+// deprecate-below.mjs — put one warning on every published version below a named stable, or on a named
+// range of published versions.
 //
 //   node scripts/deprecate-below.mjs --below 0.3.1 [--dry-run]
+//   node scripts/deprecate-below.mjs --range "0.2.0..0.4.0-beta.0 except 0.3.3" [--dry-run]
 //
 // ── WHY THIS IS A SCRIPT IN CI AND NOT SOMETHING A PERSON RUNS ──────────────────────────────────────
 //
@@ -70,6 +72,56 @@ export function compareVersions(a, b) {
   return 0;
 }
 
+// ── THE RANGE MODE: A NAMED SET OF VERSIONS, ONE SENTENCE, NO REASON GIVEN ──────────────────────────
+//
+// Some versions have to be warned that are not simply "everything below a stable": a stretch of betas
+// and stables with one version held out because an install still runs it. The range says exactly that,
+// inclusive at both ends in npm's own order, and the exceptions are named one by one.
+//
+// ITS SENTENCE IS FIXED HERE AND NOT TYPED AT DISPATCH. It is public text on every version page, so it
+// is the owner's sentence, approved word for word, and a dispatch box is no place to redraft it.
+//
+// IT REPLACES AN OLDER MESSAGE IN THE RANGE, unlike the mode above. A range is warned for one reason, so
+// every version in it reads the same; a version that already says exactly this is left alone.
+//
+// IT NEVER TOUCHES A VERSION A DIST-TAG POINTS AT. `latest` and `beta` are what `npm install` resolves
+// to, and a warning on the version a reader is told to install is worse than none.
+export const RANGE_MESSAGE = "This version is no longer supported. Please upgrade to the latest version of clearotron.";
+
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/;
+
+/** Read "<from>..<through>[ except <v>[,<v>…]]". Throws on anything else. */
+export function parseRangeSpec(spec) {
+  const m = String(spec ?? "").trim().match(/^(\S+)\.\.(\S+?)(?:\s+except\s+(\S+))?$/);
+  if (!m) throw new Error(`"${spec}" is not a range: write <from>..<through>, optionally followed by " except <v>,<v>"`);
+  const [, from, through, ex = ""] = m;
+  const except = ex ? ex.split(",").map((v) => v.trim()).filter(Boolean) : [];
+  for (const v of [from, through, ...except]) if (!VERSION.test(v)) throw new Error(`"${v}" is not a version`);
+  if (compareVersions(from, through) > 0) throw new Error(`${from} is above ${through}: the range is empty`);
+  return { from, through, except };
+}
+
+/**
+ * The published versions a range names, in order: from and through inclusive, the exceptions out.
+ * Throws, before anything is written, when a bound is not published, an exception lies outside the
+ * range or is not published, or a selected version is one a dist-tag points at.
+ */
+export function selectRange(all, { from, through, except }, distTags = {}) {
+  for (const b of [from, through]) if (!all.includes(b)) throw new Error(`${b} is not a published version of ${PKG}`);
+  const inRange = (v) => compareVersions(v, from) >= 0 && compareVersions(v, through) <= 0;
+  for (const e of except) {
+    if (!all.includes(e)) throw new Error(`the exception ${e} is not a published version of ${PKG}`);
+    if (!inRange(e)) throw new Error(`the exception ${e} lies outside ${from}..${through}`);
+  }
+  const picked = all.filter((v) => inRange(v) && !except.includes(v)).sort(compareVersions);
+  const tagged = Object.entries(distTags).filter(([, v]) => picked.includes(v));
+  if (tagged.length) {
+    throw new Error(`the range takes ${tagged.map(([t, v]) => `${v} (${t})`).join(", ")}, which a dist-tag points at; `
+      + "move the tag or hold the version out");
+  }
+  return picked;
+}
+
 const npm = (...args) => execFileSync("npm", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 
 /** Every published version, and the deprecation message each carries. Read once, as a list. */
@@ -130,9 +182,11 @@ async function main() {
   const argv = process.argv.slice(2);
   const at = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
   const DRY = argv.includes("--dry-run");
+  const range = at("--range");
+  if (range) return deprecateRange(range, DRY);
   const below = at("--below");
   if (!below) {
-    console.error("deprecate-below: --below <version> is required — the stable everything under it points at.");
+    console.error("deprecate-below: --below <version> or --range \"<from>..<through> except <v>\" is required.");
     return 2;
   }
   const MESSAGE = `This version is superseded. Please upgrade to ${below} or later: npm install ${PKG}@${below}`;
@@ -201,4 +255,62 @@ async function main() {
   return failed ? 1 : 0;
 }
 
+/** The range mode's run: select, write the fixed sentence where it is not already, read each back. */
+async function deprecateRange(spec, DRY) {
+  let picked;
+  try {
+    const parsed = parseRangeSpec(spec);
+    const all = published();
+    if (!all.length) throw new Error("the registry listed no versions");
+    const distTags = JSON.parse(npm("view", PKG, "dist-tags", "--json"));
+    picked = selectRange(all, parsed, distTags);
+    console.log(`deprecate-below: ${all.length} published version(s); ${picked.length} in ${spec}.`);
+  } catch (e) {
+    console.error(`deprecate-below: refusing — ${e.message}. Nothing was written.`);
+    return 2;
+  }
+  let done = 0, skipped = 0, failed = 0;
+  const wrote = [];
+  for (const v of picked) {
+    let existing;
+    try { existing = deprecationOf(v); }
+    catch (e) {
+      console.error(`  ${v}: could NOT be read (${String(e.message).split("\n")[0]}) — left alone.`);
+      failed += 1;
+      continue;
+    }
+    if (existing === RANGE_MESSAGE) { console.log(`  ${v}: already carries this message`); skipped += 1; continue; }
+    const was = existing ? ` (replacing "${existing.slice(0, 60)}")` : "";
+    if (DRY) { console.log(`  ${v}: would deprecate${was}`); done += 1; continue; }
+    try {
+      npm("deprecate", `${PKG}@${v}`, RANGE_MESSAGE);
+    } catch (e) {
+      console.error(`  ${v}: deprecate FAILED — ${String(e.stderr ?? e.message).split("\n")[0]}`);
+      failed += 1;
+      continue;
+    }
+    console.log(`  ${v}: deprecate accepted${was}`);
+    wrote.push(v);
+  }
+  let unconfirmed = [];
+  if (wrote.length && !DRY) {
+    // A replaced message is confirmed only once THIS sentence is served, not merely any sentence.
+    const r = await confirmWrites({
+      versions: wrote,
+      read: (v) => (deprecationOf(v) === RANGE_MESSAGE ? RANGE_MESSAGE : null),
+      sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+    });
+    unconfirmed = r.unconfirmed;
+    done += r.confirmed.length;
+    for (const v of r.confirmed) console.log(`  ${v}: serving the message`);
+    for (const v of unconfirmed) {
+      console.error(`  ${v}: WRITE ACCEPTED, not yet served after ${Math.round(r.waitedMs / 1000)}s — read it from `
+        + "outside before treating it as undone; re-running is safe and reports it as already carrying the message.");
+    }
+  }
+  console.log(`deprecate-below: ${done} ${DRY ? "would be " : ""}deprecated, ${skipped} already carried this message, `
+    + `${unconfirmed.length} accepted but not yet served, ${failed} failed.`);
+  return failed ? 1 : 0;
+}
+
 if (process.argv[1] && process.argv[1].endsWith("deprecate-below.mjs")) process.exit(await main());

package/scripts/freeze-example-run.mjs

@@ -237,7 +237,7 @@ const substituteVendorKey = (key) => {
 
 // meta.json keys the freeze is EXPECTED to change, with the reason. Anything else differing is a finding.
 const EXPECTED_META_DELTA = {
-  tokens: "telemetry pruned — _driver/*.jsonl is the only source (driver/tokens.mjs:82)",
+  tokens: "telemetry pruned — _driver/*.jsonl is the only source (rollupTokens in driver/tokens.mjs)",
   servedModels: "telemetry pruned — the attempt rows in _driver/*.jsonl are the only source (servedModels in driver/tokens.mjs)",
 };
 

package/scripts/live-surface-check.mjs

@@ -107,6 +107,7 @@ import { envFrom } from "../shared/env-aliases.mjs";
 import { gitTry, treeOf } from "../shared/tree-commit.mjs";   // — a packaged install has no git, and says its commit in build-info.json
 import { exitFor } from "../driver/surface-exit-verdict.mjs";   // — a check that could not look is not a drift, and they want different things done   // — the name a reader is told to set is the one in force
 import { planRunAgreementVerdict } from "../driver/plan-run-agreement-verdict.mjs";
+import { doorCallVerdict } from "../driver/door-call-verdict.mjs";   // — a refused or unanswered door call compared nothing
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const asJson = process.argv.includes("--json");
@@ -605,7 +606,11 @@ try {
   }
 } catch (e) {
   if (e?.message === "__door_unset__") skip("roster resolves", "this instance does not say where its ops-MCP is, so the roster was NOT PROBED");
-  else fail("roster resolves", `list_profiles failed: ${e.message}`);
+  else {
+    const v = doorCallVerdict(e, { asked: "list_profiles", notCompared: "the roster was not compared" });
+    if (v) record("roster resolves", v.state, v.message, v.blocked === true);
+    else fail("roster resolves", `list_profiles failed: ${e.message}`);
+  }
 }
 
 // 3. THE LOAD-BEARING CHECK — every door's availability answer vs the engine's own, recomputed here
@@ -644,7 +649,11 @@ try {
   }
 } catch (e) {
   if (e?.message === "__door_unset__") skip("ops-MCP reachable", "this instance does not say where its ops-MCP is — NOT PROBED");
-  else fail("ops-MCP reachable", `${MCP_URL}: ${e.message}`);
+  else {
+    const v = doorCallVerdict(e, { asked: `${MCP_URL} for describe_options`, notCompared: "the door's answers were not compared" });
+    if (v) record("ops-MCP reachable", v.state, v.message, v.blocked === true);
+    else fail("ops-MCP reachable", `${MCP_URL}: ${e.message}`);
+  }
 }
 
 // ── 3b. THE TRIGGER LANE, AS ITS OWN SURFACE ─────────────────────────────────────────────────────────