clearotron 0.3.2 → 0.3.3-beta.0

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();

package/scripts/release-note-required.mjs

@@ -53,6 +53,23 @@
 // reach a number, which is the failure this repository has already paid for once. The remaining half is
 // a person reading the diff and asking what a lawyer would want told.
 //
+// ── ONLY A PULL REQUEST'S OWN COMMITS ARE READ, AND THAT IS THE ONLY READING THAT COUNTS ─────────────
+//
+// The per-commit question below does not survive a squash. A squash commit adds every note the branch
+// carried, so it "carries its own note", and any prose release line it inherited from a folded commit is
+// excused. Measured on a simulated squash of an integration branch whose one offending commit this guard
+// refused commit by commit: over the squash it passed. So this guard is a gate only where it reads the
+// commits a pull request brings, one at a time, before they are folded. That is how CI runs it, on the
+// pull request's range; on a push to main the range is empty and it says so rather than passing quietly.
+//
+// AND POINTED AT MAIN'S OWN LINE IT SAYS SO, ON EVERY ANSWER. A range with a commit on `origin/main`'s
+// first-parent history is reading the squashes themselves. That reading still catches a squash that
+// shipped code with no note at all (an arm replays one), so it is not refused. It cannot catch a prose
+// line a squash inherited, and its pass is therefore not the per-commit answer. So every answer over
+// that line carries the sentence that says which of the two it can give. An audit of what shipped
+// reads the pull requests that brought it, never the squashes they became. An arm pins
+// both readings side by side, and that CI runs this on the pull request's range and nowhere else.
+//
 // ── A DECLINATION ANSWERS FOR ITS OWN COMMIT, NOT FOR THE RANGE ──────────────────────────────────────
 //
 // This read one `Release-note: none` anywhere in the range as the answer for all of it, so a pack of
@@ -270,7 +287,7 @@ function main() {
   // have failed, and would have reported the acceptance met for the life of the branch.
   const head = argAfter("--head") || "HEAD";
   const git = (...a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 1 << 28 });
