@starci/hfs 4.7.43 → 4.7.45

package/runtime/scripts/guards/release-definition.mjs

@@ -1,204 +1,204 @@
-// release-definition.mjs - what makes a commit of the runtime repository a RELEASE commit, the one definition shared by the
-// pre-push hook (scripts/guards/release-push-gate.mjs) and the release cut (scripts/supervisor/release-cut.mjs). The remote
-// main of the runtime moves exactly when a release is cut, so a push of main or of a v* tag is judged against this list:
-//   RELEASE_VERSION_UNCHANGED   package.json `version` at the pushed commit differs from the version at the remote main's head
-//   RELEASE_VERSION_NOT_NEXT    that version is the next release after the highest v* tag (scripts/lib/release-version.mjs, owner ruling release-waves):
-//                               the next wave alpha.N.M+1 of its line or the next line alpha.N+1, never the legacy -fix form
-//   RELEASE_TAG_VERSION         the release tag is v<version> of the pushed commit
-//   RELEASE_CHANGELOG_SECTION   CHANGELOG.md holds `## [<version>] - <date>` (a dated heading) with no unfinished marker (R222)
-//   RELEASE_TAG_MISSING         an ANNOTATED tag v<version> points at the pushed commit
-//   RELEASE_RECEIPT_MISSING     the L4 record of exactly this commit (scripts/guards/release-record.mjs, written by the cut) names this tag
-//   RELEASE_RECEIPT_INCOMPLETE  that record holds a green row for each of RECEIPT_STEPS (the package clean-test, the scaffold e2e and the checks) (RAN on this commit or reused from another with the identical input digest, the record's `reusedFrom` names it; owner ruling speed-flow, 2026-10-25)
-//   RELEASE_SUITE_MODE          the record says `suite: ci` (the Linux parity delegated to CI) while the checked-out config says `local`, or it lists no delegated linux-parity: a record never claims the mode by
-//                               itself (scripts/guards/release-suite-mode.mjs); both modes ask for the same root rows, the runtime has no spec suite to delegate (owner ruling no-runtime-specs)
-// Each finding names what is missing and the command that produces it. Pure over the git reads; no bypass.
-import { catFile } from '../api/git/cat-file.mjs';
-import { revParseQuery } from '../api/git/rev-parse-query.mjs';
-import { show } from '../api/git/show.mjs';
-import { tag as gitTag } from '../api/git/tag.mjs';
-import { mergeBaseQuery } from '../api/git/merge-base-query.mjs';
-import { pathKey, realPath } from '../lib/path-key.mjs';
-import { changelogSection, releaseNotesFindings } from '../hfs/runtime-rules/release-notes.mjs';
-import { nextReleases, releaseVersionRefusal, taggedVersions } from '../lib/release-version.mjs';
-import { readL4Record } from './release-record.mjs';
-import { suiteModeOf } from './release-suite-mode.mjs';
-
-/** The rows the L4 record must hold green, run on the commit or reused from an identical-digest row of another, in either suite mode: the package clean-test, the scaffold e2e and the checks (the runtime's real tests). */
-export const RECEIPT_STEPS = Object.freeze(['npm run test:packages', 'npm run test:e2e', 'npm run check']);
-const CUT_COMMAND = (tag) => `starci release cut --tag ${tag}`;
-const REGEX_SPECIALS = /[.*+?^$()|[\]{}\\]/g;
-const HEADING_HEAD = String.raw`^## \[`;
-const DATED_HEADING_TAIL = String.raw`\] — \d{4}-\d{2}-\d{2}\s*$`;
-const DATED_HEADING = (version) => new RegExp([HEADING_HEAD, version.replaceAll(REGEX_SPECIALS, String.raw`\$&`), DATED_HEADING_TAIL].join(''), 'mu');
-
-const finding = (code, missing, fix) => ({ code, missing, fix });
-const gitText = (verb, args, cwd) => {
-  const r = verb(args, { cwd, timeout: 60_000 });
-  return r.status === 0 ? String(r.stdout ?? '') : null;
-};
-
-/** The package.json version of `commit`, or null when the commit or its manifest cannot be read. */
-export function versionAt(cwd, commit) {
-  const text = gitText(show, [`${commit}:package.json`], cwd);
-  try { return text === null ? null : JSON.parse(text).version ?? null; } catch { return null; }
-}
-
-const releaseUnknown = (why) => ({ ok: false, status: 'unknown', why });
-const ineligibleRelease = (explicit, why) => explicit ? releaseUnknown(why) : { ok: true, candidate: null };
-
-/** A runtime Git root's nearest annotated, manifest-bound release; enclosing application history is inapplicable. */
-export function releaseTagOf({ repo, tag = null, excludeHead = false }) {
-  const history = runtimeGitHistory(repo);
-  if (!history.ok) return history;
-  const listed = tag === null ? gitText(gitTag, ['--merged', 'HEAD', '--list', 'v*'], repo) : tag;
-  if (listed === null) return releaseUnknown('release tags are unreadable');
-  const candidates = [];
-  for (const named of listed.split(/\r?\n/).filter(Boolean)) {
-    const result = releaseCandidate({ repo, named, current: history.head, explicit: tag !== null, excludeHead });
-    if (!result.ok) return result;
-    if (result.candidate) candidates.push(result.candidate);
-  }
-  return nearestRelease(repo, candidates);
-}
-
-/** Runtime history exists only at its own Git top-level with a readable HEAD and full ancestry. */
-function runtimeGitHistory(repo) {
-  const top = revParseQuery(['--show-toplevel'], { cwd: repo });
-  if (top.status !== 0) {
-    if (/not a git repository/i.test(String(top.stderr ?? ''))) return { ok: false, status: 'no-repository', why: 'release history requires a Git repository' };
-    return releaseUnknown('release repository identity is unreadable');
-  }
-  const gitRoot = String(top.stdout ?? '').trim();
-  if (!gitRoot) return releaseUnknown('release repository root is unreadable');
-  if (pathKey(realPath(gitRoot)) !== pathKey(realPath(repo))) return { ok: false, status: 'no-runtime-repository', why: 'the runtime copy is inside an enclosing Git repository; its history belongs to that repository' };
-  const head = gitText(revParseQuery, ['HEAD'], repo)?.trim();
-  if (!head) return releaseUnknown('release history HEAD is unreadable');
-  if (gitText(revParseQuery, ['--is-shallow-repository'], repo)?.trim() !== 'false') return releaseUnknown('release history is shallow or unreadable; fetch complete release history');
-  return { ok: true, head };
-}
-
-/** A candidate binds annotation, peeled commit, manifest spelling and ancestry; default discovery omits ineligible tags. */
-function releaseCandidate({ repo, named, current, explicit, excludeHead }) {
-  const kind = gitText(catFile, ['-t', `refs/tags/${named}`], repo)?.trim();
-  const head = gitText(revParseQuery, [`refs/tags/${named}^{commit}`], repo)?.trim();
-  if (!kind || !head) return releaseUnknown(`release tag ${named} is unreadable`);
-  if (kind !== 'tag') return ineligibleRelease(explicit, `release tag ${named} is not annotated`);
-  const version = versionAt(repo, head);
-  if (!version) return releaseUnknown(`release manifest of ${named} is unreadable`);
-  if (named !== `v${version}`) return ineligibleRelease(explicit, `release tag ${named} differs from its manifest version ${version}`);
-  const reachable = releaseAncestor(repo, head, current);
-  if (reachable === null) return releaseUnknown(`release ancestry of ${named} is unreadable`);
-  if (!reachable) return ineligibleRelease(explicit, `release tag ${named} is not merged in HEAD`);
-  if (excludeHead && head === current) return { ok: true, candidate: null };
-  return { ok: true, candidate: { tag: named, head } };
-}
-
-/** Only one unsuperseded release ancestor proves a boundary; incomparable releases hold. */
-function nearestRelease(repo, candidates) {
-  if (!candidates.length) return releaseUnknown('no eligible annotated, manifest-bound release tag is merged in HEAD');
-  const nearest = [];
-  for (const candidate of candidates) {
-    const superseded = candidateSuperseded(repo, candidate, candidates);
-    if (superseded === null) return releaseUnknown('release ancestry between tags is unreadable');
-    if (!superseded) nearest.push(candidate);
-  }
-  if (nearest.length !== 1) return releaseUnknown(`release history is ambiguous: ${nearest.map((entry) => entry.tag).join(', ')}`);
-  return { ok: true, ...nearest[0] };
-}
-
-/** A release loses its boundary only to a proven descendant release, never to a date or version sort. */
-function candidateSuperseded(repo, candidate, candidates) {
-  for (const other of candidates) {
-    if (candidate.head === other.head) continue;
-    const older = releaseAncestor(repo, candidate.head, other.head);
-    if (older === null) return null;
-    if (older) return true;
-  }
-  return false;
-}
-
-/** Missing Git proof is distinct from a proven non-ancestor. */
-function releaseAncestor(repo, before, after) {
-  const result = mergeBaseQuery(['--is-ancestor', before, after], { cwd: repo });
-  if (result.status === 0) return true;
-  if (result.status === 1) return false;
-  return null;
-}
-
-/** The next releases named from the released versions, for a fix text: "v<wave> or v<line>". */
-const nextNamed = (released, version = null) => {
-  const next = nextReleases(released, version);
-  return next ? `v${next.wave} or v${next.line}` : 'v<new version>';
-};
-
-function versionFindings({ cwd, remoteCommit, version, released }) {
-  if (!remoteCommit) return [];
-  const remoteVersion = versionAt(cwd, remoteCommit);
-  if (remoteVersion === null) return [finding('RELEASE_REMOTE_HEAD_UNKNOWN', `the remote main head ${remoteCommit.slice(0, 9)} is not in this repository, so its version cannot be compared`, 'git fetch origin main')];
-  if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released, version))}`)];
-  return [];
-}
-
-/** The version must be the next release after the highest v* tag other than its own: a wave alpha.N.M is counted, never guessed. */
-function nextReleaseFindings({ version, released }) {
-  if (released === null) return [finding('RELEASE_VERSION_NOT_NEXT', 'the v* tags are unreadable, so the next release cannot be derived', 'git fetch --tags')];
-  const refusal = releaseVersionRefusal(version, released);
-  return refusal ? [finding('RELEASE_VERSION_NOT_NEXT', refusal, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released.filter((entry) => entry !== version), version))}`)] : [];
-}
-
-function changelogFindings({ cwd, commit, version, tag }) {
-  const changelog = gitText(show, [`${commit}:CHANGELOG.md`], cwd);
-  if (changelog === null) return [finding('RELEASE_CHANGELOG_SECTION', 'CHANGELOG.md is not readable at the pushed commit', 'restore CHANGELOG.md')];
-  const notes = releaseNotesFindings({ tags: [tag], changelog });
-  if (notes.length) return notes.map((n) => finding('RELEASE_CHANGELOG_SECTION', n.message, 'finish the CHANGELOG section of the release (no in-preparation mark, no open marker), commit'));
-  if (!changelogSection(changelog, version).found || !DATED_HEADING(version).test(changelog)) return [finding('RELEASE_CHANGELOG_SECTION', `CHANGELOG.md has no dated heading "## [${version}] — YYYY-MM-DD"`, `date the heading of the ${version} section, commit`)];
-  return [];
-}
-
-function tagFindings({ cwd, commit, tag }) {
-  const kind = gitText(catFile, ['-t', `refs/tags/${tag}`], cwd)?.trim();
-  const target = gitText(revParseQuery, [`refs/tags/${tag}^{commit}`], cwd)?.trim();
-  if (kind === 'tag' && target === commit) return [];
-  return [finding('RELEASE_TAG_MISSING', `no annotated tag ${tag} points at ${commit.slice(0, 9)}`, CUT_COMMAND(tag))];
-}
-
-/** The finding of a record that claims the delegated mode without the checked-out config saying so (or without naming the delegated linux-parity row), else null. */
-function suiteModeFinding({ record, cwd, commit, tag }) {
-  if (record.suite !== 'ci') return null;
-  if (suiteModeOf(cwd) !== 'ci') return finding('RELEASE_SUITE_MODE', `the release record of ${commit.slice(0, 9)} says suite: ci, but this checkout's config.yaml release.suite is not ci: a record does not choose the mode`, `set release.suite: ci in config.yaml (the owner's choice), or ${CUT_COMMAND(tag)} under suite: local`);
-  if (!(record.delegated ?? []).some((row) => row?.name === 'linux-parity')) return finding('RELEASE_SUITE_MODE', `the suite: ci record of ${commit.slice(0, 9)} does not list linux-parity as delegated`, CUT_COMMAND(tag));
-  return null;
-}
-
-function receiptFindings({ cwd, commit, tag }) {
-  const record = readL4Record({ repo: cwd, head: commit, tag });
-  if (!record) return [finding('RELEASE_RECEIPT_MISSING', `no release record for exactly ${commit.slice(0, 9)} and ${tag}: the package clean-test, the scaffold e2e and the check did not run green on this commit`, CUT_COMMAND(tag))];
-  const mode = suiteModeFinding({ record, cwd, commit, tag });
-  if (mode) return [mode];
-  // A row reused from another commit (reusedFrom) counts: the cut reuses a row only when its input digest is identical (owner ruling speed-flow, 2026-10-25), and the record names the commit it came from.
-  const green = new Set((record.logs ?? []).filter((row) => row?.ok === true).map((row) => row.name));
-  const absent = RECEIPT_STEPS.filter((name) => !green.has(name));
-  return absent.length ? [finding('RELEASE_RECEIPT_INCOMPLETE', `the release record of ${commit.slice(0, 9)} has no green row for: ${absent.join(', ')}`, CUT_COMMAND(tag))] : [];
-}
-
-/**
- * The findings that keep `commit` from being a release commit of the repository at `cwd`: [{code, missing, fix}], [] when it is one.
- * `remoteCommit` is the remote main's head being replaced (null for a tag push or a first push); `tag` the release tag (default v<version>);
- * `needTag` / `needReceipt` are false only for the cut's early look, before it has created the tag and run the suite.
- */
-export function releaseFindings({ cwd, commit, remoteCommit = null, tag = null, needTag = true, needReceipt = true }) {
-  const version = versionAt(cwd, commit);
-  if (!version) return [finding('RELEASE_VERSION_UNREADABLE', `package.json at ${commit.slice(0, 9)} has no readable version`, 'restore package.json')];
-  const expected = `v${version}`;
-  const named = tag ?? expected;
-  if (named !== expected) return [finding('RELEASE_TAG_VERSION', `the tag ${named} is not v${version}, the version of ${commit.slice(0, 9)}`, `tag v${version}, or set package.json version to ${named.replace(/^v/, '')}`)];
-  const listed = gitText(gitTag, ['--list', 'v*'], cwd);
-  const released = listed === null ? null : taggedVersions(listed);
-  return [
-    ...versionFindings({ cwd, remoteCommit, version, released: released ?? [] }),
-    ...nextReleaseFindings({ version, released }),
-    ...changelogFindings({ cwd, commit, version, tag: named }),
-    ...(needTag ? tagFindings({ cwd, commit, tag: named }) : []),
-    ...(needReceipt ? receiptFindings({ cwd, commit, tag: named }) : []),
-  ];
-}
+// release-definition.mjs - what makes a commit of the runtime repository a RELEASE commit, the one definition shared by the
+// pre-push hook (scripts/guards/release-push-gate.mjs) and the release cut (scripts/supervisor/release-cut.mjs). The remote
+// main of the runtime moves exactly when a release is cut, so a push of main or of a v* tag is judged against this list:
+//   RELEASE_VERSION_UNCHANGED   package.json `version` at the pushed commit differs from the version at the remote main's head
+//   RELEASE_VERSION_NOT_NEXT    that version is the next release after the highest v* tag (scripts/lib/release-version.mjs, owner ruling release-waves):
+//                               the next wave alpha.N.M+1 of its line or the next line alpha.N+1, never the legacy -fix form
+//   RELEASE_TAG_VERSION         the release tag is v<version> of the pushed commit
+//   RELEASE_CHANGELOG_SECTION   CHANGELOG.md holds `## [<version>] - <date>` (a dated heading) with no unfinished marker (R222)
+//   RELEASE_TAG_MISSING         an ANNOTATED tag v<version> points at the pushed commit
+//   RELEASE_RECEIPT_MISSING     the L4 record of exactly this commit (scripts/guards/release-record.mjs, written by the cut) names this tag
+//   RELEASE_RECEIPT_INCOMPLETE  that record holds a green row for each of RECEIPT_STEPS (the package clean-test, the scaffold e2e and the checks) (RAN on this commit or reused from another with the identical input digest, the record's `reusedFrom` names it; owner ruling speed-flow, 2026-10-25)
+//   RELEASE_SUITE_MODE          the record says `suite: ci` (the Linux parity delegated to CI) while the checked-out config says `local`, or it lists no delegated linux-parity: a record never claims the mode by
+//                               itself (scripts/guards/release-suite-mode.mjs); both modes ask for the same root rows, the runtime has no spec suite to delegate (owner ruling no-runtime-specs)
+// Each finding names what is missing and the command that produces it. Pure over the git reads; no bypass.
+import { catFile } from '../api/git/cat-file.mjs';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { show } from '../api/git/show.mjs';
+import { tag as gitTag } from '../api/git/tag.mjs';
+import { mergeBaseQuery } from '../api/git/merge-base-query.mjs';
+import { pathKey, realPath } from '../lib/path-key.mjs';
+import { changelogSection, releaseNotesFindings } from '../hfs/runtime-rules/release-notes.mjs';
+import { nextReleases, releaseVersionRefusal, taggedVersions } from '../lib/release-version.mjs';
+import { readL4Record } from './release-record.mjs';
+import { suiteModeOf } from './release-suite-mode.mjs';
+
+/** The rows the L4 record must hold green, run on the commit or reused from an identical-digest row of another, in either suite mode: the package clean-test, the scaffold e2e and the checks (the runtime's real tests). */
+export const RECEIPT_STEPS = Object.freeze(['npm run test:packages', 'npm run test:e2e', 'npm run check']);
+const CUT_COMMAND = (tag) => `starci release cut --tag ${tag}`;
+const REGEX_SPECIALS = /[.*+?^$()|[\]{}\\]/g;
+const HEADING_HEAD = String.raw`^## \[`;
+const DATED_HEADING_TAIL = String.raw`\] — \d{4}-\d{2}-\d{2}\s*$`;
+const DATED_HEADING = (version) => new RegExp([HEADING_HEAD, version.replaceAll(REGEX_SPECIALS, String.raw`\$&`), DATED_HEADING_TAIL].join(''), 'mu');
+
+const finding = (code, missing, fix) => ({ code, missing, fix });
+const gitText = (verb, args, cwd) => {
+  const r = verb(args, { cwd, timeout: 60_000 });
+  return r.status === 0 ? String(r.stdout ?? '') : null;
+};
+
+/** The package.json version of `commit`, or null when the commit or its manifest cannot be read. */
+export function versionAt(cwd, commit) {
+  const text = gitText(show, [`${commit}:package.json`], cwd);
+  try { return text === null ? null : JSON.parse(text).version ?? null; } catch { return null; }
+}
+
+const releaseUnknown = (why) => ({ ok: false, status: 'unknown', why });
+const ineligibleRelease = (explicit, why) => explicit ? releaseUnknown(why) : { ok: true, candidate: null };
+
+/** A runtime Git root's nearest annotated, manifest-bound release; enclosing application history is inapplicable. */
+export function releaseTagOf({ repo, tag = null, excludeHead = false }) {
+  const history = runtimeGitHistory(repo);
+  if (!history.ok) return history;
+  const listed = tag === null ? gitText(gitTag, ['--merged', 'HEAD', '--list', 'v*'], repo) : tag;
+  if (listed === null) return releaseUnknown('release tags are unreadable');
+  const candidates = [];
+  for (const named of listed.split(/\r?\n/).filter(Boolean)) {
+    const result = releaseCandidate({ repo, named, current: history.head, explicit: tag !== null, excludeHead });
+    if (!result.ok) return result;
+    if (result.candidate) candidates.push(result.candidate);
+  }
+  return nearestRelease(repo, candidates);
+}
+
+/** Runtime history exists only at its own Git top-level with a readable HEAD and full ancestry. */
+function runtimeGitHistory(repo) {
+  const top = revParseQuery(['--show-toplevel'], { cwd: repo });
+  if (top.status !== 0) {
+    if (/not a git repository/i.test(String(top.stderr ?? ''))) return { ok: false, status: 'no-repository', why: 'release history requires a Git repository' };
+    return releaseUnknown('release repository identity is unreadable');
+  }
+  const gitRoot = String(top.stdout ?? '').trim();
+  if (!gitRoot) return releaseUnknown('release repository root is unreadable');
+  if (pathKey(realPath(gitRoot)) !== pathKey(realPath(repo))) return { ok: false, status: 'no-runtime-repository', why: 'the runtime copy is inside an enclosing Git repository; its history belongs to that repository' };
+  const head = gitText(revParseQuery, ['HEAD'], repo)?.trim();
+  if (!head) return releaseUnknown('release history HEAD is unreadable');
+  if (gitText(revParseQuery, ['--is-shallow-repository'], repo)?.trim() !== 'false') return releaseUnknown('release history is shallow or unreadable; fetch complete release history');
+  return { ok: true, head };
+}
+
+/** A candidate binds annotation, peeled commit, manifest spelling and ancestry; default discovery omits ineligible tags. */
+function releaseCandidate({ repo, named, current, explicit, excludeHead }) {
+  const kind = gitText(catFile, ['-t', `refs/tags/${named}`], repo)?.trim();
+  const head = gitText(revParseQuery, [`refs/tags/${named}^{commit}`], repo)?.trim();
+  if (!kind || !head) return releaseUnknown(`release tag ${named} is unreadable`);
+  if (kind !== 'tag') return ineligibleRelease(explicit, `release tag ${named} is not annotated`);
+  const version = versionAt(repo, head);
+  if (!version) return releaseUnknown(`release manifest of ${named} is unreadable`);
+  if (named !== `v${version}`) return ineligibleRelease(explicit, `release tag ${named} differs from its manifest version ${version}`);
+  const reachable = releaseAncestor(repo, head, current);
+  if (reachable === null) return releaseUnknown(`release ancestry of ${named} is unreadable`);
+  if (!reachable) return ineligibleRelease(explicit, `release tag ${named} is not merged in HEAD`);
+  if (excludeHead && head === current) return { ok: true, candidate: null };
+  return { ok: true, candidate: { tag: named, head } };
+}
+
+/** Only one unsuperseded release ancestor proves a boundary; incomparable releases hold. */
+function nearestRelease(repo, candidates) {
+  if (!candidates.length) return releaseUnknown('no eligible annotated, manifest-bound release tag is merged in HEAD');
+  const nearest = [];
+  for (const candidate of candidates) {
+    const superseded = candidateSuperseded(repo, candidate, candidates);
+    if (superseded === null) return releaseUnknown('release ancestry between tags is unreadable');
+    if (!superseded) nearest.push(candidate);
+  }
+  if (nearest.length !== 1) return releaseUnknown(`release history is ambiguous: ${nearest.map((entry) => entry.tag).join(', ')}`);
+  return { ok: true, ...nearest[0] };
+}
+
+/** A release loses its boundary only to a proven descendant release, never to a date or version sort. */
+function candidateSuperseded(repo, candidate, candidates) {
+  for (const other of candidates) {
+    if (candidate.head === other.head) continue;
+    const older = releaseAncestor(repo, candidate.head, other.head);
+    if (older === null) return null;
+    if (older) return true;
+  }
+  return false;
+}
+
+/** Missing Git proof is distinct from a proven non-ancestor. */
+function releaseAncestor(repo, before, after) {
+  const result = mergeBaseQuery(['--is-ancestor', before, after], { cwd: repo });
+  if (result.status === 0) return true;
+  if (result.status === 1) return false;
+  return null;
+}
+
+/** The next releases named from the released versions, for a fix text: "v<wave> or v<line>". */
+const nextNamed = (released, version = null) => {
+  const next = nextReleases(released, version);
+  return next ? `v${next.wave} or v${next.line}` : 'v<new version>';
+};
+
+function versionFindings({ cwd, remoteCommit, version, released }) {
+  if (!remoteCommit) return [];
+  const remoteVersion = versionAt(cwd, remoteCommit);
+  if (remoteVersion === null) return [finding('RELEASE_REMOTE_HEAD_UNKNOWN', `the remote main head ${remoteCommit.slice(0, 9)} is not in this repository, so its version cannot be compared`, 'git fetch origin main')];
+  if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released, version))}`)];
+  return [];
+}
+
+/** The version must be the next release after the highest v* tag other than its own: a wave alpha.N.M is counted, never guessed. */
+function nextReleaseFindings({ version, released }) {
+  if (released === null) return [finding('RELEASE_VERSION_NOT_NEXT', 'the v* tags are unreadable, so the next release cannot be derived', 'git fetch --tags')];
+  const refusal = releaseVersionRefusal(version, released);
+  return refusal ? [finding('RELEASE_VERSION_NOT_NEXT', refusal, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released.filter((entry) => entry !== version), version))}`)] : [];
+}
+
+function changelogFindings({ cwd, commit, version, tag }) {
+  const changelog = gitText(show, [`${commit}:CHANGELOG.md`], cwd);
+  if (changelog === null) return [finding('RELEASE_CHANGELOG_SECTION', 'CHANGELOG.md is not readable at the pushed commit', 'restore CHANGELOG.md')];
+  const notes = releaseNotesFindings({ tags: [tag], changelog });
+  if (notes.length) return notes.map((n) => finding('RELEASE_CHANGELOG_SECTION', n.message, 'finish the CHANGELOG section of the release (no in-preparation mark, no open marker), commit'));
+  if (!changelogSection(changelog, version).found || !DATED_HEADING(version).test(changelog)) return [finding('RELEASE_CHANGELOG_SECTION', `CHANGELOG.md has no dated heading "## [${version}] — YYYY-MM-DD"`, `date the heading of the ${version} section, commit`)];
+  return [];
+}
+
+function tagFindings({ cwd, commit, tag }) {
+  const kind = gitText(catFile, ['-t', `refs/tags/${tag}`], cwd)?.trim();
+  const target = gitText(revParseQuery, [`refs/tags/${tag}^{commit}`], cwd)?.trim();
+  if (kind === 'tag' && target === commit) return [];
+  return [finding('RELEASE_TAG_MISSING', `no annotated tag ${tag} points at ${commit.slice(0, 9)}`, CUT_COMMAND(tag))];
+}
+
+/** The finding of a record that claims the delegated mode without the checked-out config saying so (or without naming the delegated linux-parity row), else null. */
+function suiteModeFinding({ record, cwd, commit, tag }) {
+  if (record.suite !== 'ci') return null;
+  if (suiteModeOf(cwd) !== 'ci') return finding('RELEASE_SUITE_MODE', `the release record of ${commit.slice(0, 9)} says suite: ci, but this checkout's config.yaml release.suite is not ci: a record does not choose the mode`, `set release.suite: ci in config.yaml (the owner's choice), or ${CUT_COMMAND(tag)} under suite: local`);
+  if (!(record.delegated ?? []).some((row) => row?.name === 'linux-parity')) return finding('RELEASE_SUITE_MODE', `the suite: ci record of ${commit.slice(0, 9)} does not list linux-parity as delegated`, CUT_COMMAND(tag));
+  return null;
+}
+
+function receiptFindings({ cwd, commit, tag }) {
+  const record = readL4Record({ repo: cwd, head: commit, tag });
+  if (!record) return [finding('RELEASE_RECEIPT_MISSING', `no release record for exactly ${commit.slice(0, 9)} and ${tag}: the package clean-test, the scaffold e2e and the check did not run green on this commit`, CUT_COMMAND(tag))];
+  const mode = suiteModeFinding({ record, cwd, commit, tag });
+  if (mode) return [mode];
+  // A row reused from another commit (reusedFrom) counts: the cut reuses a row only when its input digest is identical (owner ruling speed-flow, 2026-10-25), and the record names the commit it came from.
+  const green = new Set((record.logs ?? []).filter((row) => row?.ok === true).map((row) => row.name));
+  const absent = RECEIPT_STEPS.filter((name) => !green.has(name));
+  return absent.length ? [finding('RELEASE_RECEIPT_INCOMPLETE', `the release record of ${commit.slice(0, 9)} has no green row for: ${absent.join(', ')}`, CUT_COMMAND(tag))] : [];
+}
+
+/**
+ * The findings that keep `commit` from being a release commit of the repository at `cwd`: [{code, missing, fix}], [] when it is one.
+ * `remoteCommit` is the remote main's head being replaced (null for a tag push or a first push); `tag` the release tag (default v<version>);
+ * `needTag` / `needReceipt` are false only for the cut's early look, before it has created the tag and run the suite.
+ */
+export function releaseFindings({ cwd, commit, remoteCommit = null, tag = null, needTag = true, needReceipt = true }) {
+  const version = versionAt(cwd, commit);
+  if (!version) return [finding('RELEASE_VERSION_UNREADABLE', `package.json at ${commit.slice(0, 9)} has no readable version`, 'restore package.json')];
+  const expected = `v${version}`;
+  const named = tag ?? expected;
+  if (named !== expected) return [finding('RELEASE_TAG_VERSION', `the tag ${named} is not v${version}, the version of ${commit.slice(0, 9)}`, `tag v${version}, or set package.json version to ${named.replace(/^v/, '')}`)];
+  const listed = gitText(gitTag, ['--list', 'v*'], cwd);
+  const released = listed === null ? null : taggedVersions(listed);
+  return [
+    ...versionFindings({ cwd, remoteCommit, version, released: released ?? [] }),
+    ...nextReleaseFindings({ version, released }),
+    ...changelogFindings({ cwd, commit, version, tag: named }),
+    ...(needTag ? tagFindings({ cwd, commit, tag: named }) : []),
+    ...(needReceipt ? receiptFindings({ cwd, commit, tag: named }) : []),
+  ];
+}

