@rightkit/release 0.6.3 → 0.6.5

package/bin/rightkit-gate.mjs

@@ -24,10 +24,16 @@
 //   rightkit-gate [--base <ref>] [--plan] [--no-cache]
 //                                             run the gate (default base origin/main); --plan prints the scans and runs none;
 //                                             --no-cache (or RK_GATE_CACHE=0) reruns every scan
+//   rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
+//                                             the offline app check (../app-check.mjs): committed files only, no network, compile or
+//                                             broker, every finding in one run. Exit 0 pass, 1 findings, 2 could not run
 //   rightkit-gate install-hook [--force]      write .githooks/pre-push and set core.hooksPath. core.hooksPath hides .git/hooks, so the
-//                                             pre-push hook runs the repository's own .git/hooks/pre-push first and every other hook
-//                                             present in .git/hooks gets a .githooks/<name> trampoline that runs it; the hook finds
-//                                             the gate binary in the root node_modules/.bin, then any workspace package's, then pnpm exec
+//                                             pre-push hook runs the repository's own .git/hooks/pre-push first, then `rightkit-gate
+//                                             check --commit HEAD`, then the gate; every other hook present in .git/hooks gets a
+//                                             .githooks/<name> trampoline that runs it; the hook finds the gate binary in the root
+//                                             node_modules/.bin, then any workspace package's, then pnpm exec. Where @rightkit/release is
+//                                             installed it also writes the advisory ownership pre-commit step (`right-release hooks install`
+//                                             is an alias of this command)
 //
 // From the pre-push hook, git's ref lines arrive on stdin: the commit being pushed must be the checked-out HEAD (broker scans
 // read the live checkout), and the remote's current commit is the diff base. To push an earlier commit of the local stack,
@@ -58,7 +64,7 @@ const text = (r) => String(r?.stdout ?? "");
 const failed = (r) => !r || Boolean(r.error) || r.status !== 0;
 const why = (r) => String(r?.error?.message ?? r?.stderr ?? "").trim().split(/\r?\n/).slice(-3).join(" | ");
 
-const USAGE = `usage: rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | --version`;
+const USAGE = `usage: rightkit-gate [--base <ref>] [--plan] [--no-cache] [--pre-push] | rightkit-gate install-hook [--force] | rightkit-gate check [--repo <dir>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>] | --version`;
 
 // ---- pure helpers (exported for tests) ----------------------------------------------------------------------
 
