clearotron 0.2.1 → 0.3.0-beta.0

package/driver/suite-census.json

@@ -213,6 +213,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-dynamic-import-of-a-path-is-a-file-url.test.mjs": {
+          "tests": 3,
+          "asserts": 6,
+          "skips": 1,
+          "todos": 0
+        },
         "a-fact-about-a-named-party.test.mjs": {
           "tests": 30,
           "asserts": 80,
@@ -298,8 +304,8 @@
           "todos": 0
         },
         "a-memo-over-a-delivered-report-leaves-it-alone.test.mjs": {
-          "tests": 9,
-          "asserts": 45,
+          "tests": 13,
+          "asserts": 52,
           "skips": 0,
           "todos": 0
         },
@@ -387,6 +393,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-queued-what-if-is-answered-before-its-run-archives.test.mjs": {
+          "tests": 3,
+          "asserts": 12,
+          "skips": 0,
+          "todos": 0
+        },
         "a-real-install-starts-with-an-empty-archive.test.mjs": {
           "tests": 6,
           "asserts": 16,
@@ -496,8 +508,8 @@
           "todos": 0
         },
         "a-screenshot-of-an-error-page-is-not-a-report.test.mjs": {
-          "tests": 17,
-          "asserts": 44,
+          "tests": 21,
+          "asserts": 55,
           "skips": 4,
           "todos": 0
         },
@@ -567,6 +579,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-unit-is-attributed-by-what-it-runs-not-only-by-what-it-declares.test.mjs": {
+          "tests": 10,
+          "asserts": 27,
+          "skips": 0,
+          "todos": 0
+        },
         "a-verb-is-a-module-until-it-is-the-command.test.mjs": {
           "tests": 3,
           "asserts": 8,
@@ -700,8 +718,8 @@
           "todos": 0
         },
         "an-experiment-receipt-names-its-engine.test.mjs": {
-          "tests": 6,
-          "asserts": 22,
+          "tests": 8,
+          "asserts": 27,
           "skips": 0,
           "todos": 0
         },
@@ -711,12 +729,24 @@
           "skips": 1,
           "todos": 0
         },
+        "an-observed-model-id-says-whether-it-is-pinned.test.mjs": {
+          "tests": 4,
+          "asserts": 10,
+          "skips": 0,
+          "todos": 0
+        },
         "an-ordered-field-is-a-field-the-tool-can-express.test.mjs": {
           "tests": 1,
           "asserts": 6,
           "skips": 0,
           "todos": 0
         },
+        "an-unread-probe-is-not-a-failed-measurement.test.mjs": {
+          "tests": 5,
+          "asserts": 11,
+          "skips": 0,
+          "todos": 0
+        },
         "anchor-and-script-aware-quote.test.mjs": {
           "tests": 12,
           "asserts": 40,
@@ -1348,8 +1378,8 @@
           "todos": 0
         },
         "declination-is-stated-not-inferred.test.mjs": {
-          "tests": 20,
-          "asserts": 60,
+          "tests": 24,
+          "asserts": 69,
           "skips": 0,
           "todos": 0
         },
@@ -1397,7 +1427,7 @@
         },
         "deployment-hostnames.test.mjs": {
           "tests": 13,
-          "asserts": 37,
+          "asserts": 36,
           "skips": 0,
           "todos": 0
         },
@@ -2457,6 +2487,12 @@
           "skips": 2,
           "todos": 0
         },
+        "no-run-codenames-in-tracked-files.test.mjs": {
+          "tests": 6,
+          "asserts": 13,
+          "skips": 4,
+          "todos": 0
+        },
         "no-test-writes-inside-the-checkout.test.mjs": {
           "tests": 16,
           "asserts": 35,
@@ -3161,7 +3197,7 @@
         },
         "register-count.test.mjs": {
           "tests": 20,
-          "asserts": 145,
+          "asserts": 148,
           "skips": 0,
           "todos": 0
         },
