clearotron 0.3.2 → 0.3.3-beta.1

package/scripts/live-surface-check.mjs

@@ -106,6 +106,7 @@ import { processTable } from "../shared/process-table.mjs";
 import { envFrom } from "../shared/env-aliases.mjs";
 import { gitTry, treeOf } from "../shared/tree-commit.mjs";   // — a packaged install has no git, and says its commit in build-info.json
 import { exitFor } from "../driver/surface-exit-verdict.mjs";   // — a check that could not look is not a drift, and they want different things done   // — the name a reader is told to set is the one in force
+import { planRunAgreementVerdict } from "../driver/plan-run-agreement-verdict.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const asJson = process.argv.includes("--json");
@@ -500,8 +501,8 @@ if (!snapshot) {
     catch { return null; }
   })();
   const { groups: managerGroups, why } = readUserManagerGroups(uid);
-  const { state, message } = managerGroupsVerdict({ idGroups, managerGroups, user, uid, why });
-  ({ pass, fail, skip })[state]("user manager groups are current", message);
+  const v = managerGroupsVerdict({ idGroups, managerGroups, user, uid, why });
+  record("user manager groups are current", v.state, v.message, v.blocked === true);
 }
 
 // 1b. — HOW THIS BOX DIFFERS FROM PRODUCTION on the flags that change output without saying so.
@@ -582,9 +583,9 @@ try {
   try { caller = (await import("../driver/portal-service.mjs")).opsTokenPosture(OPS_TOKEN); }
   catch { /* stays unreadable — the verdict reports what it could not compare */ }
   if (bundledDemos) {
-    const { state, message } = rosterVerdict({ keys, onDisk, bundledDemos, caller,
+    const v = rosterVerdict({ keys, onDisk, bundledDemos, caller,
       expectDemos: process.env.CLEAROTRON_E2E_EXPECT_DEMO_ROSTER === "1" });
-    ({ pass, fail, skip })[state]("roster resolves", message);
+    record("roster resolves", v.state, v.message, v.blocked === true);
   }
   // A COMPANY IN THE STORE THAT THIS KEY CANNOT START is its own finding, not a roster disagreement. A
   // warning, not a failure: the portal re-takes its credential at the start of every call, so a Start for
@@ -639,7 +640,7 @@ try {
       effectiveMode: (process.env.TRADEMARK_MCP_AUTH_MODE || "").trim().toLowerCase() === "token" ? "token" : "cf-access",
       allowedHosts: (process.env.TRADEMARK_MCP_ALLOWED_HOSTS || "").split(",").map((h) => h.trim()).filter(Boolean),
     });
-    record("the ops door's auth mode was chosen for it", posture.state, posture.message);
+    record("the ops door's auth mode was chosen for it", posture.state, posture.message, posture.blocked === true);
   }
 } catch (e) {
   if (e?.message === "__door_unset__") skip("ops-MCP reachable", "this instance does not say where its ops-MCP is — NOT PROBED");
@@ -735,20 +736,11 @@ if (mcpOptions && built) {
   //
   //     plan_run needs an explicit profileKey: an accounts-scoped session refuses without one. The key
   //     comes from what the door ITSELF resolved (below), so no customer is ever hardcoded here.
-  const planDisagreements = [];
-  for (const key of (probeProfileKey ? seen : [])) {
-    try {
-      const plan = await mcpToolCall({ url: MCP_URL, token: OPS_TOKEN, tool: "plan_run",
-        args: { markName: "SURFACE CHECK", classes: [9], product: key, profileKey: probeProfileKey }, timeoutMs: 20000 });
-      const unavailable = (plan?.blockers ?? []).some((b) => /not part of the current release|not switched on|unavailable/i.test(String(b)));
-      if (unavailable !== !doorSays.get(key)) {
-        planDisagreements.push(`${key}: describe_options=${doorSays.get(key) ? "available" : "unavailable"} plan_run=${unavailable ? "unavailable" : "available"}`);
-      }
-    } catch (e) { planDisagreements.push(`${key}: plan_run errored — ${e.message.slice(0, 120)}`); }
-  }
-  if (!probeProfileKey) skip("describe_options and plan_run agree", "no customer resolved to plan against — see the roster check");
-  else if (planDisagreements.length) fail("describe_options and plan_run agree", planDisagreements.join(" · "));
-  else pass("describe_options and plan_run agree", `${seen.length} products checked through both code paths`);
+  //     A plan_run that throws (a 429, a timeout) compared nothing: a marked skip, exit 3, never a drift.
+  const pv = await planRunAgreementVerdict({ keys: seen, doorSays, probeProfileKey,
+    ask: (key) => mcpToolCall({ url: MCP_URL, token: OPS_TOKEN, tool: "plan_run",
+      args: { markName: "SURFACE CHECK", classes: [9], product: key, profileKey: probeProfileKey }, timeoutMs: 20000 }) });
+  record("describe_options and plan_run agree", pv.state, pv.message, pv.blocked === true);
 }
 
 // 5. Leak scan on what a door actually returned. An env name or a path in a live response is a defect
@@ -827,11 +819,12 @@ else {
 // process that is in no unit, so this arm derives from the PROCESS TABLE and from a stamp the drainer
 // writes about itself.
 //
-// IT FAILS ON COULD-NOT-LOOK, and that is deliberate. This script exits non-zero on `fail` only —
-// `skip` does not move the exit code — so recording an absent stamp as a skip would let the deploy
-// report a build live having never established what the executing process holds, which is the exact
-// state the incident's drainer was in. The fourth criterion of that issue is that the deploy does not
-// report a build live until this arm has looked; a skip here would be that criterion silently unmet.
+// A COULD-NOT-LOOK HERE MOVES THE EXIT CODE, and that is deliberate. An ordinary skip does not, so
+// recording an absent stamp as one would let the deploy report a build live having never established
+// what the executing process holds, which is the exact state the incident's drainer was in. It is
+// recorded through `blocked`, which exits 3 rather than the 1 a drift gives: the deploy still does not
+// report a build live until this arm has looked, and the reader is told it could not look rather than
+// that something drifted.
 {
   let workspaceRoot = null, resolveError = null;
   try { workspaceRoot = config.workspaceRoot; }
@@ -937,7 +930,7 @@ else {
       // which tree this deploy is. Reading it twice is how they would come to.
       deployClone,
     });
-    record("the updater that deploys this box is the current one", v.state, v.message);
+    record("the updater that deploys this box is the current one", v.state, v.message, v.blocked === true);
   }
   }
 }
