clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/driver/run-requirements.mjs

@@ -44,6 +44,9 @@
 //   BLOCKING — without these nothing runs at all, in any product. The register and its credential (the
 //     driver throws by name at the first stage), the engine and the binary it drives, and the pool the
 //     report is written into. This is the set whose absence produced the outcome at the top of this file.
+//     And what the billing word needs, because the run door refuses without it before any turn: under
+//     `cloud` the switch of the cloud it pays through (or the gateway address), under `api-key` the
+//     engine's key; and the billing word itself, whenever the run door refuses the way it is set.
 //
 //   NARROWING — `PERPLEXITY_API_KEY`. Its absence does NOT crash a run and does not deliver a false
 //     notice: the three clearance searches carry the common-law grid and cannot switch it off, so they
@@ -71,13 +74,16 @@
 //     Refusing here is refusing over OUR bug, and there is nothing for a reader to go and set.
 //
 //   at:"order"   the value an OPERATOR supplies — the register, its credential, the engine and the
-//     binary it drives. Absent, the install is not finished. The doors come up and every run is refused
-//     AT ORDER TIME, before a stage dispatches and before anything is spent, naming what is missing.
+//     binary it drives, and what the billing word needs (above). Absent, the install is not finished.
+//     The doors come up and every run is refused AT ORDER TIME, before a stage dispatches and before
+//     anything is spent, naming what is missing.
 //
 // The axis is on the ROW, not in the caller, for the reason the whole module exists: a start that
 // decides for itself which names are its own and a runner that decides separately are two opinions
 // about one list, and they drift in the direction where the second asks for less.
 
+import { BILLING_MODES, CLOUD_SWITCH, CLOUD_SETTINGS, CLOUD_CREDENTIAL_CHECK, billingMode, cloudsSwitchedOn, resolveAuthMode } from "./engine/auth.mjs";   // — the billing row asks the one resolver which ways an engine can be paid for, and the cloud rows read its own lists
+
 /** The pool a report is written into. Named once; the supervisor already writes it. */
 export const POOL_ENV = "CLEAROTRON_REPORTS_DIR";
 /** The register selection, and the engine selection. */
@@ -85,6 +91,9 @@ export const REGISTER_ENV = "CLEAROTRON_DATABASE";
 export const ENGINE_ENV = "CLEAROTRON_AI";
 /** Narrowing, never blocking — see the header. */
 export const RESEARCH_ENV = "PERPLEXITY_API_KEY";
+/** The settings that decide WHICH cloud a Claude turn goes to: each cloud's switch, and the gateway address.
+ *  Any one of them answers the cloud billing word; start compares all of them against the services' file. */
+export const CLOUD_ROUTES = Object.freeze([...Object.values(CLOUD_SWITCH), "ANTHROPIC_BASE_URL"]);
 
 /** WHEN a blocking value is asked for. `START` is what `clearotron start` writes itself; `ORDER` is what
  *  an operator configures, and its absence refuses a RUN rather than an install. See the header. */
@@ -93,6 +102,35 @@ export const ORDER = "order";
 
 const val = (env, name) => String(env?.[name] ?? "").trim();
 
+// THE WAYS AN ENGINE CAN BE PAID FOR, AS THE BILLING ROW SAYS THEM. The row named all three for every engine,
+// and Codex refuses a cloud account (engine/auth.mjs, resolveAuthMode), so a Codex install was offered a way
+// to pay its run door refuses.
+const PAY_WORDS = Object.freeze({ subscription: "subscription", "api-key": "API key", cloud: "cloud account" });
+
+/**
+ * The billing words `engineId` can be paid by, in BILLING_MODES order: each one asked of the resolver, the
+ * one authority on it, with what that word needs set (the engine's key for `api-key`, a cloud's switch for
+ * `cloud`), so a word the resolver accepts only when its settings are present is not read as refused. An
+ * import of a leaf with no imports of its own, so this module stays pure.
+ */
+export function payWays(engineId, engine = {}) {
+  return BILLING_MODES.filter((mode) => {
+    const env = { [engine.authEnv ?? "CLEAROTRON_AI_BILLING"]: mode,
+      ...(mode === "api-key" && engine.apiKeyEnv ? { [engine.apiKeyEnv]: "set" } : {}),
+      ...(mode === "cloud" ? { [CLOUD_SWITCH.vertex]: "1" } : {}) };
+    try { resolveAuthMode({ engineName: engineId, env }); return true; } catch { return false; }
+  });
+}
+
+/**
+ * A billing refusal from the run door, in words that carry no value. Every refusal names settings and the
+ * billing word, except the one for a word that is not a billing mode, which quotes the word as it is set;
+ * that quote is replaced by the setting's name. PURE. Any other message comes back unchanged.
+ */
+export function billingRefusalWords(message) {
+  return String(message ?? "").replace(/^([A-Z][A-Z0-9_]*)=[\s\S]*? is not a billing mode/, "$1 is set to a word that is not a billing mode");
+}
+
 /**
  * Every environment name this box's configuration says a clearance needs, with the reason each one is
  * there and whether its absence blocks or narrows.
@@ -101,9 +139,9 @@ const val = (env, name) => String(env?.[name] ?? "").trim();
  * environment in hand: the composer has the supervisor's, and the guard has the one it just wrote into
  * the unit file. A function that read the ambient environment would answer about neither.
  *
- * PURE.
+ * PURE, apart from the engine resolver a caller passes in `tables.resolveEngine` (see the engine row).
  */
