@rightkit/release 0.6.3 → 0.6.5

package/README.md

@@ -59,6 +59,18 @@ Every Right app has absolutely NO access to DevTools; the single exception is Vi
 - S1-S4 need `compiledOut`: `feature:<name>`, `cfg:test`, `cfg:debug_assertions` or, for Swift, `swift:DEBUG` (the read sits inside `#if DEBUG`; the read exists only there). The source walk skips test directories, including Swift bundles named `Tests`, `UITests`, `<App>Tests` and `<App>UITests`. S5 needs `userGesture: true`. S6 needs `valueType` of `bool`, `int` or `enum`.
 - `anchor` and `note` are informational. Fixtures: `fixtures/release-switches/` (`app/` is a clean example).
 
+#### Non-shipped tooling: `releaseSwitches.nonShipped`
+
+On desktop (non-iOS) targets the source walk covers the whole app root, so app tooling that never ships (a bakeoff harness) can produce `unregistered-read` findings that cannot truthfully be declared in `switches.json`. Declare such directories in the release config:
+
+```json
+"releaseSwitches": { "nonShipped": [ { "dir": "bakeoff", "reason": "bakeoff harness; not compiled or bundled" } ] }
+```
+
+- It is an exclusion list: any directory not listed is still scanned, so an omission fails safe. `dir` is relative to the app root; `reason` is required and non-empty. iOS is unchanged (it already walks only the Xcode project and the local crates in its cargo tree).
+- Every entry is validated before the walk and a bad one fails the release with `inventory-invalid`. Refused: a dir that is missing, not a real directory (a symlink), absolute, escaping the root, or the root itself; an empty `reason`; a dir that contains or sits inside a local crate of the resolved release cargo tree (a crate at the app root protects `src/`), `src-tauri`, or the Tauri `frontendDist` bundle; a dir that contains a `package.json` or sits inside a directory below the root that has one; when the root has a `package.json`, `src/`, `public/` and every existing directory named by the root `index.html` (`src`/`href`), a quoted string in `vite.config.*` (root, publicDir, build input) or `include`/`files` of `tsconfig.json`, plus anything inside or containing them; and any dir holding a path named by `src-tauri/tauri.conf.json` `beforeBuildCommand`/`beforeDevCommand`/`beforeBundleCommand` a root `package.json` `build*` script, or the release recipe's own commands (`targets.<os>.prePackage`, `package`, `postSign`, `packageHook`, the finalizer; followed through `pnpm|npm|yarn run <script>`), because those run during the release build.
+- Not protected: the release code does not otherwise know the frontend source layout. A frontend input that none of the rules above names (for example one referenced only from a nested config, or built by a script not reachable from those commands) is not refused, so list only directories you know never ship.
+
 ## Commands
 
 `right-release` maps these subcommands to the modules in this package:
@@ -79,6 +91,36 @@ Every Right app has absolutely NO access to DevTools; the single exception is Vi
 | Legal | `license-notices npm`, `license-notices cargo`, `license-notices binaries` |
 | Other | `dev`, `doctor`, `suite-doctor`, `qa`, `dmg`, `cache`, `apple`, `inventory`, `model`, `addon`, `hooks`, `lsclean`, `generate-dmg-background`, `publish cargo`, `publish npm`, `publish swift` |
 