@@ -947,10 +940,10 @@ else {
 // inline string equality over a two-word vocabulary, which is why a `Type=oneshot` doing its job read as
 // a fault on the deploy's final gate. The decision now lives in driver/unit-state-verdict.mjs, where a
 // test can reach it — same move made for the roster arm, for the same reason.
-// `record`, not the ({pass, fail, skip})[state] shorthand used above: `warn` is a real outcome here.
+// `record`, not a ({pass, fail, skip})[state] shorthand: `warn` is a real outcome here.
 {
   const v = unitsActiveVerdict({ units: clones, probe: unitProbe });
-  record("units active", v.state, v.message);
+  record("units active", v.state, v.message, v.blocked === true);
 }
 
 // 10. — THE UNIT A BOX RUNS versus the unit the deployed commit SHIPS. The deploy syncs code, not
@@ -1013,7 +1006,7 @@ else {
     return { unit: fragName ?? c.unit, live, tracked, dropIns };
   });
   const v = unitFileDriftVerdict({ units: rows, probe: unitProbe });
-  record("units match the deployed commit", v.state, v.message);
+  record("units match the deployed commit", v.state, v.message, v.blocked === true);
 }
 
 // 10a. — IS EVERY UNIT THIS BOX RUNS ACCOUNTED FOR AT ALL?