@@ -340,13 +346,15 @@ export function lockScope({ changed, cargoDir = ".", unitNames, showBase, readLo
 /**
  * The pre-push hook. git's ref lines arrive on stdin and the gate consumes them, so stdin is buffered once and fed to both the
  * repository's own .git/hooks/pre-push (which core.hooksPath=.githooks would otherwise hide; it runs first and a failure stops the
- * push) and the gate. The gate binary is the root node_modules/.bin/rightkit-gate, else any workspace package's (up to three
- * levels down: tauri-app-next, apps/*, packages/*), else `pnpm exec rightkit-gate`, else node with a package-relative path when
- * pnpm is absent; the line it chose is printed. No absolute path is written: everything is resolved from git at run time.
+ * push) and the gate. Between them runs the app check, `rightkit-gate check --commit HEAD`: seconds, committed files only, so a
+ * red tree stops the push before the gate's scans start; a push that only deletes refs has no content to check and skips it. The
+ * gate binary is the root node_modules/.bin/rightkit-gate, else any workspace package's (up to three levels down: tauri-app-next,
+ * apps/*, packages/*), else `pnpm exec rightkit-gate`, else node with a package-relative path when pnpm is absent; the line it
+ * chose is printed once. No absolute path is written: everything is resolved from git at run time.
  */
 export function hookText(nodePath) {
   return `#!/bin/sh
-# Mandatory local gate before every push (rightkit-gate install-hook). Never bypass with --no-verify.
+# Mandatory local check and gate before every push (rightkit-gate install-hook). Never bypass with --no-verify.
 cd "$(git rev-parse --show-toplevel)" || exit 1
 stdin=$(mktemp "\${TMPDIR:-/tmp}/rightkit-gate.XXXXXX") || exit 1
 trap 'rm -f "$stdin"' EXIT
@@ -358,18 +366,27 @@ if [ -x "$own" ]; then
   "$own" "$@" < "$stdin" || exit $?
 fi
 # The gate binary: the root install, any workspace package's install, then pnpm exec.
+found=""
 for bin in node_modules/.bin/rightkit-gate */node_modules/.bin/rightkit-gate */*/node_modules/.bin/rightkit-gate */*/*/node_modules/.bin/rightkit-gate; do
-  if [ -x "$bin" ]; then
-    echo "rightkit-gate: using $bin" >&2
-    ("$bin" --base origin/main) < "$stdin"; exit $?
-  fi
+  if [ -x "$bin" ]; then found="$bin"; break; fi
 done
-if command -v pnpm >/dev/null 2>&1; then
+if [ -n "$found" ]; then
+  echo "rightkit-gate: using $found" >&2
+  rightkit_gate() { "$found" "$@"; }
+elif command -v pnpm >/dev/null 2>&1; then
   echo "rightkit-gate: using pnpm exec rightkit-gate" >&2
-  (exec pnpm exec rightkit-gate --base origin/main) < "$stdin"; exit $?
+  rightkit_gate() { pnpm exec rightkit-gate "$@"; }
+else
+  echo "rightkit-gate: using node ${nodePath}" >&2
+  rightkit_gate() { node "${nodePath}" "$@"; }
 fi
-echo "rightkit-gate: using node ${nodePath}" >&2
-(exec node "${nodePath}" --base origin/main) < "$stdin"; exit $?
+# The check first, over the committed files of HEAD; a push that only deletes refs has nothing to check.
+if [ -s "$stdin" ] && ! awk '$2 !~ /^0+$/ { found = 1 } END { exit !found }' "$stdin"; then
+  echo "rightkit-gate: only deletions are pushed; nothing to check" >&2
+else
+  rightkit_gate check --commit HEAD < /dev/null >&2 || exit $?
+fi
+rightkit_gate --base origin/main < "$stdin"; exit $?
 `;
 }
 
@@ -750,13 +767,13 @@ export function quietLeaseLane(o, { tag = "rightkit-gate:", reason = "rightkit-g
 
 // ---- command resolution -------------------------------------------------------------------------------------
 
-// Cargo only through the broker: `rightkit cargo`, or a `cargo` on PATH that is the managed shim (it runs cargo-guard.mjs).
+// Cargo only through the broker: `rustright cargo`, or a `cargo` on PATH that is the managed shim (it runs cargo-guard.mjs).
 function resolveCargoCommand(o) {
   const which = (cmd) => {
     const r = o.spawn(o.platform === "win32" ? "where" : "which", [cmd]);
     return failed(r) ? [] : text(r).split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   };
-  if (which("rightkit").length) return ["rightkit", "cargo"];
+  if (which("rustright").length) return ["rustright", "cargo"];
   const first = which("cargo")[0];
   if (first) { try { if (o.readFile(first).includes("cargo-guard.mjs")) return ["cargo"]; } catch { /* unreadable: not the shim */ } }
   return null;
@@ -780,7 +797,12 @@ function releaseProvider(o, root, git) {
   return null;
 }
 
-function installHook(o, root, force) {
+// The advisory ownership pre-commit step (`right-release hooks install`, ownership-hooks.mjs) runs the pinned @rightkit/release, so
+// it is written only where that is installed. Its own hook and the repository's .git/hooks/pre-commit both keep running.
+const PINNED_CLI = "node_modules/@rightkit/release/cli/right-release.mjs";
+const FOREIGN_PRE_COMMIT = "pre-commit.rightkit-foreign";
+
+async function installHook(o, root, force) {
   const git = (...a) => o.spawn("git", a, { cwd: root });
   const hooksDir = path.join(root, ".githooks");
   const hookPath = path.join(hooksDir, "pre-push");
@@ -797,15 +819,29 @@ function installHook(o, root, force) {
   const gitDirResult = git("rev-parse", "--git-dir");
   let present = [];
   if (!failed(gitDirResult) && text(gitDirResult).trim()) { try { present = o.readdir(path.join(path.resolve(root, text(gitDirResult).trim()), "hooks")); } catch { present = []; } }
+  const gitHooksDir = !failed(gitDirResult) && text(gitDirResult).trim() ? path.join(path.resolve(root, text(gitDirResult).trim()), "hooks") : null;
   const own = present.filter(chainableHook).sort();
-  const skipped = present.filter((name) => !name.endsWith(".sample") && !chainableHook(name)).sort();
+  // The ownership step takes .githooks/pre-commit. The repository's own pre-commit hook keeps running first, through a trampoline
+  // beside it, unless it is the ownership hook a plain `right-release hooks install` wrote (this one replaces that), whose own
+  // chained hook, pre-commit.rightkit-foreign, then runs instead. A name that is no plain hook name is reported, never chained.
+  const ownership = o.exists(path.join(root, PINNED_CLI)) ? await import("../ownership-hooks.mjs") : null;
+  const readHook = (name) => { try { return o.readFile(path.join(gitHooksDir, name)); } catch { return ""; } };
+  const chainName = !ownership ? null : own.includes("pre-commit") && !readHook("pre-commit").includes(ownership.HOOK_MARKER) ? "pre-commit" : present.includes(FOREIGN_PRE_COMMIT) ? FOREIGN_PRE_COMMIT : null;
+  const skipped = present.filter((name) => !name.endsWith(".sample") && !chainableHook(name) && !(ownership && name === FOREIGN_PRE_COMMIT)).sort();
   if (skipped.length) o.err(`rightkit-gate: WARNING: not chaining .git/hooks/${skipped.join(", .git/hooks/")}: not a plain hook file name (letters, digits, - and _ only); run it from a hook of its own.`);
-  const trampolines = own.filter((name) => name !== "pre-push").map((name) => ({ name, file: path.join(hooksDir, name), wanted: trampolineText(name) }));
+  const trampolines = own.filter((name) => name !== "pre-push" && !(ownership && name === "pre-commit")).map((name) => ({ name, file: path.join(hooksDir, name), wanted: trampolineText(name), note: `runs .git/hooks/${name}` }));
+  if (ownership) {
+    trampolines.push({ name: "pre-commit", file: path.join(hooksDir, "pre-commit"), wanted: ownership.renderPreCommitHook(), ownership: true, replaces: [trampolineText("pre-commit")], marker: ownership.HOOK_MARKER, note: "the advisory ownership gate: right-release ownership --staged" });
+    if (chainName) trampolines.push({ name: FOREIGN_PRE_COMMIT, file: path.join(hooksDir, FOREIGN_PRE_COMMIT), wanted: trampolineText(chainName), note: `runs .git/hooks/${chainName}, before the ownership gate` });
+  }
   for (const t of trampolines) {
     t.exists = o.exists(t.file);
-    t.current = t.exists ? o.readFile(t.file).replace(/\r\n/g, "\n") === t.wanted : false;
-    if (t.exists && !t.current && !force) {
-      o.err(`rightkit-gate: .githooks/${t.name} already exists and differs; nothing changed. Review it, or run \`rightkit-gate install-hook --force\` to replace it with a trampoline to .git/hooks/${t.name}.`);
+    const found = t.exists ? o.readFile(t.file).replace(/\r\n/g, "\n") : null;
+    t.current = found === t.wanted;
+    // Our own earlier artifacts are updated in place: a plain trampoline where the ownership hook now goes, and an older ownership hook.
+    const ours = found !== null && (t.current || t.replaces?.includes(found) || (t.marker && found.includes(t.marker)));
+    if (t.exists && !ours && !force) {
+      o.err(`rightkit-gate: .githooks/${t.name} already exists and differs; nothing changed. Review it, or run \`rightkit-gate install-hook --force\` to replace it with ${t.ownership ? "the ownership pre-commit hook" : `a trampoline to .git/hooks/${chainName ?? t.name}`}.`);
       return 1;
     }
   }
@@ -825,7 +861,7 @@ function installHook(o, root, force) {
   else put(hookPath, wanted, `${hasHook ? "replaced" : "wrote"} .githooks/pre-push`, ` (${nodePath} without pnpm)`);
   for (const t of trampolines) {
     if (t.current) done.push(`.githooks/${t.name} already current`);
-    else put(t.file, t.wanted, `${t.exists ? "replaced" : "wrote"} .githooks/${t.name}`, ` (runs .git/hooks/${t.name})`);
+    else put(t.file, t.wanted, `${t.exists ? "replaced" : "wrote"} .githooks/${t.name}`, ` (${t.note})`);
   }
   if (existingPath === ".githooks") done.push("core.hooksPath already .githooks");
   else {
@@ -836,6 +872,7 @@ function installHook(o, root, force) {
   for (const line of done) o.out(`rightkit-gate: ${line}`);
   const chained = own.length ? own.map((name) => (name === "pre-push" ? "pre-push (run first, then the gate)" : name)) : [];
   o.out(`rightkit-gate: chained hooks from .git/hooks: ${chained.length ? chained.join(", ") : "none"}${own.includes("pre-push") ? "" : "; the pre-push hook still runs .git/hooks/pre-push first if one appears later"}`);
+  if (!ownership) o.out(`rightkit-gate: no ownership pre-commit step: ${PINNED_CLI} is not installed here; install @rightkit/release, then run install-hook again`);
   const files = [".githooks/pre-push", ...trampolines.map((t) => `.githooks/${t.name}`)];
   o.out(`rightkit-gate: commit the hooks with executable mode (git add --chmod=+x ${files.join(" ")}); the pre-push hook finds rightkit-gate in node_modules/.bin of the repository root, else of any workspace package, else through \`pnpm exec\`.`);
   const provider = releaseProvider(o, root, git);
@@ -865,14 +902,16 @@ export async function main(argv, io = {}) {
   }
   if (args.includes("--help") || args.includes("-h")) { o.out(USAGE); return 0; }
   const sub = args[0] && !args[0].startsWith("-") ? args[0] : null;
-  if (sub && sub !== "install-hook") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
+  if (sub && sub !== "install-hook" && sub !== "check") { o.err(`rightkit-gate: unknown command ${JSON.stringify(sub)}\n${USAGE}`); return 2; }
+  // The app check has its own export and reads no gate state: it needs neither the base ref nor the pushed refs on stdin.
+  if (sub === "check") return (o.appCheck ?? (await import("../app-check.mjs")).main)(args.slice(1), { out: o.out, err: o.err, label: "check", cwd: o.cwd });
   if (args.includes("--base") && (!option("--base") || option("--base").startsWith("--"))) { o.err("rightkit-gate: --base needs a ref"); return 2; }
 
   const top = o.spawn("git", ["rev-parse", "--show-toplevel"], { cwd: o.cwd });
   if (failed(top) || !text(top).trim()) { o.err("rightkit-gate: not inside a git repository"); return 2; }
   const root = path.resolve(text(top).trim());
   const git = (...a) => o.spawn("git", a, { cwd: root });
-  if (sub === "install-hook") return installHook(o, root, args.includes("--force"));
+  if (sub === "install-hook") return await installHook(o, root, args.includes("--force"));
 
   const planOnly = args.includes("--plan");
   let base = option("--base") ?? "origin/main";
@@ -900,12 +939,12 @@ export async function main(argv, io = {}) {
   const readLive = (f) => o.readFile(f);
 
   // Units come from the live checkout (cargo reads it); a dirty checkout then blocks below.
-  let rust; let npm; let cargoCommand = ["rightkit", "cargo"];
+  let rust; let npm; let cargoCommand = ["rustright", "cargo"];
   try {
     const manifests = tracked("Cargo.toml");
     if (manifests.length) {
       cargoCommand = resolveCargoCommand(o);
-      if (!cargoCommand) { o.err(`${tag} BLOCKED: neither \`rightkit\` nor the managed cargo shim (cargo-guard.mjs) is first on PATH; plain cargo is never used`); return 1; }
+      if (!cargoCommand) { o.err(`${tag} BLOCKED: neither \`rustright\` nor the managed cargo shim (cargo-guard.mjs) is first on PATH; plain cargo is never used`); return 1; }
       if (!o.exists(path.join(root, GRANT_FILE))) { o.err(`${tag} BLOCKED: no local compile grant (${GRANT_FILE}); the broker refuses cargo, so the Rust units cannot be discovered or scanned`); return 1; }
     }
     // Untracked (not ignored) manifests only: git does not descend into ignored directories, so this stays cheap. A member of a

package/build-release.mjs

@@ -20,7 +20,9 @@ import {
 import path from "node:path";
 import { preflightOwnershipScope } from "./ownership-scope.mjs";
 import { spawn, spawnSync } from "./background-process.mjs";
-import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord } from "./rightkit-registry-resolver.mjs";
+import { RightKitRegistryError, SNAPSHOT_ENV, SNAPSHOT_FILE, assertManifestRegistryEvidence, loadAdmittedSnapshot, prepareRightKitResolution, registryManifestFields, rightKitLockInventory, writeAdmissionRecord, writeSnapshot } from "./rightkit-registry-resolver.mjs";
+import { formatAdmission, formatNotRun, runAdmission } from "./admission.mjs";
+import { sccacheRefusal } from "./admission-host.mjs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
 import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
@@ -129,12 +131,15 @@ for (let i = 0; i < args.length; i += 1) {
 if (platform !== "win" && platform !== "mac" && platform !== "android" && platform !== "ios") fail("--platform must be win, mac, android or ios");
 if (resumeFrom && !["prepackage", "sign", "package", "post-sign", "harden"].includes(resumeFrom)) fail("--resume-from must be prepackage, sign, package, post-sign, or harden");
 
-const configPath = path.resolve(configName);
+// Native real paths: Git reports the long form of a Windows short name (RUNNER~1) and the target of a symlinked temp root
+// (macOS /var -> /private/var). The config path is resolved the same way the doctor resolves it (release.mjs), so every path
+// derived from it (app root, build inputs, scan roots) compares equal to what Git reports; a non-canonical app root made the
+// build-inputs qualification drop every input and the clean-source gate speak before the dirty-inputs row.
+const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
+const configPath = nativeReal(path.resolve(configName));
 const invocationRoot = path.dirname(configPath);
 const repoRoot = git(invocationRoot, ["rev-parse", "--show-toplevel"]);
 assertPrimaryReleaseCheckout(repoRoot);
-// Native real paths: Git reports the long form of a Windows short name (RUNNER~1).
-const nativeReal = (file) => { try { return realpathSync.native(file); } catch { return file; } };
 const relativeConfig = path.relative(nativeReal(repoRoot), nativeReal(configPath)).replaceAll("\\", "/");
 if (relativeConfig.startsWith("../")) fail("release config must live inside the Git repository");
 const appRoot = path.dirname(configPath);
@@ -148,21 +153,19 @@ let heavySlot;
 let interrupted;
 let requestActiveRunStop = null;
 
-// A dry-run is an inspection contract, not a partial build. It must finish
-// before locks, cache directories, receipts, dependency installation, or any
+// Admission (admission.mjs): every refusal the committed files, this host or the registries can decide is raised here, before the
+// dry-run exit, the clean-source gate, the release lock, any state file, the install, a slot or the worker. `right-release doctor`
+// runs the same rows with the same text, so the two cannot disagree (rightkit#946); a refused build leaves nothing behind.
+const admitted = await admit();
+
+// A dry-run is an inspection contract, not a partial build. It prints the admission rows and exits with their verdict, so it can
+// never pass what the build refuses. It must finish before locks, cache directories, receipts, dependency installation, or any
 // child build/sign process can exist.
 if (dryRun) {
-  const commit = git(invocationRoot, ["rev-parse", "HEAD"]);
-  const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
-  if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
-  const config = (await import(`${pathToFileURL(configPath).href}?dry-run=${commit}`)).default;
-  if (!config?.app || !config?.version) fail("release config must expose app and version");
-  const target = config.targets?.[platform];
-  // Android builds with target.gradle (validated by release.mjs), not a package command; iOS with targets.ios.iosPackage.
-  if (platform !== "android" && platform !== "ios" && !target?.package && !packageCommandOptional(target, resolveProjectType({ appRoot, config, target }))) fail(`${config.app} has no ${platform} package command`);
-  console.log(`right-release build dry-run: ${config.app} ${config.version} ${platform}`);
+  console.log(`right-release build dry-run: ${admitted.config.app} ${admitted.config.version} ${platform}`);
   console.log(`config: ${configPath}`);
-  console.log(`commit: ${commit}`);
+  console.log(`commit: ${admitted.commit}`);
+  for (const line of formatAdmission(admitted.result)) console.log(line);
   process.exit(0);
 }
 
@@ -396,7 +399,8 @@ try {
   let rightKitResolution = null;
   if (!legacySealed) {
     try {
-      rightKitResolution = await prepareRightKitResolution({
+      // A fresh build already asked the registries in admission(); the snapshot is bound to this release's state root below.
+      rightKitResolution = (!rightKitReuse && admitted.registry) || await prepareRightKitResolution({
         root: appRoot,
         extraLocks: rightKitLockInventory({ requiredInputs, cargoLockPaths: pinnedCargoLocks, nativeLayout, config, root: appRoot }),
         versions: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-versions.json"), "utf8")),
@@ -414,6 +418,7 @@ try {
       if (!(error instanceof RightKitRegistryError)) throw error;
       fail(`${error.recoverable ? "RECOVERABLE " : ""}${error.message}`);
     }
+    if (rightKitResolution === admitted.registry) writeSnapshot(rightKitSnapshotFile, rightKitResolution.snapshot);
     for (const line of rightKitResolution.freshness.tasks) console.error(`[right-release] LANE TASK ${line}`);
     for (const line of rightKitResolution.freshness.warnings) console.error(`[right-release] WARNING ${line}`);
     console.error(`[right-release] rightkit-registry: ${rightKitResolution.summary}`);
@@ -552,6 +557,52 @@ try {
   lock?.release();
 }
 
+// Read the config and run the admission rows (files, this host and, for a fresh build, the registries) with no side effect: no lock,
+// state directory, cache directory, install or snapshot file. A finding is printed with its row and the process exits 1, no stack.
+async function admit() {
+  let commit;
+  let config;
+  try {
+    commit = git(invocationRoot, ["rev-parse", "HEAD"]);
+    const dirtyConfig = dirtyBuildInputs(repoRoot, { include: [relativeConfig], required: [relativeConfig] }, commit);
+    if (dirtyConfig.length > 0) fail(`dirty release config cannot be executed:\n${dirtyConfig.map((file) => `- ${file}`).join("\n")}`);
+    try { config = (await import(`${pathToFileURL(configPath).href}?commit=${commit}`)).default; } catch (error) { fail(`release config could not be loaded (${configPath}): ${error instanceof Error ? error.message : String(error)}`); }
+  } catch (error) {
+    if (error?.reported) process.exit(1);
+    throw error;
+  }
+  // A fresh build asks the registries once, here; a resume or a re-run over a sealed release reuses its recorded snapshot instead.
+  const platformName = platform === "win" ? "windows" : platform;
+  const sealed = config?.app && config?.version
+    && existsSync(path.join(repoRoot, ".right-release", "sealed", `${config.app}-${config.version}-${commit.slice(0, 8)}`, platformName, "release-manifest.json"));
+  const reuse = Boolean(resumeFrom) || Boolean(sealed);
+  const result = await runAdmission({
+    root: appRoot, repoRoot, configPath, config: config ?? {}, platform, commit, skipChecks,
+    tiers: reuse ? ["files", "host"] : ["files", "host", "network"],
+    registry: async (ctx) => {
+      const inputs = ctx.buildInputs();
+      if (!inputs.ok) return undefined; // the build-inputs row reports it
+      return prepareRightKitResolution({
+        root: appRoot,
+        extraLocks: rightKitLockInventory({ requiredInputs: inputs.value.requiredInputs, cargoLockPaths: inputs.value.cargoLockPaths, nativeLayout: inputs.value.nativeLayout, config, root: appRoot }),
+        versions: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-versions.json"), "utf8")),
+        ownership: JSON.parse(readFileSync(path.join(TOOL_ROOT, "rightkit-ownership.json"), "utf8")),
+        releaseVersion: RELEASE_TOOL_VERSION,
+        // Build admission: refuse every pin behind the registry's latest. A dry run asks, but keeps no cache on disk.
+        admission: true,
+        ...(dryRun ? { cacheDir: "" } : {}),
+      });
+    },
+  });
+  for (const finding of result.findings) console.error(`right-release build: ${finding.row}: ${finding.detail}`);
+  for (const line of formatNotRun(result)) console.error(`right-release build: ${line}`);
+  if (result.findings.length > 0) {
+    console.error(`right-release build: admission found ${result.findings.length} blocking problem(s); nothing was started`);
+    process.exit(1);
+  }
+  return { config, commit, result, registry: result.out.registry ?? null };
+}
+
 function hashInputs(files) {
   const hashes = {};
   for (const file of files) {
@@ -610,6 +661,14 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
     current.add(role);
     sources.set(source, current);
   };
+  // Named refusals for a config the admission's seal-routes row already refused, so nothing here crashes on an undefined field.
+  for (const artifact of [...(target.installer?.artifacts ?? []), ...(target.updater?.artifacts ?? [])]) {
+    if (typeof artifact?.file !== "string" || !artifact.file) fail("installer and updater artifacts must each declare a file");
+  }
+  for (const artifact of target.updater?.artifacts ?? []) {
+    if (target.updater?.kind !== "appinstaller" && (typeof artifact.signature !== "string" || !artifact.signature)) fail(`updater artifact ${artifact.file} must declare the signature file sign-updater writes next to it`);
+    if (artifact.key === undefined && config.distribution?.provider !== "github-releases") fail(`updater artifact ${artifact.file} must declare the R2 route key (key); only github-releases names the route from the file`);
+  }
   for (const artifact of target.installer?.artifacts ?? []) addSource(resolveArtifactPath(artifact.file), "installer");
   for (const artifact of target.updater?.artifacts ?? []) {
     addSource(resolveArtifactPath(artifact.file), "updater");
@@ -741,9 +800,9 @@ function sealRelease({ configRoot, managedCargoTarget, androidTarget, iosSpec, n
     // an unsound seal, not a portable release.
     signing: signingIdentity ? { ...signingIdentity, receipts: (() => {
       const present = signingIdentity.receiptInputs.filter((file) => existsSync(file));
-      if (present.length === 0) throw new Error(`no signing receipts found to seal; expected at least ${signingIdentity.receiptInputs[0]}`);
+      if (present.length === 0) fail(`no signing receipts found to seal; expected at least ${signingIdentity.receiptInputs[0]}`);
       if (platform === "mac") {
-        if (present.length !== signingIdentity.receiptInputs.length) throw new Error("missing current-build macOS signing or notarization receipt");
+        if (present.length !== signingIdentity.receiptInputs.length) fail("missing current-build macOS signing or notarization receipt");
         validateNotarizationReceipt({ receiptPath: signingIdentity.receiptInputs[1], archive: resolveArtifactPath(target.notarize.file) });
       }
       return present.map((file) => ({ file, sha256: hashFile(file) }));
@@ -941,7 +1000,7 @@ function commandExists(name) {
 
 function assertSccacheVersion(version) {
   const match = String(version ?? "").match(/sccache\s+(\d+)\.(\d+)\.(\d+)/i);
-  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail("shared cache requires sccache >= 0.15.0; install with: cargo install sccache --locked; then verify: sccache --version");
+  if (!match || Number(match[1]) === 0 && Number(match[2]) < 15) fail(sccacheRefusal(match ? match.slice(1).join(".") : null));
 }
 
 function commandOutput(cmd, runArgs) {
@@ -1000,7 +1059,8 @@ function usage(code) {
 
 function fail(message) {
   console.error(`right-release build: ${message}`);
-  throw new Error(message);
+  // `reported` marks an error whose text is already printed, so a caller that exits on it prints nothing twice.
+  throw Object.assign(new Error(message), { reported: true });
 }
 
 function throwIfInterrupted() { if (interrupted) throw interrupted; }

package/cli/right-release.mjs

@@ -54,7 +54,17 @@ const commands = new Map([
 
 const args = process.argv.slice(2);
 const first = args[0];
+// The commands that compile, package, sign, ship or inspect a release run the app check (../app-check.mjs, CHECKED_COMMANDS) in this
+// process before they start a child. A red check prints its findings and exits 1; there is no flag that skips it.
+async function requireGreenCheck() {
+  const { guardCommand } = await import("../app-check.mjs");
+  const refused = guardCommand({ args });
+  if (!refused) return;
+  for (const line of refused.lines) console.error(line);
+  process.exit(refused.exitCode);
+}
 if (first === "dev") {
+  await requireGreenCheck();
   import("../development.mjs").then(({ main }) => main(args.slice(1))).catch((error) => {
     console.error(`right-release dev: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
     process.exitCode = 1;
@@ -81,6 +91,8 @@ if (!first || first === "-h" || first === "--help") {
   process.exit(0);
 }
 
+await requireGreenCheck();
+
 if (first === "--version" || first === "-v") {
   run("release.mjs", ["--version"]);
 } else if (first === "doctor") {
@@ -89,6 +101,18 @@ if (first === "--version" || first === "-v") {
   } else {
     run("release.mjs", ["--doctor", ...args.slice(1)]);
   }
+} else if (first === "check") {
+  // The same offline check as `rightkit-gate check`; the repository is the git top-level of --config's folder, else the cwd.
+  const { appDirectory, main } = await import("../app-check.mjs");
+  process.exit(await main(args.slice(1), { label: "check", cwd: appDirectory(args, process.cwd()) }));
+} else if (first === "hooks" && args[1] === "install") {
+  // One installer: `hooks install` is `rightkit-gate install-hook` (pre-push check and gate, ownership pre-commit step) run in the app.
+  const app = args.indexOf("--app");
+  if (app >= 0 && (!args[app + 1] || args[app + 1].startsWith("-"))) {
+    console.error("right-release hooks install: --app needs a directory");
+    process.exit(2);
+  }
+  run("bin/rightkit-gate.mjs", ["install-hook", ...(args.includes("--force") ? ["--force"] : [])], { cwd: app >= 0 ? path.resolve(args[app + 1]) : process.cwd() });
 } else if (first === "hooks") {
   run("ownership-hooks.mjs", args.slice(1));
 } else if (first === "suite-doctor") {
@@ -170,9 +194,9 @@ if (first === "--version" || first === "-v") {
   process.exit(2);
 }
 
-function run(script, scriptArgs) {
+function run(script, scriptArgs, { cwd = process.cwd() } = {}) {
   const child = spawn(process.execPath, [path.join(packageRoot, script), ...scriptArgs], {
-    cwd: process.cwd(),
+    cwd,
     env: process.env,
     stdio: "inherit",
     windowsHide: true,
@@ -270,7 +294,8 @@ Commands:
   upload --platform ios --release <id> [--apply]       Sealed IPA to TestFlight, then the exact build into the beta groups; dry run unless --apply (macOS)
   ios-credentials store --key-id <KEYID> --issuer <uuid> | check
                                                       Put the App Store Connect API key (stdin), key id and issuer into the login Keychain once, or check them; never a file (macOS)
-  qa --stage source|installed --platform mac|win [--release <id>]   Run rightkit-qa and write the sealed QA receipt (a missing receipt warns and is recorded; it never blocks)
+  qa --stage source|installed --platform mac|win [--release <id>]   Run rightkit-qa (and the journeys lane when the config sets qa.journeys) and write the sealed QA receipt. Refused inside a QA run. The receipt must match the platform and release id, come from an approved runner digest, and show every release-critical journey passed
+                                                      Admission is per app in qa-admission-policy.json: warn (default) records a refusal and continues; refuse blocks build, upload and publish. Only adrian moves an app from refuse back to warn
   qa audit [--app <dir>] [--json] [--since <YYYY-MM-DD>]            List source/installed QA status per release; exit 1 if an uploaded build lacks passing QA
   publish-update --release <id> --platform mac|win --tier patch|update
                                                       Upload sealed bytes to R2 & register RightApps
@@ -307,12 +332,21 @@ Commands:
   apple profile renew [--config <file>] [--profile <file>] [--dry-run]
                                                       Renew macOS profile for current Keychain signer
   signing-agent install|uninstall|status              Manage invisible Aqua-session signing service
-  doctor [--platform mac|win]                        Inspect one app's release config
+  check [--repo <dir>] [--config <file>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]
+                                                      The offline app check, same as rightkit-gate check: committed files only, every finding in one run (exit 0 pass, 1 findings, 2 could not run).
+                                                      Build, package, dev, test, web-build, swift-package, recipe-build, stage-sidecar, qa, upload, publish, publish-update, github, doctor,
+                                                      sign-windows, sign-updater, sign-candidate, sign-dev-artifact, addon build and create-mac-updater run it first and start nothing when it is red; there is no flag that skips it.
+                                                      Baseline: .rightkit/app-check-baseline.json (entries carry issue, added and sunset; the sunset is at most 90 days after added)
+  doctor [--platform mac|win] [--gates] [--inspect] [--strict]
+                                                      Inspect one app's release config the way the build would refuse it; --gates also runs the build's pre-build source gates
+                                                      --inspect lists admission findings (newer RightKit versions) as information instead of refusing them
+                                                      --strict makes a row that could not run on this host (NOT RUN) a blocking problem; without it NOT RUN is printed and does not fail
+                                                      --admission is still accepted and does nothing (admission is the default); it cannot be combined with --inspect
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories
   ownership [--app <dir>] [--json]                   Fail on app copies of RightKit-owned capabilities
   ownership --staged [--app <dir>] [--json]          Pre-commit gate: scan the staged index for block-tier findings
-  hooks install [--app <dir>]                        Install the advisory pre-commit ownership gate (pinned @rightkit/release)
+  hooks install [--app <dir>] [--force]              Alias of rightkit-gate install-hook: the pre-push check and gate, and the advisory pre-commit ownership gate (pinned @rightkit/release)
   ownership enroll [--root] [--name <device>] [--root-fingerprint <sha256>] [--app <dir>]
                                                       Enroll one native key or create a signed-device request
   ownership approve-key <fingerprint|request.json>    Approve one pending device key from an active host

package/deterministic-scans.mjs

@@ -10,10 +10,10 @@
 // repository has none. A deferred scan is listed by name (result.deferred, scanDeferrals), is never a
 // pass (result.ok and result.complete are false while any scan is deferred) and cannot become a SCAN_B receipt.
 // Content scans run on the exported HEAD (contentRoot). Only a scan that inherently needs the live
-// checkout uses liveRoot: `rightkit cargo` scans (the broker binds to the registered checkout), the
+// checkout uses liveRoot: `rustright cargo` scans (the broker binds to the registered checkout), the
 // tsc, eslint and package tests (need installed node_modules).
 // Class B runs only when every selected class A scan passed (SCAN_B is distinct from SCAN_A and
-// follows it). Rust commands go through `rightkit cargo`, JavaScript tools through `pnpm exec`.
+// follows it). Rust commands go through `rustright cargo`, JavaScript tools through `pnpm exec`.
 // The runner takes injectable spawn/exists/readFile/readdir so tests execute nothing real. The
 // result is a plain object (per-scan status, tool versions, scanSetDigest) usable as receipt content
 // (packages/release/pipeline-receipts.mjs); it carries no authority by itself.
@@ -34,7 +34,7 @@ export const SCAN_CLASS = Object.freeze({ A: "A", B: "B" });
 export const CLASS_A_SCAN_PREFIXES = Object.freeze([
   "rustfmt", "node-check", "json-parse", "toml-parse", "yaml-parse", "ownership-catalog",
   "actionlint", "pnpm-lockfile", "pnpm-audit", "cargo-metadata", "cargo-deny", "cargo-audit", "cargo-package-list",
-  "changelog-version", "license", "secret-scan", "path-policy", "advisory-exceptions",
+  "changelog-version", "license", "secret-scan", "path-policy", "advisory-exceptions", "suite-api",
 ]);
 export const CLASS_B_SCAN_PREFIXES = Object.freeze([
   "clippy", "check", "check-all-features", "check-features", "check-dependent", "doc", "tsc", "eslint", "swift-build", "test", "generated-docs",
@@ -205,10 +205,13 @@ const WORKSPACE_JS_FILE = /^(package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|
 const ESLINT_FILES = ["eslint.config.js", "eslint.config.mjs", ".eslintrc.json"];
 const ROOT_LINT_FILES = [...ESLINT_FILES, "biome.json"];
 // Everything scripts/generate-index.mjs reads or writes (its header and loadInventory): crate and package manifests and
-// READMEs, the root Cargo.toml (workspace version), the versions and ownership data, the ownership-availability helper it imports, itself, and its outputs.
-const GENERATOR_INPUT = /^(crates\/[^/]+\/(Cargo\.toml|README\.md)|packages\/[^/]+\/(package\.json|README\.md)|Cargo\.toml|packages\/release\/(rightkit-versions\.json|rightkit-ownership\.json|ownership-availability\.mjs)|scripts\/generate-index\.mjs|INDEX\.md|docs\/(ADOPTION|CAPABILITY-MAP)\.md)$/;
+// READMEs, the root Cargo.toml (workspace version), the versions and ownership data, the ownership-availability helper it imports, itself,
+// the port matrix generator it imports, and its outputs (the port matrix's MD and HTML are checked for consistency with its JSON).
+// The Right Suite API contract and every projection scripts/gen-suite-api.mjs writes from it (the test-vector copy included).
+const SUITE_API_INPUT = /^(contracts\/right-suite-api\.v1\.json|scripts\/gen-suite-api\.mjs|crates\/rightkit-license\/src\/suite_api_generated\.rs|packages\/app-update\/src\/suite-api\.generated\.ts|packages\/release\/suite-api\.generated\.mjs|crates\/rightkit-license\/test-vectors\/right-suite-api\.v1\.json)$/;
+const GENERATOR_INPUT = /^(crates\/[^/]+\/(Cargo\.toml|README\.md)|packages\/[^/]+\/(package\.json|README\.md)|Cargo\.toml|packages\/release\/(rightkit-versions\.json|rightkit-ownership\.json|ownership-availability\.mjs)|scripts\/generate-(index|port-matrix)\.mjs|INDEX\.md|docs\/(ADOPTION|CAPABILITY-MAP|PORT-MATRIX)\.md|docs\/port-matrix\.(html|json))$/;
 const PROBES = Object.freeze({
-  rustfmt: ["--version"], node: ["--version"], rightkit: ["cargo", "--version"], pnpm: ["--version"],
+  rustfmt: ["--version"], node: ["--version"], rustright: ["cargo", "--version"], pnpm: ["--version"],
   actionlint: ["-version"], "right-git": ["--version"], swift: ["--version"],
 });
 
@@ -221,7 +224,7 @@ function commandText(d) {
 /**
  * The scan plan for a change: derived from the changed files plus the manifests they belong to.
  * `contentRoot` is a clean export of the commit (pure content checks); `liveRoot` is the checkout the
- * managed `rightkit cargo` and `pnpm` run in. A scan whose files did not change is not planned.
+ * managed `rustright cargo` and `pnpm` run in. A scan whose files did not change is not planned.
  */
 export function planScans({
   changed = [], contentRoot, liveRoot = contentRoot, exists = fs.existsSync, readFile = (f) => fs.readFileSync(f, "utf8"),
@@ -230,8 +233,8 @@ export function planScans({
   // CI shards (one crate per runner, where the port, pipe, desktop and wall-clock conflicts that force the serial lane do not exist)
   // and records a note naming them (Adrian 2026-10-22: compile locally on the warm cache, qualify the conflicting tests on VMs).
   quietTests = "local",
-  // The command prefix every cargo scan runs through: `rightkit cargo` on a managed host, plain `cargo` in CI.
-  cargoCommand = ["rightkit", "cargo"],
+  // The command prefix every cargo scan runs through: `rustright cargo` on a managed host, plain `cargo` in CI.
+  cargoCommand = ["rustright", "cargo"],
   // Physical containment: a changed path whose real path leaves the real content root (a symlink) is refused.
   realpath = (p) => fs.realpathSync(p),
   // Bytes of a changed file for the input digest (defaults to readFile; the gates pass the raw reader).
@@ -260,8 +263,8 @@ export function planScans({
   rustLocks = null,
 } = {}) {
   if (!contentRoot) throw new TypeError("planScans: contentRoot is required");
-  if (!Array.isArray(cargoCommand) || cargoCommand.length === 0 || !["rightkit", "cargo"].includes(cargoCommand[0]) || cargoCommand.slice(1).some((a) => a !== "cargo")) {
-    throw new TypeError('planScans: cargoCommand must be ["rightkit", "cargo"] or ["cargo"]');
+  if (!Array.isArray(cargoCommand) || cargoCommand.length === 0 || !["rustright", "cargo"].includes(cargoCommand[0]) || cargoCommand.slice(1).some((a) => a !== "cargo")) {
+    throw new TypeError('planScans: cargoCommand must be ["rustright", "cargo"] or ["cargo"]');
   }
   const refusals = []; const accepted = [];
   for (const raw of new Set(changed)) {
@@ -356,10 +359,25 @@ export function planScans({
   // ---- class A: content checks on the exported commit
   // A vendor/ file keeps upstream formatting only when vendor/upstream-files.json records it and its
   // bytes still match that upstream digest; any other vendor/ .rs (new, patched) is rustfmt-checked.
-  let upstream = {};
-  try { upstream = JSON.parse(readFile(path.join(contentRoot, "vendor/upstream-files.json"))).files ?? {}; } catch { /* no manifest: nothing exempt */ }
+  // A patched vendor/ file (rightkit#915) keeps upstream formatting only while its bytes match the
+  // reviewed `patched` record, which names its upstream base digest and the note describing the patch;
+  // reformatting it would bury the patch. Any edit changes the digest, so the file is checked until re-recorded.
+  let upstream = {}; let patched = {};
+  try {
+    const manifest = JSON.parse(readFile(path.join(contentRoot, "vendor/upstream-files.json")));
+    upstream = manifest.files ?? {}; patched = manifest.patched ?? {};
+  } catch { /* no manifest: nothing exempt */ }
+  const DIGEST = /^[0-9a-f]{64}$/;
   const verbatimUpstream = (f) => f.startsWith("vendor/") && typeof upstream[f] === "string" && bytesDigest(f) === upstream[f];
-  const rustFiles = files.filter((f) => f.endsWith(".rs") && !verbatimUpstream(f));
+  const recordedPatch = (f) => f.startsWith("vendor/") && DIGEST.test(patched[f]?.base ?? "") && typeof patched[f]?.note === "string"
+    && patched[f].note.startsWith("vendor/") && DIGEST.test(patched[f]?.sha256 ?? "") && bytesDigest(f) === patched[f].sha256;
+  // Generated Rust is not hand-formatted: bindgen output, or rustfmt's own `@generated` marker in the first five lines.
+  const generatedRust = (f) => {
+    let head = "";
+    try { head = readFile(path.join(contentRoot, f)).split("\n", 5).join("\n"); } catch { return false; }
+    return /@generated\b|automatically generated by rust-bindgen\b/.test(head);
+  };
+  const rustFiles = files.filter((f) => f.endsWith(".rs") && !verbatimUpstream(f) && !recordedPatch(f) && !generatedRust(f));
   const byEdition = new Map();
   for (const f of rustFiles) {
     let dir = path.dirname(path.join(contentRoot, f));
@@ -434,6 +452,9 @@ export function planScans({
 
   // Exceptions expire by date, not by change: checked on every run, whatever changed.
   if (exists(path.join(contentRoot, "ci/advisory-exceptions.json"))) add({ id: "advisory-exceptions", class: A, internal: "advisory-exceptions" });
+  // Like generated-docs, planned only when a changed file is one of the contract's inputs or projections. The generator runs from
+  // the trusted scanner checkout (the import below); the exported contract and projections are data it checks.
+  if (files.some((f) => SUITE_API_INPUT.test(f)) && exists(path.join(contentRoot, "contracts/right-suite-api.v1.json"))) add({ id: "suite-api", class: A, internal: "suite-api" });
   if (rustTouched) {
     for (const ws of touchedWs) add({ id: `cargo-metadata${wsIdSuffix(ws)}`, class: A, ...cargoIn(ws, ...metadataArgs()) });
     for (const name of crateNames.filter((n) => rustMap?.get(n).publish !== false)) add({ id: rustScanId.packageList(name), class: A, ...cargoIn(wsOf(name), "package", "-p", crateOf(name), "--list", "--allow-dirty", "--locked") });
@@ -578,7 +599,7 @@ export function planScans({
   const deferred = [];
   if (!localCompile) {
     scans = scans.map((x) => {
-      if (x.tool !== "rightkit" && !(x.tool === "cargo" && cargoCommand.length === 1)) return x;
+      if (x.tool !== "rustright" && !(x.tool === "cargo" && cargoCommand.length === 1)) return x;
       deferred.push(x.id);
       return { ...x, deferred: "no local compile grant; the broker refuses this scan" };
     });
@@ -758,6 +779,12 @@ const INTERNAL = {
   // Every RustSec exception is dated, scoped to the locked versions and identical in deny.toml and
   // .cargo/audit.toml (ci/advisory-exceptions.json; Astra 2026-10-22). Expiry fails every run.
   "advisory-exceptions": (s, ctx) => checkAdvisoryExceptions({ root: ctx.contentRoot, readFile: ctx.read }),
+  // Every Right Suite API projection must equal what the generator writes from the contract. The pure check is imported from the
+  // scanner's own checkout (scripts/ sits beside packages/release), never from the content root.
+  "suite-api": async (s, ctx) => {
+    const { suiteApiProblems } = await import("../../scripts/gen-suite-api.mjs");
+    return suiteApiProblems((f) => ctx.read(f));
+  },
   "ownership-catalog": (s, ctx) => (ctx.read(s.files[0]) === ctx.read(s.files[1]) ? [] : ["copy packages/release/rightkit-ownership.json to crates/rightkit-ownership/catalog/ownership-catalog.json"]),
   "changelog-version": (s, ctx) => {
     const version = (ctx.read(s.files[0]).match(/^version\s*=\s*"([^"]+)"/m) || [])[1];