clearotron 0.3.2 → 0.3.3-beta.1

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/repo-writes.mjs

@@ -11,7 +11,7 @@
 // attribute the red that produces: it surfaces in a file whose diff is empty, on another branch, in
 // another agent's session, and it is intermittent — the three properties that make a defect expensive.
 //
-// `doctor-refuses-what-cannot-run.test.mjs:70` already states the rule in prose: moving the real
+// `doctor-refuses-what-cannot-run.test.mjs` already states the rule in prose: moving the real
 // `portal-ui/dist` aside "would have been shorter and is wrong". Prose is not an instrument. This is.
 //
 // THE RULE IS ABSOLUTE, AND IT IS NOT A QUESTION ABOUT `git`. Tracked, untracked and ignored are the

package/scripts/report-sections-render-check.mjs

@@ -27,6 +27,7 @@ import { fileURLToPath } from 'node:url'
 import { reapOnExit } from '../shared/reap-on-exit.mjs'
 import { browserRun } from '../shared/browser-temp-root.mjs'
 import { prepareReportForEmbed } from '../driver/portal-report.mjs'
+import { scrollAfterPress } from '../shared/scroll-settle.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(HERE, '..')
@@ -225,11 +226,14 @@ for (const width of [1440, 400]) {
     const target = 2
     const before = await value('window.scrollY')
     await value(`document.querySelectorAll('nav.report-sections .report-section')[${target}].click()`)
-    let settled = before, last = -1
-    for (let i = 0; i < 40 && settled !== last; i++) { last = settled; await wait(150); settled = await value('window.scrollY') }
+    // The jump is animated and starts on the browser's own schedule, so the page is given a deadline to
+    // START moving before it is read as still. Waiting only for the position to settle answers "it never
+    // moved" for a scroll that had not yet begun — see scroll-settle.mjs.
+    const { moved, y: settled, waitedMs } = await scrollAfterPress({ read: () => value('window.scrollY'), wait, from: before })
     const s = await strip()
     const foot = await atFoot()
-    if (!(settled > before)) fail.push(`${at}: pressing "${SECTIONS[target]}" did not move the page`)
+    if (!moved) fail.push(`${at}: pressing "${SECTIONS[target]}" did not move the page in ${waitedMs}ms`)
+    else if (!(settled > before)) fail.push(`${at}: pressing "${SECTIONS[target]}" left the page at ${settled}, not below ${before}`)
     else if (filled(s) !== (foot ? SECTIONS.length : target + 1)) fail.push(`${at}: after the jump to "${SECTIONS[target]}" the strip reads "${s}"`)
     else ok.push(`${at}: a press jumps to "${SECTIONS[target]}" and marks it — ${s}`)
   }

package/scripts/score.mjs

@@ -245,9 +245,15 @@ function scopeOf(runDir, ref) {
   const instructed = readJson(driverDir(runDir, "instructed-scope.json"));
   const cls = instructed?.classes ?? instructed?.nice_classes ?? null;
   const terr = instructed?.jurisdictions ?? instructed?.territories ?? null;
+  // A worldwide request is recorded as a MODE, not a list entry: intake takes the word off the territory
+  // list and stamps `geography.mode` (enqueue-schema.mjs, GEOGRAPHY_MODES). So a worldwide run carries no
+  // territories, and falling through to the reference's own scope would score the run against what the
+  // lawyer wrote there instead of what the run was asked. The run's record wins, stated as the mode.
+  const worldwide = instructed?.geography?.mode === "worldwide";
   return {
     classes: Array.isArray(cls) && cls.length ? cls.map(String) : (ref.scope?.classes ?? []).map(String),
-    territories: Array.isArray(terr) && terr.length ? terr.map(String) : (ref.scope?.territories ?? []).map(String),
+    territories: Array.isArray(terr) && terr.length ? terr.map(String)
+      : worldwide ? ["worldwide"] : (ref.scope?.territories ?? []).map(String),
   };
 }
 

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?

package/shared/scroll-settle.mjs

@@ -0,0 +1,67 @@
+// 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
+// scroll-settle.mjs — after a press, wait for the page to START moving, then for it to STOP.
+//
+// ── WHY A SETTLE WAIT ALONE IS NOT ENOUGH, WHICH IS THE WHOLE POINT ──────────────────────────────
+//
+// A check that presses something and reads the scroll position wants the position the page came to
+// rest at. The obvious shape reads twice and stops when two reads agree:
+//
+//     let settled = before, last = -1
+//     for (let i = 0; i < 40 && settled !== last; i++) { last = settled; await wait(150); settled = await read() }
+//
+// That is a settle detector, and it cannot tell a page that has STOPPED from one that has not STARTED.
+// A smooth scroll begins on the browser's own schedule; when it has not begun by the first read, the
+// first two reads are both the position before the press, they agree, the loop ends, and the caller is
+// told the page never moved. The page then moves, a moment after nobody is looking.
+//
+// This failed once in continuous integration on a branch whose range touched no part of that page, and
+// passed on re-run with nothing changed — the signature of a measurement that races the thing it
+// measures rather than a defect in the page.
+//
+// So the wait is in two parts, and only the first is new: hold until the position CHANGES, giving up at
+// a deadline; then hold until it stops changing. A page that does not move is now told apart from one
+// that has not moved yet by how long it was given — which is why the deadline is returned, for the
+// caller to name in its failure. A caller that says only "it did not move" leaves the next reader
+// unable to tell a real defect from this race.
+//
+// PURE, with the read and the clock injected, so a test drives every path without a browser: a wait
+// that can only be exercised against a real renderer cannot be shown to fail.
+
+// Long enough that a scroll which has not begun by then is not merely late. The press is animated, so
+// this is a deadline for the FIRST movement, never for the whole journey — the settle below carries that.
+export const MOVE_DEADLINE_MS = 4000;
+const STEP_MS = 150;
+const QUIET_STEPS = 40;
+
+/**
+ * Wait for a press to move the page, then for the movement to stop.
+ *
+ * @param {object} o
+ * @param {() => Promise<number|null>} o.read     reads the scroll position now
+ * @param {(ms: number) => Promise<void>} o.wait  sleeps
+ * @param {number} o.from                         the position before the press
+ * @param {() => number} [o.now]                  the clock the deadline is measured on
+ * @returns {Promise<{moved: boolean, y: number|null, waitedMs: number}>}
+ *   `moved` false means the position never changed within `waitedMs` — the page was given that long.
+ */
+export async function scrollAfterPress({ read, wait, from, now = Date.now,
+  deadlineMs = MOVE_DEADLINE_MS, stepMs = STEP_MS, quietSteps = QUIET_STEPS }) {
+  const started = now();
+  let y = from;
+  // FIRST, THAT IT MOVED AT ALL. The deadline is what makes the answer below a finding rather than a race.
+  while (y === from) {
+    if (now() - started >= deadlineMs) return { moved: false, y, waitedMs: now() - started };
+    await wait(stepMs);
+    y = await read();
+  }
+  // THEN, WHERE IT CAME TO REST. `last` starts at a value no read returns, so the position is always
+  // read at least once more: the first changed position is mid-animation, not the answer.
+  let last = null;
+  for (let i = 0; i < quietSteps && y !== last; i++) {
+    last = y;
+    await wait(stepMs);
+    y = await read();
+  }
+  return { moved: true, y, waitedMs: now() - started };
+}