@@ -1082,7 +1075,7 @@ else {
   const box = deploymentBox();   // — the shared rule, so /portal/health cannot disagree with this
   const v = unitInventoryVerdict({ live: liveUnits, files: walk.files, collisions: walk.collisions,
     filesError: walk.error, box, probe, boxNames: DEPLOYMENT_BOXES });
-  record("every live unit is declared", v.state, v.message);
+  record("every live unit is declared", v.state, v.message, v.blocked === true);
 
   // — AND WHETHER ANYTHING STILL STARTS THE TIMER-DRIVEN ONES. Reported separately from the line above
   // because it answers a different question: that one says a declared unit exists and is not adrift,
@@ -1090,7 +1083,7 @@ else {
   // fails the second, and reads `inactive` for both — which is why one line could not carry both.
   const t = declaredTimers();
   const tv = timerVerdict(t.rows, { probeFailed: t.probeFailed });
-  record("every declared timer is still armed", tv.state, tv.message);
+  record("every declared timer is still armed", tv.state, tv.message, tv.blocked === true);
 }
 
 // ── — EVERY QUEUE THIS DEPLOYMENT WOULD DRAIN IS WATCHED BY SOMETHING ──────────────────────────
@@ -1116,7 +1109,7 @@ else {
   // job's life, and two readers of one unit file is how the deploy tick and a door come to different
   // conclusions about the same box. The unit path now has one home.
   const v = probeQueueWatch({ queueDirs, resolveError });
-  record("every queue this deployment would drain is watched", v.state, v.message);
+  record("every queue this deployment would drain is watched", v.state, v.message, v.blocked === true);
 }
 
 // ── report ───────────────────────────────────────────────────────────────────────────────────────────
@@ -1129,8 +1122,14 @@ const couldNotLook = results.filter((r) => r.blocked);
 // — extracted for the reason roster-verdict and unit-state-verdict were: this file is a program, and a
 // decision that can only be reached by running it is a decision nobody can drive.
 
+// ONE DECISION, READ BY BOTH SURFACES. `--json` used to print `ok: failed.length === 0`, so a run that
+// could not look at a surface and found nothing else wrong told a machine reader `ok: true` while the
+// terminal said COULD NOT LOOK and the process exited 3. The human surface was fixed and the one a script
+// believes silently was not. `ok` is now the exit code's own answer, and `exit` carries which of the three.
+const code = exitFor({ failed: failed.length, couldNotLook: couldNotLook.length });
+
 if (asJson) {
-  console.log(JSON.stringify({ ok: failed.length === 0, poolRoot: POOL_ROOT, register: wiredRegister, results }, null, 2));
+  console.log(JSON.stringify({ ok: code === 0, exit: code, poolRoot: POOL_ROOT, register: wiredRegister, results }, null, 2));
 } else {
   const mark = { pass: "  ok  ", fail: " FAIL ", warn: " warn ", skip: " skip " };
   console.log(`\n== live surface check — ${POOL_ROOT} ==\n`);
@@ -1148,4 +1147,4 @@ if (asJson) {
   }
 }
 
-process.exit(exitFor({ failed: failed.length, couldNotLook: couldNotLook.length }));
+process.exit(code);

package/scripts/mint-suite-census.mjs

@@ -148,6 +148,60 @@ export function laidPathVerdict({ laid = 0, laidPaths = [], cutRecordPresent = f
  * A tree with no HEAD cannot say what it published. That is a failure to look, and it exits rather
  * than reading as "nothing is laid here", which is the permissive answer and the one that passes.
  */
+/**
+ * — A HALF-FINISHED MERGE CANNOT SAY WHAT ITS SUITE IS, and it does not know that it cannot.
+ *
+ * The refusal above catches one of the two ways a mid-merge tree lies to this script: a path arriving
+ * from the other parent is in the index and not in HEAD, so it is laid, named and refused. It cannot
+ * catch the other. A file both parents changed IS in HEAD, so nothing about it is laid — it is counted,
+ * and what is counted is a working copy holding `<<<<<<<`, `=======` and `>>>>>>>` as though they were
+ * source. Measured 2026-09-21 on a tree conflicted in one test file: the mint read all 980 driver
+ * files, counted the conflicted one, printed "unchanged — no file added, removed, grown, shrunk or
+ * newly skipped", and exited 0. The operator's confirmation and the defect are the same sentence.
+ *
+ * THE STATE IS THE TEST, NOT THE MARKERS. Scanning files for marker lines would find this instance and
+ * would also refuse a test that legitimately contains one in a string, while missing a conflict
+ * resolved into plausible nonsense. Git already publishes the fact: an operation is half-finished, so
+ * no tree it produced is a population anyone should stamp. That covers both mechanisms at once, and
+ * covers a rebase and a cherry-pick, where the same two lies are available for the same reason.
+ *
+ * REFUSES RATHER THAN REPAIRS. Reading the index instead of HEAD would fix the counting and would still
+ * mint over markers, so it is the weaker of the two. There is a correct tree a few seconds away —
+ * finish the operation and mint on the result — and the census is a deliberate act whose whole value is
+ * that somebody looked at the diff.
+ *
+ * Pure, and takes the list rather than reading it, so both branches can be driven without a test
+ * having to conflict a real tree.
+ */
+export const MID_OPERATION_STATES = Object.freeze([
+  ["MERGE_HEAD", "merge"],
+  ["CHERRY_PICK_HEAD", "cherry-pick"],
+  ["REVERT_HEAD", "revert"],
+  ["rebase-merge", "rebase"],
+  ["rebase-apply", "rebase"],
+]);
+
+export function midOperationVerdict({ inProgress = [] } = {}) {
+  if (!inProgress.length) return { refuse: false, message: null };
+  const what = [...new Set(inProgress.map(([, label]) => label))].join(" and a ");
+  return { refuse: true,
+    message: `mint-suite-census: this tree is in the middle of a ${what}, so the files in it are not a\n`
+      + "  population anybody published. A path from the other parent is missing from HEAD and would be\n"
+      + "  dropped from the count; a file both sides changed is in HEAD and would be counted WITH its\n"
+      + "  conflict markers. Either way this would print \"unchanged\" for a population it had just\n"
+      + `  misread. Finish the ${what} and mint on the tree that comes out.` };
+}
+
+/** Which half-finished operations this worktree's own git directory is carrying. */
+export function operationsInProgress(root, exists = existsSync) {
+  let gitDir;
+  try {
+    gitDir = execFileSync("git", ["-C", root, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" }).trim();
+  } catch { return []; }
+  if (!gitDir) return [];
+  return MID_OPERATION_STATES.filter(([name]) => exists(join(gitDir, name)));
+}
+
 /**
  * The paths the private overlay says it laid over this clone, or null where it laid nothing.
  *
@@ -219,6 +273,18 @@ export function buildCensus(root = ROOT) {
 const readManifest = (rel) => { try { return JSON.parse(readFileSync(join(ROOT, rel), "utf8")); } catch { return null; } };
 
 function main() {
+  // ── BEFORE EVEN THAT — IS THIS TREE A POPULATION AT ALL? ────────────────────────────────────
+  //
+  // First, because every check below reads files from this working tree, and mid-merge those files are
+  // not what either parent published. A census that is internally consistent about a tree nobody
+  // committed passes every other refusal in this file, `--check` included.
+  const mid = midOperationVerdict({ inProgress: operationsInProgress(ROOT) });
+  if (mid.refuse) {
+    console.error(`\nREFUSING — ${mid.message}`);
+    process.exitCode = 2;
+    return;
+  }
+
   // ── ITEM 1 — BEFORE ANY COUNTING, DOES THIS CENSUS DESCRIBE WHAT THE RUNNER RUNS? ───────────
   //
   // FIRST, and it refuses rather than warns. Everything below counts files inside a corpus this list

package/scripts/package-size-budget.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+// package-size-budget.mjs — THE TARBALL CANNOT GROW WITHOUT SOMEBODY DECIDING THAT IT SHOULD.
+//
+// The package is large by design: most of it is bundled demo evidence, and that was ruled to be right.
+// What was missing is not a smaller package, it is a MEASUREMENT — nothing recorded the size, so it
+// could double across a few betas and no one would find out from the repository. A number nobody
+// records is a number nobody can notice changing.
+//
+// WHAT THIS IS NOT. It is not a size limit chosen by taste, and it does not argue about what ships.
+// It compares against a RECORDED baseline and allows a margin; anything inside the margin passes
+// silently, anything past it fails and prints the ten largest paths so the growth has a name before
+// anyone debates it.
+//
+// WHY A COMMITTED BASELINE RATHER THAN A LIVE LOOKUP of the last published version. A gate must give
+// the same answer on every machine, including one with no network, and it must not start failing
+// because a registry is slow or a version was unpublished. The baseline is minted into this repository
+// the same way the suite census is, so the comparison is deterministic, reviewable in the diff that
+// changes it, and honest about being a decision somebody made rather than a fact fetched at runtime.
+//
+// Usage:
+//   node scripts/package-size-budget.mjs            measure and report against the baseline
+//   node scripts/package-size-budget.mjs --check    …and exit non-zero when it is past the margin
+//   node scripts/package-size-budget.mjs --apply    re-record the baseline as it is now
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const BASELINE = join(ROOT, "package-size-baseline.json");
+
+// THE MARGIN, and why it is one number rather than per-field taste. A change that adds a demo run
+// moves every field at once, so a single proportion catches the shape of growth that matters and
+// leaves ordinary churn alone. 10% is roughly one more bundled run on today's package — big enough
+// that nobody trips it by editing source, small enough that a doubling cannot arrive unannounced.
+export const MARGIN = 0.10;
+
+/** What `npm pack` says this tree would publish. */
+export function measure({ root = ROOT } = {}) {
+  const out = execFileSync("npm", ["pack", "--dry-run", "--json"], {
+    cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024,
+  });
+  const p = JSON.parse(out)[0];
+  return {
+    size: p.size,
+    unpackedSize: p.unpackedSize,
+    entryCount: p.entryCount,
+    files: (p.files ?? []).map((f) => ({ path: f.path, size: f.size })),
+  };
+}
+
+const mb = (n) => `${(n / 1_000_000).toFixed(1)} MB`;
+const pct = (now, was) => `${now >= was ? "+" : ""}${(((now - was) / was) * 100).toFixed(1)}%`;
+
+/** The ten largest paths, so growth has a name rather than a number. */
+export function largest(files, n = 10) {
+  return [...files].sort((a, b) => b.size - a.size).slice(0, n);
+}
+
+/**
+ * Compare a measurement against a baseline. Returns `{ over: [...], rows: [...] }` — `over` names the
+ * fields past the margin and is empty when nothing is.
+ */
+export function compare(now, was, { margin = MARGIN } = {}) {
+  const rows = [];
+  const over = [];
+  for (const [field, label] of [["size", "packed"], ["unpackedSize", "unpacked"], ["entryCount", "entries"]]) {
+    const limit = Math.floor(was[field] * (1 + margin));
+    const breached = now[field] > limit;
+    if (breached) over.push(field);
+    rows.push({ field, label, now: now[field], was: was[field], limit, breached });
+  }
+  return { over, rows };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const apply = process.argv.includes("--apply");
+  const check = process.argv.includes("--check");
+  const now = measure();
+
+  if (apply) {
+    writeFileSync(BASELINE, `${JSON.stringify({
+      note: "What `npm pack` produced when this was recorded. The budget allows a margin over these; see scripts/package-size-budget.mjs.",
+      margin: MARGIN,
+      size: now.size, unpackedSize: now.unpackedSize, entryCount: now.entryCount,
+    }, null, 2)}\n`);
+    console.log(`recorded: ${mb(now.size)} packed, ${mb(now.unpackedSize)} unpacked, ${now.entryCount} entries`);
+    process.exit(0);
+  }
+
+  if (!existsSync(BASELINE)) {
+    console.error("package-size-budget: no baseline recorded. `node scripts/package-size-budget.mjs --apply` writes one.");
+    process.exit(check ? 1 : 0);
+  }
+  const was = JSON.parse(readFileSync(BASELINE, "utf8"));
+  const { over, rows } = compare(now, was, { margin: was.margin ?? MARGIN });
+
+  for (const r of rows) {
+    const shown = r.field === "entryCount" ? `${r.now} against ${r.was}` : `${mb(r.now)} against ${mb(r.was)}`;
+    console.log(`  ${r.label.padEnd(9)} ${shown} (${pct(r.now, r.was)}${r.breached ? " — PAST THE MARGIN" : ""})`);
+  }
+
+  if (!over.length) {
+    console.log(`package-size-budget: inside the ${Math.round((was.margin ?? MARGIN) * 100)}% margin.`);
+    process.exit(0);
+  }
+
+  console.error(`\npackage-size-budget: ${over.join(" and ")} past the ${Math.round((was.margin ?? MARGIN) * 100)}% margin.`);
+  console.error("The ten largest paths in what would be published:\n");
+  for (const f of largest(now.files)) console.error(`  ${mb(f.size).padStart(8)}  ${f.path}`);
+  console.error("\nIf the growth is intended, re-record the baseline in the same commit that causes it:");
+  console.error("  node scripts/package-size-budget.mjs --apply");
+  process.exit(check ? 1 : 0);
+}

package/scripts/register-plan-shape.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// register-plan-shape.mjs — recompile a recorded run's register plan from its own inputs and print
+// the SHAPE of the result: how many questions run without being asked for, how many wait, and whether
+// the waiting ones are waiting for the reading turn.
+//
+//   node scripts/register-plan-shape.mjs <run-directory>
+//
+// WHY THIS PRINTS COUNTS AND NOTHING ELSE. It exists to be run against recorded client runs, where the
+// mark, the goods words, the owners and the records are not ours to quote anywhere — and a plan entry's
+// own qid contains the mark, so even an identifier list would be a disclosure. What comes out is
+// arithmetic: numbers, axis names and predicate names, all of which are vocabulary this repository
+// already publishes. Nothing here reads a record, and nothing here can print one.
+//
+// IT WRITES NOTHING, which is the other half of being safe to point at a real run. The ordinary compile
+// path freezes the plan it built and writes run-journal rows; this reads the same inputs and compiles
+// in memory. A recorded run is evidence, and a tool that measures it must leave it byte-identical.
+//
+// WHAT IT IS FOR. The plan a recorded run froze was compiled by the compiler of its day. Reading that
+// artifact says what the engine DID ask; it cannot say what today's engine WOULD ask. Recompiling from
+// the run's own inputs answers the second question, which is the one a rule change has to be judged on.
+//
+// AN ABSENT INPUT IS A FINDING, NOT A DEFAULT. Every input is named and checked, and a missing one
+// stops the run with the path that was looked for. A compile over a half-read run directory would
+// produce a number, and a number produced that way is worse than no number.
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { paths } from "../driver/stages.mjs";
+import { driverDir } from "../shared/driver-dir.mjs";   // — the run-directory layout has one namer; a literal here is how two spellings drift
+import { compileRegisterPlan, awaitsReadingTurn, planMaxOrWidth } from "../driver/register-plan.mjs";
+import { parseVariantManifestModel } from "../driver/variant-manifest-model.mjs";
+import { registerCapabilities, registerUnavailableOffices } from "../driver/register-unreachable.mjs";
+import { frameIdentifiedClassRows } from "../driver/matter-frame-record.mjs";
+import { excludeHouseElement, mintSupplementalQid, HOUSE_ELEMENT_RECEIPT } from "../driver/register-plan.mjs";
+import { inScopeClassList, registerJurisdictions } from "../driver/pipeline.mjs";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
+
+/**
+ * The three kinds that run without being asked for (decision 10, as amended 2026-09-21).
+ *
+ * READ OFF THE ENTRY, deliberately, rather than re-deriving the compiler's own test: this is a
+ * measuring instrument, and an instrument that shares the mechanism it measures cannot disagree with
+ * it. The subtlety worth stating is the third line — the BARE contains entry on the mark waits, and
+ * only the goods-narrowed one is always on (ruled 2026-09-20), so `provenance === "mark"` alone is not the
+ * test and a reader who assumed it were would count a waiting entry as open.
+ */
+function openKind(e) {
+  if (e.axis === "saturation-probe") return "saturation probe";
+  if (Array.isArray(e.goods_text) && e.goods_text.length) return "goods-narrowed";
+  if (e.provenance === "mark" && String(e.predicate) !== "default") return "identical mark";
+  if (e.unsupported === true) return "unsupported (a disclosure, not a search)";
+  return null;
+}
+
+export function planShape(plan) {
+  const open = [], waiting = [], other = [], unexpected = [];
+  for (const e of plan.entries ?? []) {
+    if (awaitsReadingTurn(e.when)) { waiting.push(e); continue; }
+    if (e.when) { other.push(e); continue; }
+    const kind = openKind(e);
+    if (kind) open.push({ e, kind }); else unexpected.push(e);
+  }
+  const byKind = {};
+  for (const { kind } of open) byKind[kind] = (byKind[kind] ?? 0) + 1;
+  const byAxis = {};
+  for (const e of waiting) byAxis[e.axis] = (byAxis[e.axis] ?? 0) + 1;
+  // EVERY entry by axis, waiting or not — the comparison against a frozen plan needs the whole
+  // population per lane, not only the part that waits.
+  const byAxisAll = {};
+  for (const e of plan.entries ?? []) byAxisAll[e.axis] = (byAxisAll[e.axis] ?? 0) + 1;
+  return { total: (plan.entries ?? []).length, open: open.length, byKind,
+    waiting: waiting.length, byAxis, byAxisAll, parentGated: other.length,
+    unexpected: unexpected.map((e) => `${e.axis}/${e.predicate}`) };
+}
+
+function inputsFor(runDir) {
+  const P = paths(runDir);
+  const need = (label, p) => {
+    if (!existsSync(p)) {
+      console.error(`register-plan-shape: ${label} is not in this run directory — looked for ${p}.`);
+      console.error("  Without it the compile would be over a population this run never had. Refusing.");
+      process.exit(2);
+    }
+    return p;
+  };
+  let manifest = parseVariantManifestModel(readFileSync(need("the variant manifest", P.variantManifestModel), "utf8"));
+  // ── THE CLIENT'S OWN ELEMENT, IF THIS RUN VERIFIED THAT IT OWNS IT ──────────────────────────────
+  //
+  // MISSING FROM THE FIRST CUT, and it mattered on the first real run this tool was pointed at. Where
+  // a run verified that the client owns an element of its own mark, that element leaves the conflict
+  // analysis: the compile is handed the element so its form band becomes unreachable rather than
+  // merely unasked-for, and a single confirmation question is appended in its place. On a matter that
+  // is a house mark plus a tagline, that element can account for more than half the questions — so a
+  // recompile that skipped it reported a population the run could never have had, in the direction of
+  // too many. The condition is the receipt's own, exactly as the run applies it: an absent,
+  // unreadable or unverified receipt excludes nothing, which is the safe direction and the one a
+  // client is never harmed by.
+  let houseElement = null, houseConfirmation = null;
+  try {
+    const receipt = readJson(driverDir(runDir, HOUSE_ELEMENT_RECEIPT));
+    if (receipt?.verified === true) {
+      const r = excludeHouseElement(manifest, { element: receipt.element, remainder: receipt.remainder });
+      // REFUSED IS NOT APPLIED. The receipt answers who owns the element; the transform answers whether
+      // this manifest's mark survives the cut. The run requires both, so this does too.
+      if (!r.refused) { manifest = r.manifest; houseConfirmation = r.confirmation; houseElement = receipt.element; }
+    }
+  } catch { /* no receipt — nothing was verified, so nothing is excluded */ }
+  const scope = readJson(need("the instructed scope", driverDir(runDir, "instructed-scope.json")));
+  const profile = readJson(need("the customer profile", driverDir(runDir, "profile.json")));
+  // OPTIONAL INPUTS ARE REPORTED, NOT DEFAULTED IN SILENCE. Each one that is absent removes questions
+  // from the recompile, and an absence nobody is told about is indistinguishable from a compiler that
+  // stopped asking them. A preserved run directory that lost an input recompiles exactly like a
+  // compiler that retired a lane, and those are different facts.
+  //
+  // EACH LINE SAYS HOW MUCH, not that something is missing. The first cut said the form band "compiles
+  // to nothing" — true, and read by a careful reader as a large number on every register. It is a large
+  // number only where the register has no OR surface. That wording was acted on before it was measured.
+  const absent = [];
+  let form = null;
+  if (existsSync(P.formNeighbourhood)) form = readJson(P.formNeighbourhood);
+  else {
+    // QUANTIFIED, AND BY THIS REGISTER, because the qualitative version of this line was misleading and
+    // was acted on. The form band is OR-BATCHED at the provider's declared width, so on a register with
+    // a wide OR surface the WHOLE band — eight terms or forty — compiles to one question plus one
+    // wildcard fringe. Measured: 40 terms cost 2 questions on a 500-wide register and 41 on one with no
+    // OR surface. "A whole lane compiles to nothing" reads as a large number on every register and is
+    // one only on the narrow ones.
+    const w = planMaxOrWidth(registerCapabilities());
+    absent.push(`form-neighbourhood.json — the form band does not compile. On this register `
+      + `(OR width ${w}) that is about ${w > 1 ? "2 questions however many terms the band held" : "one question per term in the band"}.`);
+  }
+  if (!existsSync(driverDir(runDir, HOUSE_ELEMENT_RECEIPT)))
+    absent.push(`${HOUSE_ELEMENT_RECEIPT} — no element was excluded, so the client's own element is searched as a conflict`);
+  if (!(manifest.goods_words ?? []).length)
+    absent.push("goods_words on the manifest — no goods-narrowed question can compile from it");
+
+  // THE RUN'S OWN RESOLVERS, NOT THE RAW FIELDS. An earlier cut read `scope.classes` and
+  // `scope.jurisdictions` straight off the file. Two of those reads are wrong:
+  //
+  //   · A matter that instructed NO class falls back to the customer profile's defaults, so the raw
+  //     read compiles an unscoped plan where the run compiled a scoped one — and a plan is always
+  //     class-scoped, so the compiler would refuse outright rather than differ quietly.
+  //   · Territories come off a shared ladder that reads the geography stamp, not off the field alone.
+  //
+  // MEASURED, because the obvious third claim is not true and was in this comment until it was
+  // checked: a worldwide matter records `jurisdictions: null` and the resolver answers `[]`, which is
+  // the SAME answer the raw read gives, and `[]` is correct — worldwide means no region clause at all.
+  // The resolvers earn their place on the two cases above, not on that one.
+  //
+  // The whole scope object is handed over rather than two fields, so the ladder sees the stamp it reads.
+  const job = { ...scope, jobKey: "shape-read" };
+  return {
+    manifest,
+    job: { ...job, classes: inScopeClassList(job, profile), jurisdictions: registerJurisdictions(job, profile) },
+    addedClasses: frameIdentifiedClassRows(runDir),
+    form,
+    houseElement,
+    __houseConfirmation: houseConfirmation,
+    __absent: absent,
+    capabilities: registerCapabilities(),
+    unavailableOffices: registerUnavailableOffices(),
+  };
+}
+
+function main() {
+  const runDir = process.argv[2];
+  if (!runDir) {
+    console.error("usage: node scripts/register-plan-shape.mjs <run-directory>");
+    console.error("  Prints how many register questions run unasked and how many wait. Counts only —");
+    console.error("  no marks, no terms, no identifiers. Writes nothing into the run directory.");
+    process.exit(2);
+  }
+  const dir = resolve(runDir);
+  if (!existsSync(dir)) { console.error(`register-plan-shape: no such run directory: ${dir}`); process.exit(2); }
+
+  const inputs = inputsFor(dir);
+  const plan = compileRegisterPlan(inputs);
+  // THE ONE QUESTION THE EXCLUDED ELEMENT STILL OWES, appended after the compile exactly as the run
+  // appends it: the element leaves the conflict analysis, and in its place the plan asks once whether
+  // the client's own registrations are there. It is not derived from the manifest, so it cannot come
+  // out of the compile — and a recompile that dropped it would under-count by one on every run that
+  // excluded an element.
+  if (inputs.__houseConfirmation && plan?.entries) {
+    const used = new Set(plan.entries.map((e) => e.qid));
+    plan.entries.push({ ...inputs.__houseConfirmation,
+      qid: mintSupplementalQid({ prefix: "house", term: inputs.__houseConfirmation.term, used }),
+      nice_classes: plan.nice_classes ?? [], regions: plan.regions ?? [] });
+  }
+  const s = planShape(plan);
+
+  // WHICH REGISTER THIS BOX IS CONFIGURED FOR, because the shape depends on it — a provider that cannot
+  // express a predicate stamps the entry unsupported, and unsupported entries are counted here. A
+  // number read against the wrong provider is not this run's shape. The vendor name is vocabulary this
+  // repository already publishes; nothing about the matter is.
+  // ── AND WHAT THIS RUN ACTUALLY FROZE, BESIDE IT ────────────────────────────────────────────────
+  //
+  // The recompile answers "what would today's engine ask". On its own that number is uninterpretable:
+  // the first real run this tool saw compiled 44 questions against 129 in the frozen plan, and nobody
+  // could say from one number whether that was a deliberate removal, a defect, or a difference in the
+  // inputs. Printed side by side and split by axis, the same two numbers say WHERE the population
+  // moved, which is the question a reader actually has. Still counts only, and the frozen plan is read,
+  // never rewritten.
+  // THE CATCH IS NARROWED TO THE FILE BEING ABSENT, deliberately. A blanket catch here swallowed a
+  // ReferenceError on the first cut — the path was read off a variable that is not in scope in this
+  // function — and the comparison silently never printed, reading exactly like a run with no frozen
+  // plan. An absent artifact is a fact about the run; anything else is a fault in this script and must
+  // say so rather than look like one.
+  let frozen = null;
+  const frozenPath = paths(dir).registerPlan;
+  if (existsSync(frozenPath)) frozen = planShape(JSON.parse(readFileSync(frozenPath, "utf8")));
+
+  if (inputs.__absent?.length) {
+    console.log("  INPUTS THIS RUN DIRECTORY DOES NOT CARRY — each one lowers the counts below:");
+    for (const a of inputs.__absent) console.log(`      · ${a}`);
+    console.log("");
+  }
+  console.log(`  register configured here    ${inputs.capabilities?.id ?? "none — CLEAROTRON_DATABASE is unset"}`);
+  console.log(`  questions compiled          ${s.total}`);
+  console.log(`  run without being asked for ${s.open}`);
+  for (const [kind, n] of Object.entries(s.byKind).sort()) console.log(`      ${String(n).padStart(4)}  ${kind}`);
+  console.log(`  waiting for the reading turn ${s.waiting}`);
+  for (const [axis, n] of Object.entries(s.byAxis).sort()) console.log(`      ${String(n).padStart(4)}  ${axis}`);
+  if (s.parentGated) console.log(`  waiting on a parent question ${s.parentGated}   (the crowd-gated fringe)`);
+  if (plan.added_classes?.length) console.log(`  classes the frame added      ${plan.added_classes.length}`);
+
+  if (frozen) {
+    console.log(`\n  THIS RUN'S OWN FROZEN PLAN, for comparison — what it asked, not what today would ask:`);
+    console.log(`  questions frozen            ${frozen.total}   (recompiled now: ${s.total})`);
+    const axes = [...new Set([...Object.keys(frozen.byAxis), ...Object.keys(s.byAxis),
+      ...(frozen.byAxisAll ? Object.keys(frozen.byAxisAll) : []), ...Object.keys(s.byAxisAll ?? {})])].sort();
+    for (const a of axes) {
+      const was = frozen.byAxisAll?.[a] ?? 0, now = s.byAxisAll?.[a] ?? 0;
+      if (was || now) console.log(`      ${String(was).padStart(4)} -> ${String(now).padStart(4)}  ${a}`);
+    }
+    if (frozen.total !== s.total) {
+      console.log(`\n  The two populations differ by ${Math.abs(frozen.total - s.total)}. Gating marks an entry WAITING,`);
+      console.log("  it never removes one, so a difference here is the compiler's, not the gate's — the axis");
+      console.log("  rows above say which lane moved. Expected where a lane was deliberately retired.");
+    }
+  }
+
+  // THE PROPERTY, STATED AS A VERDICT the reader does not have to derive from the numbers above.
+  // `unexpected` is the whole of it: an entry that neither waits nor is one of the three sanctioned
+  // kinds is a question this plan would ask in the same breath as the identical mark.
+  if (s.unexpected.length) {
+    console.log(`\n  NOT HELD — ${s.unexpected.length} question(s) run unasked that are none of the three kinds:`);
+    for (const u of [...new Set(s.unexpected)].sort()) console.log(`      ${u}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log("\n  HELD — every question outside the identical-mark, saturation and goods-narrowed set waits.");
+}
+
+if (isEntrypoint(import.meta.url)) main();