clearotron 0.4.0 → 0.4.1-beta.0

package/providers/signa/src/core.js

@@ -83,8 +83,24 @@ export function refToOffice(ref) {
 // 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.
+// ── WHAT EACH CALL COST, AS THE REGISTER STATES IT ──────────────────────────────────────────────
+//
+// The register charges by the credit and says how many on every response, `X-Credits-Charged`, errors
+// included (0). A search page and a record fetch differ tenfold, and the ledger's `tool` names the caller,
+// not the endpoint, so a run's spend could not be added up from the ledger: every figure was a guess. The
+// header is copied onto the ledger row with the endpoint it answered. NULL when the header is absent or
+// unreadable, never 0 — a missing figure is not a free call. A call answered from the run memory sent
+// nothing, so it is a real 0.
+const creditsCharged = (resp) => {
+  const v = resp?.headers?.get?.("x-credits-charged");
+  const n = v == null || String(v).trim() === "" ? NaN : Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+const endpointOf = (method, path) => `${method} ${String(path).split("?")[0].replace(/^(\/v1\/trademarks\/)[^/]+/, "$1{id}")}`;
+
 export async function signaFetch(apiKey, base, path, { method = "GET", body = null, retries = 1, tctx = null } = {}) {
   const url = `${base}${path}`;
+  const endpoint = endpointOf(method, path);
   const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
   const init = { method, headers };
   if (body !== null) { headers["Content-Type"] = "application/json"; init.body = JSON.stringify(body); }
@@ -106,7 +122,7 @@ export async function signaFetch(apiKey, base, path, { method = "GET", body = nu
     // 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 });
+    logCall(tctx, { http_status: held.status, ok, attempts: 0, took_ms: Date.now() - t0, bytes: held.raw.length, cache_hit: true, endpoint, credits_charged: 0 });
     note({ held: true, served: true, status: held.status });
     return { status: held.status, ok, url, body: parsed, raw: held.raw, parseError };
   }
@@ -119,14 +135,14 @@ export async function signaFetch(apiKey, base, path, { method = "GET", body = nu
       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, endpoint, credits_charged: null });
     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, endpoint, credits_charged: creditsCharged(resp) });
   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
@@ -180,7 +196,24 @@ export function rememberableAnswer(method, status, body, parseError) {
 // `match_mode: "starts_with"` for a trailing-`*` wildcard entry, and with no deterministic shape to
 // put it in, that entry fell through to a plain `exact` — a NARROWER query than the plan asked for,
 // answering as though it were the one requested.
-const DETERMINISTIC_MATCH = new Set(["similar", "exact", "starts_with", "ends_with", "contains"]);
+//
+// ── ON THE WIRE, A DETERMINISTIC MODE IS A TEXT FILTER, NOT `match` ──────────────────────────────
+//
+// The register retired `match` on the same date as `query` and `strategies`, and after that date it
+// refuses the parameter rather than ignoring it. That would take the containing count with it: a
+// refused request is an error, and an error on that band is "not available" on the report. So
+// `match` stays this file's own word for the mode, and the request builder sends the text filter the
+// register maps it to: `filters.mark_text.<op>` with the term as a one-value list, and no `q` and no
+// `similarity`, because a text filter on its own is the plain listing the old `match` was.
+//
+// Compared old form against new for every mode, by record and paged to exhaustion, on neutral terms
+// under one class filter and again with a territory filter: the same records in the same order, and
+// the new form draws no deprecation notice. The register already ran the old form as this filter, so
+// the order it lists in is unchanged; nothing here adds a `sort`. The register's three-character floor
+// on `contains` and `ends_with` refused a shorter term under the old form as well, so a short term
+// fails the same way it always has. `similar` has no filter: the register's word for it is "remove it",
+// because a term on its own is always ranked now, so it is sent as the ranked shape.
+const TEXT_FILTER_FOR = Object.freeze({ exact: "is", starts_with: "starts_with", ends_with: "ends_with", contains: "contains" });
 
 // ── THE RANKED STRATEGIES, AS SIMILARITY CHANNELS ────────────────────────────────────────────────
 //
@@ -273,30 +306,58 @@ 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 = {};
-  // ── `q` CARRIES ONE TERM, AND AN ARRAY HERE WOULD BE A DIFFERENT SEARCH ────────────────────────
+  // ── `q` CARRIES ONE TERM, AND AN ARRAY HERE IS 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.
+  // A list in `q` is a ranked search over every term, and it does not answer the same question as one
+  // request per term. Its results are ranked across the terms, so a page is not complete for any one of
+  // them; its total counts the whole list, so the enumerate ceiling cannot read a per-term crowd off it;
+  // and the register's own reference says a list skips two single-term ranking boosts and the
+  // word-by-word fuzzy retry. Sending several terms in one request is a change to what the engine asks
+  // the register, decided on its own and wired through the planner, never reached by an array that
+  // happens to arrive here.
   //
   // 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;
+  //
+  // THE ONE LIST THAT IS SENT: exact spellings on the exact channels, which `toSignaParams` builds only
+  // where `exactListable` holds. Anything else arriving as a list is still refused.
+  if (Array.isArray(p.query)) {
+    const channels = similarityFor(p.strategies);
+    const exactChannels = channels.length === 2 && channels[0] === "identical" && channels[1] === "lookalike";
+    const terms = p.query.filter((t) => String(t ?? "").trim());
+    if (p.match || !exactChannels || terms.length < 2 || terms.length > CAPABILITIES.exactOrWidth)
+      throw new Error("[signa] `query` reached the request builder as a list outside the one shape the register "
+        + "answers term for term: exact spellings on the identical and lookalike channels, 2 to "
+        + `${CAPABILITIES.exactOrWidth} of them. Send one term per request.`);
+    body.q = terms;
+    body.similarity = channels;
+    const listFilters = buildFilters(p);
+    if (Object.keys(listFilters).length) body.filters = listFilters;
+    return finishSearchRequest(body, p);
+  }
+  const term = String(p.query ?? "").trim() ? p.query : null;
   const match = typeof p.match === "string" ? p.match.trim() : "";
-  if (match && DETERMINISTIC_MATCH.has(match)) {
-    body.match = match;   // sending similarity alongside is a 4xx, not a preference
-  } else {
+  const filters = buildFilters(p);
+  const textOp = TEXT_FILTER_FOR[match];
+  if (textOp && term != null) {
+    // A text filter alone: no `q`, and no `similarity` — the register refuses channels without a `q`.
+    filters.mark_text = { [textOp]: [term] };
+  } else if (term != null) {
+    body.q = term;
     body.similarity = similarityFor(p.strategies);
   }
-  const filters = buildFilters(p);
+  // No term at all is the owner-only shape: the owner filter is the whole question, and `similarity`
+  // "requires q" in the register's reference, so none is sent. With no owner either, the request would be
+  // an unfiltered listing of the register — a stack of names that could not go as a list arrives here
+  // with no term — so it is refused rather than sent.
+  if (term == null && !(typeof p.owner === "string" && p.owner.trim()))
+    throw new Error("[signa] a search reached the request builder with no term and no owner. A stack of names goes "
+      + "to this register whole only as exact spellings on the exact channels; send one term per request.");
   if (Object.keys(filters).length) body.filters = filters;
+  return finishSearchRequest(body, p);
+}
+
+/** What every search request carries whatever its term: territory layer, paging and the total. */
+function finishSearchRequest(body, p) {
   if (Array.isArray(p.jurisdictions) && p.jurisdictions.length && p.territory_match) {
     // Governs `filters.jurisdictions` ONLY — it has no effect on `filters.offices`, which is always
     // literal. Sent verbatim rather than defaulted here: the vendor's own default is `protection`, and
@@ -362,6 +423,11 @@ export function normalizeClasses(rec) {
   return out.length ? Array.from(new Set(out)).sort((a, b) => a - b) : null;
 }
 
+const httpsUrlOrNull = (v) => {
+  if (typeof v !== "string") return null;
+  try { return new URL(v).protocol === "https:" ? v : null; } catch { return null; }
+};
+
 // Map a raw Signa record → the NEUTRAL normalized shape the driver + skill consume. officeHint = the
 // office of the synthetic ref the caller cited (keeps cited==logged); record's jurisdiction_code is the
 // fallback (Signa records carry an ISO jurisdiction_code directly, so no office map is needed).
@@ -397,7 +463,14 @@ export function normalizeRecord(rec, officeHint = null) {
     ownerCountry: owner0?.country_code ?? owner0?.country ?? null,
     representative: atty0?.name ?? null,
     imageAvailable: rec.has_media ?? null,
-    resolved_link: null, // Signa exposes no per-record public URL; renderer shows "verify at office"
+    // Signa publishes no page per record of its own, so no record URL is minted here and the model's
+    // record links stay refused for this register (hasPublicRecordUrl: false).
+    resolved_link: null,
+    // THE OFFICE'S PAGE, AS THE REGISTER GIVES IT: `office_url`, a link to the record on the office's own
+    // site, absent on some records. Carried as data for publish (office-record-links.mjs), which addresses
+    // the office's page from the record's numbers first and falls back to this only where that table
+    // gives no address. Only an https address is kept.
+    officeUrl: httpsUrlOrNull(rec.office_url),
     // ── WHICH LAYER THIS RIGHT SITS ON, carried as data ( →) ──────────────────────────
     // The normalizer read under half the fields a search row carries. Among the ones it dropped were the
     // four that say what KIND of right a record is — and those are not extras, they are the whole
@@ -488,6 +561,10 @@ function normalizeSearchRow(rec) {
     application_date: filed,
     registration_date: toIso(rec.registration_date),
     relevance_score: Number.isInteger(rec.relevance_score) ? rec.relevance_score : null,
+    // Why the register returned this row: `{ tier, via, terms }` — the tier it rates the resemblance,
+    // the channels that found it, and the terms or filter values it matched. It replaced the per-row
+    // `match_explanation` and `matched_terms`, which the register removed on 2026-10-05.
+    match: rec.match && typeof rec.match === "object" ? rec.match : null,
     raw: rec,
   };
 }
@@ -546,8 +623,10 @@ export function normalizeSearchResponse(body, echoQuery) {
   const { total, approximate, floor } = readTotal(body);
   return {
     query: meta.query ?? echoQuery,
-    strategies_used: meta.strategies_used ?? [],
-    match: meta.match ?? null,
+    // The channels the register says it ran. It removed `strategies_used` and `match` from this object
+    // on 2026-10-05 and names this field as their replacement; reading the old two returned `[]` and
+    // `null` on every answer after that date while looking like a report of what ran.
+    similarity_applied: Array.isArray(meta.similarity_applied) ? meta.similarity_applied : null,
     search_id: meta.search_id ?? null,
     // ── THE REGISTER'S OWN WARNINGS, CARRIED WHOLE ──────────────────────────────────────────────
     //
@@ -571,8 +650,17 @@ export function normalizeSearchResponse(body, echoQuery) {
     // 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.
+    // is what makes that visible; `total_counts` below says it where the total is read.
     warnings: Array.isArray(meta.warnings) ? meta.warnings : [],
+    // ── WHAT THE TOTAL COUNTS, WHEN THE REGISTER SAYS ────────────────────────────────────────────
+    //
+    // `records` when the register flagged `expanded_fallback` on this answer: the total then counts one
+    // row per record, so a mark filed in several countries is counted once per country it covers. The
+    // count stays the register's own number and is never presented as a count of marks (ruled
+    // 2026-10-02: record only, no extra call). Absent when the register said nothing: its grouped view
+    // answered, or the response was not an answer. Keyed on the code the register writes into
+    // `search_meta.warnings`, in the shape measured live and kept by the warnings test beside this file.
+    ...(answered && (Array.isArray(meta.warnings) ? meta.warnings : []).some(isExpandedFallback) ? { total_counts: "records" } : {}),
     // 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.
@@ -722,9 +810,74 @@ export async function doSearch(apiKey, base, params, tctx, { mock = false } = {}
   if (!isSearchResponseBody(r.body)) {
     return { type: "text", text: nonAnswerBodyError("signa_search", r, "a search response (no data[] — the key every /v1/trademarks answer carries)", ` ${searchTargetLabel(params).slice(0, 120)}`) };
   }
+  // A 200 that did not run every channel it was asked for answered a narrower question; see skippedChannels.
+  const skipped = skippedChannels(r.body, body.similarity);
+  if (skipped.length) {
+    return { type: "text", text: `ERROR: signa_search — the register skipped the ${skipped.join(", ")} channel`
+      + `${skipped.length > 1 ? "s" : ""} this search asked for, so its answer covers a narrower question than the one `
+      + `asked and is not taken as this search's answer. The register decides this from the term, so asking the same `
+      + `search again will be skipped the same way. ${searchTargetLabel(params).slice(0, 120)}` };
+  }
+  // A text filter compares letters as written, so a term mixing alphabets matches nothing; see mixedScriptFilters.
+  const unreadable = mixedScriptFilters(r.body, body.filters?.mark_text);
+  if (unreadable.length) {
+    return { type: "text", text: `ERROR: signa_search — the register reports that the term mixes alphabets, and its `
+      + `${unreadable.join(", ")} filter compares letters as written, so it can match nothing. Its zero is not a count `
+      + `of filings and is not taken as this search's answer. ${searchTargetLabel(params).slice(0, 120)}` };
+  }
   return { type: "text", text: JSON.stringify(normalizeSearchResponse(r.body, params.query), null, 2) };
 }
 
+// ── A TEXT FILTER CANNOT READ A TERM THAT MIXES ALPHABETS ─────────────────────────────────────────
+//
+// The text filters compare letters as written. A term mixing Latin with Greek or Cyrillic letters
+// therefore matches no filing, and the register answers 200 with zero rows and an `info`-level
+// `mixed_script` warning naming the filter — in its own words, "a ranked q with the lookalike similarity
+// channel folds look-alike letters". Measured live on an invented term with one Cyrillic letter: the
+// ranked search found 219 filings, the containing filter 0. That zero would be the containing count on the
+// report, an exact zero on a figure the client reads. So the answer is refused, naming the filter, and
+// the count reads as unknown rather than none.
+//
+// Matched on the warning's `affected_filter` (`mark_text_<op>`) against the filter this request sent; a
+// warning that names no filter counts against any text filter the request carried.
+export function mixedScriptFilters(body, markText) {
+  const sent = Object.keys(markText && typeof markText === "object" ? markText : {});
+  if (!sent.length) return [];
+  const warnings = Array.isArray(body?.search_meta?.warnings) ? body.search_meta.warnings : [];
+  const out = [];
+  for (const w of warnings) {
+    if (String(w?.code ?? "") !== "mixed_script") continue;
+    const named = String(w?.affected_filter ?? "").replace(/^mark_text_/, "");
+    for (const op of named ? sent.filter((o) => o === named) : sent) if (!out.includes(op)) out.push(op);
+  }
+  return out;
+}
+
+// ── A CHANNEL THE REGISTER SKIPPED IS A QUESTION IT DID NOT ANSWER ─────────────────────────────────
+//
+// The register runs a term through the similarity channels a request names, and when one of them cannot
+// run on that term it says so in `search_meta.warnings` — `<channel>_skipped`, with the channel in
+// `channel` — and answers 200 with what the other channels found. Its migration guide states it in those
+// words. A sound-alike search answered with `phonetic_skipped` has been answered by `identical` alone: the
+// same rows an exact search gives, under the sound-alike question's name, and the band would read as
+// searched. That is the failure this connector refuses everywhere else — a narrower query wearing a
+// complete answer — so it is refused here too, and the band is left incomplete with the channel named.
+//
+// Only a channel the request ASKED for counts. A warning about a channel nobody asked for changes nothing
+// about the answer to the question that was asked. A warning carrying no `channel` is read from its code.
+export function skippedChannels(body, requested) {
+  const asked = new Set(Array.isArray(requested) ? requested : []);
+  const warnings = Array.isArray(body?.search_meta?.warnings) ? body.search_meta.warnings : [];
+  const out = [];
+  for (const w of warnings) {
+    const code = String(w?.code ?? "");
+    if (!code.endsWith("_skipped")) continue;
+    const channel = String(w?.channel ?? code.slice(0, -"_skipped".length)).trim().toLowerCase();
+    if (asked.has(channel) && !out.includes(channel)) out.push(channel);
+  }
+  return out;
+}
+
 // ── Record fetch ─────────────────────────────────────────────────────────────────────────────────
 // Accepts a synthetic `/mark/<office>/<id>` ref OR a raw Signa id. Returns the NORMALIZED record and
 // persists it (keyed by the synthetic ref) for the driver's A1 citation-fidelity gate.
@@ -766,25 +919,57 @@ export async function doRecordFetch(apiKey, base, params, tctx, { mock = false }
 // speaks the same dialect as the code under test cannot find a dialect mismatch, which is why the one
 // below builds its params the way the kernel does and not the way doSearch prefers.
 //
-// `names` (an OR-stack) is deliberately NOT accepted: `maxOrWidth: 1` — verified against the live
-// specification, which carries no OR array on this endpoint — so a stack must reach here already split
-// by the planner. Silently searching only its first term would be a narrowed query wearing a complete
-// answer, which is this whole track's failure mode.
+// `names` (an OR-stack) goes to the register whole only as exact spellings, as one ranked list (see
+// `exactListable`); every other stack must reach here already split. Silently searching only its first
+// term would be a narrowed query wearing a complete answer, which is this whole track's failure mode.
+// ── WHEN A STACK OF SPELLINGS GOES AS ONE REQUEST ─────────────────────────────────────────────────
+//
+// An exact question over several spellings, each long enough for the ranked search, with no owner
+// clause: the shape the register answers as one ranked list exactly as it answers each spelling alone
+// (see `exactOrWidth` in capabilities.js for the measurement). The list's terms ride a POST body the
+// register caps at 8 KB, so a stack of long spellings is cut to fit with room for the filters.
+const LIST_BODY_BUDGET = 6000;
+const termBytes = (t) => Buffer.byteLength(JSON.stringify(String(t)), "utf8") + 1;
+function exactStackShape(p) {
+  if (String(p?.match_mode ?? "").trim() !== "exact") return null;
+  if (typeof p?.owner === "string" && p.owner.trim()) return null;
+  if (Array.isArray(p?.owners) && p.owners.length) return null;
+  const stack = Array.isArray(p?.names) ? p.names.filter(Boolean) : [];
+  if (stack.length < 2) return null;
+  if (stack.some((t) => foldedLength(t) < CAPABILITIES.rankedMinLength)) return null;
+  return stack;
+}
+/** How many spellings one request carries for this kernel query, or null when it is one per request. */
+export function namesChunkFor(p) {
+  const stack = exactStackShape(p);
+  if (!stack) return null;
+  const widest = Math.max(...stack.map(termBytes));
+  return Math.max(1, Math.min(CAPABILITIES.exactOrWidth, Math.floor(LIST_BODY_BUDGET / widest)));
+}
+/** May this stack go to the register whole, as one ranked list? */
+export function exactListable(p) {
+  const stack = exactStackShape(p);
+  return Boolean(stack) && stack.length <= namesChunkFor(p)
+    && stack.reduce((n, t) => n + termBytes(t), 0) <= LIST_BODY_BUDGET;
+}
+
 export function toSignaParams(p = {}) {
   const out = { ...p };
   if (p.name != null && p.query == null) out.query = p.name;
   // ── A ONE-TERM `names` WINDOW IS A TERM, NOT A STACK ────────────────────────────────────────────
-  // `maxOrWidth: 1` means the kernel CHUNKS a wide names band into windows of one and runs the full
-  // enumerate contract on each — that is what `namesChunkDefault: 1` is for. Every window therefore
+  // Outside an exact spelling stack the kernel CHUNKS a wide names band into windows of one and runs the
+  // full enumerate contract on each — that is what `namesChunkDefault: 1` is for. Every window therefore
   // arrives here as `names: ["one-term"]`, and with no mapping it came back "ERROR: query is
   // required": a names band could not run on this provider AT ALL, and the failure was reported as
   // chunk 1 failing rather than as the adapter refusing a shape the kernel had already split.
   //
-  // Refusing a MULTI-term stack is still right and is the assertion below — picking names[0] there
-  // would be a narrowed query wearing a complete answer. One term is not a choice between terms.
-  if (out.query == null && Array.isArray(p.names) && p.names.filter(Boolean).length === 1) {
-    out.query = p.names.filter(Boolean)[0];
-  }
+  // A MULTI-term stack is never narrowed to names[0] — that would be a narrowed query wearing a complete
+  // answer. It is sent whole, as one ranked list, only where `exactListable` says the register answers
+  // the list exactly as it answers each spelling alone; otherwise it reaches the request builder with no
+  // term and is refused there.
+  const stack = Array.isArray(p.names) ? p.names.filter(Boolean) : [];
+  if (out.query == null && stack.length === 1) out.query = stack[0];
+  else if (out.query == null && stack.length > 1 && exactListable(p)) out.query = stack;
   // ── STAGE 2 — A TERRITORY IS A STACK OF RIGHTS, AND THIS PROVIDER CAN SEARCH THE STACK ─────
   //
   // The plan's `regions` are the territories the matter ordered, already translated into this vendor's
@@ -846,7 +1031,7 @@ export function toSignaParams(p = {}) {
   // identical question relies on. So exact stays ranked from the floor up, and only a term below it
   // goes deterministic, where it is answered rather than refused.
   const mode = String(p.match_mode ?? "").trim();
-  if (mode === "exact" && foldedLength(out.query) < CAPABILITIES.rankedMinLength) out.match = "exact";
+  if (mode === "exact" && !Array.isArray(out.query) && foldedLength(out.query) < CAPABILITIES.rankedMinLength) out.match = "exact";
   else if (mode === "exact" || mode === "phonetic" || mode === "prefix") out.strategies = [mode];
   else if (mode === "starts_with" || mode === "ends_with" || mode === "contains") out.match = mode;
   // ── `default` IS THE COUNT LANE'S WORD FOR THE SAME UNANCHORED QUERY THE PLAN LANE CALLS `{}` ────
@@ -987,6 +1172,9 @@ const { enumerate: __enumerate } = makeEnumerate({
   missingElementError: MISSING_ELEMENT_ERROR,
   capabilities: { ...CAPABILITIES.kernel },
   ceilingFor: ownerWindowCeiling,
+  // Exact spelling stacks go as one ranked list of up to `exactOrWidth`; every other names band stays at
+  // one term per request (`namesChunkDefault`).
+  namesChunkFor,
   // The kernel's default cheap-probe params are CORSEARCH'S — `{limit:1, fields:["uri"]}` — and `uri`
   // is not a field this vendor has. Its `fields` projection rejects unknown names, so inheriting the
   // default would 400 every count-first rescue while the ordinary search beside it worked. `limit: 1`
@@ -1098,3 +1286,12 @@ export async function doCountHits(apiKey, base, params, tctx, { mock = false } =
     }, null, 2),
   };
 }
+
+/**
+ * The register's own flag that a total counts records rather than marks: the `expanded_fallback` warning,
+ * which it writes into `search_meta.warnings` when its grouped view cannot serve a filter. Matched on the
+ * code, or on a message that opens with it, so a warning reshaped either way is still read. PURE.
+ */
+export function isExpandedFallback(w) {
+  return w?.code === "expanded_fallback" || /^expanded_fallback\b/.test(String(w?.message ?? ""));
+}

package/scripts/band-shape-probe.mjs

@@ -64,7 +64,7 @@ if (!/^\d+$/.test(String(opts.seed)) || Number(opts.seed) <= 0)
 
 // ── the inputs deriveBandShape uses, read the same way it reads them ─────────────────────────────────
 //
-// Deliberately mirrors driver/pipeline.mjs:441-490 rather than inventing a gathering step. If the two
+// Deliberately mirrors driver/pipeline.mjs:441-490 mergeRegisterBands rather than inventing a gathering step. If the two
 // diverge, this probe measures a shape the run never had.
 
 const runDir = opts.run;
@@ -243,7 +243,7 @@ if (membershipBroken.length) {
 
 console.log(`\n${"═".repeat(78)}`);
 console.log(`This measures the BAND SHAPE only, and it is free. It is NOT the noise floor #217 needs.`);
-console.log(`That floor lives in the model-authored placement tier (placement-model.mjs:46) and needs`);
+console.log(`That floor lives in the model-authored placement tier (placement-model.mjs:46 PLACEMENT_TIERS) and needs`);
 console.log(`repeat paid arms on a named run dir with approved spend. Nothing here substitutes for it.`);
 console.log(`Nothing was written. Exit code is 0 either way — this records, it does not judge.\n`);
 process.exit(0);

package/scripts/deprecate-below.mjs

@@ -114,9 +114,26 @@ export function selectRange(all, { from, through, except }, distTags = {}) {
     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);
+  return refuseTagged(picked, distTags, "the range");
+}
+
+/**
+ * The published versions below a stable. Throws, before anything is written, when one of them is a
+ * version a dist-tag points at: the same refusal the range mode makes, because the hazard is the same.
+ */
+export function selectBelow(all, below, distTags = {}) {
+  return refuseTagged(all.filter((v) => compareVersions(v, below) < 0), distTags, `the sweep below ${below}`);
+}
+
+/**
+ * ONE CHECK FOR EVERY MODE. `latest` and `beta` are what `npm install` resolves, so deprecating the version
+ * a tag points at warns every installer about the version they were just given. Each mode passes its
+ * selection through here, so a mode added later cannot select versions without it.
+ */
+export function refuseTagged(picked, distTags = {}, what = "the selection") {
   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; `
+    throw new Error(`${what} takes ${tagged.map(([t, v]) => `${v} (${t})`).join(", ")}, which a dist-tag points at; `
       + "move the tag or hold the version out");
   }
   return picked;
@@ -124,6 +141,9 @@ export function selectRange(all, { from, through, except }, distTags = {}) {
 
 const npm = (...args) => execFileSync("npm", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 
+/** The registry's dist-tags, read in one place so every mode is refused on the same facts. */
+const readDistTags = () => JSON.parse(npm("view", PKG, "dist-tags", "--json"));
+
 /** Every published version, and the deprecation message each carries. Read once, as a list. */
 function published() {
   const versions = JSON.parse(npm("view", PKG, "versions", "--json"));
@@ -202,7 +222,12 @@ async function main() {
     return 2;
   }
 
-  const candidates = all.filter((v) => compareVersions(v, below) < 0);
+  let candidates;
+  try { candidates = selectBelow(all, below, readDistTags()); }
+  catch (e) {
+    console.error(`deprecate-below: refusing — ${e.message}. Nothing was written.`);
+    return 2;
+  }
   console.log(`deprecate-below: ${all.length} published version(s); ${candidates.length} below ${below}.`);
 
   let done = 0, skipped = 0, failed = 0;
@@ -262,8 +287,7 @@ async function deprecateRange(spec, DRY) {
     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);
+    picked = selectRange(all, parsed, readDistTags());
     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.`);

package/scripts/e2e-first-time.mjs

@@ -36,6 +36,18 @@ import { driverDir, labelOfDriverFile } from "../shared/driver-dir.mjs";
 // What no file of the run record holds, stated on every answer. The register's own HTTP retries are
 // written to the provider call log, which is per machine, not per run; and a tool result whose text reports a
 // failure while its call settles ok carries no marker the call log keeps.
+/** One line for what interrupted a session, from its record: counts only, never the program's words. */
+function interruptionOf(session) {
+  const parts = [];
+  const cuts = session?.classifierCuts?.length ?? 0, refusals = session?.refusals?.length ?? 0;
+  const errors = (session?.results ?? []).filter((r) => r?.isError).length, starts = Number(session?.starts) || 0;
+  if (cuts) parts.push(`${cuts} classifier cut${cuts === 1 ? "" : "s"}`);
+  if (refusals) parts.push(`${refusals} refusal${refusals === 1 ? "" : "s"}`);
+  if (errors) parts.push(`${errors} error result${errors === 1 ? "" : "s"}`);
+  if (starts > 1) parts.push(`${starts - 1} restart${starts === 2 ? "" : "s"}`);
+  return parts.length ? `the session went on to deliver after ${parts.join(", ")}` : "the session's record marks it interrupted";
+}
+
 export const NOT_RECORDED = [
   "register calls the provider retried inside one tool call (the call log is per machine, not per run)",
   "a tool result that reports a failure in its text while the call settles ok",
@@ -347,7 +359,10 @@ export function firstTimeRows({ attempts = [], runLog = [], status = {}, markers
       if (prev === undefined || n <= prev) cycles.set(stage, [...(cycles.get(stage) ?? []), { start: n, after: prev ?? null, row }]);
       prevAttempt.set(stage, n);
     }
-    if (row.ok === false) add("failed attempt", stage, n, row.fail ?? "no cause recorded", row);
+    // A session that was cut, refused or restarted and still delivered is not ok and did not fail: it is
+    // named for what happened to it (engine/session-record.mjs), never as a failure with no cause.
+    if (row.ok === false && !row.fail && row.session?.interrupted) add("interrupted session", stage, n, interruptionOf(row.session), row);
+    else if (row.ok === false) add("failed attempt", stage, n, row.fail ?? "no cause recorded", row);
     else if (Number.isFinite(n) && n > 1) add("retry", stage, n, `attempt ${n} succeeded`, row);
     if (row.rescued) add("rescue", stage, n, `rescued: ${row.rescued}`, row);
     if (row.selfReportContradicted === true && row.ok !== false) add("self-report contradicted", stage, n, "the model reported done and its file said otherwise", row);

package/scripts/freeze-example-run.mjs

@@ -100,8 +100,8 @@ for (const path of Object.keys(PUBLISH_INPUTS)) {
 const KNOCKOUT_FILES = [
   { path: "knockout-findings.json", required: true, why: "report-registry.mjs:66 the batch findings ARE the report source" },
   { path: "knockout-plan.json", why: "report-registry.mjs:77 plan" },
-  { path: "knockout-assessment.md", why: "the merged prose the lane writes (gateway.mjs:184)" },
-  { path: "knockout-frame.md", why: "the batch scope note (gateway.mjs:65)" },
+  { path: "knockout-assessment.md", why: "the merged prose the lane writes (gateway.mjs:184 TOOL_WRITTEN_PATTERNS)" },
+  { path: "knockout-frame.md", why: "the batch scope note (gateway.mjs:65 TOOL_WRITTEN_ARTIFACTS)" },
   { path: "email-body.md", why: "the delivery prose the lane writes beside the assessment" },
   { path: "status.json", why: "publish/index.mjs:913 machineLedgerNote + markName" },
   { path: "audit.md", why: "publish/index.mjs:1022 auditMd, the audit workbook source" },

package/shared/scope.mjs

@@ -792,6 +792,12 @@ function tenantStamp(scope, asked) {
   throw new Error(`name the organisation whose Generic this is (tenant) — your access covers ${orgs.length}`);
 }
 
+// The install's organisation when the grants file holds exactly one; null with several, none, or no file.
+function soleOrganisation() {
+  const orgs = Object.keys(loadGrants()?.tenants ?? {});
+  return orgs.length === 1 ? orgs[0] : null;
+}
+
 // True iff `email`'s domain (the part after the final '@') is one of firmDomains. PURE (no jose), so the HTTP
 // handler can derive firm-staff-ness from the already-verified CF identity without pulling the auth lib. The
 // `internal` (read-all) grant rests on THIS positive check — NOT on which CF app admitted the caller — so a
@@ -1016,8 +1022,18 @@ export function authorize(scope, toolName, args = {}) {
     // paid run whose delivery packet routes nowhere. A refusal naming the missing field is the cheaper
     // failure by far, and it is not the "accepted then quietly narrower" shape: the preview describes a
     // job stamped from the verified identity, and start_run says plainly which field to add.
-    if (toolName === "plan_run") return stampForwarder(scope, args);
-    return args;
+    //
+    // WHICH ORGANISATION'S GENERIC. An ops token names no person, so there is nobody's reach to read the
+    // organisation from — and passed through bare, every Generic run a connector started was filed under
+    // no organisation, where the Generic filter on Clearances can never find it. On an install that holds
+    // exactly one organisation there is nothing to guess, so the job takes it: the same answer the
+    // person-scoped branch gives a person who sees that one organisation. A named tenant passes as it
+    // stands, and with several organisations (or none) the job is left as it was.
+    const placed = (toolName === "start_run" || toolName === "plan_run") && (args?.profileKey ?? "generic") === "generic"
+      && !(typeof args?.tenant === "string" && args.tenant.trim()) ? soleOrganisation() : null;
+    const routed = placed ? { ...args, tenant: placed } : args;
+    if (toolName === "plan_run") return stampForwarder(scope, routed);
+    return routed;
   }
   // kind === "account": a signed-in CLIENT, across their OWN account(s). Reads the client layer on any of
   // their runs, and drives the run lifecycle for them. Run OWNERSHIP is not checked here — it is enforced