clearotron 0.2.1 → 0.2.3

package/driver/unit-state-verdict.mjs

@@ -14,9 +14,9 @@
 //
 // Anything that is neither `active` nor `inactive` is a fault. `prelim-driver` is a `Type=oneshot` fired
 // by a 90-second timer, so EVERY drain passes through `activating` — and `activating` landed in that
-// list. The filter tolerated the oneshot at rest and failed it for working. deploy-test.sh gates the
-// hourly test-instance deploy on this script's exit code, so a deploy that happened to land inside a
-// drain window reported the instance unhealthy and exited 1 on a deployment that was fine.
+// list. The filter tolerated the oneshot at rest and failed it for working. The hourly test-instance
+// deploy gates on this script's exit code, so a deploy that happened to land inside a drain window
+// reported the instance unhealthy and exited 1 on a deployment that was fine.
 //
 // The bug is not the enumeration — was right to give this three outcomes instead of two. The bug is
 // INVERSE ENUMERATION over an incomplete vocabulary: listing the two states you have seen and calling
@@ -39,7 +39,7 @@
 // The ruling on says "starting and stopping are both tolerated for a one-shot". That is descriptive
 // of the case that was observed, not a restriction: the issue's own Scope section carries no unit-type
 // qualifier, the arm has never been unit-type-aware, and it already tolerates `inactive` for everything.
-// It is also the wrong place to draw the line — deploy-test.sh RESTARTS the long-running services
+// It is also the wrong place to draw the line — the hourly deploy RESTARTS the long-running services
 // immediately before running this check, so `trademark-portal=activating` is the same race with a
 // different unit, and a oneshot-only fix would leave it standing. The unit's Type is still carried into
 // the message so a reader can tell a oneshot mid-fire from a service mid-restart.
@@ -56,16 +56,16 @@
 //
 // ── what this module deliberately does NOT touch: the zero-check ────────────────────────────────
 //
-// 's Scope is one paragraph and it names one thing — the state vocabulary. So the FAULT branch is
-// the only branch whose behaviour changes. 's separate guard, "0 active is not a pass", keeps
+// That Scope is one paragraph and it names one thing — the state vocabulary. So the FAULT branch is
+// the only branch whose behaviour changes. That separate guard, "0 active is not a pass", keeps
 // origin/main's predicate (`ActiveState === "active"`, literally) and origin/main's message.
 //
 // This is not caution for its own sake. An earlier draft of this fix also widened the count to treat
 // transitional units as up, on the reasoning that a oneshot mid-fire is "not nothing". The consequence:
 // {5 services activating, 3 inactive} returned `pass` with a message that began "0 active" — a green
-// tick on the deploy's final gate having confirmed that ZERO services were running. deploy-test.sh
+// tick on the deploy's final gate having confirmed that ZERO services were running. The hourly deploy
 // restarts the long-running services immediately before running this check, so that is the ordinary
