clearotron 0.3.2-beta.7 → 0.3.2-beta.8

package/scripts/freeze-example-run.mjs

@@ -29,9 +29,11 @@
 //   _driver/run.jsonl        the event log
 //   _driver/stage-inputs/    what each stage was handed
 //   _history/                pre-reopen snapshots
-// Dropping the telemetry drops `meta.tokens` (driver/publish/index.mjs:1136 rollupTokens — the only consumer of
-// rollupTokens). That is the one difference step 5 is told to expect, and it says so out loud rather than
-// normalising it away in silence.
+// Dropping the telemetry drops `meta.tokens` (driver/publish/index.mjs rollupTokens — the only consumer of
+// rollupTokens), and with it the record of which models served the run (servedModels in
+// driver/tokens.mjs): `servedModels` on meta.json and report-data.json, and the one line that closes the
+// report's footer. Those are the differences step 5 is told to expect, and it says so out loud rather
+// than normalising them away in silence.
 //
 // WHAT THIS SCRIPT DOES NOT DO
 // It does not decide the sample is publishable. It greps for the shapes that must never leave the VM
@@ -59,21 +61,21 @@ const FROZEN_FILES = [
   { path: "audit.md", why: "publish/index.mjs:1022 auditMd, the audit workbook source" },
   { path: "findings.json", why: "publish/index.mjs:715 readStore, the per-finding machine contract" },
   { path: "status.json", why: "publish/index.mjs:913 machineLedgerNote + markName" },
-  { path: "case-law-findings.md", why: "publish/index.mjs:849 clPath, the case-law section" },
-  { path: "common-law-grid.json", why: "publish/index.mjs:973 commonLawJoinedTerms, common-law coverage" },
+  { path: "case-law-findings.md", why: "publish/index.mjs:875 clPath, the case-law section" },
+  { path: "common-law-grid.json", why: "publish/index.mjs:1006 commonLawJoinedTerms, common-law coverage" },
   // publish/index.mjs — the _driver sidecars it reads by name
   { path: "_driver/receipts.json", why: "publish/index.mjs:761 fetchReceipts" },
   { path: "_driver/senior-rights.json", why: "publish/index.mjs:787 seniorRights" },
   { path: "_driver/verdict.json", why: "publish/index.mjs:792 verdictInfo" },
   { path: "_driver/framework.json", why: "publish/index.mjs, the frozen band vocabulary the run was rated under" },
-  { path: "_driver/register-plan.json", why: "publish/index.mjs:820 scopeBasis" },
-  { path: "_driver/instructed-scope.json", why: "publish/index.mjs:821 searchedJurisdictions, the fallback for register-plan" },
-  { path: "_driver/enforcer-signals.json", why: "publish/index.mjs:861 esPath" },
-  { path: "_driver/predelivery-lint.json", why: "publish/index.mjs:170 lintSink" },
-  { path: "_driver/escalation-state.json", why: "publish/index.mjs:171 escSink" },
-  { path: "_driver/reasoning-integrity.json", why: "publish/index.mjs:898 integritySink" },
-  { path: "_driver/corrections-state.json", why: "publish/index.mjs:172 correctionsSink" },
-  { path: "_driver/search-policy.json", why: "publish/index.mjs:955 searchPolicy, level + stage label" },
+  { path: "_driver/register-plan.json", why: "publish/index.mjs:846 scopeBasis" },
+  { path: "_driver/instructed-scope.json", why: "publish/index.mjs:847 searchedJurisdictions, the fallback for register-plan" },
+  { path: "_driver/enforcer-signals.json", why: "publish/index.mjs:887 esPath" },
+  { path: "_driver/predelivery-lint.json", why: "publish/index.mjs:172 lintSink" },
+  { path: "_driver/escalation-state.json", why: "publish/index.mjs:173 escSink" },
+  { path: "_driver/reasoning-integrity.json", why: "publish/index.mjs:924 integritySink" },
+  { path: "_driver/corrections-state.json", why: "publish/index.mjs:174 correctionsSink" },
+  { path: "_driver/search-policy.json", why: "publish/index.mjs:987 searchPolicy, level + stage label" },
   { path: "_driver/profile.json", why: "publish/index.mjs reads the frozen profile; report-registry.mjs:42 republishRun, customer key" },
 ];
 
@@ -106,7 +108,7 @@ const KNOCKOUT_FILES = [
   // knockout report render empty (publish/knockout.mjs:140-155). Named by stages-knockout.mjs:32,41.
   { path: "_driver/register-counts.json", why: "publish/knockout.mjs:140-155 counted figures + the Register column" },
   { path: "_driver/register-records.json", why: "stages-knockout.mjs:41 the terms behind the close-variation axis" },
-  { path: "_driver/instructed-scope.json", why: "publish/index.mjs:821 searchedJurisdictions, the fallback for register-plan" },
+  { path: "_driver/instructed-scope.json", why: "publish/index.mjs:847 searchedJurisdictions, the fallback for register-plan" },
 ];
 
 /** The allowlist for a template. One place, so a new template cannot half-exist. */
@@ -162,7 +164,7 @@ const SCRUB = [
 // hides the next real difference.
 const VOLATILE = [
   { id: "issued", re: /\d{4}-\d{2}-\d{2} · \d{2}:\d{2} [A-Z]{2,5}/g, sub: "<issued>", why: "publish/index.mjs, the generation stamp in the firm locale" },
-  { id: "iso-timestamp", re: /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z/g, sub: "<ts>", why: "publish/index.mjs:666 asOf" },
+  { id: "iso-timestamp", re: /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z/g, sub: "<ts>", why: "publish/index.mjs:668 asOf" },
 ];
 
 // ── REWRITES — what is CHANGED on the way out, as opposed to what is refused ───────────────────────
@@ -226,8 +228,19 @@ const substituteVendorKey = (key) => {
 // meta.json keys the freeze is EXPECTED to change, with the reason. Anything else differing is a finding.
 const EXPECTED_META_DELTA = {
   tokens: "telemetry pruned — _driver/*.jsonl is the only source (driver/tokens.mjs:82)",
+  servedModels: "telemetry pruned — the attempt rows in _driver/*.jsonl are the only source (servedModels in driver/tokens.mjs)",
 };
 
+// THE SAME CAUSE, ON THE TWO OTHER SURFACES THAT SHOW IT. report-data.json carries `servedModels` beside the
+// report's content, and the page renders it as the scope section's closing line (render.mjs
+// servedModelsLine, class "servedby"). Only that key and that one paragraph are set aside, on both sides
+// and out loud; a difference anywhere else in either file is still a finding. The paragraph holds escaped
+// text and no markup, so the pattern cannot run past its own closing tag. It takes the whitespace before
+// the paragraph with it: the clearance page joins its scope parts with a line break and an indent, which
+// exists only because the line does.
+const EXPECTED_DATA_DELTA = ["servedModels"];
+const SERVED_LINE_RE = /\s*<p class="servedby"[^>]*>[^<]*<\/p>/g;
+
 // ── args ─────────────────────────────────────────────────────────────────────────────────────────────
 const argv = process.argv.slice(2);
 const flag = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; };
@@ -594,7 +607,27 @@ if (proofOk) {
       }
       continue;
     }
-    if (normalise(rawA) === normalise(rawB)) { note(`${name} identical (${rawB.length} bytes)`); continue; }
+    // The served-model record is set aside by name on both sides (EXPECTED_DATA_DELTA, SERVED_LINE_RE),
+    // and only when it is what differed does the note say so.
+    let sA = normalise(rawA), sB = normalise(rawB), aside = [];
+    if (/^report-data(?:-.+)?\.json$/.test(name)) {
+      let dA = null, dB = null;
+      try { dA = JSON.parse(rawA); dB = JSON.parse(rawB); } catch { dA = dB = null; }
+      if (dA && dB) {
+        aside = EXPECTED_DATA_DELTA.filter((k) => JSON.stringify(dA[k]) !== JSON.stringify(dB[k]));
+        for (const k of EXPECTED_DATA_DELTA) { delete dA[k]; delete dB[k]; }
+        sA = normalise(JSON.stringify(dA, null, 2)); sB = normalise(JSON.stringify(dB, null, 2));
+      }
+    } else if (name.endsWith(".html") && sA !== sB) {
+      const tA = sA.replace(SERVED_LINE_RE, ""), tB = sB.replace(SERVED_LINE_RE, "");
+      if (tA === tB) { aside = ["the footer's served-models line"]; sA = tA; sB = tB; }
+    }
+    if (sA === sB) {
+      note(aside.length
+        ? `${name} identical apart from ${aside.join(", ")}, which differs as expected — ${EXPECTED_META_DELTA.servedModels}`
+        : `${name} identical (${rawB.length} bytes)`);
+      continue;
+    }
     finding(`${name} differs between the source run and the frozen copy — the allowlist dropped an input the renderer reads`);
   }
 }

package/scripts/generated-files-are-current.mjs

@@ -53,6 +53,29 @@ export function treeState(root = ROOT) {
  * The alternative — dirtying a real generated file and restoring it — is a shared-file mutation, and
  * the test runner runs files in parallel, so it would be a race that reddens somebody else's arm.
  */
+/**
+ * Which paths differ between two `git status --porcelain` readings, named so a reader can see WHAT moved.
+ *
+ * A porcelain line is a two-character state, a space, and the path. Lines are compared as a multiset so
+ * a path whose STATE changed — staged to modified, say — is reported as having moved, and the paths are
+ * returned rather than a count, because two numbers agreeing is not the same as two sets agreeing.
+ */
+export function movedPaths(before, after) {
+  const bag = (s) => {
+    const m = new Map();
+    for (const line of String(s).split("\n")) {
+      if (!line.trim()) continue;
+      m.set(line, (m.get(line) ?? 0) + 1);
+    }
+    return m;
+  };
+  const [b, a] = [bag(before), bag(after)];
+  const out = new Set();
+  for (const [line, n] of a) if ((b.get(line) ?? 0) !== n) out.add(line.slice(3).trim() || line.trim());
+  for (const [line, n] of b) if ((a.get(line) ?? 0) !== n) out.add(line.slice(3).trim() || line.trim());
+  return [...out].sort();
+}
+
 export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree = () => treeState(root) } = {}) {
   const found = minters(dir);
   if (!found.length) return { found, stale: [], unreadable: [], wrote: [], empty: true };
@@ -60,6 +83,7 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
   const stale = [];
   const unreadable = [];
   const wrote = [];
+  const unattributable = [];
   for (const m of found) {
     // ── `--check` IS A CONTRACT, AND NOTHING WAS VERIFYING IT ──────────────────────────────────────
     //
@@ -73,13 +97,41 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
     // one ran, it wrote. THE LIMIT, SAID RATHER THAN LEFT: this catches the harmful inert form, the
     // one that silently repairs. A minter that ignores the flag and does nothing at all still reports
     // `current`, and no probe from out here can tell that from a file that really is current.
+    // ── "DID THE TREE MOVE" IS NOT "DID THIS PROCESS WRITE" ────────────────────────────────────────
+    //
+    // Those are the same question only where nothing else can write, and this probe does not run
+    // there. Inside the suite it is a subprocess of one test file while every other file in its shard
+    // runs beside it, deliberately unserialised — dropping `--test-concurrency=1` is what made the
+    // suite 2.4 times faster. So a neighbour writing anywhere in the repository moved the snapshot and
+    // this reported it as the minter having written.
+    //
+    // Measured: a commit whose whole diff was one stylesheet's phone-width rules and a release note
+    // failed here naming TWO minters, and the same bytes passed on a rerun. Two is the tell — a minter
+    // that ignores `--check` and re-mints leaves its repair in the tree, so the NEXT minter's `before`
+    // already carries it and the next one is not flagged. Both being named cannot come from either.
+    //
+    // So the accusation is made only where it can be: from a tree that was CLEAN when this minter
+    // started, where a change appearing during its run has no other author available. A tree that was
+    // already dirty is one where somebody else is writing, and the honest answer is that this probe
+    // could not look — which is this file's own rule one level in, since it already refuses to read a
+    // minter that could not look as a pass.
+    //
+    // THE LIMIT, SAID RATHER THAN LEFT: a neighbour that begins writing after a clean reading and
+    // before the minter exits is still attributed here. Closing that needs the probe to own the tree,
+    // which is a change to where it runs rather than to what it asks.
     const before = readTree();
     const r = spawnSync(process.execPath, [join(dir, m), "--check"], { cwd: root, encoding: "utf8" });
     const after = readTree();
     const out = ((r.stdout || "") + (r.stderr || "")).trim();
     if (before !== null && after !== null && before !== after) {
-      wrote.push({ m, out });
-      log(`  WROTE    ${m} (during --check)`);
+      const moved = movedPaths(before, after);
+      if (before.trim() === "") {
+        wrote.push({ m, out, moved });
+        log(`  WROTE    ${m} (during --check): ${moved.join(", ") || "the tree moved"}`);
+      } else {
+        unattributable.push({ m, moved });
+        log(`  ?        ${m} — the tree moved and this probe cannot say who moved it: ${moved.join(", ") || "paths unknown"}`);
+      }
       continue;
     }
     // 0 is current, 1 is stale, anything else is a minter that could not look — reported separately,
@@ -89,11 +141,11 @@ export function checkAll({ dir = HERE, root = ROOT, log = console.log, readTree
     unreadable.push({ m, out, code: r.status });
     log(`  ?        ${m} (exit ${r.status})`);
   }
-  return { found, stale, unreadable, wrote, empty: false, contractChecked: readTree() !== null };
+  return { found, stale, unreadable, wrote, unattributable, empty: false, contractChecked: readTree() !== null };
 }
 
 function main() {
-  const { found, stale, unreadable, wrote, empty, contractChecked } = checkAll();
+  const { found, stale, unreadable, wrote, unattributable, empty, contractChecked } = checkAll();
   if (empty) {
     console.error("generated-files-are-current: no scripts/mint-*.mjs found. Either they moved or the "
       + "naming changed — and a pass over nothing is not a pass.");
@@ -111,6 +163,19 @@ function main() {
       + `commit without the repair, and reports current over a check that did not happen. Fix the minter.`);
     process.exit(2);
   }
+  // BEFORE the staleness verdict, and exit 2 rather than 1: a tree moving under the probe means the
+  // staleness answers were read off a tree that was changing while they were taken, so "out of date" is
+  // not a claim this run has the standing to make either. Could-not-look is the whole verdict.
+  if (unattributable.length) {
+    console.error(`\n${unattributable.length} minter(s) ran while the tree was ALREADY dirty and it moved `
+      + `underneath them. This probe cannot say whether the minter wrote or something running beside it `
+      + `did, so it names neither. That is a could-not-look, not a pass and not an accusation.\n`);
+    for (const { m, moved } of unattributable) {
+      console.error(`  ${m} — moved: ${moved.join(", ") || "paths unknown"}`);
+    }
+    console.error(`\nRun it on a tree nobody else is writing to, and it will answer.`);
+    process.exit(2);
+  }
   if (unreadable.length) {
     console.error(`\n${unreadable.length} minter(s) could not look. That is not a pass; fix the minter first.`);
     process.exit(2);

package/scripts/settings-render-check.mjs

@@ -89,6 +89,20 @@ const server = createServer((req, res) => {
   if (path === '/portal/admin/config' && !wantsPage) return json(adminConfig)
   if (path === '/portal/api/about') return json(about)
   if (path === '/portal/admin/roster' && !wantsPage) return json({ customers: [{ key: 'northwind', name: 'Northwind Foods' }] })
+  // THE PEOPLE SCREEN'S OWN DATA. Rows with real-length values on purpose: the defect this screen was
+  // filed for is a second column cut off at a phone's right edge, and a table of empty rows cannot show
+  // it. The permission phrases are the product's own words, the longest of them included.
+  if (path === '/portal/admin/access' && !wantsPage) {
+    return json({
+      note: '',
+      unknownAccounts: [],
+      people: [
+        { email: 'rosa.venn@northwind.example', permissions: { run: true, manage: true }, accounts: '*', listed: true },
+        { email: 'imani.oduya@northwind.example', permissions: { run: true, manage: false }, accounts: ['northwind'], listed: true },
+        { email: 'peter.halvorsen@northwind.example', permissions: { run: false, manage: false }, accounts: ['northwind'], listed: true },
+      ],
+    })
+  }
   if (path === '/portal/login') {
     res.writeHead(200, { 'content-type': 'text/html' })
     return res.end(loginPage({ email: EMAIL, resetCommand: state.reset }))
@@ -176,11 +190,16 @@ async function setTheme(theme) {
 
 // A FULL-HEIGHT VIEWPORT, not a beyond-viewport capture: a beyond-viewport capture paints the sticky rail
 // and top bar where the 900px viewport put them.
-async function capture(name) {
+async function capture(name, width = 1280) {
   if (!shotDir) return
   await evalIn('window.scrollTo(0, 0)')
+  // THE WIDTH IS APPLIED BEFORE THE HEIGHT IS MEASURED. A narrow viewport reflows the page taller, and
+  // measuring first captures a page cut off at the fold — which is how a phone-width check ends up
+  // producing a picture that looks fine and shows half the screen.
+  await cmd('Emulation.setDeviceMetricsOverride', { width, height: 900, deviceScaleFactor: 1, mobile: width < 700 })
+  await sleep(250)
   const h = await evalIn('Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)') ?? 900
-  await cmd('Emulation.setDeviceMetricsOverride', { width: 1280, height: Math.max(900, h), deviceScaleFactor: 1, mobile: false })
+  await cmd('Emulation.setDeviceMetricsOverride', { width, height: Math.max(900, h), deviceScaleFactor: 1, mobile: width < 700 })
   await sleep(400)
   const shot = await cmd('Page.captureScreenshot', { format: 'png' })
   await cmd('Emulation.clearDeviceMetricsOverride', {})
@@ -544,6 +563,60 @@ for (const theme of ['light', 'dark']) {
   state.reset = null
 }
 
+// ── People, at a desktop width and a phone's ────────────────────────────────────────────────────────
+//
+// THE SCREEN NOTHING COULD DRAW. It was reported as clipping its Permissions column at 400px "with no
+// horizontal scroll offered", and the reading could not be settled from the source: the table sits in a
+// wrapper set to scroll and carries a 760px floor, and both were already true at the sha the report was
+// measured against. So either the scrollbar is an overlay one — real, invisible, and invisible in a
+// capture — or something else clipped it and has since changed. No check reached this screen, so nobody
+// could look. This is the looking.
+//
+// The rows carry real-length values deliberately. A table of empty rows cannot show a column being cut.
+console.log('\nPeople, at 1280 and at 400:')
+if (await open('/portal/people', "document.querySelector('table.data tbody tr')", 'People drew its table')) {
+  const peopleProbe = `(() => {
+    const wrap = document.querySelector('.table-wrap');
+    const table = document.querySelector('table.data');
+    const head = [...document.querySelectorAll('table.data thead th')].map((th) => th.innerText.trim());
+    const perm = [...document.querySelectorAll('table.data tbody tr')].map((tr) => tr.children[1]?.innerText.trim() ?? '');
+    return {
+      rows: document.querySelectorAll('table.data tbody tr').length,
+      head, perm,
+      // Does the wrapper actually have somewhere to scroll TO, and does it allow it?
+      scrollable: wrap ? wrap.scrollWidth > wrap.clientWidth + 1 : null,
+      overflowX: wrap ? getComputedStyle(wrap).overflowX : null,
+      wrapW: wrap ? Math.round(wrap.clientWidth) : null,
+      tableW: table ? Math.round(table.scrollWidth) : null,
+      // The page itself must NOT scroll sideways — that is the failure the clearances fix was about.
+      pageScrollsSideways: document.documentElement.scrollWidth > document.documentElement.clientWidth + 1,
+    };
+  })()`
+
+  for (const [label, width] of [['desktop', 1280], ['phone', 400]]) {
+    await cmd('Emulation.setDeviceMetricsOverride', { width, height: 900, deviceScaleFactor: 1, mobile: width < 700 })
+    await sleep(350)
+    const p = (await evalIn(peopleProbe)) ?? {}
+    ok(p.rows === 3, `${label}: the three people are drawn (saw ${p.rows})`)
+    // The heading is upper-cased by CSS, so innerText returns it that way — compare the word, not the casing.
+    ok(p.head?.[1]?.toLowerCase() === 'permissions', `${label}: the second column is still the permissions one (saw ${JSON.stringify(p.head)})`)
+    ok(p.perm?.every((t) => t.length > 0), `${label}: every row states an access (saw ${JSON.stringify(p.perm)})`)
+    // THE PROPERTY, not the pixel. A column wider than its wrapper is fine as long as the wrapper
+    // scrolls; it is a defect only when the overflow has nowhere to go, or when the PAGE takes it.
+    ok(p.overflowX === 'auto' || p.overflowX === 'scroll',
+      `${label}: the table's wrapper can scroll sideways (overflow-x: ${p.overflowX})`)
+    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}`)
+    await cmd('Emulation.clearDeviceMetricsOverride', {})
+    for (const theme of ['light', 'dark']) {
+      await setTheme(theme)
+      await capture(`people-${label}-${theme}`, width)
+    }
+    await setTheme('light')
+  }
+}
+
 // ── a browser whose storage refuses ──────────────────────────────────────────────────────────────────
 //
 // localStorage throws outright in a null-origin or locked-down document. The page must still draw, the

package/scripts/test-full.mjs

@@ -166,10 +166,89 @@ export function plan(root = ROOT, { providerFiles } = {}) {
   return { corpora, faults };
 }
 
+/**
+ * ── SHARDING, AND WHY IT CANNOT SILENTLY DROP A FILE ──────────────────────────────────────────────
+ *
+ * The offline suite was the whole wall clock of CI: 12.8 minutes against 4.3 for the portal bundle and
+ * under one each for the other two jobs, which run beside it. Nearly all of that is `driver`, 925 of the
+ * ~980 test files in the tree, executed in one serial job. Agents write faster than that gate opens, so
+ * the gate — not the work — set the pace of the day.
+ *
+ * A shard is a SLICE OF THE SORTED FILE LIST TAKEN BY INDEX: shard i of n takes every file whose
+ * position satisfies `index % n === i - 1`. That is exhaustive and disjoint by construction — every
+ * index lands in exactly one shard, for any n — so the union of the shards is the whole list as a
+ * property of the arithmetic, not as something a check has to confirm afterwards. Round-robin rather
+ * than contiguous blocks because neighbouring files in a sorted list tend to be the same subsystem and
+ * to cost the same; interleaving spreads the slow ones.
+ *
+ * WHAT IS NOT SHARDED, and why that is stated rather than assumed. Only a corpus whose own test script
+ * is the plain `node --test test/*.test.mjs` shape can be expressed as an explicit file list and cut up
+ * this way. `portal-ui` runs a typecheck first and drives `.test.ts` through `--experimental-strip-types`,
+ * so it is not that shape: it runs WHOLE, on shard 1, and says so on every other shard rather than
+ * disappearing from them. Anything else that stops matching the shape falls into the same branch and is
+ * reported, never quietly skipped.
+ */
+const PLAIN_GLOB = /^node \.\.\/scripts\/test-run\.mjs node --test test\/\*\.test\.mjs$/;
+
+export function shardSlice(list, i, n) {
+  return list.filter((_, idx) => idx % n === i - 1);
+}
+
+function workspaceTestFiles(root, ws) {
+  const dir = join(root, ws, "test");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".test.mjs")).sort().map((f) => `${ws}/test/${f}`);
+}
+
+/** Is this workspace's `test:full` the plain shape we can express as a file list? */
+function isShardable(root, ws) {
+  try {
+    const scripts = JSON.parse(readFileSync(join(root, ws, "package.json"), "utf8")).scripts ?? {};
+    let cmd = scripts["test:full"] ?? "";
+    // `test:full` is often just `npm run test`; follow that one hop.
+    const hop = cmd.match(/^npm run (\S+)$/);
+    if (hop) cmd = scripts[hop[1]] ?? "";
+    return PLAIN_GLOB.test(cmd.trim());
+  } catch { return false; }
+}
+
+/**
+ * Rewrite the plan for one shard. Every corpus stays in the list and is reported; what changes is how
+ * many of its files THIS shard runs.
+ */
+export function applyShard(corpora, { i, n }, root = ROOT) {
+  return corpora.map((c) => {
+    if (c.kind === "covered") return c;
+    if (c.kind === "files") {
+      const mine = shardSlice(c.files, i, n);
+      return { ...c, files: mine, total: c.files.length,
+               argv: ["node", "scripts/test-run.mjs", "node", "--test", ...mine] };
+    }
+    if (c.kind === "workspace" && isShardable(root, c.name)) {
+      const all = workspaceTestFiles(root, c.name);
+      const mine = shardSlice(all, i, n);
+      return { ...c, kind: "files", files: mine, total: all.length,
+               argv: ["node", "scripts/test-run.mjs", "node", "--test", ...mine] };
+    }
+    // Not expressible as a file list: run it whole, once, on shard 1.
+    return { ...c, wholeOnShard: 1, skippedHere: i !== 1 };
+  });
+}
+
 function main() {
   const only = (() => { const i = process.argv.indexOf("--only"); return i === -1 ? null : process.argv[i + 1]; })();
   const listOnly = process.argv.includes("--list");
-  const { corpora, faults } = plan();
+  const shard = (() => {
+    const i = process.argv.indexOf("--shard");
+    if (i === -1) return null;
+    const m = String(process.argv[i + 1] ?? "").match(/^(\d+)\/(\d+)$/);
+    if (!m) { console.error("test-full: --shard wants i/n, e.g. --shard 2/4"); process.exit(2); }
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    if (a < 1 || b < 1 || a > b) { console.error(`test-full: --shard ${a}/${b} is not a shard of anything`); process.exit(2); }
+    return { i: a, n: b };
+  })();
+  const { corpora: full, faults } = plan();
+  const corpora = shard ? applyShard(full, shard, ROOT) : full;
 
   // FAULTS BEFORE ANYTHING RUNS. A missing corpus discovered after a green suite reads as an
   // afterthought; discovered first, it is the answer.
@@ -195,9 +274,13 @@ function main() {
     return;
   }
 
+  if (shard) console.log(`\ntest-full: shard ${shard.i} of ${shard.n} — slices are taken by index from the sorted file list, so the shards are disjoint and their union is the whole list.`);
+
   const ran = [];
   for (const c of chosen) {
     if (c.kind === "covered") { ran.push({ ...c, status: "covered" }); continue; }
+    if (c.skippedHere) { ran.push({ ...c, status: "elsewhere" }); continue; }
+    if (c.kind === "files" && c.files.length === 0) { ran.push({ ...c, status: "empty" }); continue; }
     console.log(`\n──── ${c.name} ────`);
     // STDIO INHERITED, NOT CAPTURED. CI reads the child stream for the corpus-guard markers, and a
     // runner that buffered its children would take those markers out of the log the check greps.
@@ -213,13 +296,23 @@ function main() {
   for (const c of ran) {
     if (c.status === "covered") {
       console.log(`  covered  ${c.name} — ${c.hasTests} file(s), run by the ${c.cover.corpus} corpus: ${c.cover.why}`);
+    } else if (c.status === "elsewhere") {
+      console.log(`  shard ${c.wholeOnShard}  ${c.name} — not expressible as a file list, so it runs WHOLE on shard ${c.wholeOnShard}, not here. It is not missing from this run; it is somewhere else in it.`);
+    } else if (c.status === "empty") {
+      console.log(`  none     ${c.name} — 0 of ${c.total} file(s) fell in this shard. Not an absence: the other shards hold them.`);
     } else {
-      const n = c.kind === "files" ? `${c.files.length} file(s)` : "workspace suite";
+      const n = c.kind === "files"
+        ? `${c.files.length}${c.total != null ? ` of ${c.total}` : ""} file(s)`
+        : "workspace suite";
       console.log(`  ${c.status === "ok" ? "ran    " : "FAILED "}  ${c.name} — ${n}${c.code ? ` (exit ${c.code})` : ""}`);
     }
   }
   const bad = ran.filter((c) => c.status === "FAILED");
-  console.log(bad.length ? `\n${bad.length} corpus/corpora failed.` : `\nEvery corpus above was run or accounted for.`);
+  console.log(bad.length
+    ? `\n${bad.length} corpus/corpora failed.`
+    : shard
+      ? `\nEvery corpus above was run, accounted for, or named as belonging to another shard. This shard alone is not the suite: the gate is every shard green.`
+      : `\nEvery corpus above was run or accounted for.`);
   if (bad.length) process.exit(1);
 }
 

package/scripts/test-run.mjs

@@ -644,6 +644,16 @@ if (String(process.env[REAL_ENGINE_OVERRIDE] ?? "").trim()) {
     catch { copyFileSync(ENGINE_STUB, p); chmodSync(p, 0o755); }
   }
   process.env.PATH = shimDir + delimiter + (process.env.PATH ?? "");
+  // AND THE COPY CLEAROTRON INSTALLED, which no PATH can close. The resolver's last step
+  // (driver.config.mjs resolveEngineProgram) reads the engines folder under the home directory, where
+  // setup installs `@anthropic-ai/claude-code` or `@openai/codex`, never PATH, and on a developer's machine
+  // that folder can hold a REAL program. The shim above answers every child that keeps this PATH, because
+  // PATH is asked first; a child that composes its own PATH would fall straight through to a real binary.
+  // So the folder is pointed at an EMPTY directory for the whole suite: the suite keeps the no-installed-
+  // copy world it was written for, and an arm about the installed copy plants its own folder and names it.
+  const noEngines = join(root, "no-installed-engines");
+  mkdirSync(noEngines, { recursive: true });
+  process.env.CLEAROTRON_ENGINES_DIR = noEngines;
   // Names, never values — this line is read by whoever is wondering why a credential-reading test skipped.
   const withheld = Object.keys(process.env)
     .filter((n) => CREDENTIAL_RE.test(n) || CREDENTIAL_NAMES.includes(n))

package/shared/deployment-box.mjs

@@ -16,10 +16,15 @@
 // of the same allowlist agree on the day they are written and drift afterwards; that is the defect
 // was filed about one field over, and the fix there was the same — import the function, never
 // re-derive the answer.
-export const DEPLOYMENT_BOXES = ["prod", "test"];
+// `preprod` JOINED 2026-09-17. It is a packaged install like production, on its own account, which takes
+// every published version before production does. Until it could name itself it ran with the variable
+// UNSET — and an unset box does not fail loudly: `live-surface-check` SKIPS its expected-units check
+// when the box is null, so the one install that most wants that check was the one not getting it.
+// Setting `prod` instead would have made the box lie about which box it is.
+export const DEPLOYMENT_BOXES = ["prod", "preprod", "test"];
 
 /**
- * @returns {"prod"|"test"|null} the self-declared box, or null when unset or unrecognised.
+ * @returns {"prod"|"preprod"|"test"|null} the self-declared box, or null when unset or unrecognised.
  *
  * Read at CALL time, deliberately. `shared/brand.mjs` builds its value at module scope and that is
  * exactly why a rename reached the report and not the portal — portal-service is outside

package/shared/driver-dir.mjs

@@ -35,7 +35,7 @@
 // its own population needs an exception list — which would rebuild this issue's defect inside its fix:
 //
 //   · `driver/stage-freshness.mjs` creates a CHILD, `join(runDir, "_driver", STAMP_DIR)`.
-//   · `driver/pipeline.mjs:15945 shadowDir` passes a shadow dispatch sandbox under `_experiments/`, not a run
+//   · `driver/pipeline.mjs shadowDir` passes a shadow dispatch sandbox under `_experiments/`, not a run
 //     directory. It is a run-dir-SHAPED base, which is why the parameter is `base` and not `runDir`.
 //
 // ── WHAT THIS DELIBERATELY DOES NOT DO ────────────────────────────────────────────────────────────

package/shared/names-in-force.mjs

@@ -23,7 +23,6 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_AI",
   "CLEAROTRON_AI_BILLING",
   "CLEAROTRON_AI_PATH",
-  "CLEAROTRON_AZURE_MODEL",
   "CLEAROTRON_BAND_RESPONSE_CHARS",
   "CLEAROTRON_BAND_RUN_DIR",
   "CLEAROTRON_BAND_TRUTH_GATE",
@@ -54,6 +53,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_E2E_EVIDENCE_DIR",
   "CLEAROTRON_E2E_EXPECT_DEMO_ROSTER",
   "CLEAROTRON_EDGE_ORIGIN",
+  "CLEAROTRON_ENGINES_DIR",
   "CLEAROTRON_ENGINE_CWD",
   "CLEAROTRON_ENGINE_MAX_BUFFER",
   "CLEAROTRON_ENUMERATE_CEILING",