clearotron 0.3.2-beta.6 → 0.3.2-beta.8

package/driver/terminal-clamp.mjs

@@ -87,6 +87,36 @@ export function recordNamesDefect(record) {
   return typeof record?.defect === "string" && record.defect.trim().length > 0 && record?.delivered === true;
 }
 
+
+/**
+ * The conditions `clientConditions` could NOT render, so the surface does not carry them. PURE.
+ *
+ * A REFUSAL NOBODY RECORDS IS THE DEFECT ONE LAYER ALONG. The fallback drops a token-bearing reason it
+ * cannot compose a sentence for, which is the right answer for the client and a silent loss for
+ * everyone else: the condition was in the run record, it applies, and the delivered page no longer says
+ * so. Before this, the operator's signal was the voice lint flagging the token on the page. Take the
+ * token off the page and that flag goes quiet — the gap would be closed and the disclosure would go
+ * with it, with nothing in between to say which. So the drop reports itself here, the lint reads it,
+ * and the run record keeps the reason either way.
+ *
+ * @param {{reasons?: string[], clauses?: string[]}} sidecar  the parsed `_driver/verdict.json`
+ * @returns {string[]} the run-record reasons that reach no client surface
+ */
+// IT DECIDES THE SAME THREE THINGS `clientConditions` DECIDES, and they have to keep agreeing: what
+// counts as a stored clause, what counts as an empty reason, and which reasons the authority can
+// render. The third cannot drift — both call `clauseFromReason` — and the first two are the two lines
+// below. A change to either belongs in both, and arm 9 drives them together against one sidecar.
+export function unrenderableConditions({ reasons, clauses } = {}) {
+  const rs = Array.isArray(reasons) ? reasons : [];
+  const cs = Array.isArray(clauses) ? clauses : [];
+  return rs.filter((r, i) => {
+    if (typeof cs[i] === "string" && cs[i].trim()) return false;
+    const text = String(r ?? "").trim();
+    if (!text) return false;
+    return !clauseFromReason(text) && ENGINE_TOKEN_RE.test(text);
+  }).map((r) => String(r).trim());
+}
+
 /**
  * THE LEDE IS THE OPINION'S, BY DECISION AND NOT BY PUSH ORDER. The terminal guards run
  * earlier in the delivery block than the coverage floor, so their clauses landed at index 0 and the
@@ -107,6 +137,70 @@ export function orderClausesForLede(clauses, reasons, guardSet) {
   return { clauses: ordered.map((x) => x.c), reasons: ordered.map((x) => x.r) };
 }
 
+/**
+ * THE CLAUSE AUTHORITY — one composer for the reader's sentence, called both where the numbers are
+ * known and where only the run-record reason survives. PURE.
+ *
+ * A run recorded before clauses were persisted carries `reasons` and no `clauses`, so every condition
+ * fell back to the run-record sentence and a republished archived report opened its Conditions list
+ * with `floor_duty_undischarged:4 of 430 floor row(s)…` — on the page and in the exported PDF. Dropping
+ * the condition instead loses a point the reader must weigh, and re-generating every archived run is
+ * not on offer. The third way is this: for both defects that can reach that list the reader's sentence
+ * is fully determined by the two numbers the reason already carries in its own prefix. An archived run
+ * therefore holds everything needed to compose the client's sentence; what it lacks is only the store.
+ *
+ * ONE DEFINITION, TWO ENTRY POINTS. The clamp site calls `clauseForDefect` with the counts it already
+ * holds; the republish path calls `clauseFromReason`, which reads the same two numbers off the reason's
+ * prefix and hands them to the same composer. A second spelling of either sentence would drift, and the
+ * drift would be invisible: both surfaces render, and only a reader comparing a fresh run against a
+ * republished one would ever see it.
+ *
+ * AN UNRECOGNISED SHAPE IS REFUSED, AND REFUSED HERE MEANS `null` — NEVER A THROW. This runs on the
+ * republish path. A throw there is the failure at the top of this file: a live run died at delivery
+ * after 5.55 hours and the client received nothing instead of a report naming one gap. The caller
+ * decides what the absence means.
+ */
+const CLAUSE_AUTHORITY = Object.freeze({
+  synthesis_unaccounted_delivered: (n, m) =>
+    `${n} of the ${m} register records this search surfaced are neither addressed as findings nor expressly set aside in this report — they remain open points a reader must weigh`,
+  floor_duty_undischarged: (n, m) =>
+    `${n} of the ${m} live registrations identical or near-identical to the mark are not individually addressed in this report — each remains an open point a reader must weigh`,
+});
+
+/**
+ * The reader's sentence for a defect, from its counts. PURE.
+ *
+ * @param {string} defect  the machine token, with or without its `:N` tail
+ * @param {number} n       the count the defect names
+ * @param {number} m       the population it is out of
+ * @returns {string|null}  the client's sentence, or null for a shape this module cannot render
+ */
+export function clauseForDefect(defect, n, m) {
+  const compose = CLAUSE_AUTHORITY[String(defect ?? "").split(":")[0].trim()];
+  if (!compose) return null;
+  const a = Number(n), b = Number(m);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
+  return compose(a, b);
+}
+
+// The run-record reason's own opening: `<token>:<n> of <m> <noun>`. The NOUN is deliberately not part
+// of the match — `record(s)` and `floor row(s)` are the two spellings today, and a third would make
+// this stop recognising a shape it can render perfectly well. The token is what selects the sentence.
+const REASON_PREFIX_RE = /^([a-z][a-z0-9_]*):(\d[\d,]*)\s+of\s+(\d[\d,]*)\s/i;
+
+/**
+ * The reader's sentence for a condition that has only its run-record reason. PURE.
+ *
+ * @param {string} reason  the run-record sentence
+ * @returns {string|null}  the client's sentence, or null when the reason is not one this can render
+ */
+export function clauseFromReason(reason) {
+  const m = String(reason ?? "").match(REASON_PREFIX_RE);
+  if (!m) return null;
+  const num = (t) => Number(String(t).replace(/,/g, ""));
+  return clauseForDefect(m[1], num(m[2]), num(m[3]));
+}
+
 /**
  * THE CLIENT'S CONDITION LIST, from a verdict sidecar. PURE.
  *
@@ -135,6 +229,15 @@ export function orderClausesForLede(clauses, reasons, guardSet) {
  *   · a clean reason with no clause survives       → break: return "" for a missing clause, arm 2 red
  *   · a legacy sidecar still yields its conditions  → break: require the clauses key, arm 3 red
  *   · clauses shorter than reasons loses nothing    → break: map over clauses, arm 4 red
+ *   · a pre-split reason renders as the lawyer's    → break: return the reason, arm 5 red
+ *   · an unrenderable token-bearing reason is gone  → break: return it, arm 6 red
+ *
+ * THE FALLBACK NO LONGER PRINTS THE RUN RECORD. Where no clause was stored, the clause authority above
+ * composes one from the reason's own counts; where it cannot, the condition is DROPPED rather than
+ * rendered in engine voice. Dropping is a loss and it is the smaller one: a client who reads
+ * `floor_duty_undischarged:4` has been handed the engine's private vocabulary as their own advice. A
+ * reason carrying no engine identifier is a factual open-state already — the three machinery sites push
+ * the reason AS the clause — and it still survives untouched, which is arm 2.
  *
  * @param {{reasons?: string[], clauses?: string[]}} sidecar  the parsed `_driver/verdict.json`
  * @returns {string[]} one condition per reason, in the sidecar's own order
@@ -144,6 +247,9 @@ export function clientConditions({ reasons, clauses } = {}) {
   const cs = Array.isArray(clauses) ? clauses : [];
   return rs.map((r, i) => {
     const clause = typeof cs[i] === "string" ? cs[i].trim() : "";
-    return clause || String(r ?? "").trim();
+    if (clause) return clause;
+    const text = String(r ?? "").trim();
+    if (!text) return "";
+    return clauseFromReason(text) ?? (ENGINE_TOKEN_RE.test(text) ? "" : text);
   }).filter(Boolean);
 }

package/driver/tokens.mjs

@@ -46,10 +46,10 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { driverDir } from "../shared/driver-dir.mjs";   //
-import { resolveModel } from "./driver.config.mjs";
+import { resolveModel, modelFamily } from "./driver.config.mjs";
 import { runLog, note } from "./log.mjs";
 import { writeRunStatus } from "./progress.mjs";
-import { stampRunEconomics, isCodeSide } from "./run-economics.mjs";
+import { stampRunEconomics, isCodeSide, vendorOf } from "./run-economics.mjs";
 
 function emptyAcc() {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, attempts: 0, thoughtTurns: 0 };
@@ -84,9 +84,27 @@ function modelKey(rec) {
   // them would break byModel summing to total, and an invisible gap is the failure this file already
   // fixed once for byEngine), and the key says what is missing rather than asserting an Anthropic
   // model produced them.
+  //
+  // A TURN THAT NAMED NO MODEL, a native-language row recording `modelActual: null` (see isAttemptRow),
+  // has no id at all. Its tokens still account, under a key that says the model is missing rather than
+  // one built from the absent field. Such a row always carries its vendor's stamp, so it reaches here.
+  if (typeof rec.model !== "string") return `${engine || "unknown"}/no-model-reported`;
   return `${engine}/unstamped:${rec.model}`;
 }
 
+/**
+ * WHETHER A ROW IS A PROVIDER ATTEMPT, the one test rollupTokens and servedModels both apply. A row that
+ * names a model is one: every stage attempt row carries the tier it asked for, and a native-language row
+ * the id its turn reported. So is a native-language row whose turn ran and named no model, which records
+ * `modelActual: null` instead (jxModelFields in jx-lanes.mjs). Without that second half, such a turn's
+ * attempt and the tokens it reported were dropped from every total, and a run made only of such turns
+ * read as one where nothing was looked at. A row with neither field is not a turn: the run log's events,
+ * a tool call, a native-language call no provider served.
+ */
+export function isAttemptRow(rec) {
+  return Boolean(rec) && (typeof rec.model === "string" || rec.modelActual === null);
+}
+
 // usage shape (gateway.mjs): {input,output,cacheRead,cacheWrite}. There is deliberately NO reasoning-token
 // field: the old `reasoning`/`reasoningTokens` pair was an unfillable slot — no reasoning count exists
 // anywhere in the claude payload (not result.usage, not usage.iterations), so no shipped adapter ever