-// shape of the box, not a corner. Widening a count to make a message read better is how a guard dies.
+// shape of the instance, not a corner. Widening a count to make a message read better is how a guard dies.
 
 /** The six documented ActiveState values of systemd 255, mapped to what the check must do about them. */
 export const ACTIVE_STATE_MEANING = Object.freeze({
@@ -134,19 +134,27 @@ export function unitsActiveVerdict({ units, probe }) {
   // CHANGES NOTHING HERE. The count below is origin/main's, predicate and message unchanged:
   // `active`, literally, and nothing else. An earlier draft of this fix widened it to count
   // transitional units as up, which defeated this guard outright — {5 activating, 3 inactive} then
-  // returned `pass` with a message that began "0 active", on the deploy's FINAL gate, on a box where
-  // deploy-test.sh has just restarted every long-running service. 's Scope names one thing, the
+  // returned `pass` with a message that began "0 active", on the deploy's FINAL gate, on an instance
+  // where the hourly deploy has just restarted every long-running service. Scope names one thing, the
   // state vocabulary of the FAULT branch above. Transitional units are named in the messages here so
   // they are never swallowed; they are counted as up nowhere.
+  // A unit this inventory declares can be absent from THIS box for a legitimate reason: the inventory
+  // spans prod and test, so on the test box every prod-only entry reports `LoadState=not-found`. So the
+  // count is INFORMATION in the message and never a verdict of its own — a warn here would fire on every
+  // run of the test box and be ignored by the second week. The finding that matters is the mirror of it
+  // and lives in unitInventoryVerdict: a unit RUNNING here whose entry claims it runs on no box.
+  const absentHere = (units ?? []).filter((u) => u.load === "not-found").length;
+  const notHere = absentHere ? `; ${absentHere} declared unit(s) do not exist on this box` : "";
+
   const activeCount = (units ?? []).filter((u) => u.active === "active").length;
   const alsoSeen = (by.transitional.length ? `; ${by.transitional.length} starting or stopping — ${by.transitional.map(label).join(", ")}` : "")
     + (by["at-rest"].length ? `; ${by["at-rest"].length} at rest` : "");
 
   if (activeCount === 0)
     return { state: "skip", message: "systemd --user answered and reported 0 active units — nothing was probed, "
-      + `which is not the same as nothing being wrong${alsoSeen}` };
+      + `which is not the same as nothing being wrong${alsoSeen}${notHere}` };
 
-  return { state: "pass", message: `${activeCount} active`
+  return { state: "pass", message: `${activeCount} active${notHere}`
     + (by.transitional.length ? `; ${by.transitional.length} starting or stopping — ${by.transitional.map(label).join(", ")}, which is a unit doing its job, not a fault` : "")
     + (by["at-rest"].length ? `; ${by["at-rest"].length} at rest` : "") };
 }

package/driver/verify-knockout.mjs

@@ -442,7 +442,7 @@ export const validators = {
       // — the register reads and the per-finding weighed lists, both joined to the store.
       if (m.registerReads !== undefined && m.registerReads !== null) {
         if (!Array.isArray(m.registerReads))
-          return { ok: false, reason: `mark "${m.name}": registerReads must be an ARRAY of { recordId, read } rows, or omitted entirely` };
+          return { ok: false, reason: `mark "${m.name}": registerReads must be an ARRAY of { recordId, read, band? } rows, or omitted entirely` };
         const held = registerRecordIdsFor(runDir, m.name);
         for (const row of m.registerReads) {
           const id = String(row?.recordId ?? "").trim();
@@ -451,6 +451,14 @@ export const validators = {
           if (!read) return { ok: false, reason: `mark "${m.name}": registerReads row "${id}" has an empty read. Omit the row rather than sending an empty one: a filing with no read keeps the card's neutral line, which is true` };
           if (!held.has(id))
             return { ok: false, reason: `mark "${m.name}": registerReads cites "${id}", which is not a record this run holds for that mark. The id must be copied from the filings you were handed — the driver joins it against the store and never takes your word for it` };
+          // The band is OPTIONAL and, when present, is the same closed vocabulary the mark's own rating
+          // uses — the card prints it as this filing's rating, so a word outside the frozen ladder would
+          // put a chip on the page in a dialect the framework does not define. Absence stays free: a read
+          // with no band prints the read and no chip, which is what every run before this one produced.
+          if (row?.band != null && String(row.band).trim()) {
+            if (ladder.length && bandIdx(ladder, row.band) < 0)
+              return { ok: false, reason: `knockout_band_unknown:${m.name}: registerReads row "${id}" carries band "${row.band}", which is not in the frozen ladder (${ladder.join(" / ")}) — rate the filing in the framework's own vocabulary, or omit the band and let the read stand alone` };
+          }
         }
       }
       for (const f of (Array.isArray(m.findings) ? m.findings : [])) {
@@ -490,7 +498,7 @@ export const validators = {
       // THE TYPED RECORD. findings-model.mjs owns the shape; this is where it becomes a GATE.
       // Unconditional — no shape sniffing: this validator only ever reads a chunk THIS run's assess turn
       // just wrote, so a "looks like the old shape, validate it loosely" arm could only ever be a way to
-      // skip the check. A resumed run holding a pre- chunk file fails here and re-asks the turn
+      // skip the check. A resumed run holding a pre-change chunk file fails here and re-asks the turn
       // (pipeline-knockout.mjs koStage logs stage-stale and re-runs), which is the correct outcome: the
       // report renders `net`/`basis`/`evidence[]` and a prose row cannot fill them.
       //

package/driver/verify.mjs

@@ -61,7 +61,7 @@ function readRunProfile(p) {
 
 // ── doc 50: the run-scoped FROZEN framework manifest ────────────────────────────────────────────────
 // _driver/framework.json is the framework-in-force's manifest, frozen beside profile.json at
-// attachProfile time — the band vocabulary every v4 gate joins against (zephyr "Medium" vs house
+// attachProfile time — the band vocabulary every v4 gate joins against (a customer ladder's "Medium" vs house
 // "Moderate" stays consistent within a run and across resume). Same walk-up + fail-closed convention as
 // readRunProfile: absent ⇒ null (archived/legacy runs); unreadable ⇒ invalid (driver-written, so a
 // corrupt one is a bug that must surface, never a silent downgrade to the wrong vocabulary).
@@ -146,7 +146,7 @@ function nonEmpty(content, min = MIN) {
  * The obvious fix — emit the failing marker INSTEAD of the label — silently breaks the corrective hints.
  * `correctionHint` branches on the label text (`gateway.mjs:2181` on `findings+ledger`, `:2188` on
  * `negative-results|coverage-ledger|audit-trail|findings-heading`), so a renamed token would fall through
- * to a generic hint. 's comment records that arm being removed once already on a reading that was
+ * to a generic hint. That comment records that arm being removed once already on a reading that was
  * true for only one lane, and put back. Appending keeps every existing matcher matching — they all test
  * substrings — and gives the seat the one word it was missing.
  *
@@ -289,7 +289,7 @@ const COMMONLAW_UNAVAILABLE_RE = /(perplexity|marketplace research|common.?law (
 // Deliberately NOT done: loosening the honesty vocabulary. The prose is correct and stays.
 //
 // Driver-bug tokens are never masked. `half_path_unrecognized` says the DRIVER called this validator
-// with a path it does not own; "write NO findings file" is the wrong remedy for that, and pre- the
+// with a path it does not own; "write NO findings file" is the wrong remedy for that, and pre-change the
 // path guard returned before the regex was ever reached. Keep it that way.
 const VETO_NEVER_MASKS = new Set(["half_path_unrecognized"]);
 
@@ -651,7 +651,7 @@ export function parseVerdict(content) {
  * `UPSTREAM_STALE_REPAIR["narrative-refutation"]` re-runs the reviewer at DELIVERY time, long after the
  * verdict gate. Its caller re-reads what the repaired stage wrote — findings.json, the case-law layer —
  * but not `senior-eye-review.md`, which is the one artifact that stage authors. So the reviewer could
- * refuse to sign at 00:52 and the run would deliver on the verdict it settled at 00:22 (,
+ * refuse to sign at 00:52 and the run would deliver on the verdict it settled at 00:22 (
  * `bf21580e`, 2026-08-23: a registration date contradicting the fetched record reached the client).
  *
  * ONE DIRECTION ONLY, and that is deliberate. This returns the file's verdict when it is STRICTER than
@@ -683,7 +683,7 @@ export function verdictHardenedTo(carried, reviewMd) {
 // The two guards must not share a POLICY and they still do not: what separates them is which sections
 // they read, and whether a bullet under a flag is that flag's body. Whether a line is a list item at
 // all is NOT policy — and while each walk carried its own copy of that answer, the copies drifted.
-// taught one of them to see `**1.` and left the other on the pre- pattern, so the walk whose
+// taught one of them to see `**1.` and left the other on the pre-change pattern, so the walk whose
 // job is to decide whether to DISCARD a review quietly became the stricter of the two.
 //
 // Restating the marker in a second place is what made that possible, so it is stated once here. Both
@@ -692,7 +692,7 @@ export function verdictHardenedTo(carried, reviewMd) {
 // The trailing `\*{0,2}` is the bold CLOSER: reviewers write both `**1. [kind: …]** text` (bold around
 // the marker and its tokens) and `**1.** text` (bold around the marker alone). The second counted ZERO
 // on both walks — consistently, so it is not the asymmetry above, but it is the same defect wearing a
-// different style, and 's criterion says a bold-numbered flag must count. It cannot swallow prose:
+// different style, and the criterion says a bold-numbered flag must count. It cannot swallow prose:
 // a single letter or digit must still be followed by its own `.` or `)`, so `**Note.** …` matches nothing.
 const LIST_MARKER = String.raw`(?:\*{0,2})(?:[-*•]|\d+[.)]|[A-Za-z][.)])(?:\*{0,2})\s+`;
 const LIST_LINE_RE = new RegExp(`^${LIST_MARKER}\\S`);
@@ -819,7 +819,7 @@ function parseOn(line) {
 // deferrals`, `Headline, re-derived independently`, `Grounded profiles` and the plan audit.
 //
 // THE HEADLESS FALLBACK IS DELIBERATE AND IT IS NOT A DENYLIST IN DISGUISE. A review with NO corrections
-// heading anywhere still has corrections — 's fixture is exactly that, and 's writes them under
+// heading anywhere still has corrections — the fixture is exactly that, and the writes them under
 // `## Corrections`. So: if the document names a corrections section, ONLY that section is read; if it
 // names none, the whole document is read as before. The fallback cannot reopen this defect, because it
 // only applies to documents that have no section structure to get wrong.
@@ -840,7 +840,7 @@ export const NOT_A_CORRECTIONS_SECTION_RE =
 //
 // THE FAILURE IS SILENT IN THE WORST DIRECTION. An unreadable flag does not error — it is simply not
 // there, and every downstream count agrees with itself about a document it never read. Both directions
-// of 's lesson apply at the LINE level too: too permissive publishes noise as grounds, too strict
+// of the lesson apply at the LINE level too: too permissive publishes noise as grounds, too strict
 // drops the grounds entirely.
 //
 // SCOPE OF THE WIDENING, MEASURED RATHER THAN ASSUMED. Across the 28 distinct reviews on both scratch
@@ -874,7 +874,7 @@ export const opensWithKind = (content) => /^\[kind:/i.test(String(content ?? "")
  * matched and the whole document was skipped". The allowlist fails closed on purpose, and a guard that
  * fails closed silently is how a real defect reads as a clean run.
  *
- * `named: false` is not a fault — it is the headless document 's fixture is built from, and the walk
+ * `named: false` is not a fault — it is the headless document the fixture is built from, and the walk
  * falls back to the whole document. It is reported so a caller can tell the two apart.
  *
  * PURE.
@@ -918,7 +918,7 @@ export function parseCorrections(reviewMd) {
     // underneath as `- "…"` bullets. Those are evidence FOR a correction, not five more corrections,
     // and counting them is how five quoted excerpts became five of the published grounds of a BLOCKING
     // verdict. A review that writes its flags as BULLETS never trips this — no numbered flag is ever
-    // seen, so every bullet stays a flag, which is 's contract and 's fail-safe both intact.
+    // seen, so every bullet stays a flag, which is the contract and the fail-safe both intact.
     // ORDER MATTERS: ask "is this enumerated" FIRST. `**2. [kind: …]` begins with an asterisk, so a
     // bullet test run before the enumerated test swallows every flag after the first as the first
     // one's body.
@@ -1023,7 +1023,7 @@ export function findReviewerCoherenceFlags(md) {
 // divergent arms of one requirement. They are three different contracts:
 //   · commonLawStructural (LIVE) — the common-law findings' prose Coverage ledger still carries these
 //     tokens, and this floor still polices it.
-//   · registerFindings' UNSTAMPED arm (ARCHIVE-ONLY since  M6) — judges pre- archived replays
+//   · registerFindings' UNSTAMPED arm (ARCHIVE-ONLY since  M6) — judges pre-change archived replays
 //     whose seats hand-wrote the prose table. No live run reaches it; replay verdicts get quoted, so
 //     it stays.
 //   · register-digest's LIVE path carries the same three tokens as VALUES through the
@@ -1957,7 +1957,7 @@ export const validators = {
     // So the old floor and the new gate are armed by the SAME condition, and it is this one:
     //   stamped   ⇒ the driver wrote a form, the seat was told not to write a table, and the form is the
     //               whole coverage judgement (below).
-    //   unstamped ⇒ every pre- check applies unchanged, and stages.mjs — reading THIS SAME STAMP —
+    //   unstamped ⇒ every pre-change check applies unchanged, and stages.mjs — reading THIS SAME STAMP —
     //               tells the seat to write the prose table. The two cannot disagree about which
     //               document the run owes.
     //
@@ -1967,7 +1967,7 @@ export const validators = {
     // digest and before it — so NO LIVE RUN reaches here unstamped, and stages.mjs no longer has a
     // second arm to tell a seat to write the prose table. The prose floor below, and the prose-era
     // joins it feeds (findUnaccountedDeferredSlices, findUnverifiedIncompleteCleanClaims), are
-    // therefore DEAD FOR LIVE RUNS and LOAD-BEARING FOR REPLAY: an archived pre- run carries no
+    // therefore DEAD FOR LIVE RUNS and LOAD-BEARING FOR REPLAY: an archived pre-change run carries no
     // stamp at all, and its coverage verdict is judged by exactly this arm.
     //
     // DO NOT DELETE THEM AS DEAD CODE. Removing them does not change any live run's answer; it changes

package/driver/whatif-memo-run.mjs

@@ -31,7 +31,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { driverDir } from "../shared/driver-dir.mjs";
+import { driverDir, DRIVER_DIR } from "../shared/driver-dir.mjs";   // the subtree name from its one definition, never a literal
 import { composeMemo } from "./whatif-memo.mjs";
 
 export const SKILL_ROOT = join(dirname(fileURLToPath(import.meta.url)), "skills");
@@ -85,6 +85,43 @@ export function movedArtifacts(before = {}, after = {}) {
     .map((p) => ({ path: p, before: before[p] ?? null, after: after[p] ?? null }));
 }
 
+/**
+ * Split what moved into the memo's OWN RECORD and everything else.
+ *
+ * A memo legitimately leaves two kinds of trace on its parent. Its documents go under `_memos/`, which
+ * `digestRunDir` already skips. Its DISPATCH leaves driver telemetry — `_driver/whatif-memo.*` and an
+ * appended line in `_driver/run.jsonl` — because the memo rides the same gateway ladder as any seat and
+ * the gateway records what it dispatched. That is the parent gaining a RECORD of the memo, which is
+ * correct behaviour and the same rule the experiment path already lives by; it is not the archive being
+ * rewritten.
+ *
+ * ✕ EVERYTHING ELSE IS THE SEAT WRITING WHERE IT WAS NOT INVITED, and it is refused by name. The seat
+ * has a real file-write grant on the run directory, and on a delivered run it used it: an archived
+ * client run carries `memo-osler-coexistence.json` at its root, which is the seat's reply written to a
+ * path of its own choosing instead of to the `expectFile` it was given. That also explains the retry
+ * that preceded it — the harness looked for the reply where it had asked for it and did not find it.
+ *
+ * `run.jsonl` may only GROW. A shrink or a rewrite is not an append, and an append is the only thing a
+ * dispatch does to it. The check is on size because the digest carries `sha:size` and not the bytes; a
+ * rewrite that happened to keep the same length would pass, and that is written down rather than
+ * claimed against. PURE.
+ */
+export function splitMemoFootprint(moved = []) {
+  const own = [];
+  const foreign = [];
+  const sizeOf = (v) => { const n = Number(String(v ?? "").split(":")[1]); return Number.isFinite(n) ? n : null; };
+  for (const m of moved) {
+    const p = String(m?.path ?? "");
+    if (p.startsWith(`${DRIVER_DIR}/whatif-memo.`)) { own.push(m); continue; }
+    if (p === `${DRIVER_DIR}/run.jsonl`) {
+      const b = sizeOf(m.before); const a = sizeOf(m.after);
+      if (b !== null && a !== null && a > b) { own.push(m); continue; }
+    }
+    foreign.push(m);
+  }
+  return { own, foreign };
+}
+
 /** The profile key the PARENT rated under — read from its frozen sidecar, never re-resolved. */
 export function parentRatedUnder(runDir, { read = readFileSync } = {}) {
   try { return JSON.parse(read(driverDir(runDir, "profile.json"), "utf8"))?.profileKey ?? null; }
@@ -120,7 +157,7 @@ export async function seatReason({ runDir, runId, assumption, ratedUnder, findin
   const replyPath = join(runDir, MEMO_DIR, `reply-${sha(`${runId}${assumption}`).slice(0, 10)}.json`);
   mkdirSync(join(runDir, MEMO_DIR), { recursive: true });
   const r = await dispatch("whatif-memo", {
-    message: composeMemoMessage({ assumption, findings, ratedUnder, skill }),
+    message: composeMemoMessage({ assumption, findings, ratedUnder, skill, replyPath }),
     model,
     // A BOUNDED READING, and the ceiling says so. This re-reads evidence already gathered; a memo that
     // needed the clearance's own ceiling would not be the cheap thing the plan promised the reader.
@@ -141,7 +178,7 @@ export async function seatReason({ runDir, runId, assumption, ratedUnder, findin
 
 /**
  * Validate the seat's reply. TYPED, not parsed prose — the reply is a JSON object the skill dictates,
- * so a phrasing choice can never fail it. That is deliberate and it is tracker issue 129's lesson applied
+ * so a phrasing choice can never fail it. That is deliberate and the lesson is applied
  * before the fact: a gate keyed on how a model worded something is one drift from killing the call.
  *
  * Returns { ok, reading } or { ok: false, fail, detail }. Refuses rather than repairing: a memo composed
@@ -193,7 +230,12 @@ export function validateMemoReply(raw) {
  * The findings are handed over as the run's own JSON rather than summarised: a memo that reasoned over
  * our paraphrase of the evidence would be answering about the paraphrase.
  */
-export function composeMemoMessage({ assumption, findings, ratedUnder = null, skill = "" } = {}) {
+// `ratedUnder` DEFAULTS HERE AND IS REFUSED BY `composeMemo`, and that asymmetry is only safe while the
+// artifact is the gate. One resolution is threaded to both, and nothing reaches disk without the memo
+// composing — so a forgotten field is caught there. It stops being safe the moment a dispatch path calls
+// this composer alone: the seat would be instructed "house default" with no artifact refusal behind it,
+// because no artifact would be composed. A caller that dispatches without composing owes its own check.
+export function composeMemoMessage({ assumption, findings, ratedUnder = null, skill = "", replyPath = null } = {}) {
   return [
     skill.trim(),
     "",
@@ -213,8 +255,21 @@ export function composeMemoMessage({ assumption, findings, ratedUnder = null, sk
     JSON.stringify(findings ?? null, null, 2),
     "```",
     "",
-    "Write the JSON object the skill dictates, and nothing else.",
-  ].join("\n");
+    // NAME THE FILE, IN THE FIRST MESSAGE. The skill says what to write and the harness was told where
+    // to look, and until this line nothing told the SEAT where to put it. A seat given a write grant and
+    // no destination writes somewhere reasonable of its own choosing — an archived run carries one such
+    // reply at its run root — and the harness then looks where it asked, does not find it, and fails the
+    // attempt on `missing_file`. The warm patch names the path, which is the whole reason the retry
+    // succeeded: the second attempt was the first one that said where.
+    //
+    // The cost of not saying it was never the failure. It was that every memo billed two dispatches for
+    // one document and left a retried stage on the parent run's ledger — an INVESTIGATE line on a report
+    // that had already been delivered clean.
+    replyPath
+      ? `Write it to this ABSOLUTE path (create parent dirs if needed): ${replyPath}`
+      : "Write the JSON object the skill dictates, and nothing else.",
+    replyPath ? "Write the JSON object the skill dictates, and nothing else." : null,
+  ].filter((l) => l !== null).join("\n");
 }
 
 /**
@@ -282,6 +337,10 @@ export async function askArchivedRun({ runId, question, requestedBy = null } = {
     body: String(reading?.body ?? ""),
     limits: Array.isArray(reading?.limits) ? reading.limits : [],
     mark: run.markName ?? null,
+    // The authority the seat was instructed to assess under, carried to the artifact rather than ending
+    // at the return value. `parentRatedUnder` answers null for a run that froze no profile, which is a
+    // fact the memo states rather than omits.
+    ratedUnder,
   });
   if (!composed.ok)
     return { ok: false, fail: MEMO_FAILS.COMPOSE_REFUSED, detail: composed.reason, missing: composed.missing };
@@ -299,10 +358,14 @@ export async function askArchivedRun({ runId, question, requestedBy = null } = {
 
   // AFTER the write, deliberately: the check has to cover this call's own behaviour, not merely the
   // reasoning pass's. If writing the memo touched the parent, that is exactly what must be caught.
-  const moved = movedArtifacts(before, digestRunDir(run.runDir));
-  if (moved.length)
+  const { own, foreign } = splitMemoFootprint(movedArtifacts(before, digestRunDir(run.runDir)));
+  if (foreign.length)
     return { ok: false, fail: MEMO_FAILS.PARENT_MOVED,
-      detail: `the parent run's artifacts moved during the memo: ${moved.slice(0, 5).map((m) => m.path).join(", ")}`, moved };
+      // NAMES WHAT IT FOUND AND WHY IT IS WRONG. "the parent's artifacts moved" was true of a correct
+      // memo too — the dispatch telemetry tripped it — so the sentence could not tell a reader whether
+      // the archive had been rewritten or the memo had merely run.
+      detail: `a memo may write only to ${MEMO_DIR}/ and its own reply file; these were written into the parent run instead: ${foreign.slice(0, 5).map((m) => m.path).join(", ")}`,
+      moved: foreign, memoFootprint: own };
 
   return {
     ok: true,

package/driver/whatif-memo.mjs

@@ -43,10 +43,25 @@ export const REQUIRED = Object.freeze(["assumption", "parentRunId", "parentRepor
  * needs new evidence" — it is a claim, and `limitsStated` records which claim was made rather than
  * leaving a reader to infer it from silence.
  */
-export function composeMemo({ assumption, parentRunId, parentReport, date, body, limits = [], mark = null } = {}) {
+export function composeMemo({ assumption, parentRunId, parentReport, date, body, limits = [], mark = null, ratedUnder } = {}) {
   const missing = REQUIRED.filter((k) => !String({ assumption, parentRunId, parentReport, date, body }[k] ?? "").trim());
   if (missing.length) return { ok: false, missing, reason: `a memo cannot be composed without: ${missing.join(", ")}` };
 
+  // THE RATING AUTHORITY IS REQUIRED BY PRESENCE, NOT BY TRUTHINESS, because `null` is a real answer.
+  // A memo is reasoned under an authority — the seat is instructed to assess under a named framework, or
+  // told the run froze none and to stay with the house default — and until this line the only thing that
+  // reached disk was the reasoning. A lawyer may act on this document; it has to say what it was rated
+  // under.
+  //
+  // Three states, and the third is the one worth separating. A named key is one fact. The house default
+  // is a DIFFERENT fact, not an absence, and it is recorded rather than left blank. A caller that never
+  // resolved an authority at all is neither, and refusing it is the point: a memo whose artifact is
+  // silent about its authority is exactly the defect this closes, so it must not be composable.
+  if (ratedUnder === undefined)
+    return { ok: false, missing: ["ratedUnder"],
+      reason: "a memo cannot be composed without its rating authority — pass the resolved key, or null "
+        + "for a run that froze no customer profile. Absent is not the same fact as either." };
+
   const limitLines = limits
     .map((l) => ({ cannot: String(l?.cannot ?? "").trim(), smallestSearch: String(l?.smallestSearch ?? "").trim() }))
     .filter((l) => l.cannot);
@@ -64,6 +79,9 @@ export function composeMemo({ assumption, parentRunId, parentReport, date, body,
     "",
     `**Date:** ${date}`,
     `**Derived from:** ${parentReport} (run ${parentRunId})`,
+    `**Rated under:** ${ratedUnder === null
+      ? "the house default — this report's run froze no customer profile"
+      : String(ratedUnder).trim()}`,
     "",
     "## The assumption you asked me to apply",
     "",

package/driver/whatif-queue.mjs

@@ -50,7 +50,7 @@ import { randomUUID } from "node:crypto";
 
 // ── WHICH RUNS A WHAT-IF MAY TOUCH — ONE DECLARATION, TWO READERS ───────────────────────────────────
 //
-// FOUND BY DRIVING IT (, 2026-09-03). There were THREE copies of this question and
+// FOUND BY DRIVING IT (2026-09-03). There were THREE copies of this question and
 // they did not agree. `whatIfPlan` and `whatIfEnqueue` refused `location === "archive" || state ===
 // "delivered"`; the worker refused the presence of any of `.delivered`, `.failed`, `.cancelled`,
 // `.cancel`. A run that had FAILED passed the first two and was refused by the third — so a client could

package/driver/whatif-worker.mjs

@@ -119,7 +119,7 @@ async function settleOne(entry, exec) {
   if (!job) return null;                       // another worker won it, or the manifest was recorded bad
   const { runDir, id } = entry;
   // The verdict is rendered HERE and not in the scan, because only now is the job's kind known. A
-  // delivered run refuses a stage re-run and welcomes a memo — that is the whole of tracker issue 132 —
+  // delivered run refuses a stage re-run and welcomes a memo — that is the whole distinction —
   // and a scan over run directories cannot tell those apart.
   const refusal = whatIfRefusal({ markers: entry.markers ?? [], kind: job.op?.kind ?? "stage" });
   if (refusal) {

package/examples/README.md

@@ -26,8 +26,8 @@ surfaces as a failing test rather than as a wrong report.
 (`loadGrants` in `shared/scope.mjs`) and asserted to grant what it looks like it grants — `../INSTALL.md`
 §8 tells an installer to copy this file, and a row that silently resolves to nothing means an empty
 world on their first sign-in. **Read it as a shape, not as a starting roster.** Most of the accounts it
-names — `aurora`, `zephyr`, `petcary` — are fixtures the test suite reads and are not part of the
-published package; the one a fresh install actually has is `demo-brand-owner`. Replace the names with
+names are invented and resolve to nothing on a fresh install; the one account a fresh install
+actually has is `demo-brand-owner`. Replace the names with
 your own accounts and keep the shapes: a tenant with every account, a tenant with one, a tenant whose
 users see different subsets.
 

package/examples/grants.example.json

@@ -5,27 +5,26 @@
       "users": {
         "principal@firm.example": "*",
         "associate@firm.example": [
-          "aurora"
+          "demo-brand-owner"
         ]
       }
     },
-    "aurora-direct": {
+    "brand-owner-direct": {
       "accounts": [
-        "aurora"
+        "demo-brand-owner"
       ],
       "users": {
-        "*@aurora.example": "*"
+        "*@brand-owner.example": "*"
       }
     },
     "evaluation": {
       "accounts": [
-        "zephyr",
-        "petcary"
+        "demo-brand-owner"
       ],
       "users": {
         "reviewer@partner.example": "*",
         "observer@partner.example": [
-          "zephyr"
+          "demo-brand-owner"
         ]
       }
     },

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,11 @@
 # trademark-artifacts-mcp
 
+## 0.2.3
+
+## 0.2.2
+
+## 0.3.0-beta.0
+
 ## 0.2.1
 
 ## 0.2.1-beta.2

package/mcp-server/README.md

@@ -1,9 +1,9 @@
 # trademark-artifacts-mcp
 
-An MCP server to **interrogate prelim trademark-clearance runs** — for an integrator's agent platform and for
+An MCP server to **interrogate clearotron trademark-clearance runs** — for an integrator's agent platform and for
 your **own Claude** (Claude Code / Desktop) alike. One stdio binary, two consumers.
 
-It answers three kinds of question against any run the `prelim-driver` produced:
+It answers three kinds of question against any run the `clearotron-driver` produced:
 1. **"How did you reach Y?"** — `trace` walks the full logic flow from any point (a stage, an artifact, a
    finding, the verdict) back through the stage that emitted it, its model + any failover, its inputs (with the
    sha each input had *when consumed* vs now), the per-search audit-trail rationale, the search terms + record
@@ -15,7 +15,7 @@ It answers three kinds of question against any run the `prelim-driver` produced:
 
 ## Design
 
-- **Imports the `prelim-driver` read-only** via `lib/driver.mjs` (the single coupling point). It hardcodes **no**
+- **Imports the `clearotron-driver` read-only** via `lib/driver.mjs` (the single coupling point). It hardcodes **no**
   artifact filename or stage name, so the driver can rename artifacts freely — the server tracks
   `paths()` / `STAGE_ORDER` automatically. It edits **no** driver, template, or deploy file.
 - **Provenance from the self-describing `_driver/run.jsonl`** (each `stage` event records its own

package/mcp-server/http-server.mjs

@@ -27,6 +27,9 @@ import { envFileRead } from "../shared/env-local.mjs";   // side effect: apply t
 import { envFrom } from "../shared/env-aliases.mjs";   // — a refusal names the name in force
 import { accessAudience, audienceLabel } from "../shared/access-audience.mjs";   // — F54; jose-free on purpose
 import { doorPostureVerdict } from "./door-posture.mjs";   // — say when this door's mode came from another door's variables
+// The local key door (tracker issue 174): a second listener on a unix socket, so a scoped access key has
+// a path that no tunnel can forward to and the TCP door never learns about keys.
+import { keyDoorRefusal, openKeyDoor, KEY_SOCKET_MODE } from "./key-socket.mjs";
 import { demoPostureLine } from "../driver/demo-posture.mjs";   // — the two mis-aimed warnings answer from one place
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
@@ -85,13 +88,17 @@ const DEV = process.env.TRADEMARK_MCP_DEV === "1";
 // the opposite of `TRADEMARK_MCP_AUTH_DISABLED` — which authenticates nobody and hands every caller
 // `local-test@disabled` — and the handler refuses outright to build the two together.
 //
-// It exists because 's one-command local install needs the trigger lane, the trigger lane is this
+// It exists because the one-command local install needs the trigger lane, the trigger lane is this
 // face, and a startup command that has to switch authentication off to reach it is the defect that
 // issue is about. The portal holds a verb-scoped, account-capped ops token; this door demands it.
 //
 // NAMED, NEVER INFERRED — the same rule wrote for PORTAL_AUTH_MODE, for the same reason. Unset
 // means exactly what it meant before this line existed, including the dev bypass still working, so a
 // deployment that loses CLEAROTRON_OIDC_AUDIENCE still refuses to start rather than quietly becoming a key door.
+// NAMED, NEVER INFERRED, like every other setting on this door: the key path is opt-in and a deployment
+// that does not set it gets exactly the door it has today. Unset is not "pick a default socket" — a
+// default path would put a key door on every install that never asked for one.
+const KEY_SOCKET = (process.env.TRADEMARK_MCP_KEY_SOCKET || "").trim();
 const AUTH_MODE = (process.env.TRADEMARK_MCP_AUTH_MODE || "").trim().toLowerCase();
 const TOKEN_ONLY = AUTH_MODE === "token";
 const TEAM = process.env.CF_ACCESS_TEAM || "";
@@ -214,6 +221,19 @@ if (isMain) {
     }
   }
 
+  // ── THE KEY PATH, ON THE POSTURE SURFACE (tracker issue 174) ──────────────────────────────────────
+  //
+  // An operator must be able to see that a local key path exists, and with what permissions, WITHOUT
+  // reading a unit file — the acceptance asks for exactly that, and it is the same reasoning as the
+  // posture line above: a door whose shape can only be learned by reading configuration is a door whose
+  // shape nobody checks. The mode is printed in octal because that is how an operator reads `ls -l`.
+  //
+  // The ABSENT case is a line too. Silence would leave "this deployment has no key path" and "this build
+  // does not have the feature" looking identical, which is the confusion this issue is about.
+  log(KEY_SOCKET
+    ? `key path: ${KEY_SOCKET} (mode ${KEY_SOCKET_MODE.toString(8)} once open) — a scoped access key is accepted HERE and nowhere else; the network door never honours one`
+    : "key path: none configured (TRADEMARK_MCP_KEY_SOCKET unset) — a program on this box holding an access key has no door on this process");
+
   // ── THE ROSTER THIS PROCESS CAN ACTUALLY SEE ──────────────────────────────────────────────────────
   //
   // WHAT THIS EXISTS FOR. `start_run` validates `profileKey` against `loadProfiles()`, which reads
@@ -297,4 +317,27 @@ if (isMain) {
     port: PORT, host: HOST, what: "the MCP staff surface", portVar: "TRADEMARK_MCP_HTTP_PORT", portSource: PORT_CHOICE.source, portFile: envFileRead(), log,
     onReady: ({ port: bound }) => log(`listening on http://${HOST}:${bound}/mcp — READ-ONLY staff surface, firmDomains=[${ALLOWED_DOMAINS.join(", ")}], ${door}`),
   });
+
+  // ── THE SECOND DOOR: A LOCAL KEY PATH ON A UNIX SOCKET (tracker issue 174) ────────────────────────
+  //
+  // One process, two transports, two handlers. The TCP door above is untouched and still never honours a
+  // key; this one takes a scoped access key and cannot be reached from any network. A tunnel forwards to
+  // a port, so it cannot reach a socket — which is the whole reason the discriminator is the transport
+  // rather than the peer address. See key-socket.mjs for why a loopback check is not a control here.
+  //
+  // A SEPARATE SESSION MAP, deliberately. The handler already refuses a session whose owner is not the
+  // caller, so sharing one map would probably be safe — but "probably safe" across an authentication
+  // boundary is the kind of reasoning this repository keeps paying for, and two maps cost one allocation.
+  // A session minted behind the key door is not addressable from the tunnel-facing one at all.
+  if (KEY_SOCKET) {
+    const refusal = keyDoorRefusal({ authDisabled: AUTH_DISABLED, accessFile: envFrom(process.env, "CLEAROTRON_ACCESS_FILE"), authMode: AUTH_MODE });
+    if (refusal) { log(`FATAL: ${refusal}`); process.exit(1); }
+    const keyHandler = makeHttpHandler({
+      verify: null, tokenOnly: true, devMode: false,
+      limiter, opsLimiter, sessions: new Map(), createSession, ns: NS, sessionMax: SESSION_MAX,
+      authHeader: AUTH_HEADER, firmDomains: ALLOWED_DOMAINS, log,
+    });
+    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); });
+  }
 }