-export function runRequirements(env = {}, { registers = [], engines = {}, defaultEngine = null } = {}) {
+export function runRequirements(env = {}, { registers = [], engines = {}, defaultEngine = null, resolveEngine = null } = {}) {
   const out = [];
   const push = (name, blocking, why, at = ORDER) =>
     out.push({ name, blocking, why, at, present: Boolean(val(env, name)) });
@@ -128,11 +166,135 @@ export function runRequirements(env = {}, { registers = [], engines = {}, defaul
 
   // ── THE ENGINE, AND THE BINARY IT DRIVES ─────────────────────────────────────────────────────────
   push(ENGINE_ENV, true, "which reasoning engine runs the stages");
-  const engine = (engines ?? {})[val(env, ENGINE_ENV) || defaultEngine || ""];
-  if (engine?.env)
+  const engineId = val(env, ENGINE_ENV) || defaultEngine || "";
+  const engine = (engines ?? {})[engineId];
+  if (engine?.env) {
     push(engine.env, true, `the path to the ${engine.vendor} CLI this engine drives — a stage cannot dispatch without it`);
-  if (engine?.authEnv)
-    push(engine.authEnv, false, "how the engine bills — subscription or key; the adapter refuses before spending if the sign-in it names is absent");
+    // FOUND IS WHAT COUNTS, NOT SET. A program on this environment's PATH, or the copy installed with
+    // Clearotron, needs no path written anywhere, and asking only whether the variable was set refused an
+    // install whose engine the run door would have started. The resolver arrives through the tables, like
+    // everything else this module knows about the install; a caller that passes no resolver gets the
+    // variable's own answer, which is all it can see. The module's one import is engine/auth.mjs, for the
+    // billing row below: a driver leaf with no imports of its own, pure, and the one authority on which
+    // billing words an engine takes, so importing it keeps this module pure and reaches nothing in `bin/`.
+    const row = out[out.length - 1];
+    if (!row.present && typeof resolveEngine === "function") {
+      try { row.present = Boolean(resolveEngine(engineId, { env })?.resolved); } catch { /* not found is not present */ }
+    }
+  }
+  if (engine?.authEnv) {
+    const ways = payWays(engineId, engine);
+    const said = ways.map((m) => PAY_WORDS[m]);
+    push(engine.authEnv, false, `how the engine is paid for — ${said.length > 1 ? `${said.slice(0, -1).join(", ")} or ${said.at(-1)}` : said[0]}; `
+      + `unset means the subscription, and the adapter refuses before spending if the ${ways.includes("cloud") ? "key or cloud account" : "key"} it names is absent`);
+    const billingRow = out[out.length - 1];
+    const billingRows = out.length;
+    const word = billingMode(env);
+    const refused = "without it the engine refuses every search before spending";
+    // ── THE KEY, WHEN THE WORD IS `api-key` ──────────────────────────────────────────────────────────
+    //
+    // The same defect as the cloud below, one billing word over: the word travelled to the services' file
+    // and the key did not, so the run door refused every search after intake ("api-key but
+    // ANTHROPIC_API_KEY is not set"), while start and doctor reported nothing. Blocking at order time, like
+    // the switch: an operator's value, and the run door's own refusal without it.
+    if (word === "api-key" && engine.apiKeyEnv && ways.includes("api-key"))
+      push(engine.apiKeyEnv, true, `the key ${engine.authEnv}=api-key bills every turn to — ${refused}`);
+    // ── THE LONG-LIVED SIGN-IN, WHEN THE WORD IS THE SUBSCRIPTION ────────────────────────────────────
+    //
+    // Setup captures it on a machine that cannot complete a sign-in, which is the server a background
+    // install runs on, and the program reads it from its environment. Carried when set and never asked
+    // for: a machine signed in through the program itself needs none.
+    const tokenEnv = engine.headless?.tokenEnv;
+    if (word === "subscription" && tokenEnv && val(env, tokenEnv))
+      push(tokenEnv, false, `the long-lived sign-in the ${engine.vendor} CLI uses for the subscription on a machine it cannot sign in on; carried as set, and not asked for`);
+    // ── A CLOUD ACCOUNT, AND THE SETTINGS THAT REACH IT ──────────────────────────────────────────────
+    //
+    // The billing word travelled and the cloud did not. A machine set up to pay through a cloud account and
+    // started as background services wrote CLEAROTRON_AI_BILLING=cloud into the services' file and none of
+    // the cloud's own settings, so the run door refused every search: "none of CLAUDE_CODE_USE_VERTEX, …
+    // is set". Measured 2026-09-15 on a Microsoft Foundry configuration.
+    //
+    // ONLY WHEN THE WORD IS `cloud` AND THE ENGINE TAKES ONE — the resolver's answer through `payWays`, not
+    // a list of engines here. Under subscription or api-key nothing of a cloud is carried: a switch left on
+    // in a shell and written into the services' file sends Claude to that cloud, and the run door refuses
+    // a switch beside either word. Codex refuses a cloud account outright, so its rows do not change.
+    if (word === "cloud" && ways.includes("cloud")) {
+      const on = cloudsSwitchedOn(env);
+      const payWord = `${engine.authEnv}=cloud`;
+      // BLOCKING, AT ORDER TIME. Without the switch the run door refuses (engine/auth.mjs), so this is the
+      // same class as the engine and its program: an operator's value, whose absence refuses a run at
+      // intake and never a start.
+      for (const c of on)
+        push(CLOUD_SWITCH[c], true, `sends Claude to ${CLOUD_CREDENTIAL_CHECK[c].who}, the account ${payWord} pays through — ${refused}`);
+      if (!on.length && val(env, "ANTHROPIC_BASE_URL"))
+        push("ANTHROPIC_BASE_URL", true, `the gateway ${payWord} pays through — ${refused}`);
+      if (!on.length && !val(env, "ANTHROPIC_BASE_URL")) {
+        // NOTHING SAYS WHICH CLOUD, and a row has one name. Any one of four settings satisfies it. The row is
+        // NAMED by one real setting, Google's switch, the representative `payWays` above already uses for "a
+        // cloud account", because every reader of a row treats its name as a variable: start and doctor print
+        // it, the runner logs it, and a composite name read as four more items in doctor's list of what is
+        // missing. The REASON names all four, with whose each is. And the row carries all four as `anyOf`,
+        // which `runRequiredNames` hands out as names to read: doctor fills its view of the services by name,
+        // and reading only Google's switch reported an Azure machine's switch, held by its services, as
+        // missing.
+        //
+        // A SWITCH THAT IS SET AND NOT ON IS SAID, because it reads as on to a person and as off to the
+        // program: `CLAUDE_CODE_USE_FOUNDRY=0` on an Azure machine was answered with Google's switch
+        // and nothing else, and the reader was left to work out why the one they set did not count.
+        // And it is not an alternative to read or carry: `anyOf` is handed to the composer too, and the
+        // set-and-off line would travel through it.
+        const off = Object.values(CLOUD_SWITCH).filter((k) => val(env, k));
+        out.push({ name: CLOUD_SWITCH.vertex, anyOf: CLOUD_ROUTES.filter((k) => !off.includes(k)), blocking: true, at: ORDER, present: false,
+          why: `${payWord} pays through a cloud account and nothing names which one — set `
+            + `${["vertex", "foundry", "bedrock"].map((c) => `${CLOUD_SWITCH[c]}=1 for ${CLOUD_CREDENTIAL_CHECK[c].who}`).join(", ")}, `
+            + `or ANTHROPIC_BASE_URL for a gateway`
+            + (off.length ? ` (${off.join(" and ")} ${off.length > 1 ? "are" : "is"} set, but not on: a switch is on at 1, true, yes or on)` : "")
+            + `; ${refused}` });
+      }
+      // EVERY OTHER CLOUD SETTING THAT IS SET, CARRIED AND NEVER ASKED FOR. Which of them a cloud needs
+      // depends on how the machine signs in to it — an Azure key or the Azure sign-in, an AWS profile, an
+      // instance role or keys, gcloud or a key file — and the model pins are optional everywhere. The run
+      // door asks for none of them; the cloud refuses a missing one at the first turn. So a row is made
+      // only for a name that is set: present by construction, it can never be reported missing or refuse
+      // anything, and exists so the composer carries it. Names on CLOUD_SETTINGS only — never the rest of
+      // the environment, which would put every secret in a shell into the services' file.
+      //
+      // NEVER A SWITCH. One that is on is a row above. One that is set and not on switches nothing, and
+      // carried into the services' file it held that line there, where the add-only merge kept a later
+      // `=1` out of it for good.
+      const who = on.length === 1 ? CLOUD_CREDENTIAL_CHECK[on[0]].who : !on.length && val(env, "ANTHROPIC_BASE_URL") ? "the gateway" : "the cloud account";
+      const named = new Set(out.flatMap((r) => r.anyOf ?? [r.name]));
+      for (const k of CLOUD_SETTINGS)
+        if (!named.has(k) && !Object.values(CLOUD_SWITCH).includes(k) && val(env, k))
+          push(k, false, `one of the settings Claude reads to reach and pay ${who}; carried as set, and not asked for, because which ones a cloud needs depends on how this machine signs in to it`);
+    }
+    // ── AND ANY OTHER WAY THE RUN DOOR REFUSES HOW THIS IS PAID FOR ──────────────────────────────────
+    //
+    // The rows above name what is MISSING. The run door also refuses what is set wrongly: two clouds
+    // switched on, a switch left on beside `subscription` or `api-key`, a word that is not a billing mode,
+    // a cloud account on Codex. Each passed start's guard, the order wall and doctor, and the run was then
+    // refused after intake. Measured 2026-09-15: a services' file holding Azure's switch from one start
+    // and Google's from the next read clean everywhere and refused every search.
+    //
+    // ASKED OF THE RUN DOOR ITSELF, `resolveAuthMode`, over the environment being judged, and its refusal
+    // is the reason: one authority, so this check can be neither stricter nor laxer than the door. Its
+    // words carry names and the billing word, never a key. The row that turns blocking is the billing
+    // word's own, so no new name is handed to the composer: a switch beside `subscription` stays out of
+    // the services' file, as the cloud rows above intend. `present` on a row means SATISFIED, which is
+    // what every reader of it asks; for this row, set is not enough. When a row above already names what
+    // is missing, that row is the answer and this adds nothing, because the door's refusal is the same one.
+    //
+    // ONE OF THE DOOR'S REFUSALS QUOTES A VALUE: the word that is not a billing mode. A key pasted into the
+    // billing word by mistake is that value, and this reason is printed by start, by doctor and in the
+    // runner's log. So it is said by name, through billingRefusalWords below.
+    if (!out.slice(billingRows).some((r) => r.blocking && !r.present)) {
+      try { resolveAuthMode({ engineName: engineId, env }); } catch (e) {
+        if (e?.billingRefusal)
+          Object.assign(billingRow, { blocking: true, present: false, at: ORDER,
+            why: `every search is refused before spending, over how this machine is set to pay: ${billingRefusalWords(e.message)}` });
+      }
+    }
+  }
 
   push(RESEARCH_ENV, false, "the three clearance searches carry the common-law grid and refuse at preflight without it; a Knockout search still runs and discloses the half it skipped");
 
@@ -147,7 +309,9 @@ export function runRequirements(env = {}, { registers = [], engines = {}, defaul
  * a box whose operator configured them, which is the same shape of defect one size down.
  */
 export function runRequiredNames(env = {}, tables = {}) {
-  return runRequirements(env, tables).map((r) => r.name);
+  // A row any one of several settings satisfies names them in `anyOf`, and each is a name to carry or read.
+  // Each name once: a name handed out twice is read twice and reported twice.
+  return [...new Set(runRequirements(env, tables).flatMap((r) => r.anyOf ?? [r.name]))];
 }
 
 /**

package/driver/runner.mjs

@@ -21,7 +21,7 @@
 import "../shared/env-local.mjs";   // side effect: apply <repo>/.env when THIS file is the CLI entry (never on library import)
 import "./engine/mcp/http-dispatcher.mjs";   // side effect: raise undici headersTimeout (code-side fetches)
 import { readdirSync, renameSync, existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, statSync } from "node:fs";
-import { join, dirname, basename } from "node:path";
+import { join, dirname, basename } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
 import { driverDir, ensureDriverDir } from "../shared/driver-dir.mjs";   // — one definition of where `_driver/` is
 // The queue's filename vocabulary, in ONE place — the rule, extended by to the prose-sidecar and
 // claim-sidecar names, because a harness check retyped four of them from memory and false-alarmed on the
@@ -774,15 +774,15 @@ async function backstopFailureNotice({ res, job, agentId, base, codename, studio
 // starts, so nothing is spent and nothing is promised.
 
 let __runTables = null;
-async function runTables() {
+export async function runTables() {   // exported for the requirement-check wiring test
   // AT CALL TIME, never a static import. `driver/run-requirements.mjs`'s header states the reason and it
   // is load-bearing: the register SELECTION table lives in `bin/onboard.mjs`, a CLI entry point, and a
   // static import from `driver/` would point the driver at `bin/` — the cycle that makes `clearotron
   // doctor` exit 13 after printing most of a report.
   if (!__runTables) {
     const { PROVIDERS } = await import("../bin/onboard.mjs");
-    const { ENGINE_BINARIES, DEFAULT_ENGINE_ID } = await import("./driver.config.mjs");
-    __runTables = { registers: PROVIDERS, engines: ENGINE_BINARIES, defaultEngine: DEFAULT_ENGINE_ID };
+    const { ENGINE_BINARIES, DEFAULT_ENGINE_ID, resolveEngineProgram } = await import("./driver.config.mjs");
+    __runTables = { registers: PROVIDERS, engines: ENGINE_BINARIES, defaultEngine: DEFAULT_ENGINE_ID, resolveEngine: resolveEngineProgram };
   }
   return __runTables;
 }
@@ -1548,7 +1548,7 @@ export function agentStudioRoots() {
   try {
     for (const name of readdirSync(config.workspaceRoot)) {
       if (config.agentIdFromWorkspaceName(name) == null) continue;
-      const s = join(config.workspaceRoot, name, "studio", "prelim-search");
+      const s = studioDirFor(join(config.workspaceRoot, name));
       if (existsSync(s)) out.push(s);
     }
   } catch { /* workspaceRoot absent in some envs */ }

package/driver/scope-facts.mjs

@@ -26,6 +26,7 @@
 // keys only on the neutral plan/band vocabulary, never a vendor name or vendor-shaped field.
 
 import { classTokensFromScopeText } from "./coverage-ledger.mjs";
+import { capabilitiesFor } from "./register-capabilities.mjs";
 
 const clsStr = (c) => String(c ?? "").trim();
 
@@ -144,10 +145,11 @@ export function deriveScopeFacts({ instructedScope = null, plan = null, planExec
 
   const searched_jurisdictions = Array.isArray(plan?.regions) ? plan.regions.map(String) : [];
   const scope_basis = plan?.scope_basis === "worldwide" ? "worldwide" : null;
+  const register_service = registerServiceOf(plan);
 
   const classes_line = instructedClasses.length ? instructedClasses.join(", ") : null;
   const coverage_line = instructedClasses.length && entries.length
-    ? buildCoverageLine(instructedClasses, per_class, { searched_jurisdictions, scope_basis, instructedScope })
+    ? buildCoverageLine(instructedClasses, per_class, { searched_jurisdictions, scope_basis, instructedScope, register_service })
     : null;
 
   return {
@@ -184,7 +186,7 @@ export function deriveScopeFacts({ instructedScope = null, plan = null, planExec
 // clause is word-for-word the same are stated ONCE, over the classes they are about. Nothing is pooled
 // and no number moves: the grouping is on the rendered text, so two classes only share a line when the
 // line they would each have printed is already the same string.
-function buildCoverageLine(classes, per_class, { searched_jurisdictions = [], scope_basis = null, instructedScope = null } = {}) {
+function buildCoverageLine(classes, per_class, { searched_jurisdictions = [], scope_basis = null, instructedScope = null, register_service = null } = {}) {
   const sorted = [...classes].sort((a, b) => (Number(a) || 0) - (Number(b) || 0));
   const byBody = new Map();
   for (const c of sorted) {
@@ -197,7 +199,7 @@ function buildCoverageLine(classes, per_class, { searched_jurisdictions = [], sc
   // bodies A, B, A renders "Classes 5 and 32: A; Class 9: B", not A twice.
   const groups = [...byBody.entries()].map(([body, classes]) => ({ body, classes }));
   const head = (cs) => (cs.length === 1 ? `Class ${cs[0]}` : `Classes ${joinAnd(cs.map(String))}`);
-  return `${groups.map((g) => `${head(g.classes)}: ${g.body}`).join("; ")}${jurisdictionTail({ searched_jurisdictions, scope_basis, instructedScope })}`;
+  return `${groups.map((g) => `${head(g.classes)}: ${g.body}`).join("; ")}${jurisdictionTail({ searched_jurisdictions, scope_basis, instructedScope, register_service })}`;
 }
 
 // One plain-language clause per class, routed on the COUNTS (state-agnostic), not on the state label.
@@ -263,11 +265,24 @@ const joinAnd = (parts) => (parts.length <= 1 ? parts.join("") : `${parts.slice(
 // EU US CH WO doesn't make sense". A worldwide-scoped plan (scope_basis, or a worldwide token riding
 // an instructed list) collapses the tail to the one word; only a genuinely named list is listed.
 const WORLDWIDE_TOKEN_RE = /^(worldwide|world|ww|global)$/i;
-function jurisdictionTail({ searched_jurisdictions = [], scope_basis = null, instructedScope = null } = {}) {
+
+// WORLDWIDE NAMES THE SERVICE THAT SEARCHED IT (owner, 2026-09-18). "Worldwide" is eleven registers on one
+// installation and 186 on another, and a reader can only tell which by being told the service. The name is
+// the provider's own label from its capabilities contract — the same name the order form shows — read off
+// the provider the frozen plan records. A plan that records none, or one this build does not know, keeps
+// the bare word: a guessed name would be worse than none. Never a list of offices, never a count.
+function registerServiceOf(plan) {
+  if (!plan?.provider) return null;
+  try { return capabilitiesFor(plan.provider).label ?? null; } catch { return null; }
+}
+
+function jurisdictionTail({ searched_jurisdictions = [], scope_basis = null, instructedScope = null, register_service = null } = {}) {
   const list = (searched_jurisdictions.length
     ? searched_jurisdictions
     : (Array.isArray(instructedScope?.jurisdictions) ? instructedScope.jurisdictions : [])).map((j) => String(j).trim()).filter((j) => j);
-  if (scope_basis === "worldwide" || list.some((j) => WORLDWIDE_TOKEN_RE.test(j))) return " · registers: worldwide";
+  if (scope_basis === "worldwide" || list.some((j) => WORLDWIDE_TOKEN_RE.test(j))) {
+    return ` · registers: worldwide${register_service ? ` (${register_service})` : ""}`;
+  }
   if (!list.length) return "";
   // 2–3-letter office codes display uppercase ("us" reads as a pronoun, "US" as a jurisdiction);
   // longer names pass through untouched.

package/driver/scope-ledger.mjs

@@ -1,12 +1,12 @@
 // 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
-// scope-ledger.mjs — the machine mirror of the prelim-variants `### Scope ledger` (the frame-omission
+// scope-ledger.mjs — the machine mirror of the clearance-variants `### Scope ledger` (the frame-omission
 // design: the blind-pass framing fix, approved into this file — the code is its own record).
 //
-// prelim-variants emits a prose `### Scope ledger` table — one row per variant / field / source the
+// clearance-variants emits a prose `### Scope ledger` table — one row per variant / field / source the
 // run CONSIDERED and DROPPED (or applied), each carrying the observation that should REOPEN it. The
 // driver CODE-DERIVES scope-ledger.json from that prose (renderScopeLedgerJson, called after
-// prelim-variants validates) so the JSON is authored by the driver, never the model, and matches the
+// clearance-variants validates) so the JSON is authored by the driver, never the model, and matches the
 // prose BY CONSTRUCTION — exactly the coverage-ledger.mjs pattern. The blind frame-diff reads the
 // dropped set + reopen triggers to decide which omissions to escalate.
 //
@@ -115,7 +115,7 @@ export function parseScopeLedgerJson(raw) {
 
 /**
  * CODE-DERIVE the JSON scope ledger FROM the prose `### Scope ledger` table (the driver calls this after
- * prelim-variants validates; never-killed at the call site). PURE. Throws `scope_ledger_unparseable`
+ * clearance-variants validates; never-killed at the call site). PURE. Throws `scope_ledger_unparseable`
  * when the prose carries a Scope ledger heading but yields no classifiable row, so the caller's catch
  * routes to the manifest-prose-fallback path (the run still delivers). Returns a JSON ARRAY string that
  * round-trips through parseScopeLedgerJson.
@@ -136,7 +136,7 @@ export function renderScopeLedgerJson(md) {
  * MARKDOWN TABLE back out of a prose manifest a model had typed, on fixed column positions. A machine
  * artifact the downstream depends on, recovered from a table.
  *
- * `record_prelim_variants` now receives those rows TYPED, so the driver can serialise them directly. Both
+ * `record_clearance_variants` now receives those rows TYPED, so the driver can serialise them directly. Both
  * paths call THIS function, which is what makes the recorded and the archived ledger byte-identical for
  * the same rows by construction rather than by an assertion someone has to maintain — and it is why the
  * prose parse can stay for archives (the anchor rule: a new way in, never a replacement) without becoming

package/driver/search-policy.mjs

@@ -15,10 +15,10 @@
 // ── THE DEPTH LADDER IS GONE ─────────────────────────────────────────────────────────────────────────────────
 //
 // There used to be a second vocabulary here: a closed set of LEVELS (`knockout`, `knockout-register`,
-// `prelim`, `prelim-jx`) with a display face reading "Depth 1"…"Depth 5", ordered by effort. A client
+// `clearance`, `clearance-jx`) with a display face reading "Depth 1"…"Depth 5", ordered by effort. A client
 // bought a level; the thing they were sold — a knockout, a worldwide preliminary, a single-country deep
 // dive — was a different word that appeared on no wire. The two disagreed in the one place it mattered:
-// `prelim` named THREE products depending on where it pointed, and the composer's own footer had to
+// `clearance` named THREE products depending on where it pointed, and the composer's own footer had to
 // invent labels ("Deep dive — United States", "Full clearance") for distinctions "the registry has no
 // word for". The registry now has the word. The level menu, its numbering, its ordering and the
 // `searchLevel` wire field are DELETED — not deprecated, not hidden behind the product name.
@@ -61,7 +61,7 @@ export const ORDERABLE_PRODUCTS = PRODUCT_IDS;
 //
 // This is the reading that squares "no old mechanism survives its replacement" with an archive: the
 // delete rule governs the ORDERABLE path, and naming a run that already happened is not that path.
-export const RETIRED_PRODUCTS = ["knockout", "knockout-register", "prelim-register-only", "prelim", "prelim-jx"];
+export const RETIRED_PRODUCTS = ["knockout", "knockout-register", "clearance-register-only", "clearance", "clearance-jx"];
 
 /** Saved searches dropped by the last `loadRecipes` because their base is a retired product. Rewritten on
  *  every load, so it describes the CURRENT store and never accumulates. Read it to tell a reader why a
@@ -304,9 +304,9 @@ export const RETIRED_POLICIES = {
   // Retired 2026-08-06: the clearance shape with its unregistered-use half removed. That basis
   // still composes into riskStatement, and the workbook's own gate still inverts on it, because an
   // archived run of it must not re-render claiming a sweep that never ran.
-  "prelim-register-only": { product: "prelim-register-only", stageLabel: "Depth 3", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance — register only" },                       components: { registerProbe: false, jxLanes: false, commonLawGrid: false } },
-  "prelim":               { product: "prelim",               stageLabel: "Depth 4", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance" },                                       components: { registerProbe: false, jxLanes: false, commonLawGrid: true } },
-  "prelim-jx":            { product: "prelim-jx",            stageLabel: "Depth 5", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance with jurisdiction deep-dive" },           components: { registerProbe: false, jxLanes: true,  commonLawGrid: true } },
+  "clearance-register-only": { product: "clearance-register-only", stageLabel: "Depth 3", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance — register only" },                       components: { registerProbe: false, jxLanes: false, commonLawGrid: false } },
+  "clearance":               { product: "clearance",               stageLabel: "Depth 4", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance" },                                       components: { registerProbe: false, jxLanes: false, commonLawGrid: true } },
+  "clearance-jx":            { product: "clearance-jx",            stageLabel: "Depth 5", pipeline: "clearance", report: { template: "clearance", identity: "Preliminary clearance with jurisdiction deep-dive" },           components: { registerProbe: false, jxLanes: true,  commonLawGrid: true } },
 };
 
 /** The report identity to print on a run's document: `{ template, identity, stageLabel, banner }`.
@@ -464,13 +464,23 @@ export function isRegisterOnly(policy) {
  *  search asked for. Asking it "does this exist" is asking the wrong question — the orderability test is
  *  always `ORDERABLE_PRODUCTS.includes(...)`, and a typo must fail closed against that positive list. */
 export function policyFor(product) {
-  const k = String(product ?? "").trim().toLowerCase();
+  const k = productKeyAsRenamed(product);
   return PRODUCT_POLICIES[k] ?? RETIRED_POLICIES[k] ?? null;
 }
+// THREE RETIRED KEYS WERE RENAMED WITH THE IDENTIFIER, and records written before it still carry the old
+// spelling: an archived run's product, a saved search's base in a client's store. Read the old key as the
+// new wherever a key is looked up, or an archived report loses its name and a store's saved searches fail
+// to load over a base this build still knows as retired.
+const PRE_RENAME_PRODUCT_KEYS = Object.freeze({ "prelim": "clearance", "prelim-register-only": "clearance-register-only", "prelim-jx": "clearance-jx" });
+/** A product key, lower-cased, with a pre-rename spelling read as its current one. PURE. */
+export function productKeyAsRenamed(product) {
+  const k = String(product ?? "").trim().toLowerCase();
+  return PRE_RENAME_PRODUCT_KEYS[k] ?? k;
+}
 
 // What THIS build can actually execute. A resolution onto machinery a build does not carry must CLARIFY
 // at admission (never silently run the wrong-priced product — a knockout request running as a $40
-// prelim, or a 1.5 request running as a plain Stage 1, is the exact silent-substitution this file exists
+// clearance, or a 1.5 request running as a plain Stage 1, is the exact silent-substitution this file exists
 // to forbid). These flags are flipped in CODE as each lane lands, never from the environment: there are
 // no runtime env kill switches — see the note below.
 // EXPORTED because availability is now asked about in two places, not one. The runner asks "may this
@@ -498,7 +508,7 @@ export const BUILT = { knockout: true, jxLanes: true, registerProbe: true };
 // They were not merely dead, they were actively harmful, and in exactly the way the old comment here
 // predicted: a caller outside the engine's environment reads every switch as unset, and unset was
 // indistinguishable from off. The portal was given a snapshot to work around it. The ops-MCP was not,
-// so `describe_options` and `plan_run` told clients that knockout, knockout-register and prelim-jx were
+// so `describe_options` and `plan_run` told clients that knockout, knockout-register and clearance-jx were
 // "Not switched on for this account yet" while the engine would have run all three (2026-07-27). That is
 // the second time this service has lied for want of an environment variable — the first was the profiles
 // dir answering with a demo roster. Deleting the switch is the fix that cannot recur; plumbing a
@@ -830,7 +840,7 @@ export const CAPABILITY_SKIPPED_CAUSE = {
  * now honoured wherever it resolves, and built machinery is never "off".
  *
  * The RESOLVED policy is measured, never `policyFor(resolved.level)`: a recipe can turn jxLanes on over a
- * base of `prelim`, and the base registry entry would answer "available" for a resolution that is not.
+ * base of `clearance`, and the base registry entry would answer "available" for a resolution that is not.
  * Delegating the built arms to productAvailability is what makes the null-equivalence with
  * gateResolvedPolicy structural rather than a coincidence two edits can break (search-policy.test.mjs
  * pins it over the whole matrix).
@@ -1115,7 +1125,7 @@ export function loadRecipes({ dir = process.env.CLEAROTRON_RECIPES_DIR || null,
       // NOT SILENT, because unlike a retired extra this one is observable: a saved search disappears. The
       // skip is recorded so a caller can say why rather than leaving a lawyer's saved search gone with no
       // reason. Everything else still throws — a config error is still load-blocking.
-      if (RETIRED_PRODUCTS.includes(String(r?.base ?? "").trim().toLowerCase())) {
+      if (RETIRED_PRODUCTS.includes(productKeyAsRenamed(r?.base))) {
         retiredBaseSkips.push({ customer, slug, base: String(r.base), why: "base names a retired search — the saved search cannot be ordered" });
         continue;
       }
@@ -1216,7 +1226,7 @@ export function checkMarkBudget(job, policy) {
 // THE SCOPE ITSELF.
 //
 // THAT LAST RUNG IS THE OFFERING, AND IT IS NOT A CONSTANT. The Generic default used to be the literal
-// level `prelim`, which named three different products depending on where it pointed. A clearance that
+// level `clearance`, which named three different products depending on where it pointed. A clearance that
 // names no product IS whichever product its territories make it — `productFor(pipeline, scope)`, the one
 // function that answers that question anywhere — so the default is derived, not picked. The caller hands
 // in the RESOLVED scope (`territories`) because resolving it needs the profile and the project overlay,

package/driver/skills/README.md

@@ -2,7 +2,7 @@
 
 **Every file here is prompt payload served to the model at runtime.** A stage is one engine turn told to read named
 files and follow them exactly, so an edit for brevity or tone changes what a clearance concludes —
-`prelim-search/synthesis-rules.md` is 1,025 lines of program. Never touch this tree in a documentation or tidy-up
+`clearance-search/synthesis-rules.md` is 1,025 lines of program. Never touch this tree in a documentation or tidy-up
 task, and never let a mass edit reach it — the [ADR-0005](../../docs/decisions/0005-comments-carry-reasoning.md)
 comment sweep is required to exclude this tree, and that script does not exist yet, so nothing enforces it but you.
 
@@ -20,21 +20,21 @@ One directory per skill. `SKILL.md` is the entry point — YAML frontmatter (`na
 procedure. Every other file beside it is a reference the SKILL.md or the stage message names explicitly, with six
 exceptions: the four `risk-framework*.manifest.json` sidecars, whose paths the code DERIVES from the deck
 (`manifestPathFor()`, `../framework.mjs`) so validators and the renderer read band vocabulary without parsing prose;
-`prelim-search/risk-framework-triage.md`, the knockout lane's default ladder, named in code only
+`clearance-search/risk-framework-triage.md`, the knockout lane's default ladder, named in code only
 (`../pipeline-knockout.mjs`) because the knockout stage message hands the seat the frozen `_driver/framework.json`
-instead; and `prelim-search/templates/search-request-form.html`, named only in `../publish/index.mjs`.
+instead; and `clearance-search/templates/search-request-form.html`, named only in `../publish/index.mjs`.
 
 | Skill | What the stage does |
 |---|---|
 | `matter-frame` | Phase 0. Writes the matter's commercial context — sector, customer base, channels of trade, jurisdictions that materially matter, off-field sectors, watchlist seeds — before any search runs. `watchlist-reference.md` is enrichment, not authority. |
-| `prelim-variants` | Classifies the mark into one of six archetypes, derives a risk theory from that, emits the variant manifest both execution skills read. Non-Latin scripts: `transliteration-scripts.md`. |
+| `clearance-variants` | Classifies the mark into one of six archetypes, derives a risk theory from that, emits the variant manifest both execution skills read. Non-Latin scripts: `transliteration-scripts.md`. |
 | `blind-frame`, `frame-diff` | Re-derives the threat model from the raw instruction alone, deliberately starved of the matter frame, then diffs that model against what the run actually scoped and emits reopen directives the driver acts on. Something has to test the frame instead of reasoning inside it. |
-| `prelim-common-law` | The marketplace / web / social sweep, as structured Perplexity research over the platform list the stage dictates. Prompt templates: `perplexity-prompts.md`. |
-| `prelim-register` | Register execution in the two modes a spawn selects: `unit.md` (the funnel — enumerate one axis to completion, decide nothing) and `digest.md` (judgment over the merged band). Plus `register-recipes.md`, `status-rules.md`, `stealth-filer-indicators.md`, `providers/`. |
+| `clearance-common-law` | The marketplace / web / social sweep, as structured Perplexity research over the platform list the stage dictates. Prompt templates: `perplexity-prompts.md`. |
+| `clearance-register` | Register execution in the two modes a spawn selects: `unit.md` (the funnel — enumerate one axis to completion, decide nothing) and `digest.md` (judgment over the merged band). Plus `register-recipes.md`, `status-rules.md`, `stealth-filer-indicators.md`, `providers/`. |
 | `placement-inquiry` | Applies commercial relevance per candidate — headline-candidate / sheet-2 / watchlist-annex / out-of-scope-filtered — before any tiering runs. |
 | `case-law-citation` | Grounds risk-relevant findings in precedent fetched in-session, never from memory. One thin adapter per source in `sources/`; `evals.md` defines what working means. |
 | `narrative-refutation` | Reads the finished narrative against the underlying findings files and returns CLEAR / CONDITIONAL / BLOCKING with itemised flags. Delivery is gated on the verdict. |
-| `prelim-search` | The doctrine the synthesis and delivery stages are held to: `synthesis-rules.md`, the `risk-framework*.md` ladders with their `.manifest.json` band vocabularies, `delivery-contract.md`, `report-prose.md`, `worked-examples.md`, `phase2-execution.md`, `field-doctrine-pharma.md`. |
+| `clearance-search` | The doctrine the synthesis and delivery stages are held to: `synthesis-rules.md`, the `risk-framework*.md` ladders with their `.manifest.json` band vocabularies, `delivery-contract.md`, `report-prose.md`, `worked-examples.md`, `phase2-execution.md`, `field-doctrine-pharma.md`. |
 | `knockout-frame`, `knockout-assess` | Stages A and C of the knockout doctrine — a broad kill/no-kill triage screen over several candidate names at once (Stage B is a code-side research sweep). Not a clearance. |
 
 ## What reads it
@@ -53,25 +53,25 @@ instead; and `prelim-search/templates/search-request-form.html`, named only in `
 
 ## The provider boundary
 
-Operator syntax and vendor tool tokens like `corsearch_*` live only in `prelim-register/providers/`; the spine names
+Operator syntax and vendor tool tokens like `corsearch_*` live only in `clearance-register/providers/`; the spine names
 the `register_*` tools, whichever vendor `CLEAROTRON_DATABASE` selects.
 `../test/provider-neutral-prose.test.mjs` holds three of that boundary's lines: no vendor-prefixed tool token
 outside `providers/` and the `engine/mcp/<provider>-server.mjs` glue; no provider record host in a provider-agnostic
 skill file (banned hosts are read FROM the provider docs, so a sixth provider is covered the day its doc lands);
 every register server registering only `register_*`, under the MCP name `register`. Field paths are the open edge —
 the matcher requires `<vendor>_` and cannot see camelCase, so no test fails on one, and
-`prelim-register/status-rules.md` still instructs off Corsearch's own field names (`corsearchStatusCode`,
+`clearance-register/status-rules.md` still instructs off Corsearch's own field names (`corsearchStatusCode`,
 `onomaticsJurisdictionsStatuses`, the `owners[0].*` owner chain), plus one line of `register-recipes.md` off
-`onomaticsOppositions[]`. `prelim-register/SKILL.md`, `unit.md`, `digest.md` and everything under `prelim-search/`
+`onomaticsOppositions[]`. `clearance-register/SKILL.md`, `unit.md`, `digest.md` and everything under `clearance-search/`
 are clean. The authoring rules and the empirical-verification checklist a new provider doc must pass sit in
-`prelim-register/providers/README.md`.
+`clearance-register/providers/README.md`.
 
 ## Where to start
 
-`prelim-search/SKILL.md` — the orchestrator's own skill, and the one file describing the whole workflow end to end.
-Then `prelim-register/SKILL.md`, the more elaborated of the two execution skills: a spine plus per-mode files
-(`unit.md`, `digest.md`) and per-provider files (`providers/`). The other, `prelim-common-law`, is one spine plus
+`clearance-search/SKILL.md` — the orchestrator's own skill, and the one file describing the whole workflow end to end.
+Then `clearance-register/SKILL.md`, the more elaborated of the two execution skills: a spine plus per-mode files
+(`unit.md`, `digest.md`) and per-provider files (`providers/`). The other, `clearance-common-law`, is one spine plus
 `perplexity-prompts.md`, its two grid modes (deterministic `grid_spec_path` dispatch vs. the legacy authored
 program) being sections inside it — the per-mode split and `providers/` are register-only, not a shape every
-execution skill shares. `prelim-search/phase2-execution.md` is methodology, not sequencing — the pipeline is
+execution skill shares. `clearance-search/phase2-execution.md` is methodology, not sequencing — the pipeline is
 sequenced in code, in `../stages.mjs` and `../pipeline.mjs`.

package/driver/skills/blind-frame/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: blind-frame
-description: The frame-STARVED independent re-derivation for the v3 preliminary trademark search workflow. **Invoked exclusively by the `prelim-search` orchestrator/driver**, in parallel with the gather sweeps — do not call directly. Reads ONLY the raw instruction (mark, goods, classes, territories, manner of use) and NOT the matter frame, then re-derives the threat model cold across four layers — element + neighbours both directions, field by goods-overlap, sources by real channel, ranking by goods-overlap — and emits a structured model the frame-diff stage diffs against what the run actually scoped. Its job is to test the frame, not to reason inside it.
+description: The frame-STARVED independent re-derivation for the v3 preliminary trademark search workflow. **Invoked exclusively by the `clearance-search` orchestrator/driver**, in parallel with the gather sweeps — do not call directly. Reads ONLY the raw instruction (mark, goods, classes, territories, manner of use) and NOT the matter frame, then re-derives the threat model cold across four layers — element + neighbours both directions, field by goods-overlap, sources by real channel, ranking by goods-overlap — and emits a structured model the frame-diff stage diffs against what the run actually scoped. Its job is to test the frame, not to reason inside it.
 ---
 
 ## Purpose
 
-Every other stage in a clearotron run reasons *inside* a frame that was set early (at `matter-frame` / `prelim-variants`): the variants to chase, the field that counts as on-field, the sources worth searching. Verification then runs *on* that frame — nothing tests the frame itself. When the frame is mis-scoped, the whole run inherits the miss and the skeptic, reasoning from the same frame, certifies it.
+Every other stage in a clearotron run reasons *inside* a frame that was set early (at `matter-frame` / `clearance-variants`): the variants to chase, the field that counts as on-field, the sources worth searching. Verification then runs *on* that frame — nothing tests the frame itself. When the frame is mis-scoped, the whole run inherits the miss and the skeptic, reasoning from the same frame, certifies it.
 
 You are the antidote. You are **deliberately starved of the frame**: you receive only the raw instruction, exactly as the requester wrote it, and you re-derive the threat model **cold**. Because you never see the run's conclusions, you cannot anchor to them. Your output is later **diffed** against what the run actually scoped — the gaps in that diff are the omissions the frame missed.
 

package/driver/skills/case-law-citation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: case-law-citation
-description: Grounds risk-relevant trademark findings in cited case law and decisions instead of asserting them. Invoked by the prelim-search orchestrator at Step 4.5 to profile an aggressive enforcer or test a likelihood-of-confusion question against precedent, and usable inline in chat for ad-hoc conflict/enforcement questions. Queries live legal sources — CourtListener (US federal incl. CAFC), EUR-Lex (EU CJEU + General Court judgments, verbatim), and Legal Data Hunter (108-country statutes and case law) — and returns, per finding, on-point authorities (case or decision, forum, date, one-line holding, stable identifier) with relevance notes, or an explicit no-precedent result. Cites only from documents fetched in the session, never from memory. Use when grounding watchlist or aggressive-enforcer hits, or when a trademark conflict, confusability, or enforcement-history question needs precedent.
+description: Grounds risk-relevant trademark findings in cited case law and decisions instead of asserting them. Invoked by the clearance-search orchestrator at Step 4.5 to profile an aggressive enforcer or test a likelihood-of-confusion question against precedent, and usable inline in chat for ad-hoc conflict/enforcement questions. Queries live legal sources — CourtListener (US federal incl. CAFC), EUR-Lex (EU CJEU + General Court judgments, verbatim), and Legal Data Hunter (108-country statutes and case law) — and returns, per finding, on-point authorities (case or decision, forum, date, one-line holding, stable identifier) with relevance notes, or an explicit no-precedent result. Cites only from documents fetched in the session, never from memory. Use when grounding watchlist or aggressive-enforcer hits, or when a trademark conflict, confusability, or enforcement-history question needs precedent.
 ---
 
 # Case-law citation
@@ -40,17 +40,17 @@ Companion files (one level deep — read the one you need):
 
 Still-future adapter (drops in here with no change to this file): `sources/euipo.md` (EUIPO
 Boards-of-Appeal decisions — no free API today). EUIPO *register* lookups are a different layer
-(`prelim-register`), not this skill.
+(`clearance-register`), not this skill.
 
 ## Trigger
 
-Called by `prelim-search` after synthesis flags the risk-relevant findings (Step 4.5). Also triggers in
+Called by `clearance-search` after synthesis flags the risk-relevant findings (Step 4.5). Also triggers in
 chat when the user raises a trademark conflict, likelihood-of-confusion, or enforcement-history question.
 Gated and optional: if this skill is absent, clearotron skips Step 4.5 and delivers normally.
 
 ## Model
 
-**Sonnet, eval-gated** when spawned from the `prelim-search` Step 4.5 seam. The work is extraction
+**Sonnet, eval-gated** when spawned from the `clearance-search` Step 4.5 seam. The work is extraction
 from documents fetched **this session** — the fetch-before-cite discipline (cite only what you
 fetched; read the holding from the fetched text; refuse to invent when sources are empty), not model
 recall, is what keeps citations honest. That makes it a Sonnet-tier task **provided** Sonnet reliably

package/driver/skills/case-law-citation/sources/eurlex.md

@@ -65,7 +65,7 @@ successfully fetch and verify.
   would close this gap; none is wired today.)
 - **Not** the EUIPO administrative layer: **EUIPO Boards-of-Appeal decisions** have no free API and are
   not searched — report that as a coverage gap. EUIPO *register* lookups are a different layer
-  (`prelim-register`), not this skill.
+  (`clearance-register`), not this skill.
 
 ## Citing convention