@@ -128,7 +146,7 @@ export function rollupTokens(runDir) {
       if (!ln.trim()) continue;
       let rec;
       try { rec = JSON.parse(ln); } catch { continue; }
-      if (!rec || typeof rec.model !== "string") continue; // only stage-attempt records carry a model
+      if (!isAttemptRow(rec)) continue; // only provider attempts carry tokens (see isAttemptRow)
       const t = tokensOf(rec.usage);
       const accs = [total, (byStage[stage] ??= emptyAcc()), (byModel[modelKey(rec)] ??= emptyAcc())];
       // Engine and billing mode are split out because a token is not a portable unit of cost: a turn on a
@@ -168,6 +186,154 @@ export function rollupTokens(runDir) {
   return { total, byStage, byModel, byEngine, byAuthMode };
 }
 
+/**
+ * THE MODELS THAT SERVED THIS RUN, as the engine reported them: distinct ids, in the order each first
+ * served a turn. Read from every attempt row's `modelActual`, the id the wire named: the stage rows
+ * gateway.mjs writes and the native-language rows jx.mjs and jx-units.mjs write, one list across both. Never
+ * the tier a stage asked for in place of a model the wire named: a tier goes to the CLI as the vendor's
+ * alias, so the request says nothing about which model ran, and this is the record that does. The tier
+ * stands in only for a name no client may read (below).
+ *
+ * THREE-VALUED. `null` when there is no attempt row to read (no telemetry directory, or no row in it is
+ * a provider turn), so nothing was looked at. `[]` when attempt rows exist and none names a served model
+ * a client may read (an engine that does not report one, a turn killed before it said, a turn the Claude
+ * program answered itself), on a stage turn and a native-language turn alike. One more case reads `[]`:
+ * a Claude turn served under a deployment name whose requested tier the tier reader cannot place (a request
+ * outside opus, sonnet, haiku and fable) is left off, because the name must not be printed and there is no
+ * tier word to print instead. In a run that mixes such turns with others, the list names only the others.
+ * So does a turn stamped by an engine whose vendor the closed table in run-economics.mjs does not name:
+ * nobody can say whose model served it. An empty list is never a guess.
+ *
+ * WHAT IS LISTED IS WHAT A CLIENT MAY READ, mapped here and nowhere else (servedName below), so meta.json,
+ * report-data.json and the report's closing line carry one list and cannot disagree. Through a cloud, a
+ * turn reports either that cloud's spelling of a Claude model or a name the company gave its own
+ * deployment. The first is listed as the Claude id it names; the second is listed as the tier the turn
+ * asked for ("Opus"), never as the name. The attempt row itself keeps what the program reported.
+ */
+export function servedModels(runDir) {
+  const dDir = driverDir(runDir);
+  let files;
+  try { files = readdirSync(dDir).filter((f) => f.endsWith(".jsonl") && f !== "run.jsonl"); }
+  catch { return null; }
+  const firstSeen = new Map();   // id → the earliest row timestamp that named it
+  let attempts = 0;
+  for (const file of files) {
+    let raw;
+    try { raw = readFileSync(join(dDir, file), "utf8"); } catch { continue; }
+    for (const ln of raw.split("\n")) {
+      if (!ln.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(ln); } catch { continue; }
+      // The same test rollupTokens applies for an attempt row, less the driver's own code-side rows:
+      // no provider served those, so they cannot stand for "a turn ran and named no model".
+      if (!isAttemptRow(rec) || isCodeSide(rec)) continue;
+      attempts += 1;
+      const id = typeof rec.modelActual === "string" ? rec.modelActual.trim() : "";
+      // `<synthetic>` is the Claude CLI's name for a message it wrote itself, measured in testing on a
+      // turn a cloud refused for a missing deployment (2026-09-14). No model served that turn, so a
+      // bracketed marker is never listed as one.
+      if (!id || /^<.*>$/.test(id)) continue;
+      // Keyed on the name a client reads, so two deployments serving one tier, or one model reached
+      // through two clouds, are listed once.
+      const name = servedName(rec, id);
+      if (!name) continue;
+      const ts = String(rec.ts ?? "");
+      if (!firstSeen.has(name) || ts < firstSeen.get(name)) firstSeen.set(name, ts);
+    }
+  }
+  if (!attempts) return null;
+  return [...firstSeen].sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0)).map(([id]) => id);
+}
+
+// Imported here, beside its one reader: the tier every native-language step asks for (see servedName).
+import { JX_TIER } from "./engine/jx-turn.mjs";
+
+// AMAZON'S SPELLING OF A CLAUDE ID: an optional cross-region prefix (`us.`, `eu.`, `apac.`, `global.`), the
+// vendor prefix `anthropic.`, and a version suffix (`-v1:0`), optionally at the end of an inference
+// profile's full address (`arn:aws:bedrock:<region>:<account>:inference-profile/…`), whose account number
+// is the company's and is dropped with the rest. `us.anthropic.claude-opus-4-1-20250805-v1:0` is
+// `claude-opus-4-1-20250805`. Anchored on `anthropic.claude-`, so no other vendor's id is rewritten.
+const AMAZON_CLAUDE_ID_RE = /^(?:arn:aws[\w-]*:bedrock:[^/]*\/)?(?:[a-z]{2,6}(?:-[a-z]+)?\.)?anthropic\.(claude-[a-z0-9.-]+?)(?:-v\d+(?::\d+)?)?$/i;
+// GOOGLE'S SPELLING, `claude-opus-4-1@20250805`. It already names the model; it is listed as the dated id
+// `claude-opus-4-1-20250805` because that is the same model's name on Anthropic's own API and on Amazon's,
+// so a model reached through two routes is one entry rather than two spellings of one model. An older
+// model's Google name carries a version mark before the date (`claude-3-5-sonnet-v2@20241022`), the same
+// mark Amazon writes as `-v2:0`; it is not in the model's own name, so it goes too.
+const GOOGLE_CLAUDE_ID_RE = /^(claude-[a-z0-9.-]+?)(?:-v\d+)?@(\d{8})$/i;
+// THE SHAPE OF A CLAUDE MODEL ID, which is what lets an id be printed as itself. A family and one or two
+// version numbers (`claude-opus-4-1`), or the older order of version before family
+// (`claude-3-5-sonnet`); then an optional date; then an optional context-window mark (`[1m]`), which
+// the program may report beside the model and is kept as reported. Tested lower-cased, after the cloud
+// spellings above are rewritten. A prefix test is not enough: a company may name its own deployment
+// `claude-acme-prod`, or wrap its own name in Amazon's form, and neither is a Claude model. A family with
+// no version, `claude-opus`, names no model either: it is the name an operator types for a deployment of
+// that tier, and printed as itself it would put that name on the report, and a Sonnet deployment's name
+// on a turn that asked for Haiku. A `latest` alias, `-latest` or Google's `@latest`, is a pointer the
+// provider moves, never the name of the model a turn reports, so it reads as the tier too.
+const CLAUDE_MODEL_ID_RE = /^claude-(?:(?:opus|sonnet|haiku|fable)(?:-\d{1,2}){1,2}|\d(?:-\d)?-(?:opus|sonnet|haiku))(?:-\d{8})?(?:\[\d+[km]\])?$/;
+const CLAUDE_TIERS = new Set(["opus", "sonnet", "haiku", "fable"]);   // fable is reached through the synthesis override
+// A FABLE REQUEST IS READ HERE, NOT BY modelFamily. modelFamily is also the gateway's family comparison on every
+// turn, and it places opus, sonnet and haiku only: an id naming fable stays unknown there, so it can never
+// refuse a turn (driver.config.mjs says why). The report still needs the tier word of a fable turn served under
+// a company's deployment name, so it is read for the report alone, placed where the family reader places the
+// other three: the whole request, or first in it or after a `/`, with or without `claude-`. So `fable` and a
+// request in a pinned id's spelling (`claude-fable-5-1`) both read fable, and `acme-fable` does not. A turn
+// served as a fable id never reaches this: that id is a Claude model's name and prints as itself. modelFamily is
+// asked first, so a request it places reads as that tier even when it also names fable (`fable-x/sonnet` is
+// Sonnet), and one it cannot place falls through to this reader (`sonnet/fable-x` is Fable).
+const FABLE_REQUEST_RE = /(?:^|\/)(?:claude-)?fable(?:[-.]|$)/i;
+const requestedTier = (asked) =>
+  modelFamily(asked) ?? (FABLE_REQUEST_RE.test(String(resolveModel(asked) ?? "")) ? "fable" : null);
+
+/** A Claude model id in any cloud's spelling, as its own lower-case name, or null when it is not one. */
+function claudeModelId(id) {
+  const raw = String(id ?? "").trim();
+  const amazon = AMAZON_CLAUDE_ID_RE.exec(raw);
+  const google = amazon ? null : GOOGLE_CLAUDE_ID_RE.exec(raw);
+  const named = (amazon ? amazon[1] : google ? `${google[1]}-${google[2]}` : raw).toLowerCase();
+  return CLAUDE_MODEL_ID_RE.test(named) ? named : null;
+}
+
+/**
+ * The name a client reads for one served id, or null when it must not be listed.
+ *
+ * A CLAUDE ID, in any cloud's spelling, is the model it names. ANY OTHER ID ON A CLAUDE TURN names no
+ * Claude model, and on Azure Foundry that is the name a company gave its deployment (`acme-prod-opus`): a
+ * company's internal name, and never one to print on its client's report. The turn is listed as the tier
+ * it asked for instead, which is what the company deployed under that name.
+ *
+ * WHOSE TURN IT WAS IS THE VENDOR'S QUESTION, answered by the one closed table of engines (vendorOf in
+ * run-economics.mjs), not by a list kept here. An OpenAI turn's id is listed as reported: a Codex id is the
+ * model's own name. An Anthropic turn under any engine name is mapped as above; a second list of Claude
+ * engines here printed a deployment name, as reported, for every engine it left out. An engine the table
+ * does not name is left off: printing its id would make a vendor claim nobody can check.
+ *
+ * A ROW WITH NO ENGINE STAMP reads as Claude's, as modelKey above reads it, EXCEPT when the id is plainly
+ * another vendor's (a `gpt-` or o-series id, by modelFamily's OpenAI reader): printing that as a Claude
+ * tier would put a false vendor on a client's report, where a wrong guess in modelKey costs only a key.
+ */
+function servedName(rec, id) {
+  const claude = claudeModelId(id);
+  if (claude) return claude;
+  const engine = typeof rec.engine === "string" ? rec.engine : "";
+  const family = engine ? null : modelFamily(id);
+  const vendor = engine ? vendorOf(engine) : family && !CLAUDE_TIERS.has(family) ? "openai" : "anthropic";
+  if (vendor === "openai") return id;
+  if (vendor !== "anthropic") return null;
+  // THE TIER THE TURN ASKED FOR, told apart by the kind of row, which its engine stamp names. A stage row
+  // (engine "anthropic-agent", another Anthropic engine, or no stamp) records that request as `model`
+  // ("opus"), and that holds even when the served id is spelled the same as the request, as it is for a
+  // deployment named after its tier. A native-language row (engine "anthropic") records its SERVED id as `model`, beside
+  // `modelActual` (jxModelFields), so reading it as the request would hand back the deployment name;
+  // every one of those steps asks for JX_TIER. A request in a cloud's spelling is read as the Claude id it
+  // names first. modelFamily reads opus, sonnet and haiku, and requestedTier adds fable, for the report
+  // alone. A tier neither can place returns null and the id is left off: listing nothing is honest, and
+  // listing the name is the leak this prevents.
+  const asked = engine === "anthropic" ? JX_TIER : rec.model;
+  const tier = requestedTier(claudeModelId(asked) ?? asked);
+  return CLAUDE_TIERS.has(tier) ? tier[0].toUpperCase() + tier.slice(1) : null;
+}
+
 /**
  * Stamp the rollup onto the run: the `token-rollup` event in _driver/run.jsonl plus `status.json.tokens`.
  *

package/driver/unit-environment.mjs

@@ -51,36 +51,63 @@ const OPTIONAL = "-";
  * @returns {{path: string}|{unresolved: string}}
  */
 function expandSpecifiers(raw, home) {
-  const path = String(raw).replace(/%h/g, home ?? "");
-  if (!home && /%h/.test(raw)) return { unresolved: raw };
-  // %% is an escaped percent and is legal; anything else left over is a specifier we do not implement.
-  const leftover = path.replace(/%%/g, "").match(/%[A-Za-z]/);
-  return leftover ? { unresolved: raw } : { path };
+  // ONE PASS, LEFT TO RIGHT, as systemd reads them. `%%` is an escaped percent and becomes one `%`, so
+  // `%%h` is a literal `%h`, never the home. Replacing `%h` first and unescaping after read `%%h` as a
+  // `%` followed by the home, and left `50%%` doubled, so a value reached doctor and connect in a form
+  // the service was never given. Any other letter after a `%` is a specifier this reader does not
+  // implement.
+  let unresolved = false;
+  const path = String(raw).replace(/%([%A-Za-z])/g, (whole, c) => {
+    if (c === "%") return "%";
+    if (c === "h" && home) return home;
+    unresolved = true;
+    return whole;
+  });
+  return unresolved ? { unresolved: raw } : { path };
 }
 
 /**
- * Merge one unit file's environment directives IN FILE ORDER.
+ * Merge one unit file's environment directives THE WAY SYSTEMD MERGES THEM: every `Environment=`
+ * assignment first, then every `EnvironmentFile=`'s contents over them, the files in the order listed.
  *
- * systemd applies `EnvironmentFile=` and `Environment=` as it encounters them, and a later assignment
- * overrides an earlier one. Reading the whole file and applying the two kinds in separate passes would
- * be a different resolution order from the one the running service got — which is exactly the class of
- * bug this module exists to close, so the order is preserved rather than approximated.
+ * WHERE A LINE SITS DOES NOT DECIDE IT. systemd.exec(5) on `EnvironmentFile=`: "Settings from these files
+ * override settings made with Environment=." This reader used to apply the two kinds in file order, so a
+ * name set by both came back with the unit's value whenever its `Environment=` line followed the file,
+ * which is how every shipped unit is written, while the service ran with the file's. A PATH in the
+ * settings file was the case that showed: doctor looked for the engine's program on the unit's PATH,
+ * found it, and passed a machine whose services would not find it. The renderer's header
+ * (driver/systemd/render-units.mjs) states the same rule, and one unit loads no settings file because of it.
+ *
+ * Within each kind a later assignment still overrides an earlier one.
  *
  * @param {string} unitText            the unit file's contents
  * @param {(path: string) => string|null} readEnvFile  returns the file's text, or null if unreadable
- * @returns {{env: Object, missing: string[]}}  `missing` names REQUIRED files that could not be read
+ * @returns {{env: Object, missing: string[]}}  `missing` names REQUIRED files that could not be read, and
+ *   assignments whose value carries a specifier that could not be expanded
  */
 function applyUnit(unitText, readEnvFile, home) {
   const env = {};
+  const fromFiles = {};
   const missing = [];
   for (const raw of String(unitText ?? "").split("\n")) {
     const line = raw.trim();
     // `Environment=` may carry several assignments on one line; systemd splits on whitespace.
+    //
+    // ITS VALUES ARE EXPANDED TOO, by the same rule as a file path. Every shipped unit writes
+    // `Environment=PATH=%h/.local/bin:%h/.npm-global/bin:…`, and systemd hands the service that PATH with
+    // the home filled in. Passed through as written, it named a folder called `%h/.local/bin` that exists
+    // nowhere, so a check that looked for the engine's program on the units' PATH found nothing on a
+    // machine whose searches found it and ran. A value that cannot be expanded is a hole in the picture,
+    // for the reason the file branch below gives: a literal `%h` answers "absent" for a reader that
+    // failed.
     const direct = /^Environment=(.*)$/.exec(line);
     if (direct) {
       for (const pair of direct[1].trim().split(/\s+/)) {
         const m = /^"?([A-Za-z_][A-Za-z0-9_]*)=(.*?)"?$/.exec(pair);
-        if (m) env[m[1]] = m[2];
+        if (!m) continue;
+        const value = expandSpecifiers(m[2], home);
+        if (value.unresolved !== undefined) missing.push(`${m[1]}=${value.unresolved} (unresolved systemd specifier)`);
+        else env[m[1]] = value.path;
       }
       continue;
     }
@@ -106,10 +133,10 @@ function applyUnit(unitText, readEnvFile, home) {
         if (!optional) missing.push(path);
         continue;
       }
-      Object.assign(env, parseEnvFile(text));
+      Object.assign(fromFiles, parseEnvFile(text));
     }
   }
