@rightkit/release 0.6.3 → 0.6.4

package/release-qa-policy.mjs

@@ -0,0 +1,168 @@
+// QA admission policy (ADR-0001 item 10): the per-app warn -> refuse switch and the approved rightkit-qa runner
+// digests, recorded in `qa-admission-policy.json` next to this module.
+//
+//   { "schema": 1,
+//     "apps": { "<app>": { "mode": "warn" | "refuse", "since": "YYYY-MM-DD", "set_by": "<name>" } },
+//     "approvedRunners": [ { "sha256": "<64 hex>", "version": "<rightkit-qa version>", "note": "..." } ] }
+//
+// An app with no entry is in `warn` mode (default). In `refuse` mode `admit()` throws instead of warning.
+//
+// Only the owner (`adrian`) may move an app back from `refuse` to `warn` (or delete its entry). What is checkable
+// here, and enforced:
+//   - every write through `setAdmissionMode` goes through `checkPolicyTransition`, which refuses a downgrade whose
+//     new entry is not `set_by: "adrian"`;
+//   - every load compares the working file with the copy committed at `baselineRef` (default HEAD) and refuses a
+//     hand-edited downgrade the same way, so an uncommitted edit cannot quietly switch an app off refuse;
+//   - an unreadable or malformed policy file is a hard error, never a silent fall back to warn.
+// What is NOT checkable from this file: `set_by` is a recorded claim, not an authenticated identity, and a
+// downgrade that was already committed is the new baseline. The file must therefore be owner-protected in the
+// repository (CODEOWNERS on this path plus branch protection, and the file belongs in the protected policy bundle,
+// see ownership-policy-bundle.mjs). CI should set RIGHT_RELEASE_QA_POLICY_BASELINE_REF=origin/main so the baseline
+// is the protected branch rather than the local HEAD.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { canonicalJson } from "./ownership-approval.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const HEX64 = /^[a-f0-9]{64}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+export const QA_ADMISSION_POLICY_FILE = "qa-admission-policy.json";
+export const QA_POLICY_BASELINE_REF_ENV = "RIGHT_RELEASE_QA_POLICY_BASELINE_REF";
+export const ADMISSION_MODES = Object.freeze(["warn", "refuse"]);
+/** The only `set_by` that may move an app from refuse back to warn. */
+export const POLICY_OWNER = "adrian";
+
+export class QaPolicyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QaPolicyError";
+    this.code = "QA_POLICY_INVALID";
+  }
+}
+
+export function validateAdmissionPolicy(policy) {
+  const problems = [];
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) return ["policy must be an object"];
+  if (policy.schema !== 1) problems.push("policy schema must be 1");
+  if (!policy.apps || typeof policy.apps !== "object" || Array.isArray(policy.apps)) problems.push("policy apps must be an object");
+  else {
+    for (const [app, entry] of Object.entries(policy.apps)) {
+      if (!app.trim()) problems.push("policy app name is empty");
+      if (!entry || typeof entry !== "object") { problems.push(`policy app ${app} must be an object`); continue; }
+      if (!ADMISSION_MODES.includes(entry.mode)) problems.push(`policy app ${app} mode must be warn or refuse`);
+      if (typeof entry.since !== "string" || !DATE.test(entry.since)) problems.push(`policy app ${app} since must be YYYY-MM-DD`);
+      if (typeof entry.set_by !== "string" || !entry.set_by.trim()) problems.push(`policy app ${app} set_by is required`);
+    }
+  }
+  if (!Array.isArray(policy.approvedRunners)) problems.push("policy approvedRunners must be an array");
+  else {
+    for (const runner of policy.approvedRunners) {
+      if (!runner || typeof runner.sha256 !== "string" || !HEX64.test(runner.sha256)) problems.push("approvedRunners entries need a lowercase 64-hex sha256");
+    }
+  }
+  return problems;
+}
+
+/** Problems when `next` weakens `previous`: a refuse entry that is gone or now warn without `set_by: "adrian"`. */
+export function checkPolicyTransition(previous, next) {
+  const problems = [];
+  for (const [app, before] of Object.entries(previous?.apps ?? {})) {
+    if (before?.mode !== "refuse") continue;
+    const after = next?.apps?.[app];
+    if (!after) problems.push(`${app}: the refuse entry was removed; only ${POLICY_OWNER} may move an app back to warn (set mode warn with set_by "${POLICY_OWNER}")`);
+    else if (after.mode !== "refuse" && after.set_by !== POLICY_OWNER) problems.push(`${app}: refuse -> warn requires set_by "${POLICY_OWNER}", got ${JSON.stringify(after.set_by)}`);
+  }
+  return problems;
+}
+
+const digestOf = (policy) => createHash("sha256").update(canonicalJson(policy)).digest("hex");
+
+function parsePolicyText(text, label) {
+  let policy;
+  try { policy = JSON.parse(text); } catch (error) { throw new QaPolicyError(`QA admission policy is unreadable (${label}): ${error.message}`); }
+  const problems = validateAdmissionPolicy(policy);
+  if (problems.length) throw new QaPolicyError(`QA admission policy is invalid (${label}): ${problems.join("; ")}`);
+  return policy;
+}
+
+function gitBaselineText({ dir, ref, runner = spawnSync }) {
+  try {
+    const result = runner("git", ["-C", dir, "show", `${ref}:./${QA_ADMISSION_POLICY_FILE}`], { encoding: "utf8", windowsHide: true });
+    return result?.status === 0 ? String(result.stdout) : null;
+  } catch { return null; }
+}
+
+/**
+ * Load the policy. `baseline` (policy text) overrides the git lookup; `baseline: false` disables the comparison.
+ * Returns { policy, digest, baseline: "supplied" | "git" | "none" }.
+ */
+export function loadAdmissionPolicy({ dir = here, baseline, baselineRef, env = process.env, gitRunner } = {}) {
+  const file = path.join(dir, QA_ADMISSION_POLICY_FILE);
+  if (!existsSync(file)) throw new QaPolicyError(`QA admission policy is missing (${QA_ADMISSION_POLICY_FILE}); it ships with @rightkit/release and is never optional`);
+  const policy = parsePolicyText(readFileSync(file, "utf8"), QA_ADMISSION_POLICY_FILE);
+  let source = "none";
+  let baselineText = null;
+  if (typeof baseline === "string") { baselineText = baseline; source = "supplied"; }
+  else if (baseline !== false) {
+    baselineText = gitBaselineText({ dir, ref: baselineRef ?? env?.[QA_POLICY_BASELINE_REF_ENV] ?? "HEAD", runner: gitRunner });
+    if (baselineText !== null) source = "git";
+  }
+  if (baselineText !== null) {
+    const problems = checkPolicyTransition(parsePolicyText(baselineText, "baseline"), policy);
+    if (problems.length) throw new QaPolicyError(`QA admission policy weakens its baseline: ${problems.join("; ")}`);
+  }
+  return { policy, digest: digestOf(policy), baseline: source };
+}
+
+/** The mode for an app; an app with no entry is `warn`. */
+export function admissionModeFor(policy, app) {
+  const entry = policy?.apps?.[app];
+  return entry?.mode === "refuse" ? { mode: "refuse", since: entry.since, set_by: entry.set_by } : { mode: "warn", since: entry?.since ?? null, set_by: entry?.set_by ?? null };
+}
+
+export const approvedRunnerDigests = (policy) => (policy?.approvedRunners ?? []).map((runner) => runner.sha256);
+
+/**
+ * Record an app's mode. A downgrade (refuse -> warn) is refused unless `setBy` is the owner. Writes atomically.
+ * The file is read without the git baseline here (the transition rule is applied directly to what is on disk).
+ */
+export function setAdmissionMode({ app, mode, setBy, dir = here, now = () => new Date() }) {
+  if (!app || !String(app).trim()) throw new QaPolicyError("app is required");
+  if (!ADMISSION_MODES.includes(mode)) throw new QaPolicyError("mode must be warn or refuse");
+  if (!setBy || !String(setBy).trim()) throw new QaPolicyError("set_by is required");
+  const file = path.join(dir, QA_ADMISSION_POLICY_FILE);
+  const current = parsePolicyText(readFileSync(file, "utf8"), QA_ADMISSION_POLICY_FILE);
+  const next = { ...current, apps: { ...current.apps, [app]: { mode, since: now().toISOString().slice(0, 10), set_by: String(setBy) } } };
+  const problems = checkPolicyTransition(current, next);
+  if (problems.length) throw new QaPolicyError(`QA admission policy change refused: ${problems.join("; ")}`);
+  const sorted = { ...next, apps: Object.fromEntries(Object.entries(next.apps).sort(([a], [b]) => a.localeCompare(b))) };
+  mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(sorted, null, 2)}\n`);
+  renameSync(temp, file);
+  return sorted.apps[app];
+}
+
+// `node release-qa-policy.mjs show | set --app <app> --mode warn|refuse --set-by <name>`
+export function main(args, { stdout = (text) => console.log(text), stderr = (text) => console.error(text) } = {}) {
+  const value = (flag) => { const index = args.indexOf(flag); return index >= 0 ? args[index + 1] : undefined; };
+  try {
+    if (args[0] === "show") { stdout(JSON.stringify(loadAdmissionPolicy().policy, null, 2)); return 0; }
+    if (args[0] === "set") {
+      const entry = setAdmissionMode({ app: value("--app"), mode: value("--mode"), setBy: value("--set-by") });
+      stdout(`qa admission: ${value("--app")} -> ${entry.mode} (since ${entry.since}, set_by ${entry.set_by})`);
+      return 0;
+    }
+    stderr("usage: release-qa-policy.mjs show | set --app <app> --mode warn|refuse --set-by <name>");
+    return 2;
+  } catch (error) {
+    stderr(`release-qa-policy: ${error.message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exit(main(process.argv.slice(2)));

package/release-qa-receipt.mjs

@@ -85,6 +85,17 @@ export function validateQaFloor(floor) {
     const required = floor.stages?.[stage]?.required;
     if (!Array.isArray(required) || required.length === 0 || required.some((id) => typeof id !== "string" || !id)) problems.push(`floor stage ${stage} must list required check ids`);
   }
+  // `journeys` maps one floor id to "every release-critical journey required on the platform passed", proven by a
+  // rightkit.journeys.receipt/1 validated through rightkit-qa (release-qa-hardening.mjs).
+  const journeys = floor.journeys;
+  if (journeys !== undefined) {
+    if (!journeys || typeof journeys !== "object" || Array.isArray(journeys)) problems.push("floor journeys must be an object");
+    else {
+      if (typeof journeys.floorId !== "string" || !QA_STAGES.every((stage) => floor.stages?.[stage]?.required?.includes?.(journeys.floorId))) problems.push("floor journeys.floorId must be a required id of every stage");
+      if (journeys.receiptSchema !== "rightkit.journeys.receipt/1") problems.push("floor journeys.receiptSchema must be rightkit.journeys.receipt/1");
+      if (journeys.rule !== "all-release-critical-passed") problems.push("floor journeys.rule must be all-release-critical-passed");
+    }
+  }
   return problems;
 }
 