@@ -3262,8 +3298,8 @@
           "todos": 0
         },
         "release-pipeline.test.mjs": {
-          "tests": 83,
-          "asserts": 320,
+          "tests": 87,
+          "asserts": 334,
           "skips": 0,
           "todos": 0
         },
@@ -3880,8 +3916,8 @@
           "todos": 0
         },
         "start-background-units.test.mjs": {
-          "tests": 6,
-          "asserts": 20,
+          "tests": 9,
+          "asserts": 26,
           "skips": 0,
           "todos": 0
         },
@@ -4276,8 +4312,8 @@
           "todos": 0
         },
         "the-narrative-is-checked-against-its-depth-rules.test.mjs": {
-          "tests": 15,
-          "asserts": 55,
+          "tests": 19,
+          "asserts": 70,
           "skips": 0,
           "todos": 0
         },
@@ -4377,6 +4413,12 @@
           "skips": 1,
           "todos": 0
         },
+        "the-report-carries-what-the-assessment-wrote.test.mjs": {
+          "tests": 10,
+          "asserts": 41,
+          "skips": 0,
+          "todos": 0
+        },
         "the-report-shell-keeps-what-a-repair-does-not-resend.test.mjs": {
           "tests": 6,
           "asserts": 28,
@@ -4720,8 +4762,8 @@
           "todos": 0
         },
         "verify-knockout.test.mjs": {
-          "tests": 1,
-          "asserts": 5,
+          "tests": 2,
+          "asserts": 11,
           "skips": 0,
           "todos": 0
         },
@@ -4952,6 +4994,12 @@
           "skips": 0,
           "todos": 0
         },