+## The app check: deterministic first, no flag skips it
+
+`right-release check [--repo <dir>] [--config <file>] [--commit <rev> | --worktree] [--only <rule,...>] [--list] [--print-baseline] [--baseline <file>]`
+is the offline app check, the same as `rightkit-gate check`: it reads files only (the committed tree of `--commit`, default HEAD, or with
+`--worktree` the tree on disk, which is what a compile would see), runs every rule and prints every finding in one run. Exit 0 passes,
+1 has findings, 2 could not run (a repository with no commit yet says `the repository has no commit yet; commit first`). The repository
+is the git top-level of `--config`'s folder, else of `--app-root` (`recipe-build`), else of the working directory.
+
+The commands that compile, package, sign, ship or inspect a release run it first, in the same process, and start nothing when it is
+red or cannot run (outside a git repository it is red). There is no flag that skips it: `--help`, `--dry-run`, `--check` and `--list`
+only change what a command does after the check.
+
+| Mode | Commands |
+|---|---|
+| `commit` (HEAD: what is built, packaged, signed and uploaded) | `release`, `build` (also `build --web` and the direct-flag form `right-release --platform ...`), `package`, `web-build`, `swift-package`, `recipe-build`, `qa`, `upload`, `publish`, `publish-update`, `github`, `sign-windows`, `sign-updater`, `create-mac-updater`, `sign-candidate`, `addon build` |
+| `worktree` (the tree on disk, as a compile sees it) | `dev`, `doctor`, `test`, `stage-sidecar`, `sign-dev-artifact` |
+
+Not guarded: the report forms of guarded commands (`publish cargo|npm|swift`, `qa audit`, `doctor --all`) and every other command.
+Each of those is listed with its reason in `UNCHECKED_COMMANDS` (`app-check.mjs`), and `app-check.test.mjs` fails a command that is in
+neither list. `dmg` takes `--app`/`--out` paths, compiles nothing and has no repository; `addon` is checked only as `addon build` (it
+runs the add-on's own build command), its `doctor`, `upload` and `adopt` forms compile nothing.
+
+Known findings are tolerated only through a baseline: `--baseline <file>`, else the checked tree's `.rightkit/app-check-baseline.json`,
+else (from a RightKit checkout only) `ci/app-check-baseline.json`. The app's own file is always `{ "schema": 1, "known": [{ "id", "issue",
+"added", "sunset" }] }`; the central `{ "known": { "<repo>": [...] } }` shape in an app's file is refused (exit 2). Every app entry needs
+an issue, an `added` date (YYYY-MM-DD, UTC, not later than today) and a `sunset` that is not before `added` and at most 90 days after
+it. Past its sunset an entry stops tolerating its finding (the finding fails with `its baseline entry expired`) and is reported as
+`EXPIRED`; a listed identity that no finding has any more is `STALE` and fails, so the list only shrinks. A rule the build refuses
+whatever a baseline says (`switches-inventory`) fails even when listed.
+
 ## Declared test suites, web build, npm notices and artifact mirroring
 
 These replace per-app wrapper scripts. Each is declared in `right-release.config.mjs` and runs without a shell from the app
@@ -109,7 +151,7 @@ a JSON line before and after (`{"event":"e2e_suite_completed","suite":"tooling",
 (repeatable) selects suites; a group name such as `journeys` selects all its chunks. `--runner vitest -- run --project unit`
 runs a runner once with the arguments after `--` (watch mode, one project); `-- <args>` after `--suite` is allowed when exactly
 one suite is selected. `--list [--json]` prints the resolved commands and runs nothing. Wrap it as the repository needs, for
-example `rightkit storage run --app <app> -- right-release test`.
+example `rustright storage run --app <app> -- right-release test`.
 
 ### `right-release build --web` (or `web-build`)
 
@@ -187,9 +229,27 @@ Only a target directory under a managed root (`resolveManagedRoots`: `RIGHTKIT_D
 `postSign`: it packs the signed, stapled `.app` and signs the tarball. The default output is `<App>.app.tar.gz`, named after the
 app in `notarize.app`. Declare the file in `updater.artifacts` as before. See `docs/MAC-PACKAGE-RECIPE.md`.
 
-## QA receipts (warn-and-record)
+## QA receipts and admission (warn by default, refuse per app)
+
+`right-release qa --stage source|installed --platform mac|win` runs `rightkit-qa` and writes a MAC'd receipt. Admission is a per-app policy in `qa-admission-policy.json`:
+
+```json
+{ "schema": 1,
+  "apps": { "postright": { "mode": "refuse", "since": "2026-11-02", "set_by": "adrian" } },
+  "approvedRunners": [ { "sha256": "<64 hex>", "version": "0.8.0" } ] }
+```
 
-`right-release qa --stage source|installed --platform mac|win` still runs `rightkit-qa` and writes a signed receipt, and receipt verification is unchanged. A missing or invalid receipt no longer blocks a release. `build`, `upload`, `publish-update` and `github` print `[right-release] QA warning: ...` to stderr, continue, and record the outcome:
+- **`warn` (default; an app with no entry).** A missing or invalid receipt does not block. `build`, `upload`, `publish-update` and `github` print `[right-release] QA warning: ...` to stderr, continue, and record the outcome (below).
+- **`refuse`.** The same refusal throws `QA admission refused for <app> (policy refuse since ... by ...)`; nothing is sealed, uploaded or published. Switch an app on with `node release-qa-policy.mjs set --app <app> --mode refuse --set-by <name>`. Moving an app back to `warn` (or deleting its entry) is refused unless `set_by` is `adrian`; a hand edit that does so is caught on every load by comparing with the copy committed at `RIGHT_RELEASE_QA_POLICY_BASELINE_REF` (default `HEAD`; CI should use `origin/main`). `set_by` is a recorded claim, not an authenticated identity: the file must be owner-protected in the repository (CODEOWNERS and branch protection), and a downgrade that was already committed becomes the new baseline. An unreadable or malformed policy file is a hard error, never a fall back to warn.
+
+Hardening, applied in both modes (a failure is a warning in `warn` and a refusal in `refuse`):
+
+1. **Platform and release id.** The sealed receipt must be for the platform and the release id being sealed or published.
+2. **Approved runner.** The `rightkit-qa` executable's sha256 recorded in the receipt must be listed in `approvedRunners`. An empty list approves nothing. The binary is digested before the run and again after it; a swap during the run is refused.
+3. **Every release-critical journey.** With `qa.journeys` in the release config (`{ manifest?: "journeys.toml", receipt?: "<path>", args?: { source?, installed? } }`) `right-release qa` runs `rightkit-qa journeys run` (or reads `receipt`), validates the `rightkit.journeys.receipt/1` through `rightkit-qa journeys validate-receipt --manifest .. --tree ..` (exit code 0 and a final `ACCEPTED` line), and seals a `journeys` summary. `release-qa-floor.json` maps the `journey` floor id to "all release-critical journeys passed": at admission the required set is recomputed from the `journeys.toml` committed at the receipt's commit (every `release_critical` journey that lists the platform), and each must be `passed`. Zero critical journeys is never a pass. One matching check no longer satisfies the floor.
+4. **Signing outside test execution.** Checked: the receipt records the test processes' pids and the window they ran in; admission refuses a receipt sealed before that window ended, signing that began before it ended (`signingStartedAt`), a sealing or admitting process that is a test process, `RIGHT_RELEASE_QA_STAGE` set at admission (admission or signing inside a QA run), and `right-release qa` itself refuses to seal inside a QA run. Not checkable here: that test processes cannot reach the signing key (OS credential store and signing agent ACL) and that CI runs QA and signing as separate jobs (the carried receipt, rightkit#183, is the hook).
+
+`right-release qa` keeps the older behavior for evidence checks and verification of the receipt itself; the outcome is recorded:
 
 - Source stage: sealed into the manifest as `qa: { status: "passed", sourceReceiptDigest, floorDigest }` or `qa: { status: "missing" | "rejected", reason }`.
 - Installed stage: written to `.right-release/state/<releaseId>/<platformDir>/qa-installed.json` as `{ status, reason?, receiptDigest?, checkedAt, provider }`. It is written when publication starts, so a later upload failure still leaves a record.
@@ -212,7 +272,7 @@ right-release install-app --dmg <path.dmg> [--app-name Pulse.app] [--bundle-id d
 
 It mounts the image read-only and hidden (`-nobrowse`), verifies the app (`codesign --verify --deep --strict`, `spctl --assess`, `stapler validate`, bundle id, and Team ID against the installed copy; a Team ID change is refused) before touching the installed copy, stages a `ditto` copy beside it in the destination and verifies that copy, quits the running instance with SIGTERM (15 s, then SIGKILL), swaps the staged copy in (one atomic exchange when the `rightkit-swap` helper is found, otherwise two journaled renames; the old bundle is restored on failure), re-verifies the installed copy, only then moves the old bundle to `~/.Trash/<App> <timestamp>.app`, and relaunches only if it was running or `--relaunch` is given, using `open -g -j -b` (background, hidden, never activated). `--json` emits one lifecycle event per line (`start`, `verified`, `quit`, `replaced`, `relaunched`, `done`/`failed`, among others). `right-release install-app --recover [--dest <dir>] [--app-name <App.app>] [--json]` rolls an interrupted install forward or back from its journal; every install runs that recovery first. Win32 exits with "not implemented on win32". Exit codes: 0 ok, 1 failed, 2 usage, 3 unsupported platform.
 
-The shipped `bin/darwin/rightkit-swap` is Developer ID signed. Local publish adds it via `right-release publish npm --package @rightkit/release --local` on the Mac (managed `rightkit cargo build --release -p rightkit-fs --bin rightkit-swap`, `codesign --options runtime --timestamp`, strict verify). CI qualification adds it via `publish.yml` build-swap → sign-swap → pack (`docs/CI.md`); sign-swap needs `APPLE_CERTIFICATE_BASE64`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_KEYCHAIN_PASSWORD` & `APPLE_DEVELOPER_ID` in the `release` environment, & stays blocked until root provisions the certificate pair. Exporting that identity requires an Aqua login session: SSH export fails `errSecInteractionNotAllowed` (-25308) & the Aqua signing agent exposes only codesign/updater/notarize/staple, no key export — do not retry either route. `install-app` refuses a helper that exists but is not validly signed (`SWAP_HELPER_UNSIGNED`, naming the fix); with no helper at all it uses the journaled two-rename fallback and logs it (`swap-fallback`, `replaced {swap}`).
+The shipped `bin/darwin/rightkit-swap` is Developer ID signed. Local publish adds it via `right-release publish npm --package @rightkit/release --local` on the Mac (managed `rustright cargo build --release -p rightkit-fs --bin rightkit-swap`, `codesign --options runtime --timestamp`, strict verify). CI qualification adds it via `publish.yml` build-swap → sign-swap → pack (`docs/CI.md`); sign-swap needs `APPLE_CERTIFICATE_BASE64`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_KEYCHAIN_PASSWORD` & `APPLE_DEVELOPER_ID` in the `release` environment, & stays blocked until root provisions the certificate pair. Exporting that identity requires an Aqua login session: SSH export fails `errSecInteractionNotAllowed` (-25308) & the Aqua signing agent exposes only codesign/updater/notarize/staple, no key export — do not retry either route. `install-app` refuses a helper that exists but is not validly signed (`SWAP_HELPER_UNSIGNED`, naming the fix); with no helper at all it uses the journaled two-rename fallback and logs it (`swap-fallback`, `replaced {swap}`).
 
 Development builds (from `@rightkit/ci` `devArtifact`, Developer ID-signed but not notarized) install with `--dev` and exactly one of `--dmg`, `--zip <path.zip>` (extracted with `ditto -x -k`), or `--app <path.app>`: `right-release install-app --dev --zip dev-mac.zip`. `--dev` still requires `codesign --verify --deep --strict`, a Team ID, no Team ID change, and a bundle-id match; it skips only `spctl` and `stapler`, removes `com.apple.quarantine` from the new bundle only, prints `DEV BUILD (not notarized)`, and sets `dev: true` on every JSON event.
 
@@ -384,7 +444,7 @@ Updater artifacts are declared as for R2 but need no `key`; `platform` must be a
 ```js
 targets: {
   win: {
-    updater: { keyFile: "%APPDATA%/RightKit/updater.key", artifacts: [
+    updater: { artifacts: [
       { file: "src-tauri/target/release/bundle/nsis/Ember_1.2.3_x64-setup.exe", signature: "src-tauri/target/release/bundle/nsis/Ember_1.2.3_x64-setup.exe.sig", platform: "windows-x86_64" },
     ] },
     artifacts: ["dist/Ember-1.2.3-portable-win.zip"], // portable zips seal alongside; they are not in latest.json
@@ -395,6 +455,8 @@ targets: {
 }
 ```
 
+Updater signing keys are never named in the config: `sign-updater` reads the minisign key from the OS credential provider (`rightkit-credentials`, namespace `rightsuite-updater-key`; see `protected-credentials.mjs`). `targets.<platform>.updater.keyFile` is refused at config validation (`RELEASE_CONFIG_UPDATER_KEY_FILE`, listed by `right-release doctor` and the build with every other finding) and is never forwarded to the signer, so remove it from apps that still set it.
+
 NSIS, MSI, `.app.tar.gz` and AppImage bundles all work the same way (any file signed by `sign-updater`). With no sealed installer the installer platform-trust check is skipped (reported in the output); installer-bearing seals still run it. The app side: `plugins.updater.endpoints` is the `latest.json` URL above and `plugins.updater.pubkey` is the suite updater public key (see `@rightkit/app-update` README).
 
 ## Android (AAB build, Play internal track, dev install)

package/admission-files.mjs

@@ -0,0 +1,279 @@
+// The files tier of the admission (admission.mjs): refusals decided by the release config and the committed files alone.
+// Each row is the predicate of a refusal the build used to raise later, after the lock, the install or the compile; the
+// message is the build's own, so the doctor, the build and the worker say the same thing. A row names where its twin lives.
+import path from "node:path";
+import { assertGitHubRepository } from "./github-updater-release.mjs";
+import { validateAndroidTarget } from "./android-release.mjs";
+import { assertNsisInPlaceUpgradeContract } from "./nsis-upgrade-contract.mjs";
+import { dirtyBuildInputs } from "./release-invocation.mjs";
+import { packageCommandOptional } from "./project-type.mjs";
+import { planMediaSidecar, validateMediaSidecarConfig } from "./media-sidecar.mjs";
+import { loadSidecarCatalog } from "./media-sidecar-catalog.mjs";
+
+export const WINDOWS_NSIS_SIGNING_CONTRACT = "windows-raw-exe-authenticode-before-nsis-v1";
+export const DISTRIBUTION_PROVIDERS = Object.freeze(["r2-rightapps", "github-releases"]);
+const SAFE_APP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SAFE_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+// publish-update.mjs assertCurrentKey / assertVersionedKey: where the R2 objects of a private release live.
+const CURRENT_UPDATER_KEY = /\/updates\/(?:mac|windows)\/current\//;
+const CURRENT_INSTALLER_KEY = /\/installers\/(?:mac|windows)\/current\//;
+const VERSIONED_INSTALLER_KEY = /\/installers\/(?:mac|windows)\/versions\/[^/]+\/[^/]+$/;
+
+const isNsis = (ctx) => ctx.platform === "win" && ctx.target?.signingContract === WINDOWS_NSIS_SIGNING_CONTRACT;
+const asList = (value) => (Array.isArray(value) ? value : []);
+const app = (ctx) => ctx.config?.app ?? "app";
+
+// build-release.mjs (the controller) and release.mjs (the worker) read the same "which file is the app's package.json" answer.
+const workdirOf = (ctx) => path.resolve(ctx.root, ctx.config?.workdir ?? ".");
+
+export const FILES_ROWS = Object.freeze([
+  {
+    // build-release.mjs: the config must expose a release identity that is safe to put in paths and ids.
+    id: "config-identity",
+    tier: "files",
+    needsTarget: false,
+    run({ config }) {
+      const found = [];
+      if (config?.schema !== 1) found.push(`unsupported config schema: ${config?.schema ?? "<missing>"} (expected 1)`);
+      if (!config?.app || !config?.version) found.push("release config must expose app and version");
+      else if (!SAFE_APP.test(config.app) || !SAFE_VERSION.test(config.version)) found.push("app and version must be safe release-id components");
+      return found;
+    },
+  },
+  {
+    // release.mjs `has no <platform> package command`; build-release.mjs said the same after the lock.
+    id: "package-command",
+    tier: "files",
+    run(ctx) {
+      if (ctx.platform === "android" || ctx.platform === "ios") return { na: "android and ios build without a package command" };
+      if (ctx.target.package || packageCommandOptional(ctx.target, ctx.projectType())) return undefined;
+      return [`${app(ctx)} has no ${ctx.platform} package command`];
+    },
+  },
+  {
+    // release-invocation.mjs resolveReleaseBuildInputs: the doctor reports it as its own check, the build as this row.
+    id: "build-inputs",
+    tier: "files",
+    doctorOwned: true,
+    run(ctx) {
+      const inputs = ctx.buildInputs();
+      return inputs.ok ? undefined : [inputs.error.message];
+    },
+  },
+  {
+    // The files that can change the packaged app are committed: the doctor reports it as its own check, the build as this row.
+    id: "dirty-inputs",
+    tier: "files",
+    doctorOwned: true,
+    after: ["build-inputs"],
+    run(ctx) {
+      const inputs = ctx.buildInputs();
+      if (!inputs.ok) return { skipped: "build-inputs is reported on its own" };
+      const dirty = dirtyBuildInputs(ctx.repoRoot, inputs.value.buildInputs, ctx.commit());
+      return dirty.length > 0 ? [`dirty files can change the packaged app; resolve them before release:\n${dirty.map((file) => `- ${file}`).join("\n")}`] : undefined;
+    },
+  },
+  {
+    // build-release.mjs hashInputs: two inputs may not share a sealed hash key, or one silently replaces the other.
+    id: "input-key-collision",
+    tier: "files",
+    after: ["build-inputs"],
+    run(ctx) {
+      const inputs = ctx.buildInputs();
+      if (!inputs.ok) return { skipped: "build-inputs is reported on its own" };
+      const seen = new Set();
+      const collided = new Set();
+      for (const file of inputs.value.requiredInputs) {
+        const key = path.relative(path.dirname(path.dirname(file)), file);
+        if (seen.has(key)) collided.add(key);
+        seen.add(key);
+      }
+      return [...collided].map((key) => `release inputs share the hash key ${key}; rename one so every input is sealed`);
+    },
+  },
+  {
+    // build-release.mjs assertNsisInPlaceUpgradeContract: the NSIS template that upgrades in place. The build judges it on the target
+    // as the config declares it, so a winPackage recipe (which declares no signingContract) is not held to it today.
+    id: "nsis-upgrade-contract",
+    tier: "files",
+    run(ctx) {
+      if (ctx.platform !== "win" || ctx.rawTarget?.signingContract !== WINDOWS_NSIS_SIGNING_CONTRACT) return { na: "not a Windows NSIS target declared in the config" };
+      try { assertNsisInPlaceUpgradeContract(ctx.root, ctx.rawTarget.nsisUpgradeContract); } catch (error) { return [error.message]; }
+      return undefined;
+    },
+  },
+  {
+    // release.mjs, after the installer is signed: the post-code-signing minisign needs updater.artifacts to sign.
+    id: "win-updater-artifacts",
+    tier: "files",
+    run(ctx) {
+      if (!isNsis(ctx)) return { na: "not a Windows NSIS target" };
+      return asList(ctx.target.updater?.artifacts).length > 0 ? undefined : [`${app(ctx)} win must declare updater.artifacts for post-code-signing minisign`];
+    },
+  },
+  {
+    // build-release.mjs sealRelease: what the seal needs from the config, evaluated before anything is compiled or signed.
+    id: "seal-routes",
+    tier: "files",
+    run(ctx) {
+      const { target, platform, config } = ctx;
+      const found = [];
+      const declared = asList(target.artifacts);
+      for (const entry of declared) {
+        const file = typeof entry === "string" ? entry : entry?.file;
+        if (typeof file !== "string" || !file) { found.push("target.artifacts entries must be paths or { file }"); break; }
+      }
+      const installers = asList(target.installer?.artifacts);
+      const updaters = asList(target.updater?.artifacts);
+      if (installers.length + updaters.length + declared.length === 0) found.push(`nothing to seal: declare installer.artifacts, updater.artifacts or artifacts for the ${platform} target`);
+      for (const entry of [...installers, ...updaters]) {
+        if (typeof entry?.file !== "string" || !entry.file) { found.push("installer and updater artifacts must each declare a file"); break; }
+      }
+      const minisign = updaters.length > 0 && target.updater?.kind !== "appinstaller";
+      if (minisign) {
+        const publicKey = config.distribution?.updaterPublicKey ?? config.distribution?.updaterPubkey ?? target.updater?.pubkey ?? target.updater?.publicKey;
+        if (typeof publicKey !== "string" || !publicKey.trim()) found.push("updater public key is required to verify updater artifacts before sealing");
+        for (const entry of updaters) {
+          if (typeof entry?.signature !== "string" || !entry.signature) found.push(`updater artifact ${entry?.file} must declare the signature file sign-updater writes next to it`);
+        }
+      }
+      const github = config.distribution?.provider === "github-releases";
+      for (const entry of updaters) {
+        if (entry?.key === undefined && !github) found.push(`updater artifact ${entry?.file} must declare the R2 route key (key); only github-releases names the route from the file`);
+      }
+      // The R2 keys publish-update.mjs checks at upload, tier by tier. Only a private release (r2-rightapps) is held to them. Both
+      // tiers check each updater's current key; only the patch tier checks the installer keys and where the patch updater lands, and
+      // it cannot run without installer.artifacts ("patch has no installer.artifacts"). The build is tier-neutral, so the patch
+      // checks apply exactly when the config makes the patch tier possible.
+      if (config.distribution?.provider === "r2-rightapps") {
+        const patchTier = installers.length > 0;
+        if (patchTier) {
+          for (const entry of installers) {
+            // publish-update.mjs assertCurrentKey tests the key as it is, so an installer with no key is refused with "got: undefined".
+            if (!CURRENT_INSTALLER_KEY.test(entry?.key)) found.push(`installer key must target the replaceable current R2 object, got: ${entry?.key}`);
+            if (entry?.versionedKey !== undefined && !VERSIONED_INSTALLER_KEY.test(entry.versionedKey)) found.push(`installer versionedKey must be <app>/installers/<os>/versions/<version>/<file>, got: ${entry.versionedKey}`);
+          }
+        }
+        for (const entry of updaters) {
+          if (typeof entry.key !== "string") continue;
+          if (!CURRENT_UPDATER_KEY.test(entry.key)) found.push(`updater key must target the replaceable current R2 object, got: ${entry.key}`);
+          if (!patchTier) continue;
+          // publish-update.mjs patchInstallerKey: the patch updater is uploaded as an installer, under patchKey or the updater key's installers twin.
+          const patchKey = entry.patchKey ? entry.patchKey : entry.key.includes("/updates/") ? entry.key.replace("/updates/", "/installers/") : null;
+          if (patchKey === null) found.push(`patch updater key must be convertible to installers/current, got: ${entry.key}`);
+          else if (!CURRENT_INSTALLER_KEY.test(patchKey)) found.push(`installer key must target the replaceable current R2 object, got: ${patchKey}`);
+        }
+      }
+      // The Android and iOS seals pin one file of target.artifacts (the AAB, the IPA).
+      const listed = declared.map((entry) => path.posix.normalize(String(typeof entry === "string" ? entry : entry?.file).replaceAll("\\", "/")));
+      if (platform === "android") {
+        let aab = null;
+        try { aab = validateAndroidTarget(target, { root: ctx.root }).aab?.file ?? null; } catch { /* the android-target check reports a bad target */ }
+        if (aab && !listed.includes(path.posix.normalize(aab.replaceAll("\\", "/")))) found.push("android seal requires targets.android.artifacts to list aab.file");
+      }
+      if (platform === "ios") {
+        const ipa = target.recipe?.spec?.ipa;
+        if (typeof ipa === "string" && !listed.includes(path.posix.normalize(ipa.replaceAll("\\", "/")))) found.push("ios seal requires targets.ios.artifacts to list iosPackage.ipa");
+      }
+      return found;
+    },
+  },
+  {
+    // publish-update.mjs: the provider the upload takes, for the win and mac releases it uploads (iOS and Android go through their own
+    // lanes, whose providers are app-store-connect and google-play). A config that declares no distribution is refused there too, as
+    // is a provider it does not know; preflight G16 refuses an unknown provider in the config text.
+    id: "distribution-provider",
+    tier: "files",
+    needsTarget: false,
+    run({ config, platform }) {
+      if (platform !== "win" && platform !== "mac") return { na: "publish-update.mjs uploads win and mac releases; other platforms upload through their own lane" };
+      const distribution = config.distribution;
+      const provider = distribution?.provider;
+      if (!DISTRIBUTION_PROVIDERS.includes(provider)) return [`release config distribution.provider must be ${DISTRIBUTION_PROVIDERS.join(" or ")}${provider === undefined ? "" : ` (got ${JSON.stringify(provider)})`}`];
+      if (provider === "github-releases") {
+        try { assertGitHubRepository(distribution.repository); } catch (error) { return [error.message]; }
+      }
+      return undefined;
+    },
+  },
+  {
+    // release.mjs frontendBundleDirs: the mock scan locates the frontend bundle from src-tauri/tauri.conf.json.
+    id: "frontend-config-readable",
+    tier: "files",
+    run(ctx) {
+      if (Array.isArray(ctx.target.webBundleScan)) return { na: "target.webBundleScan names the bundle directories" };
+      const confPath = path.join(ctx.root, "src-tauri", "tauri.conf.json");
+      if (!ctx.exists(confPath)) return { na: "no src-tauri/tauri.conf.json" };
+      try { JSON.parse(ctx.fs.readFileSync(confPath, "utf8")); } catch (error) {
+        return [`src-tauri/tauri.conf.json is unreadable, so the frontend bundle cannot be located for the mock scan: ${error.message}`];
+      }
+      return undefined;
+    },
+  },
+  {
+    // release-checks.mjs: every config.checks entry runs `<packageManager> run <entry>` after the install; a script that is not
+    // in package.json fails there, minutes in.
+    id: "declared-checks-exist",
+    tier: "files",
+    needsTarget: false,
+    run(ctx) {
+      const checks = asList(ctx.config.checks).filter((script) => script !== false);
+      if (checks.length === 0) return { na: "the config declares no checks" };
+      if (ctx.skipChecks) return { na: "the build was asked to skip the declared checks" };
+      const file = path.join(workdirOf(ctx), "package.json");
+      let scripts;
+      try { scripts = JSON.parse(ctx.fs.readFileSync(file, "utf8")).scripts ?? {}; } catch {
+        return [`config.checks declares ${checks.map((script) => JSON.stringify(script)).join(", ")} but ${file} is missing or unreadable`];
+      }
+      return checks.filter((script) => typeof script !== "string" || !Object.hasOwn(scripts, script))
+        .map((script) => `config.checks names ${JSON.stringify(script)}, which is not a script in ${path.relative(ctx.root, file).replaceAll("\\", "/") || "package.json"}`);
+    },
+  },
+  {
+    // release.mjs: a mediaSidecar or externalBin on macOS is verified inside the built .app, so the signing set must name one.
+    id: "sidecar-app-entry",
+    tier: "files",
+    run(ctx) {
+      if (ctx.platform !== "mac" || (ctx.target.mediaSidecar === undefined && ctx.target.externalBin === undefined)) return { na: "no mac sidecar" };
+      const hasApp = asList(ctx.target.sign?.prePackageFiles).some((entry) => /\.app\/?$/.test(typeof entry === "string" ? entry : String(entry?.file ?? "")));
+      if (hasApp) return undefined;
+      return [ctx.target.mediaSidecar !== undefined
+        ? "mediaSidecar on macOS needs an .app entry in sign.prePackageFiles"
+        : "externalBin on macOS needs an .app entry in sign.prePackageFiles"];
+    },
+  },
+  {
+    // release.mjs prepareMediaSidecar: the sidecar plan is made from the catalog before anything is staged or compiled. The two parts
+    // the committed files decide: the app has a native Cargo manifest to resolve the catalog from, and the catalog the config names
+    // plans (a row for each tool, approved, with its digest and notices). A catalog read through `cargo metadata` is the host row
+    // media-sidecar-catalog. An invalid mediaSidecar config is the media-sidecar rule's finding, not this row's.
+    id: "media-sidecar-plan",
+    tier: "files",
+    after: ["build-inputs"],
+    run(ctx) {
+      if (ctx.target.mediaSidecar === undefined || (ctx.platform !== "mac" && ctx.platform !== "win")) return { na: "the target declares no mediaSidecar" };
+      let sidecar;
+      try { sidecar = validateMediaSidecarConfig(ctx.target.mediaSidecar, { platform: ctx.platform }); } catch { return { skipped: "an invalid mediaSidecar configuration is reported by the media-sidecar rule" }; }
+      const inputs = ctx.buildInputs();
+      if (!inputs.ok) return { skipped: "build-inputs is reported on its own" };
+      const layout = inputs.value.nativeLayout;
+      // Unreachable for iOS (mediaSidecar is mac and win only); a Cargo-less layout must still never be dereferenced.
+      if (!layout) return [`${app(ctx)} ${ctx.platform} mediaSidecar needs a native Cargo manifest to read the sidecar catalog, and this app has none`];
+      if (!sidecar.catalog) return { skipped: "the catalog is resolved through cargo metadata, which the media-sidecar-catalog host row asks" };
+      try {
+        const loaded = loadSidecarCatalog({ config: sidecar, root: ctx.root, manifestPath: layout.manifestPath, read: (file) => ctx.fs.readFileSync(file) });
+        planMediaSidecar({ config: sidecar, ...loaded, root: ctx.root });
+      } catch (error) { return [`${app(ctx)} ${ctx.platform} mediaSidecar: [${error.code ?? "ERROR"}] ${error.message}`]; }
+      return undefined;
+    },
+  },
+  {
+    // build-release.mjs runConfiguredReleaseCheck: the preSeal check runs a command.
+    id: "pre-seal-command",
+    tier: "files",
+    run(ctx) {
+      if (!ctx.target.preSeal) return { na: "no preSeal check" };
+      return typeof ctx.target.preSeal.cmd === "string" && ctx.target.preSeal.cmd.trim() ? undefined : ["release preSeal check must declare a command"];
+    },
+  },
+]);