package/runtime/scripts/hfs/architecture/index.mjs

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { canonical, loadArchitectureConfig } from './config.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { buildTypeScriptContext, relativePath } from './typescript.mjs';
+import { withTypeScriptProgramRun } from '../typescript-programs.mjs';
 import { checkBackend } from './backend.mjs';
 import { checkBackendContracts, PUBLIC_CONTRACT_RULE_ID, READONLY_BOUNDARY_RULE_ID } from './contracts.mjs';
 import { checkFrontend } from './frontend.mjs';
@@ -324,7 +325,7 @@ function scopeFindings({ config, context, violations, paths, surface }) {
  * that read the whole repository to answer (clones, dead exports, repository-wide symbols); the pre-push check of the changed owners uses it.
  */
 export function checkArchitecture(options = {}) {
-  return withTreeCache(() => checkArchitectureOnce(options));
+  return withTypeScriptProgramRun(() => withTreeCache(() => checkArchitectureOnce(options)));
 }
 
 function checkArchitectureOnce({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs, surface = 'all' }) {

package/runtime/scripts/hfs/architecture/type-context.mjs

@@ -103,36 +103,35 @@ function createProjects(config, paths, state, selection, ts, helpers) {
   return projects;
 }
 
+function ownershipRank(config, project, file, helpers) {
+  return helpers.isInside(path.dirname(path.join(config.root, ...project.relative.split('/'))), file)
+    ? project.relative.split('/').length : -1;
+}
+
 function collectProjectFiles(config, projects, helpers) {
-  const occurrences = new Map();
-  const sourceIn = new Map();
+  const fileMap = new Map();
+  const ownerByFile = new Map();
+  // Retain only the winning source occurrence while visiting each project. Equal ranks keep the first project,
+  // as does a file outside every project directory; the deepest enclosing tsconfig otherwise owns its checker.
+  // Within that project the last realpath alias supplies the source, matching the compiler's occurrence order.
   for (const project of projects) {
-    for (const sourceFile of project.program.getSourceFiles().filter(file => helpers.isProductionSource(config.root, file))) {
+    for (const sourceFile of project.program.getSourceFiles()) {
+      if (!helpers.isProductionSource(config.root, sourceFile)) continue;
       const name = helpers.canonical(sourceFile.fileName);
-      if (!occurrences.has(name)) occurrences.set(name, []);
-      occurrences.get(name).push(project);
-      sourceIn.set(`${project.relative}|${name}`, sourceFile);
+      const owner = ownerByFile.get(name);
+      if (owner === project) { fileMap.set(name, sourceFile); continue; }
+      if (owner && ownershipRank(config, owner, name, helpers) >= ownershipRank(config, project, name, helpers)) continue;
+      ownerByFile.set(name, project);
+      fileMap.set(name, sourceFile);
     }
   }
-  return { occurrences, sourceIn };
-}
-
-function owningProject(config, candidates, file, helpers) {
-  return candidates.filter(item => helpers.isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), file))
-    .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+  return { fileMap, ownerByFile };
 }
 
 function makeFileGraph(config, projects, helpers) {
-  const { occurrences, sourceIn } = collectProjectFiles(config, projects, helpers);
-  const fileMap = new Map();
+  const { fileMap, ownerByFile } = collectProjectFiles(config, projects, helpers);
   const checkerByFile = new Map();
-  const ownerByFile = new Map();
-  for (const [name, candidates] of occurrences) {
-    const owner = owningProject(config, candidates, name, helpers);
-    ownerByFile.set(name, owner);
-    fileMap.set(name, sourceIn.get(`${owner.relative}|${name}`));
-    checkerByFile.set(name, owner.program.getTypeChecker());
-  }
+  for (const [name, owner] of ownerByFile) checkerByFile.set(name, owner.program.getTypeChecker());
   const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
   const edges = new Map([...fileMap.keys()].map(file => [file, []]));
   for (const [file, sourceFile] of fileMap) {
@@ -142,6 +141,21 @@ function makeFileGraph(config, projects, helpers) {
   return { fileMap, checkerByFile, ownerByFile, files, edges };
 }
 
+// Resolution entries contain failed lookup paths as well as hits. Keep only one bounded batch for the current project;
+// graph edges retain the resolved targets, so rotating this scratch cache changes neither coverage nor findings.
+const RESOLUTION_BATCH_SIZE = 1024;
+
+function resolutionCache(state, project) {
+  if (state.resolutionProject !== project || state.resolutionCount === RESOLUTION_BATCH_SIZE) {
+    state.resolutionProject = project;
+    state.resolutionCount = 0;
+    state.resolutionCache = state.ts.createModuleResolutionCache(state.config.root,
+      file => state.ts.sys.useCaseSensitiveFileNames ? file : file.toLowerCase(), project.options);
+  }
+  state.resolutionCount += 1;
+  return state.resolutionCache;
+}
+
 function addUnprovenFindings(sourceFile, project, references, errors, config, helpers) {
   for (const item of references.unproven) errors.push({
     ruleId: 'ARCH_DYNAMIC_DEPENDENCY_UNPROVEN',
@@ -229,7 +243,7 @@ function processReference(from, sourceFile, project, owningWorkspace, reference,
   const { config, ts, workspaceNames, workspaces, host, errors, helpers } = state;
   // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
   const workspaceTarget = workspaces.filter(item => item.root !== helpers.canonical(config.root)).map(item => helpers.workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
-  const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host);
+  const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
   if (!resolvedName) {
     unresolvedReferenceFinding(reference, sourceFile, project, config, workspaceNames, errors, helpers);
     return;
@@ -279,7 +293,8 @@ export function contextFromProjects(config, loaded, paths, helpers) {
   const fileGraph = makeFileGraph(config, projects, helpers);
   const { edges, workspaces } = dependencyGraph(config, loaded, fileGraph, fileGraph.ownerByFile, errors, helpers);
   if (projects.length && fileGraph.files.length === 0) errors.push({ ruleId: 'ARCH_NO_SOURCE', message: 'The configured TypeScript projects contain no production TypeScript or JavaScript source.' });
+  const { checkerByFile } = fileGraph;
   return { loaded, errors, files: fileGraph.files, edges, programs: projects.map(item => item.program), program: projects[0]?.program ?? null, projects, ts, workspaces,
-    checkerFor: file => fileGraph.checkerByFile.get(helpers.canonical(file)) ?? null,
+    checkerFor: file => checkerByFile.get(helpers.canonical(file)) ?? null,
     workspaceOf: file => helpers.workspaceOf(workspaces, helpers.canonical(file)) };
 }