@rightkit/release 0.6.13 → 0.6.14

package/release-qa-audit.mjs

@@ -15,8 +15,8 @@ import { spawnSync } from "./background-process.mjs";
 import { hardenQaReceipt } from "./release-qa-hardening.mjs";
 import { admissionModeFor, loadAdmissionPolicy } from "./release-qa-policy.mjs";
 import { assertInstalledQaAdmission, assertSourceQaAdmission, loadQaFloor, QaAdmissionError, qaReceiptPath, readQaReceipt } from "./release-qa-receipt.mjs";
+import { platformDirOf, platformOfDir } from "./platform-dir.mjs";
 
-const platformDirOf = (platform) => (platform === "win" ? "windows" : platform);
 
 /** "missing" when no receipt exists; "rejected" for anything else the gate refused (bad receipt, no key, wrong commit). */
 function refusalStatus(error) {
@@ -106,7 +106,7 @@ function installedStatus({ repoRoot, releaseId, platformDir }) {
   if (record) return { uploaded: true, status: record.status, ...(record.reason ? { reason: record.reason } : {}), ...(record.checkedAt ? { checkedAt: record.checkedAt } : {}) };
   if (!published) return { uploaded: false, status: "not-uploaded" };
   // Uploaded before outcomes were recorded: fall back to the receipt file the old gate required.
-  const receipt = readQaReceipt(qaReceiptPath({ repoRoot, releaseId, platform: platformDir === "windows" ? "win" : platformDir, stage: "installed" }));
+  const receipt = readQaReceipt(qaReceiptPath({ repoRoot, releaseId, platform: platformOfDir(platformDir), stage: "installed" }));
   if (receipt?.status === "passed") return { uploaded: true, status: "passed", reason: "legacy upload; receipt file present, not re-verified" };
   return { uploaded: true, status: "missing", reason: "uploaded with no recorded installed QA outcome" };
 }

package/release-qa-command.mjs

@@ -36,6 +36,7 @@ import {
   buildQaReceipt, currentPolicyBundleDigest, dependencyClosure, ensureQaReceiptKey, evaluateRequiredChecks, loadQaFloor,
   qaReceiptPath, QA_STAGES, sealQaReceipt, sourceIdentity, validateAppQaConfig, writeQaReceipt,
 } from "./release-qa-receipt.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
 
@@ -126,7 +127,7 @@ export async function runQa({ stage, platform, releaseIdArg, configPath, carryTo
   if (stage === "source") releaseId = `${config.app}-${config.version}-${source.commit.slice(0, 8)}`;
   else {
     if (!releaseId) throw new Error("--release <sealed-id> is required for the installed stage");
-    sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platform === "win" ? "windows" : "mac"));
+    sealed = verifySealedRelease(path.join(repoRoot, ".right-release", "sealed", releaseId, platformDirOf(platform)));
     // R4: a split binds the sealed release to the selected commit (and its tree), never to the checkout's HEAD.
     if (split) assertBindsSource(release, sealed.manifest, "the sealed release");
     else if (sealed.manifest.commit !== source.commit) throw new Error("sealed release was built from a different commit than the current checkout");

package/release-qa-receipt.mjs

@@ -9,6 +9,7 @@
 // runner binary and the evidence bundle it produced, evaluates the protected QA floor, and MACs the result with a
 // key held in the protected credential store (Keychain / protected file / CI secret) — not app-writable JSON.
 // The floor, this verifier, and the receipt schema are pinned in the protected policy bundle.
+import { writeFileAtomic } from "./atomic-write.mjs";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -266,8 +267,8 @@ export function readQaReceipt(file) {
 }
 
 export function writeQaReceipt(file, receipt) {
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+  // GB-26: the authoritative QA receipt is replaced atomically (temp, fsync, rename), never overwritten in place.
+  writeFileAtomic(file, `${JSON.stringify(receipt, null, 2)}\n`);
 }
 
 function loadKeyOrRefuse(opts, command) {

package/release-state.mjs

@@ -7,6 +7,7 @@ import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
 import { bufferQaFindings } from "./qa-control-scan.mjs";
 import { sealedManifestAllowsContentDevtools } from "./devtools-policy.mjs";
 import { assertManifestRegistryEvidence } from "./rightkit-registry-resolver.mjs";
+import { platformDirOf } from "./platform-dir.mjs";
 
 export function cacheFingerprint({ cargoLockSha256, rustc, target, architecture, features = [] }) {
   const payload = JSON.stringify({
@@ -157,7 +158,7 @@ export async function runBuildStateMachine({
   ops,
 }) {
   const releaseId = `${app}-${version}-${commit.slice(0, 8)}`;
-  const platformDir = platform === "win" ? "windows" : platform === "mac" ? "mac" : platform;
+  const platformDir = platformDirOf(platform);
   const sealedDir = path.join(root, ".right-release", "sealed", releaseId, platformDir);
   const sealedRoot = path.join(root, ".right-release", "sealed");
   if (existsSync(sealedRoot)) {
@@ -202,7 +203,7 @@ export async function runBuildStateMachine({
 export async function runUploadStateMachine({ root, releaseId, platform, tier, ops = {} }) {
   if (tier !== "patch" && tier !== "update") throw new Error("upload tier is required (patch|update)");
   if (!/^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/.test(String(releaseId))) throw new Error(`invalid release id: ${releaseId}`);
-  const platformDir = platform === "win" ? "windows" : platform === "mac" ? "mac" : platform;
+  const platformDir = platformDirOf(platform);
   const sealedDir = path.join(root, ".right-release", "sealed", releaseId, platformDir);
   const sealed = verifySealedRelease(sealedDir);
   if (sealed.manifest.platform !== platform) throw new Error("sealed release platform mismatch");

package/release.mjs

@@ -3,7 +3,8 @@ import { expandPackageRecipeTarget } from "./package-recipe-targets.mjs";
 import { access, readFile, readdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
-import { buildLaunch } from "./build-launch.mjs";
+import { buildLaunch, createNativeRunner } from "./build-launch.mjs";
+import { NATIVE_SIGNING_FILE_ENV, nativeToolOf } from "./native-adapters.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -735,6 +736,9 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
   await runAndroidRelease({
     root, app: config.app ?? path.basename(root), target: androidTarget, dryRun: opts.dryRun,
     runGradle: (gradle, env) => runCommand(gradle, root, { env }),
+    // RA-07/RA-08: the production runner of the native compile phases (build-launch.mjs createNativeRunner): the carrier or the resolved executor's client, never a spawn of its own, a fixed result shape with the
+    // receipt's output mapping, and the signing-properties file as a typed path handoff (`signingFile`), never an environment. An injected executor is not accepted here.
+    native: createNativeRunner({ cwd: root, env: process.env }),
     resolveArtifact: (declared) => resolveReleaseArtifactPath(root, declared),
     scanFiles: (label, files, scanOptions) => assertNoQaControlBinaries(label, files, scanOptions),
     receiptDir: path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(root, ".right-release", "receipts")),
@@ -745,6 +749,8 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
   // --dry-run prints the plan anywhere). Upload is a separate command: `right-release upload --platform ios`.
   await runIosPackageRecipe({
     root, app: config.app ?? path.basename(root), spec: iosSpec, dryRun: opts.dryRun,
+    // RA-09: the production runner of the native compile phases (xcodegen, xcodebuild archive/export/test), never an injected executor or a spawn: build-launch.mjs createNativeRunner.
+    native: createNativeRunner({ cwd: root, env: process.env }),
     receiptDir: path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(root, ".right-release", "receipts")),
     scanFiles: (label, files, scanOptions) => assertNoQaControlBinaries(label, files, scanOptions),
     // The build number counter outlives every release id: it lives in the vault state root that right-release build exports.
@@ -1198,8 +1204,13 @@ async function runCommands(value, root, options) {
 // on a broker-managed host (rightkit#1241).
 async function runCommand(command, root, { env = {}, captureStdout = false } = {}) {
   const cwd = path.resolve(root, command.cwd ?? ".");
-  const commandEnvironment = { ...(await commandEnv(command, root)), ...env };
-  const target = buildLaunch(command.cmd, command.args ?? [], { env: { ...process.env, ...commandEnvironment }, cwd, exists: existsSync });
+  // RA-08: the dynamic signing-properties file path of a native tool (Gradle) is a typed FILE handoff of the provisioned signer session, not a step environment: it is taken out of the environment the door
+  // sees (so it never reaches RUSTRIGHT_ADAPTER_ENV or a client's environment) and handed to the door as `signingFile`. A broker route refuses it before launch when no broker can carry it (build-launch.mjs,
+  // nativeSigningFileRefusal); a direct host's launch puts the same path back in its own Gradle's environment (`target.env`). No password is in it: only the file's path.
+  const nativeCommand = nativeToolOf(command.cmd) !== null;
+  const { [NATIVE_SIGNING_FILE_ENV]: signingFile, ...dynamicEnv } = env;
+  const commandEnvironment = { ...(await commandEnv(command, root)), ...(nativeCommand ? dynamicEnv : env) };
+  const target = buildLaunch(command.cmd, command.args ?? [], { env: { ...process.env, ...commandEnvironment }, stepEnv: command.env, cwd, exists: existsSync, ...(nativeCommand && signingFile ? { signingFile } : {}) });
   // A direct (Linux) launch carries PATH without RustRight shim directories (build-launch `env`).
   return run(target.command, target.args, cwd, { ...commandEnvironment, ...(target.env ?? {}) }, {
     ...command,

package/rightkit-drift.mjs

@@ -62,14 +62,36 @@ export function rightkitDrift(appRoot, versions = loadRightkitVersions()) {
   return drift;
 }
 
-function run(command, args, cwd) {
-  const result = spawnSync(command, args, { cwd, stdio: "inherit", windowsHide: true, shell: process.platform === "win32" });
+const SHIM_EXE_LINE = /^"([A-Za-z]:\\[^"%\r\n<>|&^!*?]+\.exe)" %\*$/m;
+
+/**
+ * How a command starts (GB-08, BR11/B31). `rustright` on Windows is the managed agent shim `rustright.cmd`, which node cannot start without
+ * a shell (EINVAL; a shell would re-quote the argv): its target .exe is read from the shim and started directly, argv array, no shell.
+ * Anything else keeps the old launch (pnpm on Windows is a .cmd and keeps its shell). A client that cannot be resolved throws before anything runs.
+ */
+export function launchOf(command, args, { platform = process.platform, spawn = spawnSync, readFile = (f) => readFileSync(f, "utf8") } = {}) {
+  if (command !== "rustright") return { command, args, shell: platform === "win32" };
+  if (platform !== "win32") return { command, args, shell: false };
+  const where = spawn("where", ["rustright"], { encoding: "utf8", windowsHide: true, shell: false, timeout: 20_000 });
+  const found = String(where?.stdout ?? "").split(/\r?\n/).map((l) => l.trim()).filter((l) => /^[A-Za-z]:\\/.test(l));
+  const exe = found.find((l) => /\.exe$/i.test(l));
+  if (exe) return { command: exe, args, shell: false };
+  const shim = found.find((l) => /\.(cmd|bat)$/i.test(l));
+  let target = null;
+  if (shim) { try { target = SHIM_EXE_LINE.exec(readFile(shim))?.[1] ?? null; } catch { target = null; } }
+  if (!target) throw new Error("RK_BROKER_CLIENT_UNRESOLVED: the RustRight client (rustright.exe) cannot be resolved from PATH; nothing was started");
+  return { command: target, args, shell: false };
+}
+
+function run(command, args, cwd, { spawn = spawnSync, platform = process.platform, readFile } = {}) {
+  const launch = launchOf(command, args, { platform, spawn, readFile });
+  const result = spawn(launch.command, launch.args, { cwd, stdio: "inherit", windowsHide: true, shell: launch.shell });
   if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed in ${cwd} (exit ${result.status ?? result.error?.message})`);
 }
 
 /** Move drifted pins to the latest version (keeping their = ^ ~ prefix), then refresh lockfiles.
  * Breaking bumps need code changes, so they are adopted only with includeBreaking. */
-export function applyRightkitAdoption(appRoot, versions = loadRightkitVersions(), { refreshLocks = true, includeBreaking = false } = {}) {
+export function applyRightkitAdoption(appRoot, versions = loadRightkitVersions(), { refreshLocks = true, includeBreaking = false, runOptions = {} } = {}) {
   const drift = rightkitDrift(appRoot, versions).filter((item) => includeBreaking || !item.breaking);
   const byFile = Map.groupBy(drift, (item) => item.file);
   for (const [file, items] of byFile) {
@@ -90,8 +112,8 @@ export function applyRightkitAdoption(appRoot, versions = loadRightkitVersions()
   if (refreshLocks) {
     for (const file of byFile.keys()) {
       const dir = path.join(appRoot, path.dirname(file));
-      if (file.endsWith("package.json")) run("pnpm", ["install", "--lockfile-only", "--ignore-scripts"], dir);
-      else run("rustright", ["cargo", "metadata", "--format-version", "1", "--manifest-path", path.join(appRoot, file)], dir);
+      if (file.endsWith("package.json")) run("pnpm", ["install", "--lockfile-only", "--ignore-scripts"], dir, runOptions);
+      else run("rustright", ["cargo", "metadata", "--format-version", "1", "--manifest-path", path.join(appRoot, file)], dir, runOptions);
     }
   }
   return drift;

package/rightkit-versions.json

@@ -32,7 +32,7 @@
     "@rightkit/qa": "0.6.2",
     "@rightkit/qa-chrome": "0.1.12",
     "@rightkit/react-shell": "0.7.2",
-    "@rightkit/release": "0.6.13",
+    "@rightkit/release": "0.6.14",
     "@rightkit/settings-ui": "0.7.0",
     "@rightkit/tauri": "0.3.0",
     "@rightkit/tauri-shell": "0.1.3",
@@ -380,7 +380,8 @@
       "0.6.8",
       "0.6.10",
       "0.6.11",
-      "0.6.12"
+      "0.6.12",
+      "0.6.13"
     ],
     "@rightkit/settings-ui": [
       "0.1.0",
@@ -470,7 +471,7 @@
     "rightkit-crash": "0.3.6",
     "rightkit-credentials": "0.4.2",
     "rightkit-crypto": "0.1.0",
-    "rightkit-daemon": "0.4.0",
+    "rightkit-daemon": "0.5.0",
     "rightkit-db": "0.5.3",
     "rightkit-device": "0.4.0",
     "rightkit-docs": "0.1.3",
@@ -485,7 +486,7 @@
     "rightkit-http": "0.3.9",
     "rightkit-identity": "0.1.0",
     "rightkit-job-queue": "0.5.1",
-    "rightkit-license": "0.2.5",
+    "rightkit-license": "0.2.6",
     "rightkit-llm": "0.3.1",
     "rightkit-logs": "0.3.6",
     "rightkit-mcp": "0.7.1",
@@ -500,7 +501,7 @@
     "rightkit-pdf": "0.3.4",
     "rightkit-platform-rules": "0.1.0",
     "rightkit-playback": "0.3.0",
-    "rightkit-qa": "0.9.2",
+    "rightkit-qa": "0.10.0",
     "rightkit-qa-driver": "0.7.0",
     "rightkit-record": "0.3.3",
     "rightkit-review": "0.4.0",
@@ -508,7 +509,7 @@
     "rightkit-search": "0.4.1",
     "rightkit-send": "0.3.0",
     "rightkit-sidecar": "0.3.0",
-    "rightkit-speech-client": "0.4.0",
+    "rightkit-speech-client": "0.4.1",
     "rightkit-spend": "0.2.0",
     "rightkit-sync": "0.2.2",
     "rightkit-tauri-shell": "0.7.0",
@@ -642,7 +643,7 @@
       "@rightkit/qa": "0.6.1",
       "@rightkit/qa-chrome": "0.1.12",
       "@rightkit/react-shell": "0.7.2",
-      "@rightkit/release": "0.6.12",
+      "@rightkit/release": "0.6.13",
       "@rightkit/settings-ui": "0.7.0",
       "@rightkit/shell": "0.1.1",
       "@rightkit/tauri": "0.3.0",
@@ -891,7 +892,8 @@
       "0.3.2",
       "0.3.4",
       "0.3.5",
-      "0.3.6"
+      "0.3.6",
+      "0.4.0"
     ],
     "rightkit-crash": [
       "0.1.0",
@@ -965,7 +967,8 @@
       "0.2.2",
       "0.2.3",
       "0.2.7",
-      "0.3.0"
+      "0.3.0",
+      "0.4.0"
     ],
     "rightkit-job-queue": [
       "0.3.0",
@@ -1050,7 +1053,8 @@
       "0.2.0",
       "0.2.2",
       "0.2.3",
-      "0.2.4"
+      "0.2.4",
+      "0.2.5"
     ],
     "rightkit-credentials": [
       "0.2.0",

package/rustright-names.mjs

@@ -0,0 +1,32 @@
+// GB-09: the names the gate emits at the RustRight interface. The client reads the current `RUSTRIGHT_*` spellings and, for migration only, the legacy
+// `RIGHTKIT_*` ones (rustright-cli shims.rs LEGACY_ENV_SPELLINGS, removed by RustRight's task L-1; `RUSTRIGHT_LEGACY_ALIASES=off` makes it read none).
+// Every outbound production call carries the current spelling only: a legacy interface name found in a call's environment is translated to its current
+// spelling (the current one wins when both are set) and the legacy name is dropped, so no route depends on an alias the broker may stop reading. Gate-internal
+// RIGHTKIT_* names that are not part of this interface (RIGHTKIT_MANAGED_ROOT, RIGHTKIT_QA_*, ...) are never touched.
+export const LEGACY_INTERFACE_ENV = Object.freeze({
+  RIGHTKIT_BUILD_PRIORITY: "RUSTRIGHT_BUILD_PRIORITY", RIGHTKIT_PARENT_REQUEST_ID: "RUSTRIGHT_PARENT_REQUEST_ID", RIGHTKIT_EXCLUSIVE: "RUSTRIGHT_EXCLUSIVE",
+  RIGHTKIT_CANCEL_ON_DISCONNECT: "RUSTRIGHT_CANCEL_ON_DISCONNECT", RIGHTKIT_CALLING_GATE: "RUSTRIGHT_CALLING_GATE", RIGHTKIT_SNAPSHOT_REQUEST: "RUSTRIGHT_SNAPSHOT_REQUEST",
+  RIGHTKIT_SNAPSHOT_ADMISSION: "RUSTRIGHT_SNAPSHOT_ADMISSION", RIGHTKIT_CHECK_ADMISSION: "RUSTRIGHT_CHECK_ADMISSION", RIGHTKIT_GATE_RUN: "RUSTRIGHT_GATE_RUN",
+  RIGHTKIT_ATTEST_NONCE: "RUSTRIGHT_ATTEST_NONCE", RIGHTKIT_REQUEST_ID_FILE: "RUSTRIGHT_REQUEST_ID_FILE", RIGHTKIT_INPUT_MANIFEST: "RUSTRIGHT_INPUT_MANIFEST",
+  RIGHTKIT_OUTPUT_ROOTS: "RUSTRIGHT_OUTPUT_ROOTS", RIGHTKIT_ADAPTER_ENV: "RUSTRIGHT_ADAPTER_ENV", RIGHTKIT_FORWARD_ENV: "RUSTRIGHT_FORWARD_ENV",
+  RIGHTKIT_PARENT_CAPABILITY_TOKEN: "RUSTRIGHT_PARENT_CAPABILITY_TOKEN", RIGHTKIT_CUTOVER_WAIT_MS: "RUSTRIGHT_CUTOVER_WAIT_MS", RIGHTKIT_RECONNECT_WAIT_MS: "RUSTRIGHT_RECONNECT_WAIT_MS",
+  RIGHTKIT_RUN_ROOT: "RUSTRIGHT_RUN_ROOT", RIGHTKIT_MANAGED_AGENT_SHIM: "RUSTRIGHT_MANAGED_AGENT_SHIM",
+  RIGHTKIT_BUILD_BROKER_SOCKET: "RUSTRIGHT_BUILD_BROKER_SOCKET",
+});
+
+/** The legacy interface names set in `env` (case-insensitive, as Windows environments are). */
+export const legacyInterfaceNamesIn = (env) => Object.keys(env ?? {}).filter((key) => Object.hasOwn(LEGACY_INTERFACE_ENV, key.toUpperCase()));
+
+/** `env` with every legacy interface name translated to the current spelling (the current value wins) and removed; the same object when there is none. */
+export function currentInterfaceEnv(env) {
+  const legacy = legacyInterfaceNamesIn(env);
+  if (legacy.length === 0) return env;
+  const out = { ...env };
+  const present = new Set(Object.keys(out).map((key) => key.toUpperCase()));
+  for (const key of legacy) {
+    const current = LEGACY_INTERFACE_ENV[key.toUpperCase()];
+    if (!present.has(current)) { out[current] = out[key]; present.add(current); }
+    delete out[key];
+  }
+  return out;
+}

package/scan-tool-enrolment.mjs

@@ -0,0 +1,167 @@
+// The gate's own record of the scan tools it trusts on this host (RA-18 / L9-03; the broker-pins.mjs pattern, for analyzers instead of a broker).
+//
+// deterministic-scans.mjs runs shellcheck, actionlint, cargo-deny and cargo-audit only from an ENROLLED executable: an absolute path, the file's
+// sha256 and its version (`options.toolPolicy`, `{ [tool]: { path, sha256, version } }`), never a binary found on PATH. This module is where that
+// policy comes from, and from nowhere else:
+//
+//   record   `<managed data root>/scan-tools/<platform>.json`, `{schema, platform, tools: {<tool>: {path, sha256, version}}, enrolledAt}`,
+//            outside every repository and snapshot, written only by `enrollScanTool` (an explicit operation, one tool per call; a second
+//            enrollment of the same tool is a rotation and says so). At enrol time the file named by `path` must be a regular, executable
+//            file whose sha256 IS the one enrolled: the operator's claim is checked against the bytes, nothing is computed on their behalf.
+//   fallback RightKit's own checkout only: `ci/rk-pipeline.json` `tools.<name>.<platform>`, read from the revision of the RUNNING gate
+//            (`git show <gate repository HEAD>:ci/rk-pipeline.json`, readGateRevisionPipeline), never the checked repository, the selected
+//            commit, the snapshot or the working tree. The enrolled record decides a tool it names; the fallback only fills the tools it does not.
+//
+// Never read here: an environment variable (apart from the managed data root's own location, which the caller resolves), a flag of the run, the
+// checked repository's files, a receipt. A tool with no entry anywhere is not enrolled: deterministic-scans.mjs answers TOOL_UNTRUSTED.
+// Platforms are those whose host may run the gate's class A: darwin, win32 and linux.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readGateRevisionPipeline } from "./broker-pins.mjs";
+import { spawnSync } from "./background-process.mjs";
+
+export const SCAN_TOOLS_SCHEMA = "rightkit.scan-tools/1";
+export const SCAN_TOOLS_DIR = "scan-tools";
+/** The analyzers class A accepts only from an enrolment (deterministic-scans.mjs TRUSTED_SCAN_TOOLS; kept in step by the tests). */
+export const SCAN_TOOL_NAMES = Object.freeze(["actionlint", "shellcheck", "cargo-deny", "cargo-audit"]);
+export const SCAN_TOOL_PLATFORMS = Object.freeze(["darwin", "win32", "linux"]);
+
+export class ScanToolEnrolmentError extends Error {
+  constructor(code, message) { super(message); this.name = "ScanToolEnrolmentError"; this.code = code; }
+}
+const fail = (code, message) => { throw new ScanToolEnrolmentError(code, message); };
+const SHA256 = /^[0-9a-f]{64}$/;
+const isLink = (meta) => meta.isSymbolicLink();
+
+/** The record of one platform under the managed data root. */
+export const scanToolsFile = ({ dataRoot, platform = process.platform }) => {
+  if (!dataRoot || !path.isAbsolute(dataRoot)) fail("RK_SCAN_TOOLS_ROOT", "the managed data root must be an absolute path");
+  if (!SCAN_TOOL_PLATFORMS.includes(platform)) fail("RK_SCAN_TOOLS_PLATFORM", `${platform} is not a scan-tool host (${SCAN_TOOL_PLATFORMS.join(", ")} only)`);
+  return path.join(dataRoot, SCAN_TOOLS_DIR, `${platform}.json`);
+};
+
+/** `{path, sha256, version}` or a throw naming what is wrong: a trusted tool, an absolute path without `..`, a lowercase sha256, a version. */
+export function validateScanTool(tool, entry, { platform = process.platform, label = "the scan-tool enrolment" } = {}) {
+  const bad = (why) => fail("RK_SCAN_TOOLS_INVALID", `${label}: ${tool}: ${why}`);
+  if (!SCAN_TOOL_NAMES.includes(tool)) fail("RK_SCAN_TOOLS_INVALID", `${label}: ${JSON.stringify(tool)} is not a trusted scan tool (${SCAN_TOOL_NAMES.join(", ")})`);
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) bad("not an object");
+  const { path: file, sha256, version } = entry;
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  if (typeof file !== "string" || !paths.isAbsolute(file) || file.split(/[\\/]/).includes("..") || file.includes("\0")) bad("path is not an absolute path without '..'");
+  if (typeof sha256 !== "string" || !SHA256.test(sha256)) bad("sha256 is not a sha256 in lowercase hex");
+  if (typeof version !== "string" || !version.trim() || version !== version.trim()) bad("version is missing");
+  return { path: file, sha256, version };
+}
+
+const digestOf = (file) => {
+  const hash = crypto.createHash("sha256"); const fd = fs.openSync(file, "r");
+  try { const buffer = Buffer.alloc(1 << 20); for (let n = fs.readSync(fd, buffer, 0, buffer.length, null); n > 0; n = fs.readSync(fd, buffer, 0, buffer.length, null)) hash.update(buffer.subarray(0, n)); } finally { fs.closeSync(fd); }
+  return hash.digest("hex");
+};
+
+/** The enrolled record `{ platform, tools, source: "enrolled", file }`, or null when none exists. A link, a non-file, another platform's record, an unknown tool or a malformed entry is a refusal, never null. */
+export function readEnrolledScanTools({ dataRoot, platform = process.platform }) {
+  const file = scanToolsFile({ dataRoot, platform });
+  let meta;
+  try { meta = fs.lstatSync(file); } catch (e) { if (e.code === "ENOENT") return null; throw e; }
+  if (isLink(meta) || !meta.isFile()) fail("RK_SCAN_TOOLS_INVALID", `${file} is not a regular file`);
+  const dir = fs.lstatSync(path.dirname(file));
+  if (isLink(dir) || !dir.isDirectory()) fail("RK_SCAN_TOOLS_INVALID", `${path.dirname(file)} is not a real directory`);
+  if (process.platform !== "win32" && (meta.mode & 0o022 || dir.mode & 0o022)) fail("RK_SCAN_TOOLS_INVALID", `${file} or its directory is writable by group or others`);
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { fail("RK_SCAN_TOOLS_INVALID", `${file} is not JSON (${e.message})`); }
+  if (record?.schema !== SCAN_TOOLS_SCHEMA) fail("RK_SCAN_TOOLS_INVALID", `${file} is not a ${SCAN_TOOLS_SCHEMA} record`);
+  if (record.platform !== platform) fail("RK_SCAN_TOOLS_INVALID", `${file} is the record of ${record.platform}, not ${platform}`);
+  if (record.tools === null || typeof record.tools !== "object" || Array.isArray(record.tools)) fail("RK_SCAN_TOOLS_INVALID", `${file} has no tools object`);
+  const tools = {};
+  for (const [name, entry] of Object.entries(record.tools)) tools[name] = validateScanTool(name, entry, { platform, label: file });
+  return { platform, tools, source: "enrolled", file };
+}
+
+/**
+ * RightKit's own scan-tool pipeline entries, from the revision of the running gate: the `tools` object of `ci/rk-pipeline.json` there (raw: the
+ * caller turns it into a policy with deterministic-scans.mjs scanToolPolicyFromPipeline). Null when the gate is not run from a RightKit checkout
+ * or the file has no `tools`.
+ */
+export function readGateRevisionScanTools({ gateFile, checkout, spawn = spawnSync, realpath }) {
+  const read = readGateRevisionPipeline({ gateFile, checkout, spawn, ...(realpath ? { realpath } : {}) });
+  if (!read || read.pipeline.tools === null || typeof read.pipeline.tools !== "object") return null;
+  return { tools: read.pipeline.tools, revision: read.revision };
+}
+
+/**
+ * The scan-tool policy a gate run hands runScans as `options.toolPolicy`: `{ policy, sources, enrolledFile, revision }` where `policy` is
+ * `{ [tool]: { path, sha256, version } }`, the enrolled tools over the running gate's own revision's, and `sources[tool]` says which decided
+ * (`"enrolled"` | `"rk-pipeline"`). `fromPipeline` is deterministic-scans.mjs scanToolPolicyFromPipeline (passed in so this module adds no
+ * import of the scan engine). An empty policy is a valid answer: each tool no one enrolled is then TOOL_UNTRUSTED where a scan needs it.
+ */
+export function loadScanToolPolicy({ dataRoot, platform = process.platform, gateFile, checkout, spawn, realpath, fromPipeline }) {
+  if (typeof fromPipeline !== "function") fail("RK_SCAN_TOOLS_INVALID", "the pipeline policy reader is required (scanToolPolicyFromPipeline)");
+  // A platform that is not a scan-tool host has no enrolment to read: nothing is trusted there (every analyzer answers TOOL_UNTRUSTED).
+  if (!SCAN_TOOL_PLATFORMS.includes(platform)) return { policy: {}, sources: {} };
+  const enrolled = readEnrolledScanTools({ dataRoot, platform });
+  const fallback = gateFile && checkout ? readGateRevisionScanTools({ gateFile, checkout, spawn, realpath }) : null;
+  const policy = {}; const sources = {};
+  if (fallback) {
+    for (const [name, entry] of Object.entries(fromPipeline(fallback.tools, platform))) { policy[name] = entry; sources[name] = "rk-pipeline"; }
+  }
+  if (enrolled) for (const [name, entry] of Object.entries(enrolled.tools)) { policy[name] = entry; sources[name] = "enrolled"; }
+  return { policy, sources, ...(enrolled ? { enrolledFile: enrolled.file } : {}), ...(fallback ? { revision: fallback.revision } : {}) };
+}
+
+/**
+ * The explicit enrol operation, one tool per call. The file at `path` must exist, be a regular executable file and hash to `sha256` now
+ * (the operator's value is verified, never filled in); the record under the data root gains the tool. An already enrolled tool is replaced
+ * only with `rotate: true`. Returns `{ file, record, rotated }`.
+ */
+export function enrollScanTool({ dataRoot, platform = process.platform, tool, path: toolPath, sha256, version, rotate = false, now = () => new Date() }) {
+  const file = scanToolsFile({ dataRoot, platform });
+  const entry = validateScanTool(tool, { path: toolPath, sha256, version }, { platform, label: "the enrolment" });
+  // The claim is judged against the bytes it names, on the host that enrols (a record for another platform cannot be checked from here).
+  if (platform !== process.platform) fail("RK_SCAN_TOOLS_PLATFORM", `${platform} tools are enrolled on a ${platform} host (this is ${process.platform}): the file's bytes cannot be checked from here`);
+  let real; let meta;
+  try { real = fs.realpathSync.native(entry.path); meta = fs.statSync(real); } catch (e) { fail("RK_SCAN_TOOLS_INVALID", `the ${tool} at ${entry.path} cannot be resolved (${e.code ?? e.message})`); }
+  if (!meta.isFile()) fail("RK_SCAN_TOOLS_INVALID", `the ${tool} at ${real} is not a regular file`);
+  if (platform !== "win32" && (meta.mode & 0o111) === 0) fail("RK_SCAN_TOOLS_INVALID", `the ${tool} at ${real} is not executable`);
+  const actual = digestOf(real);
+  if (actual !== entry.sha256) fail("RK_SCAN_TOOLS_DIGEST", `the ${tool} at ${real} has sha256 ${actual}, not the ${entry.sha256} being enrolled; nothing was written`);
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const dirMeta = fs.lstatSync(dir);
+  if (isLink(dirMeta) || !dirMeta.isDirectory()) fail("RK_SCAN_TOOLS_INVALID", `${dir} is not a real directory`);
+  let existing = null;
+  try { existing = readEnrolledScanTools({ dataRoot, platform }); } catch (e) { if (!rotate) throw e; }
+  const had = existing?.tools[tool] ?? null;
+  if (had && !rotate) fail("RK_SCAN_TOOLS_EXISTS", `${file} already enrolls ${tool} ${had.version} (sha256 ${had.sha256.slice(0, 12)}); replacing it is a rotation (pass rotate: true)`);
+  const record = { schema: SCAN_TOOLS_SCHEMA, platform, tools: { ...(existing?.tools ?? {}), [tool]: entry }, enrolledAt: now().toISOString() };
+  const tmp = `${file}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+  try { fs.renameSync(tmp, file); } finally { fs.rmSync(tmp, { force: true }); }
+  return { file, record, rotated: Boolean(had) };
+}
+
+/** `node scan-tool-enrolment.mjs enroll --platform <darwin|win32|linux> --data-root <dir> --tool <name> --path P --sha256 D --version V [--rotate]` or `show --platform <p> --data-root <dir>`. */
+export function main(argv, { out = (m) => process.stdout.write(`${m}\n`), err = (m) => process.stderr.write(`${m}\n`) } = {}) {
+  const [command, ...rest] = argv;
+  const opt = (name) => { const i = rest.indexOf(name); return i < 0 ? undefined : rest[i + 1]; };
+  try {
+    const dataRoot = opt("--data-root"); const platform = opt("--platform") ?? process.platform;
+    if (command === "enroll") {
+      const r = enrollScanTool({ dataRoot, platform, tool: opt("--tool"), path: opt("--path"), sha256: opt("--sha256"), version: opt("--version"), rotate: rest.includes("--rotate") });
+      const tool = opt("--tool");
+      out(`enrolled ${tool} ${r.record.tools[tool].version} for ${r.record.platform} (sha256 ${r.record.tools[tool].sha256}) in ${r.file}${r.rotated ? " (rotation)" : ""}`);
+      return 0;
+    }
+    if (command === "show") {
+      const enrolled = readEnrolledScanTools({ dataRoot, platform });
+      out(enrolled ? JSON.stringify(enrolled) : "no enrollment");
+      return enrolled ? 0 : 1;
+    }
+    err(`usage: scan-tool-enrolment.mjs enroll|show --platform <darwin|win32|linux> --data-root <dir> [--tool <${SCAN_TOOL_NAMES.join("|")}> --path P --sha256 D --version V [--rotate]]`);
+    return 2;
+  } catch (e) { err(`${e.code ?? "error"}: ${e.message}`); return 1; }
+}
+
+if (process.argv[1] && (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })()) process.exit(main(process.argv.slice(2)));