-  return { env, missing };
+  return { env: { ...env, ...fromFiles }, missing };
 }
 
 /**
@@ -143,7 +170,7 @@ export function unitEnvironment({ units = [], readEnvFile = () => null, home = n
     // name we did not find might live in it — and reporting those as absent would be the original bug
     // with a smaller blast radius. The whole picture is refused instead.
     return { known: false, env, read,
-      why: `the units require environment file(s) this command could not read: ${[...new Set(holes)].join(", ")}` };
+      why: `the units require environment file(s) or values this command could not read: ${[...new Set(holes)].join(", ")}` };
   }
   return { known: true, env, read, why: null };
 }

package/driver/unit-inventory.mjs

@@ -73,7 +73,24 @@
 // it for current state.)
 
 /** Where a unit is expected to be installed. "none" is a claim, not an absence — see ORPHANED below. */
-export const BOXES = Object.freeze(["prod", "test", "dev"]);
+export const BOXES = Object.freeze(["prod", "preprod", "test", "dev"]);
+
+/**
+ * Whose DECLARED units a box is expected to carry, where that is not its own name.
+ *
+ * `runsOn` is a MEASURED claim — this file says so in as many words: an entry gains a box the day an
+ * enumeration of that box shows the unit, never the day somebody intends it. So pre-prod cannot be
+ * written into `runsOn` from a machine that has not enumerated pre-prod, and it must not be: that would
+ * turn a measurement into a plan, which is the one thing these entries are not.
+ *
+ * What CAN be stated from here is the expectation. Pre-prod is a packaged install of the same product on
+ * its own account, with the same doors and the same worker, so what it is expected to carry is what
+ * production is expected to carry. The expectation derives; the measurement stays measured; and a unit
+ * genuinely absent on pre-prod is reported rather than skipped, which is the whole point of the box
+ * being able to name itself.
+ */
+const EXPECTS_LIKE = Object.freeze({ preprod: "prod" });
+const expectationBox = (box) => EXPECTS_LIKE[box] ?? box;
 
 // ── RESOLVED UNITS (ruling 2026-08-25 — option B) ──────────────────────
 //