+        "knockout-audit-tools.test.mjs": {
+          "tests": 16,
+          "asserts": 73,
+          "skips": 0,
+          "todos": 0
+        },
         "lexsearch.test.mjs": {
           "tests": 5,
           "asserts": 11,

package/driver/unit-inventory.mjs

@@ -641,6 +641,53 @@ export function unitInventoryVerdict({
  * @param {string|null} raw  the value `systemctl show -p WorkingDirectory` printed
  * @returns {{path: string|null, prefixes: string, why: string|null}}
  */
+/**
+ * Which checkout is a unit actually serving — and which piece of evidence said so.
+ *
+ * A unit can be attributed two ways and they are not equally good.
+ *
+ * `WorkingDirectory` is a DECLARATION. It is what the unit file asks for, and it is frequently not a
+ * checkout at all: a unit written as `WorkingDirectory=~` reports `!/home/<user>`, which resolves to a
+ * home directory that is not a git tree, and the unit then drops out of the comparison entirely. That is
+ * not a rare shape — it is what a unit looks like when its author put the checkout in `ExecStart=`
+ * instead, which is the normal thing to do, because systemd cannot expand a variable in
+ * `WorkingDirectory=` and can in `ExecStart=`.
+ *
+ * The RUNNING COMMAND LINE is an OBSERVATION: the absolute path the live process was actually started
+ * with. So it wins, and that order is the point rather than a preference. The incident this comparison
+ * exists for is a deployment that served its portal from one clone while running its runner from
+ * another — and in that state the declaration and the process disagree, with the process telling the
+ * truth. Preferring the declaration would take the wrong side of exactly the case the check is for.
+ *
+ * WHEN BOTH RESOLVE AND DISAGREE, that IS the finding, and it is returned rather than quietly resolved:
+ * a unit whose declared tree and running tree differ has been repointed since it started, and it is
+ * serving the older one until something restarts it.
+ *
+ * PURE — the caller does the reading (systemd, the unit file, the process table) and this decides.
+ *
+ * @param {object} a
+ * @param {string|null} a.declaredTree  a git tree resolved from `WorkingDirectory`, or null
+ * @param {string|null} a.runningTree   a git tree resolved from the live process's argv, or null
+ * @param {string|null} a.declaredWhy   why the declaration gave nothing, if it gave nothing
+ * @param {string|null} a.runningWhy    why the process gave nothing, if it gave nothing
+ * @returns {{clone: string|null, source: string|null, disagreement: string|null, why: string|null}}
+ */
+export function unitClone({ declaredTree = null, runningTree = null, declaredWhy = null, runningWhy = null } = {}) {
+  const norm = (p) => String(p ?? "").replace(/\/+$/, "") || null;
+  const declared = norm(declaredTree);
+  const running = norm(runningTree);
+  const disagreement = declared && running && declared !== running
+    ? `the unit declares ${declared} and its running process was started from ${running} — it is serving the second until something restarts it`
+    : null;
+  if (running) return { clone: running, source: "the running command line", disagreement, why: null };
+  if (declared) return { clone: declared, source: "WorkingDirectory", disagreement, why: null };
+  // BOTH REASONS, never the first one that came to hand. A caller that reports only "no WorkingDirectory"
+  // sends the next reader to fix a unit file when the process table was the half that could not be read.
+  const parts = [declaredWhy, runningWhy].filter(Boolean);
+  return { clone: null, source: null, disagreement: null,
+    why: parts.length ? parts.join("; and ") : "neither the unit's WorkingDirectory nor its running command line named a checkout" };
+}
+
 export function unitWorkingDirectory(raw) {
   const s = String(raw ?? "").trim();
   if (!s) return { path: null, prefixes: "", why: "the unit reported no WorkingDirectory" };

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.
@@ -63,9 +63,9 @@
 // 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,8 +134,8 @@ 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.
   const activeCount = (units ?? []).filter((u) => u.active === "active").length;

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 : [])) {

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; }
@@ -299,10 +336,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/mcp-server/CHANGELOG.md

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

package/mcp-server/lib/brief.mjs

@@ -135,6 +135,21 @@ export function buildBrief(run) {
         lines.push(`- **${m.name}** — ${band}.${d.url ? ` Report: ${d.url}` : ""}`);
         for (const f of (m.findings ?? [])) {
           const who = [f.name, f.owner].filter(Boolean).join(" — ");
+          // A PROMOTED REGISTER FILING SHOWS THE RATING AND THE READ THE SEARCH ACTUALLY MADE (tracker
+          // issue 274). This line used to print `net` alone, and for a register card `net` carried the
+          // stated "no rating of its own" — so the one hard legal right on a page was described here as
+          // unrated even on runs where the assessment had written a full read of that exact filing and
+          // the report was already printing it. The page and this briefing disagreed.
+          //
+          // SCOPED TO `shape === 'register'` DELIBERATELY. Every other finding line is left exactly as it
+          // was: a typed conflict already leads with its own band on the report, and widening this to all
+          // findings would change what this briefing says about runs that have no register layer at all.
+          if (f.shape === "register") {
+            const rating = f.band ? ` — ${titleCase(String(f.band))} risk.` : "";
+            const read = f.basis && f.basis !== f.net ? ` ${f.basis}` : "";
+            lines.push(`  - ${who}${rating}${f.net ? ` ${f.net}` : ""}${read}`.trimEnd());
+            continue;
+          }
           lines.push(`  - ${who}${f.net ? `: ${f.net}` : ""}`.trimEnd());
         }
       }

package/mcp-server/lib/driver.mjs

@@ -14,6 +14,12 @@ export {
   REGISTER_AXES, decideAxes, axisTier,
 } from "../../driver/stages.mjs";
 
+// The KNOCKOUT lane's own run-dir table. `paths` above is the CLEARANCE table and has no entry for any
+// file this lane writes, which is why every audit projection read a delivered knockout as a run with
+// nothing on disk (tracker issue 275). Re-exported rather than re-derived for the reason this whole file
+// exists: a second copy of a path table drifts, and the drift shows up as an artifact reported missing.
+export { koPaths } from "../../driver/stages-knockout.mjs";
+
 // stripInternal/stripEngineInternals/stripTelemetry are the driver's OWN client-safety transforms — the
 // same ones publish/render.mjs applies to the client HTML export. lib/scrub.mjs composes them so the MCP
 // client surface and the delivered report answer "what may a client see?" from ONE definition ( R1: