clearotron 0.3.3 → 0.4.0-beta.1

package/scripts/release-entry-catch-up.mjs

@@ -0,0 +1,211 @@
+// 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
+//
+// release-entry-catch-up.mjs — finish a release npm was still validating when the publish job stopped waiting.
+//
+//   node scripts/release-entry-catch-up.mjs [--repo owner/name] [--bound-hours 6] [--dry-run]
+//
+// WHY THIS EXISTS. npm now accepts a publish before it serves it ("Your package is being processed and may
+// take a few minutes to become available"), and the processing is not bounded. The publish job waits for
+// an unauthenticated client to get the exact bytes it uploaded before it creates the release entry, and
+// that wait has to end somewhere. Measured 2026-09-23: 0.3.3-beta.1 was served eleven minutes after npm
+// accepted it; the 0.3.3 stable was still "Validating" on npmjs.com more than fifty minutes after, the
+// job gave up at its bound, and no entry was ever created. GitHub went on naming 0.3.2 as the latest
+// release while the stable was already published. Nothing ran again to finish it.
+//
+// So a tagged version with no entry is PENDING, not failed, and the scheduled run finishes it: once the
+// registry serves the bytes the publish job kept, the entry is created from the changelog, exactly as the
+// publish job would have created it. Past a bound with the version still not served, it says so in red.
+//
+// THE SAME CHECK, ON THE SAME BYTES. The publish job keeps the tarball it uploaded as an artifact named
+// `published-<version>`, and this hands that file to release-visible-check.mjs, so an entry is only ever
+// created over bytes the registry serves and this pipeline published. A tagged version with no kept bytes
+// (one published before this existed) is reported, never guessed at.
+//
+// THE RELEASE RUN'S ARTIFACT, NEVER ANY ARTIFACT OF THAT NAME. Any run in the repository can upload an
+// artifact called `published-<version>`, a fork's pull request included, and GitHub lists same-named
+// artifacts highest id first, so a name alone takes the last upload: its parts list would ride on the
+// official entry, and its tarball would report a sound release as different bytes. An artifact is used only
+// when the run that made it is this repository's release workflow, on `main`, at the tagged commit or
+// behind it. Behind it is the ordinary case for a cut: its publish runs on the commit it was dispatched
+// from, and the version commit it tags lands on `main` after (0.3.3-beta.1: run on `1d7722ac`, tag on
+// `d571d0ee`).
+//
+// Exit 0: nothing to do, the entry was created, or the version is pending inside the bound.
+// Exit 1: the registry serves different bytes, the version is still not served past the bound, or its bytes
+// cannot be found to check against.
+// Exit 2: could not look.
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, readdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * What to do about the version at main's head. PURE, so every branch is driven without a registry.
+ * @param {{ tagged: boolean, entryExists: boolean, keptBytes: boolean, visibleExit: number|null,
+ *           ageSec: number|null, boundSec: number }} s
+ * @returns {{ action: "none"|"create"|"wait"|"report", exit: 0|1|2, why: string }}
+ */
+export function decide(s) {
+  if (!s.tagged) return { action: "none", exit: 0, why: "not tagged: nothing has been published to finish" };
+  if (s.entryExists) return { action: "none", exit: 0, why: "the release entry already exists" };
+  if (!s.keptBytes) {
+    return { action: "report", exit: 1,
+      why: "tagged with no release entry, and no kept bytes to check the registry against: create the entry by hand after checking what the registry serves" };
+  }
+  if (s.visibleExit === 0) return { action: "create", exit: 0, why: "the registry serves the published bytes" };
+  // DIFFERENT BYTES ARE NEVER PENDING. The registry serves this version and it is not the build that was
+  // published, so it is red at once, however young the tag.
+  if (s.visibleExit === 3) {
+    return { action: "report", exit: 1, why: "the registry serves DIFFERENT BYTES for this version than the publish job kept" };
+  }
+  if (s.visibleExit === 1) {
+    if (s.ageSec != null && s.ageSec > s.boundSec) {
+      return { action: "report", exit: 1,
+        why: `tagged ${Math.round(s.ageSec / 3600)} h ago and the registry still does not serve these bytes` };
+    }
+    return { action: "wait", exit: 0, why: "npm has not served it yet; the next scheduled run looks again" };
+  }
+  return { action: "report", exit: 2, why: "the registry check could not look" };
+}
+
+export const RELEASE_WORKFLOW = ".github/workflows/release.yml";
+const RELEASE_EVENTS = new Set(["push", "workflow_dispatch", "schedule"]);
+
+/**
+ * Why a kept artifact is NOT the release run's own, or null when it is. PURE. Called first with the
+ * artifact alone, which reads only what the artifact list already says, so a fork's upload costs no further
+ * call; then with the run that made it and how that run's commit relates to the tagged one (the compare
+ * API's `status` from the run's commit to the tag: "identical" or "ahead" means at the tag or behind it).
+ * @param {{ artifact: object, repoId: number, run?: object, relation?: string }} s
+ * @returns {string|null}
+ */
+export function notTheReleaseRun({ artifact, repoId, run, relation }) {
+  const w = artifact.workflow_run ?? {};
+  if (w.repository_id !== repoId || w.head_repository_id !== repoId) return "it was made by a run from another repository, such as a fork's pull request";
+  if (w.head_branch !== "main") return `it was made by a run on ${w.head_branch ? `\`${w.head_branch}\`` : "no branch"}, not on main`;
+  if (run === undefined) return null;
+  if (run.id !== w.id) return "the run read back is not the run the artifact names";
+  if (run.path !== RELEASE_WORKFLOW) return `it was made by ${run.path ?? "an unnamed workflow"}, not the release workflow`;
+  if (!RELEASE_EVENTS.has(run.event)) return `it was made by a ${run.event ?? "nameless"} run, which never publishes`;
+  if (run.head_repository?.id !== repoId || run.head_branch !== "main") return "the run that made it is not on this repository's main";
+  if (relation !== "identical" && relation !== "ahead") return `it was made on a commit that is not the tagged commit or behind it (${relation ?? "unknown"})`;
+  return null;
+}
+
+const arg = (argv, flag, dflt = null) => { const i = argv.indexOf(flag); return i === -1 ? dflt : argv[i + 1]; };
+const gh = (args, opts = {}) => execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts });
+
+// Whether the entry exists. Only GitHub's own "release not found" is a no; any other failure throws.
+function entryFor(tag, repo) {
+  const r = spawnSync("gh", ["release", "view", tag, "--repo", repo, "--json", "tagName"], { encoding: "utf8" });
+  if (r.status === 0) return true;
+  if (/release not found/i.test(r.stderr ?? "")) return false;
+  throw Object.assign(new Error(`could not read the release entry for ${tag}`), { stderr: r.stderr || r.error?.message });
+}
+
+// The first unexpired `published-<version>` artifact the release run made, or null. Every other one is
+// named in a warning with the reason it was refused. EVERY PAGE OF THE LIST IS READ, NOT THE FIRST: any
+// run can upload an artifact of that name, so a hundred uploads made after the release run's would push
+// its own off a single page, and the version would be reported as having no kept bytes.
+function keptArtifact(repo, version, tagSha) {
+  const repoId = Number(gh(["api", `repos/${repo}`, "--jq", ".id"]).trim());
+  for (let page = 1, seen = 0, total = 1; seen < total; page++) {
+    const list = JSON.parse(gh(["api", `repos/${repo}/actions/artifacts?name=published-${version}&per_page=100&page=${page}`]));
+    const artifacts = list.artifacts ?? [];
+    if (!artifacts.length) break;   // the count named more than the pages hold: nothing further to read
+    total = list.total_count ?? 0;
+    seen += artifacts.length;
+    for (const artifact of artifacts.filter((x) => !x.expired && x.name === `published-${version}`)) {
+      let why = notTheReleaseRun({ artifact, repoId });
+      if (!why) {
+        const run = JSON.parse(gh(["api", `repos/${repo}/actions/runs/${artifact.workflow_run.id}`]));
+        const relation = gh(["api", `repos/${repo}/compare/${run.head_sha}...${tagSha}`, "--jq", ".status"]).trim();
+        why = notTheReleaseRun({ artifact, repoId, run, relation });
+      }
+      if (!why) return artifact;
+      console.log(`::warning::release-entry-catch-up: refused artifact ${artifact.id} named published-${version}: ${why}.`);
+    }
+  }
+  return null;
+}
+
+function main() {
+  try { return catchUp(process.argv.slice(2)); }
+  catch (e) {
+    // A GitHub call that failed is a check that could not look, never the verdict "past the bound".
+    console.log(`::error::release-entry-catch-up could not finish: ${String(e.stderr || e.message).trim().split("\n")[0]}`);
+    return 2;
+  }
+}
+
+function catchUp(argv) {
+  const repo = arg(argv, "--repo", process.env.GITHUB_REPOSITORY);
+  const boundSec = Number(arg(argv, "--bound-hours", "6")) * 3600;
+  const dry = argv.includes("--dry-run");
+  if (!repo || !(boundSec > 0)) { console.error("release-entry-catch-up: needs --repo (or GITHUB_REPOSITORY) and a positive --bound-hours. Could not look."); return 2; }
+
+  const version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+  const tag = `v${version}`;
+  const prerelease = version.includes("-");
+
+  // THE EXACT REF, as the publish job asks it: a prefix read would take v0.3.1 for v0.3.1-beta.0.
+  let tagged;
+  try { tagged = gh(["api", `repos/${repo}/git/ref/tags/${tag}`, "--jq", ".ref"]).trim() === `refs/tags/${tag}`; }
+  catch (e) { if (/HTTP 404/.test(String(e.stderr))) tagged = false; else { console.error(`release-entry-catch-up: could not read the tag ${tag}: ${String(e.stderr || e.message).trim()}`); return 2; } }
+  const entryExists = tagged ? entryFor(tag, repo) : false;
+
+  let keptBytes = false, visibleExit = null, ageSec = null, work = null, sbom = null;
+  if (tagged && !entryExists) {
+    const [tagSha, when] = gh(["api", `repos/${repo}/commits/${tag}`, "--jq", `.sha + " " + .commit.committer.date`]).trim().split(" ");
+    ageSec = Math.max(0, (Date.now() - Date.parse(when)) / 1000);
+    const a = keptArtifact(repo, version, tagSha);
+    if (a) {
+      work = mkdtempSync(join(tmpdir(), "entry-catch-up-"));
+      writeFileSync(join(work, "kept.zip"), execFileSync("gh", ["api", `repos/${repo}/actions/artifacts/${a.id}/zip`],
+        { maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }));
+      execFileSync("unzip", ["-q", "-o", join(work, "kept.zip"), "-d", join(work, "kept")]);
+      const kept = readdirSync(join(work, "kept"));
+      const tgz = kept.find((f) => f.endsWith(".tgz"));
+      const cdx = kept.find((f) => f.endsWith(".cdx.json"));
+      if (cdx) sbom = join(work, "kept", cdx);
+      if (tgz) {
+        keptBytes = true;
+        const r = spawnSync(process.execPath, [join(ROOT, "scripts", "release-visible-check.mjs"), "--version", version,
+          "--tag", prerelease ? "beta" : "latest", "--tarball", join(work, "kept", tgz), "--timeout", "60", "--interval", "15"],
+        { encoding: "utf8" });
+        process.stdout.write(r.stdout ?? ""); process.stderr.write(r.stderr ?? "");
+        visibleExit = r.status;
+      }
+    }
+  }
+
+  const d = decide({ tagged, entryExists, keptBytes, visibleExit, ageSec, boundSec });
+  console.log(`release-entry-catch-up: ${tag}: ${d.why}.`);
+  if (d.action === "create") {
+    if (dry) { console.log(`release-entry-catch-up: --dry-run, so no entry is created for ${tag}.`); }
+    else {
+      // THE SAME ENTRY THE PUBLISH JOB WRITES: the changelog's section for this version, flagged as a
+      // pre-release for a beta, and GitHub's own notes only when the changelog has no section.
+      const notes = spawnSync(process.execPath, [join(ROOT, "scripts", "release-notes-for.mjs"), version], { encoding: "utf8" }).stdout ?? "";
+      // The parts list the publish job kept beside the bytes rides as an asset, as it does on an entry the
+      // publish job writes itself. A version kept before the list existed has none, and gets none.
+      const args = ["release", "create", tag, ...(sbom ? [sbom] : []), "--repo", repo, "--verify-tag", "--title", tag];
+      if (notes.trim()) { const f = join(work ?? mkdtempSync(join(tmpdir(), "entry-notes-")), "notes.md"); writeFileSync(f, notes); args.push("--notes-file", f); }
+      else args.push("--generate-notes");
+      if (prerelease) args.push("--prerelease");
+      gh(args);
+      console.log(`release-entry-catch-up: created the release entry for ${tag}${prerelease ? " as a pre-release" : ""}.`);
+    }
+  }
+  if (d.exit === 1) console.log(`::error::${tag}: ${d.why}.`);
+  else if (d.action === "wait") console.log(`::notice::${tag}: ${d.why}.`);
+  if (work) rmSync(work, { recursive: true, force: true });
+  return d.exit;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = main();

package/scripts/release-note-required.mjs

@@ -101,6 +101,27 @@
 // A deletion that gives no reason still refuses, and names the deleting commit as where the reason goes.
 // The move a pre-release makes — `.changeset/<name>.md` deleted and `.changeset/pre/<name>.md` added in
 // one commit — is not a withdrawal: the note still reaches a reader, and a version commit is that shape.
+// ── A LATER COMMIT MAY ANSWER A BARE `none` FOR ONE NAMED COMMIT ───────────────────────────────────────
+//
+// A commit carried `Release-note: none` with no reason and was merged into an integration branch before
+// anyone read it, and a second branch was already built on that merge. The only fix this check offered was
+// the commit's own message, so the answer was a rewrite of a shared branch. A later commit may therefore
+// answer for it, in its own message:
+//
+//     Release-note-for: <sha> none — <why a reader would see no difference>
+//
+// Held tight, because a loose one excuses by accident:
+//   - one line names one commit, by its full sha or a prefix of at least 7 characters, resolved against
+//     THIS range's commits only. A prefix that matches none of them, or several, is refused;
+//   - the named commit must be an ANCESTOR of the answering one (git ancestry, never timestamps), and a
+//     commit cannot answer for itself;
+//   - the reason is read by NO_NOTE itself, so the two forms cannot drift. Empty, or a dash, is refused;
+//   - one commit takes one answer: two lines naming the same commit are both refused, even when they agree;
+//   - an answer naming a commit that owes none (it ships no code, carries a note, or gives its own reason)
+//     is refused as stale. An answer ignored in silence reads as though it did something.
+// Every answer taken is printed with the sha that gave it, and every refused answer fails the check and
+// names the commit that carries it. The answering commit is read like any other: one that ships no code,
+// such as an empty commit, owes nothing of its own.
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -163,6 +184,51 @@ export const NEVER_A_NOTE = [/(^|\/)CHANGELOG\.md$/, /(^|\/)package(-lock)?\.jso
 const NOTE_LINE = /^\s*Release-note:[ \t]*(?<value>.*?)[ \t]*$/gim;
 /** A note named in a `Release-note:` line: `.changeset/<name>.md`, or the bare `<name>.md`. */
 const NAMED_NOTE = /^(?:\.changeset\/)?(?<name>[\w.-]+\.md)$/;
+/** `Release-note-for: <sha> none — <reason>`: a later commit answering a bare `none` (see the header). */
+const ANSWER_LINE = /^[ \t]*Release-note-for:[ \t]*(?<rest>.*?)[ \t]*$/gim;
+const ANSWER_HEAD = /^(?<sha>[0-9a-f]{7,40})(?<tail>(?:[ \t].*)?)$/i;
+
+/**
+ * PURE. Every `Release-note-for:` line in the range, judged. `isAncestor(a, b)` says whether commit `a` is
+ * an ancestor of commit `b`; without one, range order stands in for it (the range is read oldest first).
+ * @returns {{answers: Map<string, {by:string, subject:string, reason:string}>,
+ *   refused: Array<{sha:string, subject:string, text:string, problem:string}>}}
+ */
+export function readAnswers(commits = [], isAncestor = null) {
+  const refused = [];
+  const claims = new Map();
+  commits.forEach((c, at) => {
+    for (const m of String(c.message ?? "").matchAll(ANSWER_LINE)) {
+      const text = m[0].trim();
+      const bad = (problem) => refused.push({ sha: c.sha, subject: c.subject, text, problem });
+      const head = ANSWER_HEAD.exec(m.groups.rest);
+      if (!head) { bad("names no commit: the form is `Release-note-for: <sha> none — <reason>`"); continue; }
+      const none = NO_NOTE.exec(`Release-note:${head.groups.tail}`);
+      if (!none) { bad("does not say `none` straight after one sha: one line answers one commit"); continue; }
+      if (!none.groups?.reason) { bad("gives no reason, and the reason is the whole point of the line"); continue; }
+      const prefix = head.groups.sha.toLowerCase();
+      const hits = commits.filter((k) => String(k.sha).toLowerCase().startsWith(prefix));
+      if (!hits.length) { bad(`names ${prefix}, which is not a commit in this range`); continue; }
+      if (hits.length > 1) { bad(`names ${prefix}, which matches ${hits.length} commits in this range`); continue; }
+      const target = hits[0];
+      const later = target.sha !== c.sha
+        && (isAncestor ? isAncestor(target.sha, c.sha) : commits.indexOf(target) < at);
+      if (!later) { bad(`names ${prefix}, which is not an earlier commit on this commit's own history`); continue; }
+      if (!claims.has(target.sha)) claims.set(target.sha, []);
+      claims.get(target.sha).push({ by: c.sha, subject: c.subject, text, reason: none.groups.reason });
+    }
+  });
+  const answers = new Map();
+  for (const [sha, list] of claims) {
+    if (list.length > 1) {
+      for (const a of list) refused.push({ sha: a.by, subject: a.subject, text: a.text,
+        problem: `is one of ${list.length} answers naming ${sha.slice(0, 7)}; one commit takes one answer` });
+      continue;
+    }
+    answers.set(sha, list[0]);
+  }
+  return { answers, refused };
+}
 
 const isNotePath = (p) => p.startsWith(".changeset/") && p.endsWith(".md") && !p.endsWith("README.md");
 const shipped = (paths, files) => paths.filter((p) => !NEVER_A_NOTE.some((re) => re.test(p)) && shipsCode(p, files));
@@ -181,12 +247,15 @@ const shipped = (paths, files) => paths.filter((p) => !NEVER_A_NOTE.some((re) =>
  *   non-merge, oldest first; `added` and `deleted` are the paths the commit adds and removes, when the caller read them
  * @param {string[]} o.files  the package's own `files` list
  * @param {string[]|null} [o.atHead]  every path the head carries under `.changeset/`, when the caller read it
+ * @param {((a:string, b:string) => boolean)|null} [o.isAncestor]  git ancestry for `Release-note-for:` answers; range order without it
  * @returns {{visible:string[], notes:string[], declined:Array<{sha:string, subject:string, reason:string}>,
  *   withdrawals:Array<{sha:string, subject:string, note:string, by:string, reason:string}>,
+ *   answered:Array<{sha:string, subject:string, by:string, reason:string}>,
+ *   refusedAnswers:Array<{sha:string, subject:string, text:string, problem:string}>,
  *   owed:Array<{sha:string, subject:string, why:"no-note"|"prose"|"bare-none"|"names-a-missing-note"|"note-withdrawn-unsaid",
  *   paths?:string[], text?:string, by?:string}>}}
  */
-export function commitVerdicts({ commits = [], files = [], atHead = null } = {}) {
+export function commitVerdicts({ commits = [], files = [], atHead = null, isAncestor = null } = {}) {
   // `added` and `atHead` are what the command reads from git; a caller that passes neither keeps the older
   // reading of every changed path, which is what a pure table of paths means.
   // MATCHED ON THE NAME, NOT THE PATH, BECAUSE A PRE-RELEASE MOVES A NOTE IT CONSUMES.
@@ -234,7 +303,9 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
   });
   // AND A NAME THE HEAD STILL CARRIES WAS NEVER WITHDRAWN AT ALL: the release assembles what the head has.
   if (presentNames) for (const name of [...withdrawn.keys()]) if (presentNames.has(name)) withdrawn.delete(name);
-  const declined = [], owed = [], withdrawals = [];
+  const declined = [], owed = [], withdrawals = [], answered = [];
+  const { answers, refused: refusedAnswers } = readAnswers(commits, isAncestor);
+  const used = new Set();
   for (const [i, c] of commits.entries()) {
     const ships = shipped(c.paths, files);
     if (!ships.length) continue;                              // nothing a reader could see in this commit
@@ -247,7 +318,10 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
     const none = NO_NOTE.exec(String(c.message ?? ""));
     if (none) {
       const reason = none.groups?.reason;
-      if (reason) declined.push({ ...at, reason }); else owed.push({ ...at, why: "bare-none" });
+      const answer = reason ? null : answers.get(c.sha);
+      if (reason) declined.push({ ...at, reason });
+      else if (answer) { answered.push({ ...at, by: answer.by, reason: answer.reason }); used.add(c.sha); }
+      else owed.push({ ...at, why: "bare-none" });
       continue;
     }
     if (addsNote) continue;                                   // it carries its own note
@@ -268,7 +342,16 @@ export function commitVerdicts({ commits = [], files = [], atHead = null } = {})
     if (notes.length) continue;                               // a note in the range answers for it
     owed.push({ ...at, why: "no-note", paths: ships });
   }
-  return { visible, notes, declined, withdrawals, owed };
+  // AN ANSWER THAT ANSWERED NOTHING IS REFUSED, NOT IGNORED (see the header).
+  const owing = new Set(owed.map((o) => o.sha));
+  for (const [sha, a] of answers) {
+    if (used.has(sha)) continue;
+    refusedAnswers.push({ sha: a.by, subject: a.subject, text: a.text,
+      problem: owing.has(sha)
+        ? `names ${sha.slice(0, 7)}, which owes a note this line cannot give: an answer covers only a bare \`none\``
+        : `names ${sha.slice(0, 7)}, which owes no answer: it ships no code, carries a note, or gives its own reason` });
+  }
+  return { visible, notes, declined, withdrawals, owed, answered, refusedAnswers };
 }
 
 const argAfter = (flag) => {
@@ -333,7 +416,9 @@ function main() {
       + "history is never read.");
     return;
   }
-  const { visible, notes, declined, withdrawals, owed } = commitVerdicts({ commits, files, atHead });
+  // ANCESTRY FROM GIT, NEVER TIMESTAMPS: an answer must come from a commit the named one is an ancestor of.
+  const isAncestor = (a, b) => { try { git("merge-base", "--is-ancestor", a, b); return true; } catch { return false; } };
+  const { visible, notes, declined, withdrawals, owed, answered, refusedAnswers } = commitVerdicts({ commits, files, atHead, isAncestor });
   console.log(`release-note-required: ${changed.length} changed file(s) against ${base}`
     + `${head === "HEAD" ? "" : ` (head ${head})`}; `
     + `${visible.length} ship as code; ${notes.length} release note(s) in the range; ${commits.length} commit(s) read`
@@ -352,7 +437,18 @@ function main() {
   for (const w of withdrawals) {
     console.log(`  ${w.sha.slice(0, 7)} answered with ${w.note}, which ${w.by.slice(0, 7)} withdrew: ${w.reason}`);
   }
-  if (!owed.length) return;
+  for (const a of answered) {
+    console.log(`  ${a.sha.slice(0, 7)} said a bare \`none\`, which ${a.by.slice(0, 7)} answers: ${a.reason}`);
+  }
+  if (!owed.length && !refusedAnswers.length) return;
+  if (refusedAnswers.length) {
+    console.error(`\n${refusedAnswers.length} Release-note-for answer(s) refused:\n`);
+    for (const r of refusedAnswers) {
+      console.error(`  ${r.sha.slice(0, 7)} ${r.subject}`);
+      console.error(`      "${r.text.slice(0, 120)}" ${r.problem}.`);
+    }
+  }
+  if (!owed.length) process.exit(1);
 
   console.error(`\n${owed.length} commit(s) that ship as code owe a release note:\n`);
   for (const o of owed) {

package/scripts/release-rehearsal-version.mjs

@@ -0,0 +1,60 @@
+// 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
+//
+// release-rehearsal-version.mjs — what a rehearsal publishes: the version a beta cut would publish now.
+//
+//   node scripts/release-rehearsal-version.mjs      # stdout: publish_dry_run=true|false; the rest on stderr
+//
+// WHY A REHEARSAL DOES NOT PUBLISH MAIN'S VERSION. Main's version is the one already out on almost every
+// day: a cut stamps it and publishes it, and it stays on main until the next cut. npm checks the registry
+// even on `npm publish --dry-run`, so a rehearsal of main's own version answered "You cannot publish over
+// the previously published versions" and went red (measured 2026-09-23 on 0.3.3), reading as a broken
+// pipeline when nothing was wrong. It passed only between a cut and its publish, when nobody rehearses.
+//
+// So a rehearsal stamps the tree the way a `cut: beta` dispatch does, with release-version.mjs itself, and
+// dry-runs that version: the one a cut made now would publish. The stamp lives in the job's own checkout
+// and is never committed.
+//
+// WITH NO NOTE PENDING THERE IS NOTHING TO CUT, and a cut would refuse for exactly that reason. The
+// version is then main's, which is out, so the publish dry run is skipped and says why, while every check
+// before it still runs on those bytes. A note that is pending and still cannot be cut is a real failure,
+// and the rehearsal fails with the version script's own refusal.
+//
+// Exit 0: stamped, or nothing to cut. Exit 1: the version script refused. Exit 2: could not look.
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+import { countNotes } from "./release-pre-gate.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** PURE. What a rehearsal does with the notes it finds pending at the top of `.changeset/`. */
+export function rehearsalPlan({ pendingNotes }) {
+  if (!Number.isInteger(pendingNotes) || pendingNotes < 0) return { action: "could-not-look" };
+  return pendingNotes > 0 ? { action: "stamp-next-beta" } : { action: "nothing-to-cut" };
+}
+
+export function main(root = ROOT) {
+  let pendingNotes;
+  try { pendingNotes = countNotes(join(root, ".changeset")); }
+  catch (e) { console.error(`release-rehearsal-version: could not read .changeset/: ${e.message}. Could not look.`); return 2; }
+  const plan = rehearsalPlan({ pendingNotes });
+  if (plan.action === "could-not-look") { console.error("release-rehearsal-version: could not count the pending notes. Could not look."); return 2; }
+  if (plan.action === "nothing-to-cut") {
+    console.error("release-rehearsal-version: no release note is pending, so there is nothing to cut and main's version is the one already out.");
+    console.log("publish_dry_run=false");
+    return 0;
+  }
+  console.error(`release-rehearsal-version: ${pendingNotes} note(s) pending; stamping the version a \`cut: beta\` would publish.`);
+  // The version script's own output goes to stderr, so stdout carries the one line the workflow keeps.
+  const r = spawnSync(process.execPath, [join(root, "scripts", "release-version.mjs"), "--cut=beta"], { cwd: root, stdio: ["ignore", 2, 2] });
+  if (r.status !== 0) {
+    console.error(`release-rehearsal-version: the version script refused (exit ${r.status ?? r.signal}), so a beta cut made now would refuse too.`);
+    return 1;
+  }
+  console.log("publish_dry_run=true");
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = main();

package/scripts/release-sbom.mjs

@@ -0,0 +1,104 @@
+// 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
+//
+// release-sbom.mjs — the parts list attached to every release, written from package-lock.json.
+//
+//   node scripts/release-sbom.mjs [--out <file>]      # CycloneDX 1.5 JSON; stdout when --out is absent
+//
+// WHY NOT `npm sbom`. It refuses this tree: `ESBOMPROBLEMS: invalid: uuid@11.1.1 … required by
+// exceljs@4.4.0`, on a clean `npm ci` as well, and `npm ls` flags the same edge. That is npm's reading of
+// the `uuid` override on the bundled `exceljs`, and an exact-version override is flagged the same way
+// (measured 2026-09-23 on npm 10.9.8). The reference tool, `@cyclonedx/cyclonedx-npm`, would add a
+// dependency that runs inside a release job. The lock already names every package, its version, its
+// integrity and its licence, which is what a parts list is.
+//
+// WHAT IS LISTED. Every package the lock installs that is not dev-only: the runtime dependencies and
+// everything they pull in, and the bundled ones this package carries inside its tarball. A consumer's
+// npm resolves the unbundled ones again at install time, so the list is what this release was built and
+// tested with, which is what an SBOM of a library can honestly say. Workspace links are this package's
+// own files, not parts, and are left out; a vendored package is listed by its path in this tree.
+//
+// THE SAME LOCK GIVES THE SAME BYTES. No timestamp and no serial number: both are optional in the spec,
+// and either would make two runs over one lock differ for no reason a reader can use.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** `pkg:npm/<name>@<version>`, with a scope's `@` encoded as the purl spec asks. */
+export const purlOf = (name, version) => `pkg:npm/${name.startsWith("@") ? `%40${name.slice(1)}` : name}@${version}`;
+
+/** An npm integrity string (`sha512-<base64>`) as CycloneDX hashes, hex-encoded. */
+export function hashesOf(integrity) {
+  const out = [];
+  for (const part of String(integrity ?? "").split(/\s+/).filter(Boolean)) {
+    const m = /^(sha512|sha384|sha256|sha1)-(.+)$/.exec(part);
+    if (!m) continue;
+    const alg = { sha512: "SHA-512", sha384: "SHA-384", sha256: "SHA-256", sha1: "SHA-1" }[m[1]];
+    out.push({ alg, content: Buffer.from(m[2], "base64").toString("hex") });
+  }
+  return out;
+}
+
+/**
+ * The CycloneDX document for a parsed lockfile and the root manifest. PURE.
+ * @param {{ lock: object, manifest: object }} input
+ */
+export function sbomFor({ lock, manifest }) {
+  const byRef = new Map();
+  const workspaces = new Set((manifest.workspaces ?? []).map((w) => w.replace(/\/+$/, "")));
+  for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+    if (!path.startsWith("node_modules/") && !path.includes("/node_modules/")) continue;   // the root and link targets
+    if (entry.dev) continue;                                                                 // dev-only tools
+    // A LINK TO A WORKSPACE is this package's own code. A link to anything else is code this package
+    // carries in its own tree, such as a vendored replacement, and it is listed by where it lives, with no
+    // npm purl: that would name the registry's package of the same name, which it is not.
+    if (entry.link) {
+      const target = lock.packages?.[entry.resolved] ?? {};
+      if (workspaces.has(entry.resolved) || !target.version || target.dev) continue;
+      const name = path.slice(path.lastIndexOf("node_modules/") + "node_modules/".length);
+      const ref = `file:${entry.resolved}`;
+      const vendored = { type: "library", "bom-ref": ref, name, version: target.version,
+        properties: [{ name: "clearotron:vendored-path", value: entry.resolved }] };
+      if (typeof target.license === "string" && target.license) vendored.licenses = [{ expression: target.license }];
+      byRef.set(ref, vendored);
+      continue;
+    }
+    const name = entry.name ?? path.slice(path.lastIndexOf("node_modules/") + "node_modules/".length);
+    if (!entry.version) continue;
+    const ref = purlOf(name, entry.version);
+    if (byRef.has(ref)) continue;
+    const component = { type: "library", "bom-ref": ref, name, version: entry.version, purl: ref };
+    const hashes = hashesOf(entry.integrity);
+    if (hashes.length) component.hashes = hashes;
+    if (typeof entry.license === "string" && entry.license) component.licenses = [{ expression: entry.license }];
+    byRef.set(ref, component);
+  }
+  const components = [...byRef.values()].sort((a, b) => a["bom-ref"].localeCompare(b["bom-ref"]));
+  const root = { type: "library", "bom-ref": purlOf(manifest.name, manifest.version), name: manifest.name, version: manifest.version,
+    purl: purlOf(manifest.name, manifest.version) };
+  if (manifest.license) root.licenses = [{ expression: manifest.license }];
+  return { bomFormat: "CycloneDX", specVersion: "1.5", version: 1, metadata: { component: root }, components };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf("--out");
+  const out = i === -1 ? null : argv[i + 1];
+  if (i !== -1 && !out) { console.error("release-sbom: --out needs a file."); return 2; }
+  let lock, manifest;
+  try {
+    lock = JSON.parse(readFileSync(join(ROOT, "package-lock.json"), "utf8"));
+    manifest = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+  } catch (e) { console.error(`release-sbom: could not read the lock or the manifest: ${e.message}. Could not look.`); return 2; }
+  const doc = sbomFor({ lock, manifest });
+  if (!doc.components.length) { console.error("release-sbom: the lock lists no runtime package, so there is no parts list to write. Refusing an empty one."); return 1; }
+  const text = JSON.stringify(doc, null, 2) + "\n";
+  if (out) { writeFileSync(out, text); console.log(`release-sbom: ${doc.components.length} part(s) of ${manifest.name}@${manifest.version} written to ${out}.`); }
+  else process.stdout.write(text);
+  return 0;
+}
+
+if (isEntrypoint(import.meta.url)) process.exitCode = main();

package/scripts/release-visible-check.mjs

@@ -7,9 +7,11 @@
 //        [--timeout 900] [--interval 15] [--registry https://registry.npmjs.org] [--name clearotron]
 //
 // Exit 0: the registry serves <v>, the <dist-tag> names it, and the tarball it serves is byte for byte
-// the one at <file> — the bytes this run published. Exit 1: not within the bound, or the registry serves
-// different bytes; the caller creates no release entry. Exit 2: could not look — bad arguments, or the
-// local tarball cannot be read.
+// the one at <file> — the bytes this run published. Exit 1: not served within the bound, which is PENDING:
+// npm accepts a publish before it serves it. Exit 3: the registry serves DIFFERENT BYTES for <v>, which is
+// never pending and must go red at once, so it has a code of its own; it used to share 1, and a caller
+// that waits on 1 then waited six hours on a wrong tarball. Exit 2: could not look — bad arguments, or the
+// local tarball cannot be read. In every case but 0 the caller creates no release entry.
 //
 // ── WHY THIS RUNS BEFORE THE RELEASE ENTRY ─────────────────────────────────────────────────────────
 //
@@ -89,7 +91,7 @@ async function main() {
       console.error(`\nrelease-visible-check: after ${waited}s an unauthenticated client still cannot get ${name}@${version} `
         + `under \`${tag}\`. The publish was accepted and is not yet served, so no release entry is created: `
         + "the page would name a version nobody can install. The tag is already written, so the pipeline "
-        + "knows this version is published; re-run this job to create the entry once the registry serves it.");
+        + "knows this version is published; the scheduled entry job creates the entry once the registry serves it.");
       process.exit(1);
     }
     await sleep(intervalSec * 1000);
@@ -108,7 +110,7 @@ async function main() {
     console.error(`release-visible-check: the registry serves DIFFERENT BYTES for ${name}@${version}.\n`
       + `  published by this run: ${local}\n  served:                ${served}\n  recorded integrity:    ${seen.integrity ?? "none"}\n`
       + "No release entry is created for a version whose install is not the build this run verified.");
-    process.exit(1);
+    process.exit(3);
   }
   console.log(`release-visible-check: a stranger can install ${name}@${version} under \`${tag}\`, `
     + `and the tarball served is the one this run published (${served.slice(0, 22)}…).`);

package/scripts/score.mjs

@@ -435,7 +435,7 @@ function scoreOne(run, ref) {
   //
   // Refusing the unshaped pairing was only half of it. A gold set that gains a `counts` block usually
   // KEEPS its lawyer sheet — it is a real answer to a real matter and deleting it loses history — and
-  // scoring both prints `LOST · TIKI PUNCH` beside the count that measures the product. That is the same
+  // scoring both prints `LOST · WAVO PUNCH` beside the count that measures the product. That is the same
   // structural zero the issue is about, one row smaller, and it lands in the bucket table a reader
   // scans first.
   //
@@ -644,7 +644,7 @@ function print(id, ref, run, s, delta, refPath) {
   console.log(renderCarryThrough(run.dir, { indent: "  " }).lines.join("\n"));
 
   // — a record in two buckets is a defect in THIS TOOL, and it is printed as loudly as any score.
-  // Silence here is what let `DELPHI GENETICS` sit in LOST and `DG DELPHI GENETICS` in NOISE on the same
+  // Silence here is what let `KORPHI GENETICS` sit in LOST and `DG KORPHI GENETICS` in NOISE on the same
   // page, and the recall number that reached the round handover was wrong for a week because nobody
   // reads two lists against each other.
   if (B.collisions?.length) {
@@ -656,7 +656,7 @@ function print(id, ref, run, s, delta, refPath) {
   //
   // These used to print under the line above, which tells the reader not to read the recall numbers.
   // One large filer anywhere in a matter therefore suppressed a whole run's measurement, and did: R2's
-  // real 88% → 63% recall movement went unquoted on the regression issue because `Novartis AG` held one
+  // real 88% → 63% recall movement went unquoted on the regression issue because `Norvanta AG` held one
   // withheld reference mark and one surfaced non-reference mark. Those two rows are both true.
   //
   // Kept visible because a reader may still want the pairing, and deliberately WITHOUT a verdict: this

package/shared/brand.mjs

@@ -718,7 +718,7 @@ export const CHROME_CSS = `
    thing. The three body elements that carried the class drop it too, and --wm-alpha goes with them:
    a token nothing reads is a knob somebody re-wires.
    NOTE FOR ANY FUTURE DECORATION ON body: the rule here pinned right:0 and never a negative inset,
-   because right:-2% put 26px of horizontal scrollbar on a 1280px report (#485) and pointer-events:none
+   because right:-2% put 26px of horizontal scrollbar on a 1280px report and pointer-events:none
    does not exempt a box from scrollable overflow. That is a property of the position, not of this
    rule, and scripts/report-overflow-check.mjs still measures it. */
 /* Floating settings stack (theme + privacy) — pinned bottom-right, OUT of the nav bar. Icon-only: the toggle keeps its .tt-lbl/.anon-lbl text for screen readers but clips it visually.