@@ -95,6 +106,11 @@ export function validateAppQaConfig(qa, floor, stage) {
   if (typeof qa.version !== "string" && typeof qa.version !== "number") problems.push("qa.version is required");
   if (typeof qa.config !== "string" || !qa.config) problems.push("qa.config (rightkit-qa.toml path) is required");
   for (const id of floor.stages[stage].required) {
+    // The journeys receipt proves this id; no evidence-check mapping is needed (or used) for it.
+    if (floor.journeys?.floorId === id && qa.journeys) {
+      if (typeof qa.journeys !== "object" || Array.isArray(qa.journeys)) problems.push("qa.journeys must be an object { manifest?, receipt?, args? }");
+      continue;
+    }
     const patterns = qa.checks?.[id];
     if (!Array.isArray(patterns) || patterns.length === 0 || patterns.some((p) => typeof p !== "string" || !p)) problems.push(`qa.checks must map required floor check "${id}" to evidence check names`);
   }
@@ -179,7 +195,7 @@ export function receiptDigest(receipt) {
 
 export function buildQaReceipt({
   stage, app, platform, releaseId, source, closure, releaseConfigSha256, qa, floor, floorDigest, policyBundleDigest,
-  runner, evidence, evidenceSha256, required, artifacts = [], sourceReceiptDigest = null, now = new Date(),
+  runner, evidence, evidenceSha256, required, artifacts = [], sourceReceiptDigest = null, now = new Date(), journeys = null, execution = null,
 }) {
   const evidenceOk = evidence?.status === "passed" && Boolean(evidence?.finishedAt);
   const status = evidenceOk && required.every((item) => item.status === "passed") ? "passed" : "failed";
@@ -195,6 +211,8 @@ export function buildQaReceipt({
     evidence: { sha256: evidenceSha256, runId: evidence?.runId ?? null, status: evidence?.status ?? null, schemaVersion: evidence?.schemaVersion ?? null },
     required, checks: (evidence?.checks ?? []).map((check) => ({ name: String(check.name), status: String(check.status) })),
     artifacts, sourceReceiptDigest, status, createdAt: now.toISOString(),
+    ...(journeys ? { journeys } : {}),
+    ...(execution ? { execution } : {}),
   };
 }
 
@@ -272,6 +290,7 @@ export function assertSourceQaAdmission({ repoRoot, releaseId, platform, configN
   if (carried && (receipt.releaseId !== releaseId || receipt.platform !== platform)) {
     throw new QaAdmissionError(`source QA receipt rejected: carried receipt is for ${receipt.releaseId} (${receipt.platform}), not ${releaseId} (${platform})`, { command });
   }
+  opts.afterVerify?.(receipt); // hardening hook (release-qa-hardening.mjs); throws QaAdmissionError
   return { digest: receipt.digest, floorDigest: receipt.floor.digest };
 }
 
@@ -293,5 +312,6 @@ export function assertInstalledQaAdmission({ repoRoot, manifest, platform, confi
   });
   if (!verdict.ok) throw new QaAdmissionError(`installed QA receipt rejected: ${verdict.reason}`, { command });
   if (receipt.commit !== manifest.commit) throw new QaAdmissionError("installed QA receipt commit differs from the sealed release commit", { command });
+  opts.afterVerify?.(receipt);
   return { digest: receipt.digest };
 }

package/release-switch-scan.mjs

@@ -370,7 +370,7 @@ const DYNAMIC_READS = [
 // Builtins every JS runtime sets; they select nothing and are not part of the inventory.
 const JS_BUILTINS = new Set(["MODE", "DEV", "PROD", "BASE_URL", "SSR", "NODE_ENV"]);
 
-function* walkSource(root) {
+function* walkSource(root, skipAbs = new Set()) {
   const stack = [root];
   while (stack.length) {
     const dir = stack.pop();
@@ -379,7 +379,7 @@ function* walkSource(root) {
     for (const entry of entries) {
       const full = path.join(dir, entry.name);
       if (entry.isSymbolicLink()) continue;
-      if (entry.isDirectory()) { if (!skipDir(entry.name)) stack.push(full); continue; }
+      if (entry.isDirectory()) { if (!skipDir(entry.name) && !skipAbs.has(full)) stack.push(full); continue; }
       if (entry.isFile() && SOURCE_EXT.has(path.extname(entry.name)) && !TEST_FILE.test(entry.name)) yield full;
     }
   }
@@ -388,7 +388,7 @@ function* walkSource(root) {
 function lineOf(text, index) { let n = 1; for (let i = 0; i < index; i += 1) if (text.charCodeAt(i) === 10) n += 1; return n; }
 
 // inventoryText: contents of switches.json. Returns findings only.
-export function sourceSwitchFindings({ sourceRoot, sourceRoots, inventoryText, inventoryLabel = "switches.json", extraDeny = [] }) {
+export function sourceSwitchFindings({ sourceRoot, sourceRoots, inventoryText, inventoryLabel = "switches.json", extraDeny = [], skipRoots = [] }) {
   const { doc, issues } = parseInventory(inventoryText, inventoryLabel);
   const findings = [...issues];
   if (!doc || !Array.isArray(doc.switches)) return findings;
@@ -398,7 +398,9 @@ export function sourceSwitchFindings({ sourceRoot, sourceRoots, inventoryText, i
   const denyFlags = [...REGISTRY.denyNames, ...extraDeny.map((n) => ({ name: typeof n === "string" ? n : n.name }))].map((d) => d.name).filter((n) => n.startsWith("-"));
   // `sourceRoots` (absolute directories) narrows the walk to what a target compiles; paths stay relative to `sourceRoot`.
   const walkRoots = Array.isArray(sourceRoots) && sourceRoots.length ? sourceRoots : [sourceRoot];
-  for (const file of walkRoots.flatMap((walkRoot) => [...walkSource(walkRoot)])) {
+  // `skipRoots` (paths relative to `sourceRoot`, validated by `validateNonShipped`) are directories that never ship; the walk does not enter them.
+  const skipAbs = new Set((skipRoots ?? []).map((dir) => path.resolve(sourceRoot, dir)));
+  for (const file of walkRoots.flatMap((walkRoot) => [...walkSource(walkRoot, skipAbs)])) {
     let text;
     try { text = readFileSync(file, "utf8"); } catch { continue; }
     const rel = path.relative(sourceRoot, file);
@@ -527,7 +529,7 @@ export function scanSwitchPaths(paths, { denyMap = denyNamesFor() } = {}) {
 // Every layer is optional input; a layer given no input is skipped, except that `requireBinary` fails a scan that
 // found no native binary. `bypass: ["feature-closure"]` exists only for the negative fixtures that prove the binary
 // layer independently; release.mjs never passes it.
-export function releaseSwitchFindings({ treeText, commands = [], sourceRoot, sourceRoots, inventoryText, binaryPaths = [], appForbid = [], requireBinary = true, bypass = [], remoteHost, remoteLoopback, devtools } = {}) {
+export function releaseSwitchFindings({ treeText, commands = [], sourceRoot, sourceRoots, skipRoots, inventoryText, binaryPaths = [], appForbid = [], requireBinary = true, bypass = [], remoteHost, remoteLoopback, devtools } = {}) {
   const findings = [];
   const bypassed = new Set(bypass);
   const denyMap = denyNamesFor({ appForbid: [...appForbid, ...(inventoryText != null ? inventoryDenyNames(inventoryText) : [])] });
@@ -539,7 +541,7 @@ export function releaseSwitchFindings({ treeText, commands = [], sourceRoot, sou
     }
     for (const argv of commands) findings.push(...commandSwitchFindings(argv, { allowDevtools: devtools?.mode === "content-only" }));
   }
-  if (sourceRoot && inventoryText != null) findings.push(...sourceSwitchFindings({ sourceRoot, sourceRoots, inventoryText, extraDeny: appForbid }));
+  if (sourceRoot && inventoryText != null) findings.push(...sourceSwitchFindings({ sourceRoot, sourceRoots, skipRoots, inventoryText, extraDeny: appForbid }));
   let receipt = { files: [], binaries: 0 };
   if (binaryPaths.length) {
     const scanned = scanSwitchPaths(binaryPaths, { denyMap });
@@ -571,3 +573,132 @@ export function localCrateDirsFromTree(treeText, root) {
   }
   return [...dirs].sort();
 }
+
+const NON_SHIPPED_SKIP = new Set(["node_modules", "target", ".git"]);
+function hasPackageJson(dir, depth = 0) {
+  if (depth > 6) return false;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "package.json") return true;
+    if (entry.isDirectory() && !entry.isSymbolicLink() && !NON_SHIPPED_SKIP.has(entry.name) && hasPackageJson(path.join(dir, entry.name), depth + 1)) return true;
+  }
+  return false;
+}
+const within = (outer, inner) => inner === outer || inner.startsWith(outer + path.sep);
+
+const readJsonSafe = (file) => { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } };
+const readTextSafe = (file) => { try { return readFileSync(file, "utf8"); } catch { return ""; } };
+const BUILD_HOOKS = ["beforeBuildCommand", "beforeDevCommand", "beforeBundleCommand"];
+
+// Existing paths under `base` named by shell command strings (`node ./scripts/x.mjs && pnpm run y`): each path-like token, and
+// the body of every package.json script reached through `run <name>` / `pnpm <name>`.
+function commandRefs(base, commands, scripts) {
+  const refs = new Set();
+  const seen = new Set();
+  const visit = (command, depth) => {
+    for (const raw of String(command).split(/\s+|&&|\|\||[;|]/)) {
+      const tokens = [raw.replace(/^['"]+|['"]+$/g, "")];
+      if (raw.includes("=")) tokens.push(raw.slice(raw.indexOf("=") + 1).replace(/^['"]+|['"]+$/g, ""));
+      for (const token of tokens) {
+        if (!token || token.startsWith("-") || /^[a-z][a-z0-9+.-]*:\/\//i.test(token)) continue;
+        if (!/[\\/]|\.[A-Za-z0-9]+$/.test(token)) continue;
+        const abs = path.resolve(base, token);
+        if (abs !== base && within(base, abs) && existsSync(abs)) refs.add(abs);
+      }
+    }
+    if (depth >= 4) return;
+    for (const m of String(command).matchAll(/\b(?:pnpm|npm|yarn|bun)\s+(?:run\s+)?([A-Za-z0-9:_.-]+)/g)) {
+      const name = m[1];
+      if (Object.hasOwn(scripts, name) && !seen.has(name)) { seen.add(name); visit(scripts[name], depth + 1); }
+    }
+  };
+  commands.forEach((c) => visit(c, 0));
+  return refs;
+}
+
+// The standard root-level frontend (package.json at the app root): src/, public/ and every directory index.html, vite.config.*
+// and tsconfig.json name. Quoted strings in vite.config are read as paths when they exist under the root (root, publicDir, build input).
+function rootFrontendDirs(base) {
+  const dirs = new Set();
+  const add = (rel) => {
+    const abs = path.resolve(base, rel);
+    if (abs !== base && within(base, abs) && existsSync(abs)) dirs.add(abs);
+  };
+  add("src"); add("public");
+  for (const m of readTextSafe(path.join(base, "index.html")).matchAll(/\b(?:src|href)\s*=\s*["']([^"'#?]+)["']/g)) if (!/^[a-z][a-z0-9+.-]*:|^\/\//i.test(m[1])) add(m[1].replace(/^\//, ""));
+  for (const entry of readdirSafe(base)) {
+    if (!/^vite\.config\./.test(entry)) continue;
+    for (const m of readTextSafe(path.join(base, entry)).matchAll(/["'`]([^"'`\n]+)["'`]/g)) add(m[1].replace(/^\//, ""));
+  }
+  const ts = readTextSafe(path.join(base, "tsconfig.json"));
+  for (const m of ts.matchAll(/"(?:include|files)"\s*:\s*\[([^\]]*)\]/g)) {
+    for (const q of m[1].matchAll(/"([^"]+)"/g)) add(q[1].split(/[*?{[]/)[0].replace(/\/$/, "") || ".");
+  }
+  return dirs;
+}
+function readdirSafe(dir) { try { return readdirSync(dir); } catch { return []; } }
+
+/**
+ * `releaseSwitches.nonShipped: [{ dir, reason }]`: app directories (tooling, bakeoffs, scripts) the desktop source walk skips.
+ * An exclusion list: whatever is not declared is still scanned. Each entry is refused (`inventory-invalid`) when the dir is missing,
+ * absolute, escapes the root, is a symlink or the root itself, has an empty reason, contains or sits inside a local crate of the release
+ * cargo tree, contains or sits inside `src-tauri` or the Tauri `frontendDist` bundle, or contains or sits inside a package that has a
+ * `package.json` (a frontend build input), overlaps the root frontend (`src/`, `public/`, directories named by `index.html`, `vite.config.*` or
+ * `tsconfig.json`, when the root has a `package.json`), or contains a file named by a `src-tauri/tauri.conf.json` `before*Command` or a root
+ * `package.json` `build*` script or by the release recipe's own commands (`recipeCommands`; followed through `run <script>`), which run during the release build.
+ * Returns { findings, roots } where `roots` are the validated root-relative dirs, empty if any entry was refused.
+ */
+export function validateNonShipped({ root, treeText, nonShipped, recipeCommands = [] }) {
+  const findings = [];
+  const roots = [];
+  const bad = (label, why) => findings.push({ layer: "inventory", rule: "inventory-invalid", file: `releaseSwitches.nonShipped${label}`, reason: `inventory-invalid: releaseSwitches.nonShipped${label}: ${why}` });
+  if (nonShipped === undefined) return { findings, roots };
+  if (!Array.isArray(nonShipped)) { bad("", "must be an array of { dir, reason }"); return { findings, roots }; }
+  const base = path.resolve(root);
+  const crates = localCrateDirsFromTree(treeText, base).map((dir) => (dir === base ? path.join(base, "src") : dir));
+  const protectedDirs = [path.join(base, "src-tauri"), ...crates];
+  try {
+    const conf = JSON.parse(readFileSync(path.join(base, "src-tauri", "tauri.conf.json"), "utf8")).build ?? {};
+    const dist = conf.frontendDist ?? conf.distDir;
+    if (typeof dist === "string" && !/^[a-z][a-z0-9+.-]*:\/\//i.test(dist)) protectedDirs.push(path.resolve(base, "src-tauri", dist));
+  } catch { /* no readable tauri.conf.json: nothing extra to protect */ }
+  const pkg = readJsonSafe(path.join(base, "package.json"));
+  const frontendDirs = pkg ? rootFrontendDirs(base) : new Set();
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const hookObj = readJsonSafe(path.join(base, "src-tauri", "tauri.conf.json"))?.build ?? {};
+  const commands = [
+    ...BUILD_HOOKS.map((k) => hookObj[k]).map((v) => (v && typeof v === "object" ? v.script : v)).filter((v) => typeof v === "string"),
+    ...Object.entries(scripts).filter(([name, v]) => /^build/.test(name) && typeof v === "string").map(([, v]) => v),
+    // The release recipe's own commands (targets.<os>.prePackage, package, postSign, packageHook, finalizer): `release.mjs` passes its `closureCommands`.
+    ...(Array.isArray(recipeCommands) ? recipeCommands : []).map((c) => (Array.isArray(c) ? c.join(" ") : c)).filter((c) => typeof c === "string"),
+  ];
+  const buildRefs = commandRefs(base, commands, scripts);
+  nonShipped.forEach((entry, i) => {
+    const label = `[${i}]`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) { bad(label, "must be { dir, reason }"); return; }
+    const { dir, reason } = entry;
+    if (typeof reason !== "string" || reason.trim() === "") bad(label, "reason is required and must say why the directory never ships");
+    if (typeof dir !== "string" || dir.trim() === "") { bad(label, "dir is required"); return; }
+    if (path.isAbsolute(dir) || path.win32.isAbsolute(dir)) { bad(label, `dir \`${dir}\` must be relative to the app root, not absolute`); return; }
+    const abs = path.resolve(base, dir);
+    if (abs === base) { bad(label, `dir \`${dir}\` is the app root itself`); return; }
+    if (!within(base, abs)) { bad(label, `dir \`${dir}\` escapes the app root`); return; }
+    let st;
+    try { st = lstatSync(abs); } catch { bad(label, `dir \`${dir}\` does not exist under the app root`); return; }
+    if (st.isSymbolicLink() || !st.isDirectory()) { bad(label, `dir \`${dir}\` must be a real directory`); return; }
+    for (const guarded of protectedDirs) {
+      if (within(abs, guarded) || within(guarded, abs)) { bad(label, `dir \`${dir}\` overlaps shipped code (${path.relative(base, guarded) || "."}: a local crate of the release cargo tree, src-tauri or the frontend bundle); it cannot be declared non-shipped`); return; }
+    }
+    if (hasPackageJson(abs)) { bad(label, `dir \`${dir}\` contains a package.json (a possible frontend build input); it cannot be declared non-shipped`); return; }
+    for (let up = path.dirname(abs); within(base, up) && up !== base; up = path.dirname(up)) {
+      if (existsSync(path.join(up, "package.json"))) { bad(label, `dir \`${dir}\` sits inside a package (${path.relative(base, up)}/package.json: a possible frontend build input); it cannot be declared non-shipped`); return; }
+    }
+    const guardedBy = [...frontendDirs].find((g) => within(abs, g) || within(g, abs));
+    if (guardedBy) { bad(label, `dir \`${dir}\` overlaps the app's root frontend (${path.relative(base, guardedBy)}: src/, public/ or a directory named by index.html, vite.config or tsconfig); it cannot be declared non-shipped`); return; }
+    const buildRef = [...buildRefs].find((r) => within(abs, r) || within(r, abs));
+    if (buildRef) { bad(label, `dir \`${dir}\` contains or sits inside a build-time input (${path.relative(base, buildRef).split(path.sep).join("/")}: named by a tauri.conf.json before*Command or a package.json build script, which runs during the release build); it cannot be declared non-shipped`); return; }
+    if (typeof reason === "string" && reason.trim() !== "") roots.push(path.relative(base, abs));
+  });
+  return { findings, roots: findings.length ? [] : roots };
+}