@@ -773,7 +790,7 @@ export function unitInventoryVerdict({
   // unit that is gone from a box is the ruling taking effect, not drift; reporting it as a fault trains
   // a reader to skim the arm that would have caught a real one. Both are still REPORTED — the
   // distinction is which of them is a fault.
-  const declaredHere = (u) => box && u.runsOn.includes(box) && !liveBases.includes(u.unit);
+  const declaredHere = (u) => box && u.runsOn.includes(expectationBox(box)) && !liveBases.includes(u.unit);
   const absent = box
     ? inventory.filter((u) => declaredHere(u) && !u.retired).map((u) => u.unit).sort()
     : [];

package/driver/verify.mjs

@@ -13,7 +13,8 @@ import { driverDir } from "../shared/driver-dir.mjs";   //
 import { findReceiptViolations, findGridLedgerViolations, findPlatformIdentityViolations, parsePrRiskQueries, MEANING_SEAT, erroredConnotationQueriesAmong } from "./common-law-receipts.mjs";
 // Conversion 2 — the discriminator the two rulings above key on. PURE-ish: one existsSync-shaped read.
 import { matterFrameWasRecorded, frameRatifiedForms } from "./matter-frame-record.mjs";
-import { findConnotationViolations, parsePrRiskResults, MEANING_ANGLES_RE,
+import { findConnotationViolations, parsePrRiskResults, prRiskPopulation,
+  CONNOTATION_UNMATCHED_MARK, CONNOTATION_NO_RESEMBLANCE_MARK, MEANING_ANGLES_RE,
   parseDispositionForm, CONNOTATION_UNRULED_REASONS, queryKey } from "./connotation-search.mjs";
 import { formSidecarName, formSidecarPath } from "./disposition-union.mjs";
 // B — the transport's own four failure states. The audit reads the run's records; this file locates them.
@@ -41,6 +42,7 @@ import { parseNamedBand, findCollapsedBands } from "./named-band.mjs";
 import { parseBlindFrameModel } from "./blind-frame-model.mjs";
 import { parseFrameDiff } from "./frame-diff-model.mjs";
 import { parseVariantManifestModel, variantRomanizationGaps, variantCompletenessGaps, variantTermShapeGaps } from "./variant-manifest-model.mjs";
+import { digestAccountingGap } from "./register-digest-record.mjs";
 
 // ── WS-B: the run-scoped profile sidecar ────────────────────────────────────────────────────────────
 // _driver/profile.json carries the run's frozen customer values (floor, platform list) for these
@@ -365,6 +367,13 @@ function commonLawMeaningSeat(p, c) {
   let recordedRaw;
   try { recordedRaw = parsePrRiskResults(ledgerRaw).map((e) => String(e?.query ?? "")); }
   catch (e) { return fail(`grid_ledger_unparseable:${String(e.message).slice(0, 80)}`); }
+  // THE REFUSAL NAMES THE FILE IT JOINED AGAINST, because "recorded" is not one question in a run.
+  // A run answers "what did this half record" in four places that each mean something different — this
+  // results ledger, its gap rows, the obligations sidecar, and the final-state receipts audit — and a
+  // sentence that says only "recorded" invites a reader to answer from whichever they happen to open.
+  // Two readers did exactly that on one clearance and reached three different wrong mechanisms, each
+  // from a true measurement of a real record.
+  const LEDGER = `common-law-grid.half-${MEANING_SEAT}.json`;
   const recordedQ = new Set(recordedRaw.map(queryKey));
   const dropped = dictated.filter((q) => !recordedQ.has(queryKey(q)));
   if (dropped.length) {
@@ -435,17 +444,27 @@ function commonLawMeaningSeat(p, c) {
       .flatMap((b) => (Array.isArray(b?.gaps) ? b.gaps : []));
     const reportedError = new Map(
       erroredConnotationQueriesAmong(dropped, { gaps: gapRows }).map((e) => [e.query, e.error]));
+    // AND IT SAYS WHEN THE READER REDUCED WHAT IT READ. `parsePrRiskResults` folds rows onto the raw
+    // query text, so its output is smaller than the ledger whenever a query was recorded twice. Every
+    // count taken during one evening's diagnosis was post-fold and nobody had named the raw population,
+    // which made "the seat wrote 59 rows" and "59 survived the fold" the same number and different
+    // facts: one query recorded twice while another was skipped reads exactly like one simply skipped.
+    const pop = prRiskPopulation(ledgerRaw);
+    const foldNote = pop.repeated > 0
+      ? ` (${LEDGER} carries ${pop.rows} row(s) that fold to ${pop.distinct} distinct query(ies): `
+        + `${pop.repeated} repeat a query already counted, so a repeat here may stand where a dictated query is missing)`
+      : "";
     const parts = dropped.slice(0, 3).map((q) => {
       const reported = reportedError.get(q);
       // Named separately because the remedy is different: the search was attempted and the provider
       // declined it, so re-running it unchanged is the one repair that cannot work.
-      if (reported) return `${abbrev(q, 40)} [the provider REPORTED an error on this query: ${abbrev(reported, 60)}]`;
+      if (reported) return `${abbrev(q, 40)} [not recorded in ${LEDGER} because the provider REPORTED an error on it: ${abbrev(reported, 60)}]`;
       const n = nearest(q);
       return n
-        ? `${abbrev(q, 40)} [unmatched; nearest recorded: ${abbrev(n, 40)}]`
-        : `${abbrev(q, 40)} [no recorded query resembles this one]`;
+        ? `${abbrev(q, 40)} ${CONNOTATION_UNMATCHED_MARK} ${abbrev(n, 40)}] in ${LEDGER} — that is evidence a query LIKE it was recorded there, not that these two are the same query`
+        : `${abbrev(q, 40)} ${CONNOTATION_NO_RESEMBLANCE_MARK} in ${LEDGER}, which is the only file this gate joins against`;
     });
-    return fail(`connotation_query_unrecorded:${parts.join(",")}${dropped.length > 3 ? ` (+${dropped.length - 3} more)` : ""}`);
+    return fail(`connotation_query_unrecorded:${parts.join(",")}${dropped.length > 3 ? ` (+${dropped.length - 3} more)` : ""}${foldNote}`);
   }
   if (spec?.connotation?.disposition_required === true) {
     const recorded = parsePrRiskResults(ledgerRaw);
@@ -2069,6 +2088,32 @@ export const validators = {
         ], "findings+ledger"),
         hasCoverageLedgerRow(c) ? ok() : fail("no_coverage_status_row"));
     if (!structural.ok) return structural;
+    // ── EVERY RECORD THE RUN CARRIED IN ENDS SOMEWHERE — CHECKED AT THE EXIT, NOT ONLY AT THE CALL ──
+    //
+    // The call-time refusal is scoped to the batch it judges, which is what lets a dense band be
+    // recorded at all: a 1,161-record band does not fit in one turn, and the stage failed on one for 35
+    // minutes without writing a document. It buys that at a price, and this is where the price is paid.
+    // Once batch 1 is accepted the findings document EXISTS, so a seat that stopped after batch 6 no
+    // longer fails as a missing artifact — it ships a document holding half the band, with every call it
+    // made reading as accepted. Nothing else would notice: this stage's other arms read the document's
+    // shape, and half a band is the same shape as a whole one.
+    //
+    // ARMED BY THE SAME ERA STAMP as the call-time rule, so an archived run carries no stamp and replays
+    // to the verdict it always had. A STAMPED run whose transport stored no model is a driver fault and
+    // is named as one, on `coverage_form_missing`'s precedent below and for its reason: an absent
+    // artifact must never read as a satisfied one. A throw fails closed for the same reason — this gate
+    // going quiet is indistinguishable from a complete digest, which is the state it exists to refuse.
+    {
+      let gap;
+      try { gap = digestAccountingGap(dirname(p)); }
+      catch (e) { return fail(`registerdigest_accounting_unreadable:${short(String(e?.message ?? e))} (driver-written — this is a bug, not a model defect)`.slice(0, 200)); }
+      if (gap.armed && gap.unaccounted === null)
+        return fail("registerdigest_accounting_unreadable: stamped for per-record accounting with no owed list in the driver's facts (driver-written — this is a bug, not a model defect)");
+      if (gap.armed && gap.no_model)
+        return fail("registerdigest_model_missing: stamped for per-record accounting and the typed transport stored no model, while the findings document exists (driver-written — this is a bug, not a model defect)");
+      if (gap.armed && gap.unaccounted.length)
+        return fail(`registerdigest_unaccounted_records:${gap.unaccounted.length} of ${gap.owed.length} — ${gap.unaccounted.slice(0, 6).join(",")}${gap.unaccounted.length > 6 ? ` (+${gap.unaccounted.length - 6} more)` : ""}`.slice(0, 200));
+    }
     // ── THE COVERAGE FORM, AND THE FOUR STATES THAT ARE NOT THE SAME FACT ──────────────────────────
     //   not required        — no era stamp: EVERY ARCHIVED RUN, and nothing else since  M6. A run
     //                         whose plan apparatus is out of reach used to land here too; it now gets a

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # trademark-artifacts-mcp
 
+## 0.3.2-beta.8
+
+No changes in this release.
+
+## 0.3.2-beta.7
+
+No changes in this release.
+
 ## 0.3.2-beta.6
 
 No changes in this release.

package/mcp-server/http-server.mjs

@@ -362,6 +362,10 @@ if (isMain) {
       // read inside it, so the factory keeps one rule and the caller names which door it is.
       createSession: (sessions, scope, owner) => createSession(sessions, scope, owner, { networkDoor: false }),
       authHeader: AUTH_HEADER, firmDomains: ALLOWED_DOMAINS, log,
+      // THE THIRD DOOR, and it has to name itself. It is not the staff surface and it is not the network
+      // client surface; a key presented here arrives over a local socket. Until this was passed, every
+      // audit line this door wrote carried no door at all and read as the staff surface by elimination.
+      door: "key",
     });
     openKeyDoor({ handler: keyHandler, path: KEY_SOCKET, log })
       .catch((e) => { log(`FATAL: could not open the key socket at ${KEY_SOCKET} — ${e.message}`); process.exit(1); });

package/mcp-server/lib/audit.mjs

@@ -40,6 +40,16 @@ export function summarize(body) {
   return out;
 }
 
+/**
+ * The value written when a caller names no door. A door-less line USED TO BE POSSIBLE and one writer
+ * produced them: the key door built its handler without saying which surface it was, so every line it
+ * wrote omitted the field while the lines either side of it carried it. Absence then read as the staff
+ * surface, because that was the only other thing it could have been, so the trail quietly attributed a
+ * client's calls to staff. The field is now always written and an unnamed door is loud rather than
+ * missing — a reader can search for this value, which is not true of a key that is not there.
+ */
+export const UNNAMED_DOOR = "unnamed";
+
 export function appendAudit({ email, sub, body, status, transport, door, path = DEFAULT_AUDIT_PATH }) {
   // `sub` = the inner-token PRINCIPAL (ops-token issuance, INSTALL.md §8) — distinguishes
   // two automations sharing a transport identity. null for internal/user sessions without a sub claim.
@@ -59,7 +69,7 @@ export function appendAudit({ email, sub, body, status, transport, door, path =
   // WRITTEN ONLY WHEN GIVEN, the same rule as `transport` and for the same reason: the existing log
   // shape must not move for records that have no answer to this. A door that does not name itself is a
   // record with no `door` key, not a record claiming to be from nowhere.
-  const line = JSON.stringify({ ts: new Date().toISOString(), email: email ?? null, sub: sub ?? null, ...summarize(body), status: status ?? null, ...(transport ? { transport } : {}), ...(door ? { door } : {}) }) + "\n";
+  const line = JSON.stringify({ ts: new Date().toISOString(), email: email ?? null, sub: sub ?? null, ...summarize(body), status: status ?? null, ...(transport ? { transport } : {}), door: door || UNNAMED_DOOR }) + "\n";
   try { mkdirSync(dirname(path), { recursive: true }); appendFileSync(path, line); } catch { /* best-effort */ }
 }