-  let changed, commits, atHead;
+  let changed, commits, atHead, onMainLine = [];
   try {
     changed = git("diff", "--name-only", `${base}...${head}`).split("\n").filter(Boolean);
     // THE BRANCH'S OWN COMMITS. On a pull request the range can reach commits main already carries, from
@@ -282,6 +299,12 @@ function main() {
       catch { /* no origin/main in this clone: the range as given */ }
     }
     const shas = git("rev-list", "--no-merges", "--reverse", `${base}..${head}`, ...exclude).split("\n").filter(Boolean);
+    // MAIN'S OWN LINE IS NAMED (see the header): a squash there excuses the prose it inherited. Asked
+    // only where main is known; a clone without it keeps the range as given.
+    let mainKnown = false;
+    try { git("rev-parse", "--verify", "-q", "origin/main^{commit}"); mainKnown = true; } catch { /* not known here */ }
+    const mainLine = mainKnown ? new Set(git("rev-list", "--first-parent", "origin/main").split("\n").filter(Boolean)) : new Set();
+    onMainLine = shas.filter((sha) => mainLine.has(sha));
     commits = shas.map((sha) => ({
       sha,
       subject: git("log", "-1", "--format=%s", sha).trim(),
@@ -302,6 +325,14 @@ function main() {
   catch (e) { console.error(`release-note-required: cannot read the shipped file list: ${e.message}`); process.exit(2); }
   if (!files.length) { console.error("release-note-required: package.json names no shipped files, so this cannot look"); process.exit(2); }
 
+  if (!commits.length) {
+    // NOTHING TO READ IS SAID, NOT IMPLIED. On a push to main every commit is already on main, so the range
+    // is empty by construction: the pull request that brought them was read before they were squashed.
+    console.log(`release-note-required: no commit in ${base}..${head} that main does not already hold, so there `
+      + "is nothing here to read. This guard answers for a pull request's own commits, one by one, and main's "
+      + "history is never read.");
+    return;
+  }
   const { visible, notes, declined, withdrawals, owed } = commitVerdicts({ commits, files, atHead });
   console.log(`release-note-required: ${changed.length} changed file(s) against ${base}`
     + `${head === "HEAD" ? "" : ` (head ${head})`}; `
@@ -309,6 +340,12 @@ function main() {
     + `${withdrawals.length ? `; ${withdrawals.length} answered by a note the range withdrew` : ""}`);
   // PER COMMIT, SAID AS PER COMMIT. "no note, declared on purpose" read as a verdict on the range, and beside
   // a range that carries a note it told a reader skimming the output that none went out. Found in review.
+  if (onMainLine.length) {
+    console.log(`  NOT THE GATE'S READING: ${onMainLine.length} commit(s) read here are on main's own line (first `
+      + `${onMainLine[0].slice(0, 7)}), so they are squashes. Over a squash this finds a change that shipped with no `
+      + "note at all; it cannot find a prose release line the squash inherited, so a pass here is not the "
+      + "per-commit answer. The gate is the pull request's own reading, before the squash.");
+  }
   for (const d of declined) console.log(`  ${d.sha.slice(0, 7)} declines a note of its own, on purpose: ${d.reason}`);
   // AN EXCUSED COMMIT IS PRINTED, WITH THE SHA THAT EXCUSED IT. A pass this check reached by reading
   // another commit's decision is one a person may want to disagree with, and they cannot if it is silent.

package/scripts/settings-render-check.mjs

@@ -600,6 +600,27 @@ if (await open('/portal/people', "document.querySelector('table.data tbody tr')"
     };
   })()`
 
+  // The bar's reading, then the two ways a reader moves the table with it: the table moved by a finger
+  // (the thumb follows) and a press at the track's right end (the table follows). The table is put back
+  // at its start afterwards so the screenshots below show it as a reader first meets it.
+  const pinnedBarProbe = `(async () => {
+    window.scrollTo(0, 0); await new Promise((r) => setTimeout(r, 200));
+    const wrap = document.querySelector('.table-wrap'); const bar = document.querySelector('.pinned-bar');
+    const thumb = bar && bar.querySelector('.pinned-thumb'); const track = bar && bar.querySelector('.pinned-track');
+    if (!wrap || !bar || !thumb || !track) return { wrap: !!wrap, bar: !!bar, thumb: !!thumb, track: !!track };
+    const b = bar.getBoundingClientRect(), t0 = thumb.getBoundingClientRect();
+    const out = { bar: true, onScreen: b.top >= 0 && b.bottom <= innerHeight + 1, barH: Math.round(b.height),
+      thumbW: Math.round(t0.width), thumbH: Math.round(t0.height), nativeBarH: wrap.offsetHeight - wrap.clientHeight };
+    wrap.scrollLeft = 200; await new Promise((r) => setTimeout(r, 200));
+    out.thumbFollowed = Math.round(thumb.getBoundingClientRect().left - t0.left);
+    const tr = track.getBoundingClientRect();
+    track.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, clientX: tr.right - 2, clientY: tr.top + 4, pointerId: 1 }));
+    await new Promise((r) => setTimeout(r, 200));
+    out.tableAtEnd = Math.round(wrap.scrollWidth - wrap.clientWidth - wrap.scrollLeft);
+    wrap.scrollLeft = 0; await new Promise((r) => setTimeout(r, 200));
+    return out;
+  })()`
+
   for (const [label, width] of [['desktop', 1280], ['phone', 400]]) {
     await cmd('Emulation.setDeviceMetricsOverride', { width, height: 900, deviceScaleFactor: 1, mobile: width < 700 })
     await sleep(350)
@@ -615,6 +636,21 @@ if (await open('/portal/people', "document.querySelector('table.data tbody tr')"
     ok(p.pageScrollsSideways === false,
       `${label}: the page itself does not scroll sideways — the table's overflow stays in the table`)
     console.log(`    ${label}: wrapper ${p.wrapW}px, table ${p.tableW}px, wrapper scrollable: ${p.scrollable}`)
+    // — A TABLE THAT CONTINUES SHOWS ITS SCROLLBAR, on this screen as on the Clearances list. The same
+    // pinned bar is wired on both; the Clearances check asserts it and this one did not, so the bar here
+    // was drawn and unmeasured. Where the table fits there is no bar: a bar with nothing to scroll is a
+    // control that does nothing.
+    const pin = (await evalIn(pinnedBarProbe)) ?? {}
+    console.log(`    ${label}: pinned bar ${JSON.stringify(pin)}`)
+    if (p.scrollable) {
+      ok(pin.bar && pin.onScreen, `${label}: the table continues past its edge, and its sideways bar is on screen`)
+      ok(pin.nativeBarH === 0, `${label}: only the pinned bar is drawn, not the table's own beside it`)
+      ok(pin.barH >= 9 && pin.thumbH >= 8 && pin.thumbW >= 24, `${label}: the pinned bar is drawn at a size a reader can see (${pin.barH}px, thumb ${pin.thumbW}×${pin.thumbH})`)
+      ok(pin.thumbFollowed > 0, `${label}: the thumb follows the table`)
+      ok(pin.tableAtEnd <= 1, `${label}: pressing the end of the track moves the table to its end`)
+    } else {
+      ok(pin.bar === false, `${label}: the table fits, and no sideways bar is drawn`)
+    }
     await cmd('Emulation.clearDeviceMetricsOverride', {})
     for (const theme of ['light', 'dark']) {
       await setTheme(theme)

package/scripts/travelling-predicates.mjs

@@ -103,7 +103,7 @@ function isPlumbing(node, child) {
   //
   //     const wrote   = files.length ? files.some(…) : null;              gateway.mjs (by name)
   //     const inScope = scope.size   ? tokens.some(…) : (…);              reasoning-tripwires.mjs:82
-  //     const reached = b.layer === "national" ? (…) : regions.some(…);   register-plan.mjs:340 resolveRegions
+  //     const reached = b.layer === "national" ? (…) : regions.some(…);   resolveRegions() in register-plan.mjs
   //
   // The climb stopped at the ternary and reported "unresolved", which reads as a limit of the pattern
   // and was a missing case. All three are `local` — the boolean is bound and read in the same function.

package/shared/identifier-scan.mjs

@@ -116,14 +116,31 @@ export const ALLOWED_CONTEXT =
  * Escapes become spaces before matching, which fixes the class rather than that one line: `\n`, `\t`,
  * `\r` and `\\` in any quoted source, HTML numeric and named entities, and `%20`-style percent escapes.
  * A boundary in the SOURCE is a boundary in the TEXT, whatever the encoding.
+ *
+ * READ AS A LEXER READS THEM, and two misreadings of Windows paths to Node's executable are why
+ * (2026-09-22). Both reported a three-letter mark, spelled by the letters after the path's last `\n`,
+ * that was not there:
+ *
+ *   - `\\` is consumed as a pair, in the same left-to-right pass as the others. Replaced in a separate
+ *     pass after `\n`, the second backslash of a pair was read as the start of `\n`.
+ *   - A Windows path written raw — drive letter, colon, ONE backslash, as in a comment, a doc or a TOML
+ *     literal — holds no escapes, so its backslashes are left as separators. A separator is already a
+ *     boundary, and reading `\n` there also broke a lowercase name that starts with n, r, t, f or v.
+ *     The escaped form (`C:\\`) is not a raw path, so an escape beside a path in a string is still read.
  */
-export const unescapeBoundaries = (line) =>
-  line
-    .replace(/\\[nrtfv0]/g, " ")
-    .replace(/\\\\/g, " ")
-    .replace(/\\u[0-9a-fA-F]{4}|\\x[0-9a-fA-F]{2}/g, " ")
+const BACKSLASH_ESCAPE = /\\(?:[\\nrtfv0]|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2})/g;
+const RAW_WINDOWS_PATH = /(?<![A-Za-z0-9])[A-Za-z]:\\(?!\\)[^"'`<>|?*\r\n]*/g;
+
+export const unescapeBoundaries = (line) => {
+  let out = "", at = 0;
+  for (const m of line.matchAll(RAW_WINDOWS_PATH)) {
+    out += line.slice(at, m.index).replace(BACKSLASH_ESCAPE, " ") + m[0];
+    at = m.index + m[0].length;
+  }
+  return (out + line.slice(at).replace(BACKSLASH_ESCAPE, " "))
     .replace(/&(?:#\d+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g, " ")
     .replace(/%[0-9a-fA-F]{2}/g, " ");
+};
 
 /**
  * Does this entry fire on this line?