@rightkit/release 0.6.16 → 0.6.21

package/swift-lock.mjs

@@ -0,0 +1,334 @@
+// File-only SwiftPM lockfile check (class A scan `swift-lock`; Adrian 2026-11-01: "the build should not be able to proceed if the lockfile
+// isn't a match"). Like `cargo --locked` and `pnpm --frozen-lockfile`, a committed Package.resolved that disagrees with the declared
+// dependencies must fail before any compile. This module reads committed files and executes nothing: Package.swift is code, so SwiftPM is
+// never run; the `.package(...)` declarations are read literally, and a declaration that cannot be read literally is a finding (never a
+// silent pass). It checks the ROOT package's own declarations against the pins: transitive pins and the pins' own consistency with
+// dependency manifests are SwiftPM's (`--disable-automatic-resolution` in the class B swift-build scan).
+import path from "node:path";
+
+// ---- versions -------------------------------------------------------------------------------------------------------------
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(text) {
+  const m = SEMVER.exec(String(text ?? "").trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ? m[4].split(".") : [], text: String(text).trim() };
+}
+const cmpIdent = (a, b) => {
+  const an = /^\d+$/.test(a); const bn = /^\d+$/.test(b);
+  if (an && bn) return Math.sign(Number(a) - Number(b));
+  if (an) return -1;
+  if (bn) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+export function compareVersions(a, b) {
+  for (const k of ["major", "minor", "patch"]) if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
+  if (!a.pre.length && !b.pre.length) return 0;
+  if (!a.pre.length) return 1;
+  if (!b.pre.length) return -1;
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === undefined) return -1;
+    if (b.pre[i] === undefined) return 1;
+    const c = cmpIdent(a.pre[i], b.pre[i]);
+    if (c) return c;
+  }
+  return 0;
+}
+const V = (major, minor, patch) => ({ major, minor, patch, pre: [], text: `${major}.${minor}.${patch}` });
+
+/** Requirement as { type, ... } -> readable text. */
+export function requirementText(r) {
+  switch (r.type) {
+    case "exact": return `exact ${r.version}`;
+    case "from": case "upToNextMajor": return `from ${r.version} (up to next major)`;
+    case "upToNextMinor": return `from ${r.version} (up to next minor)`;
+    case "range": return `${r.lower}${r.closed ? "..." : "..<"}${r.upper}`;
+    case "branch": return `branch ${r.branch}`;
+    case "revision": return `revision ${r.revision}`;
+    default: return JSON.stringify(r);
+  }
+}
+
+/** null when the pin ({ version, branch, revision }) satisfies the requirement, else the reason. */
+export function requirementProblem(req, pin) {
+  const pinned = pin.version ? `version ${pin.version}` : pin.branch ? `branch ${pin.branch}` : pin.revision ? `revision ${pin.revision}` : "no version";
+  if (req.type === "branch") return pin.branch === req.branch ? null : `pins ${pinned}, not branch ${req.branch}`;
+  if (req.type === "revision") return pin.revision && String(pin.revision).toLowerCase() === req.revision.toLowerCase() ? null : `pins ${pinned}, not revision ${req.revision}`;
+  const v = parseVersion(pin.version);
+  if (!v) return `pins ${pinned}, which is not a semantic version`;
+  const lo = (text) => parseVersion(text);
+  switch (req.type) {
+    case "exact": { const want = lo(req.version); return compareVersions(v, want) === 0 ? null : `pins version ${pin.version}, not ${req.version}`; }
+    case "from": case "upToNextMajor": { const a = lo(req.version); return compareVersions(v, a) >= 0 && compareVersions(v, V(a.major + 1, 0, 0)) < 0 ? null : `pins version ${pin.version}, outside ${req.version} up to next major`; }
+    case "upToNextMinor": { const a = lo(req.version); return compareVersions(v, a) >= 0 && compareVersions(v, V(a.major, a.minor + 1, 0)) < 0 ? null : `pins version ${pin.version}, outside ${req.version} up to next minor`; }
+    case "range": {
+      const a = lo(req.lower); const b = lo(req.upper);
+      const upper = compareVersions(v, b);
+      return compareVersions(v, a) >= 0 && (req.closed ? upper <= 0 : upper < 0) ? null : `pins version ${pin.version}, outside ${req.lower}${req.closed ? "..." : "..<"}${req.upper}`;
+    }
+    default: return `has an unknown requirement kind ${req.type}`;
+  }
+}
+
+// ---- locations ------------------------------------------------------------------------------------------------------------
+/** SwiftPM's package identity of a URL or path: its last path component without `.git`, lower-cased. */
+export function identityOf(location) {
+  const parts = String(location).replace(/[\\/]+$/, "").split(/[\\/:]/);
+  return (parts[parts.length - 1] ?? "").replace(/\.git$/i, "").toLowerCase();
+}
+/** A comparable form of a repository location: no scheme, user, `.git`, trailing slash or case; scp form equals URL form. */
+export function normalizeLocation(location) {
+  let t = String(location).trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "").replace(/^[^@/]+@/, "");
+  t = t.replace(/^([^/:]+):(?!\d+\/)/, "$1/").replace(/\/+$/, "").replace(/\.git$/, "").replace(/\/+$/, "");
+  return t;
+}
+
+// ---- Package.swift --------------------------------------------------------------------------------------------------------
+/** The text with comments blanked (newlines kept, offsets unchanged); string literals are left whole. */
+function maskComments(text) {
+  let out = ""; let i = 0;
+  while (i < text.length) {
+    const c = text[i]; const two = text.slice(i, i + 2);
+    if (text.startsWith('"""', i)) { const end = text.indexOf('"""', i + 3); const stop = end < 0 ? text.length : end + 3; out += text.slice(i, stop); i = stop; continue; }
+    if (c === '"') { let j = i + 1; while (j < text.length && text[j] !== '"' && text[j] !== "\n") j += text[j] === "\\" ? 2 : 1; out += text.slice(i, j + 1); i = j + 1; continue; }
+    if (two === "//") { while (i < text.length && text[i] !== "\n") { out += " "; i++; } continue; }
+    if (two === "/*") {
+      let depth = 0;
+      while (i < text.length) {
+        if (text.startsWith("/*", i)) { depth++; out += "  "; i += 2; } else if (text.startsWith("*/", i)) { depth--; out += "  "; i += 2; if (!depth) break; } else { out += text[i] === "\n" ? "\n" : " "; i++; }
+      }
+      continue;
+    }
+    out += c; i++;
+  }
+  return out;
+}
+
+/** Index just past the `)` that closes the `(` at `open`, or -1. Strings are skipped whole. */
+function closeParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') { if (text.startsWith('"""', i)) { const e = text.indexOf('"""', i + 3); if (e < 0) return -1; i = e + 2; continue; } i++; while (i < text.length && text[i] !== '"' && text[i] !== "\n") i += text[i] === "\\" ? 2 : 1; continue; }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") { depth--; if (depth === 0) return i + 1; if (depth < 0) return -1; }
+  }
+  return -1;
+}
+
+function splitArgs(body) {
+  const args = []; let depth = 0; let start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '"') { i++; while (i < body.length && body[i] !== '"') i += body[i] === "\\" ? 2 : 1; continue; }
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "," && depth === 0) { args.push(body.slice(start, i)); start = i + 1; }
+  }
+  const last = body.slice(start);
+  if (last.trim() !== "" || args.length) args.push(last);
+  return args.map((a) => a.trim());
+}
+
+const STR = '"((?:[^"\\\\\\n]|\\\\[^(\\n])*)"';
+const strOf = (expr) => { const m = new RegExp(`^${STR}$`).exec(expr.trim()); return m ? m[1] : null; };
+const RANGE = new RegExp(`^${STR}\\s*(\\.\\.<|\\.\\.\\.)\\s*${STR}$`);
+const FUNC = new RegExp(`^(?:Package\\.Dependency\\.Requirement)?\\.(upToNextMajor|upToNextMinor|exact|branch|revision)\\(\\s*(?:(?:from|_)\\s*:\\s*)?${STR}\\s*\\)$`);
+
+function versionOrNull(s) { return parseVersion(s) ? s : null; }
+
+/** Parse one `.package(...)` argument list: { kind: "remote"|"local", url, path, requirement } or { problem }. */
+function parseDependency(args) {
+  let url = null; let local = null; let requirement = null;
+  const fail = (problem) => ({ problem });
+  for (const arg of args) {
+    const lab = /^([A-Za-z_]\w*)\s*:\s*([\s\S]*)$/.exec(arg);
+    if (lab) {
+      const [, label, expr] = lab;
+      if (label === "name" || label === "traits") continue;
+      if (label === "url") { url = strOf(expr); if (url === null) return fail(`url is not a string literal (${arg.slice(0, 60)})`); continue; }
+      if (label === "path") { local = strOf(expr); if (local === null) return fail(`path is not a string literal (${arg.slice(0, 60)})`); continue; }
+      if (label === "exact" || label === "from") {
+        const v = strOf(expr);
+        if (v === null || !versionOrNull(v)) return fail(`${label}: is not a literal semantic version (${expr.slice(0, 60)})`);
+        if (requirement) return fail("more than one requirement");
+        requirement = label === "exact" ? { type: "exact", version: v } : { type: "from", version: v };
+        continue;
+      }
+      if (label === "branch" || label === "revision") {
+        const v = strOf(expr);
+        if (v === null || v === "") return fail(`${label}: is not a literal string (${expr.slice(0, 60)})`);
+        if (requirement) return fail("more than one requirement");
+        requirement = label === "branch" ? { type: "branch", branch: v } : { type: "revision", revision: v };
+        continue;
+      }
+      return fail(`unsupported argument label ${label}:`);
+    }
+    if (requirement) return fail("more than one requirement");
+    const range = RANGE.exec(arg);
+    if (range) {
+      if (!versionOrNull(range[1]) || !versionOrNull(range[3])) return fail(`range bounds are not literal semantic versions (${arg.slice(0, 60)})`);
+      requirement = { type: "range", lower: range[1], upper: range[3], closed: range[2] === "..." };
+      continue;
+    }
+    const fn = FUNC.exec(arg);
+    if (fn) {
+      const [, kind, v] = fn;
+      if ((kind === "exact" || kind === "upToNextMajor" || kind === "upToNextMinor") && !versionOrNull(v)) return fail(`${kind} is not a literal semantic version (${arg.slice(0, 60)})`);
+      requirement = kind === "branch" ? { type: "branch", branch: v } : kind === "revision" ? { type: "revision", revision: v } : { type: kind, version: v };
+      continue;
+    }
+    return fail(`requirement is not a literal the checker reads (${arg.slice(0, 60)})`);
+  }
+  if (local !== null && url !== null) return fail("declares both url: and path:");
+  if (local !== null) return { kind: "local", path: local };
+  if (url === null) return fail("has no url: or path: (registry or computed dependency)");
+  if (!requirement) return fail("remote dependency has no requirement");
+  return { kind: "remote", url, requirement };
+}
+
+/** { deps: [{ line, kind, url, path, identity, requirement }], problems: [{ line, text }] } from Package.swift source, read literally. */
+export function parsePackageSwift(source) {
+  const text = maskComments(String(source));
+  const deps = []; const problems = [];
+  const lineAt = (idx) => text.slice(0, idx).split("\n").length;
+  // Lines inside an `#if` ... `#endif` region cannot be evaluated without Swift's compiler conditions.
+  const conditional = new Set(); let depth = 0;
+  text.split("\n").forEach((l, i) => {
+    const t = l.trim();
+    if (/^#if\b/.test(t)) depth++;
+    if (depth > 0) conditional.add(i + 1);
+    if (/^#endif\b/.test(t)) depth = Math.max(0, depth - 1);
+  });
+  const re = /\.package\s*\(/g; let m;
+  while ((m = re.exec(text))) {
+    const open = m.index + m[0].length - 1;
+    const line = lineAt(m.index);
+    const end = closeParen(text, open);
+    if (end < 0) { problems.push({ line, text: "unbalanced .package( declaration" }); break; }
+    const parsed = parseDependency(splitArgs(text.slice(open + 1, end - 1)));
+    re.lastIndex = end;
+    if (parsed.problem) { problems.push({ line, text: `.package declaration cannot be read literally: ${parsed.problem}` }); continue; }
+    if (conditional.has(line)) { problems.push({ line, text: `.package declaration is inside an #if region, which cannot be evaluated literally (${parsed.kind === "remote" ? parsed.url : parsed.path})` }); continue; }
+    deps.push({ line, ...parsed, identity: identityOf(parsed.kind === "remote" ? parsed.url : parsed.path) });
+  }
+  return { deps, problems };
+}
+
+// ---- Package.resolved -----------------------------------------------------------------------------------------------------
+/** { pins: [{ identity, location, version, branch, revision }], problems: [text] } for Package.resolved versions 1, 2 and 3. */
+export function parseResolved(source) {
+  let doc;
+  try { doc = JSON.parse(String(source).replace(/^/, "")); } catch (e) { return { pins: [], problems: [`not valid JSON: ${e.message}`] }; }
+  const v = doc?.version;
+  let raw;
+  if (v === 1) raw = doc?.object?.pins;
+  else if (v === 2 || v === 3) raw = doc?.pins;
+  else return { pins: [], problems: [`unsupported Package.resolved version ${JSON.stringify(v)} (the checker reads 1, 2 and 3)`] };
+  if (!Array.isArray(raw)) return { pins: [], problems: [`Package.resolved version ${v} has no pins array`] };
+  const pins = [];
+  for (const p of raw) {
+    const location = v === 1 ? p?.repositoryURL : p?.location;
+    if (typeof location !== "string") return { pins: [], problems: [`a Package.resolved version ${v} pin has no ${v === 1 ? "repositoryURL" : "location"}`] };
+    const state = p.state ?? {};
+    pins.push({ identity: identityOf(location), location, version: state.version ?? null, branch: state.branch ?? null, revision: state.revision ?? null });
+  }
+  return { pins, problems: [] };
+}
+
+/** Findings for the declared remote dependencies against the pins. `label(dep)` prefixes each finding with its file (and line). */
+function matchPins(deps, pins, { label, resolvedFile }) {
+  const out = [];
+  for (const d of deps) {
+    const named = pins.filter((p) => p.identity === d.identity);
+    const where = `${label(d)}: package ${d.identity} requires ${requirementText(d.requirement)}`;
+    if (!named.length) { out.push(`${where} but ${resolvedFile} has no pin for it`); continue; }
+    const pin = named.find((p) => normalizeLocation(p.location) === normalizeLocation(d.url));
+    if (!pin) { out.push(`${where} from ${d.url} but ${resolvedFile} pins ${named.map((p) => p.location).join(", ")}`); continue; }
+    const why = requirementProblem(d.requirement, pin);
+    if (why) out.push(`${where} but ${resolvedFile} ${why}`);
+  }
+  return out;
+}
+
+const join = (dir, f) => (dir === "" || dir === "." ? f : `${dir}/${f}`);
+const tryRead = (read, exists, file) => (exists(file) ? { text: read(file) } : null);
+
+/** Findings for the Swift package at `dir` (repo-relative, "." for the root). `read`/`exists` take repo-relative paths. */
+export function packageLockProblems({ dir, read, exists }) {
+  const manifest = join(dir, "Package.swift"); const resolvedFile = join(dir, "Package.resolved");
+  const src = tryRead(read, exists, manifest);
+  if (!src) return [];
+  const { deps, problems } = parsePackageSwift(src.text);
+  const out = problems.map((p) => `${manifest}:${p.line}: ${p.text}`);
+  const remote = deps.filter((d) => d.kind === "remote");
+  const resolved = tryRead(read, exists, resolvedFile);
+  if (!resolved) {
+    if (remote.length) out.push(`${manifest}: ${remote.length} remote ${remote.length === 1 ? "dependency" : "dependencies"} (${remote.map((d) => d.identity).join(", ")}) and no ${resolvedFile}; commit the lockfile`);
+    return out;
+  }
+  const parsed = parseResolved(resolved.text);
+  if (parsed.problems.length) return [...out, ...parsed.problems.map((p) => `${resolvedFile}: ${p}`)];
+  out.push(...matchPins(remote, parsed.pins, { label: (d) => `${manifest}:${d.line}`, resolvedFile }));
+  return out;
+}
+
+// ---- Xcode projects -------------------------------------------------------------------------------------------------------
+const unquote = (v) => { const t = v.trim(); return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1).replace(/\\"/g, '"') : t; };
+const field = (block, name) => { const m = new RegExp(`(?:^|[\\s;{])${name}\\s*=\\s*("(?:[^"\\\\]|\\\\.)*"|[^;\\s]+)\\s*;`).exec(block); return m ? unquote(m[1]) : null; };
+
+/** { deps, problems } for the XCRemoteSwiftPackageReference objects of a project.pbxproj. */
+export function parsePbxproj(source) {
+  const text = String(source); const deps = []; const problems = [];
+  const re = /isa\s*=\s*XCRemoteSwiftPackageReference\s*;/g; let m;
+  while ((m = re.exec(text))) {
+    const line = text.slice(0, m.index).split("\n").length;
+    const open = text.lastIndexOf("{", m.index);
+    let depth = 0; let end = -1;
+    for (let i = open; i < text.length; i++) { if (text[i] === "{") depth++; else if (text[i] === "}") { depth--; if (depth === 0) { end = i; break; } } }
+    if (open < 0 || end < 0) { problems.push({ line, text: "unbalanced XCRemoteSwiftPackageReference object" }); continue; }
+    const block = text.slice(open + 1, end);
+    const url = field(block, "repositoryURL");
+    const reqOpen = block.search(/requirement\s*=\s*\{/);
+    if (!url || reqOpen < 0) { problems.push({ line, text: "XCRemoteSwiftPackageReference has no repositoryURL or requirement the checker reads" }); continue; }
+    const req = block.slice(block.indexOf("{", reqOpen) + 1, block.indexOf("}", reqOpen));
+    const kind = field(req, "kind");
+    let requirement = null;
+    if (kind === "exactVersion") { const v = field(req, "version"); if (v && parseVersion(v)) requirement = { type: "exact", version: v }; }
+    else if (kind === "upToNextMajorVersion") { const v = field(req, "minimumVersion"); if (v && parseVersion(v)) requirement = { type: "upToNextMajor", version: v }; }
+    else if (kind === "upToNextMinorVersion") { const v = field(req, "minimumVersion"); if (v && parseVersion(v)) requirement = { type: "upToNextMinor", version: v }; }
+    else if (kind === "versionRange") { const a = field(req, "minimumVersion"); const b = field(req, "maximumVersion"); if (a && b && parseVersion(a) && parseVersion(b)) requirement = { type: "range", lower: a, upper: b, closed: false }; }
+    else if (kind === "branch") { const b = field(req, "branch"); if (b) requirement = { type: "branch", branch: b }; }
+    else if (kind === "revision") { const r = field(req, "revision"); if (r) requirement = { type: "revision", revision: r }; }
+    if (!requirement) { problems.push({ line, text: `requirement of ${url} cannot be read literally (kind ${kind ?? "missing"})` }); continue; }
+    deps.push({ line, kind: "remote", url, identity: identityOf(url), requirement });
+  }
+  return { deps, problems };
+}
+
+/** Findings for one `<name>.xcodeproj` directory (repo-relative). */
+export function xcodeProjectLockProblems({ project, read, exists }) {
+  const pbx = `${project}/project.pbxproj`;
+  const resolvedFile = `${project}/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`;
+  const src = tryRead(read, exists, pbx);
+  if (!src) return [];
+  const { deps, problems } = parsePbxproj(src.text);
+  const out = problems.map((p) => `${pbx}:${p.line}: ${p.text}`);
+  const resolved = tryRead(read, exists, resolvedFile);
+  if (!resolved) {
+    if (deps.length) out.push(`${pbx}: ${deps.length} remote Swift ${deps.length === 1 ? "package" : "packages"} (${deps.map((d) => d.identity).join(", ")}) and no ${resolvedFile}; commit the lockfile`);
+    return out;
+  }
+  const parsed = parseResolved(resolved.text);
+  if (parsed.problems.length) return [...out, ...parsed.problems.map((p) => `${resolvedFile}: ${p}`)];
+  out.push(...matchPins(deps, parsed.pins, { label: (d) => `${pbx}:${d.line}`, resolvedFile }));
+  return out;
+}
+
+/** The scan's repository-relative lock owners for a changed file: a Swift package directory or an `.xcodeproj` directory. */
+export function lockOwnerOf(file, { exists, ancestorDirs }) {
+  const parts = file.split("/");
+  const xi = parts.findIndex((p) => p.endsWith(".xcodeproj"));
+  if (xi >= 0) return { kind: "xcode", dir: parts.slice(0, xi + 1).join("/") };
+  const owner = ancestorDirs(path.posix.dirname(file)).reverse().find((d) => exists(join(d, "Package.swift")));
+  return owner === undefined ? null : { kind: "package", dir: owner === "" ? "." : owner };
+}

package/test-command.mjs

@@ -30,6 +30,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawn } from "./background-process.mjs";
 import { carriedCargoMapOf, carriedLedgerIds, carriedOutputDirsSince } from "./carried-cargo.mjs";
+import { GATE_TARGET_DIRS_ENV } from "./qa-layout.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
 import { defaultReleaseConfigFile } from "./release-config.mjs";
 import { fsListRustFiles } from "./signing-files.mjs";
@@ -167,6 +168,11 @@ export function planTests(config, { suites = [], runner, passthrough = [], appRo
 }
 
 /** The refusal code of a planned `rightkit-qa journeys run` suite (GB-79). */
+/** RIGHTKIT_GATE_TARGET_DIRS: the absolute directories the gate pinned; none when unset or malformed. */
+function directOutputDirs(env) {
+  try { const dirs = JSON.parse(env[GATE_TARGET_DIRS_ENV] ?? "[]"); return Array.isArray(dirs) ? dirs.filter((d) => typeof d === "string" && path.isAbsolute(d)) : []; } catch { return []; }
+}
+
 export const QA_JOURNEYS_UNSUPPORTED = "RK_QA_JOURNEYS_PREBUILT_UNSUPPORTED";
 /** True when a suite step is `rightkit-qa journeys run ...` (by command or by node script name, extra args included). */
 export function qaJourneysRunStep(step, extraArgs = []) {
@@ -187,8 +193,10 @@ export function eventPrefix(config) {
  * Resolves `{ exitCode, results: [{ suite, exitCode, durationMs, skipped?, reason?, error? }] }`; a signal (cancellation) rejects.
  * A `sign` step (suite-signing.mjs) runs IN THIS PROCESS, never through `door` (it is no command and never a broker job); it signs what an earlier
  * suite built, named by that suite's verified carried receipts, and only a success sets RIGHTKIT_QA_APP_BINARY for the suites after it.
+ * On a direct host (no carrier) a suite's outputs are the Cargo output directories the gate pinned for the stage (RIGHTKIT_GATE_TARGET_DIRS).
+ * `within({ outputs, env })`, when given, runs once every suite passed and before the signed copies are removed; its result is returned as `within`.
  */
-export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log, errLog = console.error, door = buildLaunch, config = null, platform = process.platform, signDeps = {}, signStep = runSignStep, snapshotStage = Boolean(carriedCargoMapOf(env)?.map), qaCapability = (qa) => qaPrebuiltCapability(qa, { env }) } = {}) {
+export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log, errLog = console.error, door = buildLaunch, config = null, platform = process.platform, signDeps = {}, signStep = runSignStep, within = null, snapshotStage = Boolean(carriedCargoMapOf(env)?.map), qaCapability = (qa) => qaPrebuiltCapability(qa, { env }) } = {}) {
   const results = [];
   // One signing policy, enforced here whatever the config's format (the route probe reads JSON configs only; a legacy .mjs config is judged now): an
   // unsigned or ad hoc product build, or an identifier override, is refused before any suite runs (rightkit#1303). Mac and Dell only.
@@ -294,14 +302,16 @@ export async function runSuites(plan, { appRoot, prefix = "test", env = process.
       const durationMs = Date.now() - started;
       // Only a suite that passed hands its receipts to a sign step.
       if (exitCode === 0) {
-        const dirs = carriedOutputDirsSince(env, before);
+        const dirs = carriedCargoMapOf(env)?.map ? carriedOutputDirsSince(env, before) : directOutputDirs(env);
         for (const key of new Set([item.name, item.group])) outputs.set(key, [...new Set([...(outputs.get(key) ?? []), ...dirs])]);
       }
       log(JSON.stringify({ event: `${prefix}_suite_completed`, suite: item.name, exitCode, durationMs }));
       results.push({ suite: item.name, exitCode, durationMs, ...(failure ? { error: String(failure.message ?? failure) } : {}) });
       record(item, exitCode === 0 ? "passed" : "failed");
     }
-    return { exitCode: results.some((r) => r.skipped !== true && r.exitCode !== 0) || results.some((r) => r.skipped) ? firstFailure() : 0, results };
+    const exitCode = results.some((r) => r.skipped !== true && r.exitCode !== 0) || results.some((r) => r.skipped) ? firstFailure() : 0;
+    if (exitCode !== 0 || !within) return { exitCode, results };
+    return { exitCode, results, within: await within({ outputs, env: suiteEnv }) };
   } finally {
     // The signed copies live only as long as the run that signed them.
     for (const dir of signedDirs) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* the managed root is pruned */ } }

package/tool-build.mjs

@@ -0,0 +1,156 @@
+// The gate's tool route: `rightkit-gate --to tool --unit cargo:rightkit-qa [--no-broker <exception-id>]`.
+//
+// Release QA runs only an ENROLLED rightkit-qa runner of the exact version an app's `qa.version` names (qa-runner.mjs). The unit stages cannot
+// make that binary: `--to compile|package --unit cargo:rightkit-qa` runs the unit's test plan and packs a .crate, and refuses a version that is
+// already on crates.io (local-publish.mjs); `cargo install` is denied (cargo-shapes.mjs). This route is the one sanctioned way to produce it:
+//
+//   1. the unit's class A check (the compile tier), exactly as a unit stage runs it;
+//   2. `cargo build --release --locked --bin <bin>` in the unit's own Cargo workspace of the selected commit's snapshot, through the same executor,
+//      cargo wrapper or carrier and target-directory binding as every other unit compile (unit-gate.mjs / bindUnitCargo). There is NO registry-version
+//      check: a tool build of a published version is the point of it, and it publishes nothing;
+//   3. the produced binary is enrolled (qa-runner.mjs `enrollQaRunner`): version = the crate's COMMITTED version, answered by the binary's own
+//      `--version`, a COPY recorded with its sha256 under the managed data root. The enrolled path and sha256 are printed so the owner can add the
+//      admission-policy entry (`right-release qa policy approve-runner`). Admission itself is unchanged and stays the owner's.
+//
+// `cargo:rightkit-credentials` takes the same route and is enrolled as the managed OS credential provider (credential-provider.mjs) that updater signing runs.
+// Only units named in TOOL_UNITS have this route. The route never uploads, signs or publishes, and it enrols only on a Mac or Windows host (the platforms
+// a runner is enrolled for: its bytes are executed here to read their version).
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { endRun, startRun } from "./gate-stages.mjs";
+import { runCargoSync } from "./managed-cargo.mjs";
+import { resolveManagedRoots } from "./managed-roots.mjs";
+import { CredentialProviderError, enrollCredentialProvider } from "./credential-provider.mjs";
+import { QaRunnerError, enrollQaRunner } from "./qa-runner.mjs";
+import { knownRedEntry, resolveUnit } from "./unit-gate.mjs";
+
+export const TOOL_STAGE = "tool";
+export const TOOL_REPORT_SCHEMA = "rightkit.tool-build-report/1";
+/** The units that have a tool route: the crate, the binary its manifest declares, and what the binary is enrolled as. */
+export const TOOL_UNITS = Object.freeze({
+  "cargo:rightkit-qa": Object.freeze({ crate: "rightkit-qa", bin: "rightkit-qa", enrols: "qa-runner" }),
+  "cargo:rightkit-credentials": Object.freeze({ crate: "rightkit-credentials", bin: "rightkit-credentials", enrols: "credential-provider" }),
+});
+const HOST_PLATFORM = Object.freeze({ darwin: "mac", win32: "win" });
+const BUILD_TIMEOUT_MS = 30 * 60 * 1000;
+
+export class ToolBuildError extends Error {
+  constructor(code, message) { super(`${code}: ${message}`); this.name = "ToolBuildError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new ToolBuildError(code, message); };
+
+/** The cargo arguments of the build (no `cargo`): the one shape the broker admits as a compile and a stage grant carries (cargo-shapes.mjs). */
+export const toolBuildArgs = (bin) => ["build", "--release", "--locked", "--bin", bin];
+
+/**
+ * What `--to tool --unit <selector>` builds on `platform` (a `process.platform` value), decided before ownership, a snapshot or any process:
+ * `{ selector, crate, bin, enrols, cargoDir, argv, executable, runnerPlatform }`, or a typed ToolBuildError.
+ */
+export function toolPlan({ selector, platform }) {
+  const unit = Object.hasOwn(TOOL_UNITS, selector ?? "") ? TOOL_UNITS[selector] : null;
+  if (!unit) refuse("RK_TOOL_UNIT_UNSUPPORTED", `${JSON.stringify(selector ?? null)} has no tool route (${Object.keys(TOOL_UNITS).join(", ")}); \`--to tool\` builds only a unit named there`);
+  const runnerPlatform = HOST_PLATFORM[platform];
+  if (!runnerPlatform) refuse("RK_TOOL_HOST", `a ${unit.bin} runner is built and enrolled on a Mac or a Windows host (this is ${platform}): its bytes are executed there to read their version, and a runner is enrolled per platform`);
+  return { selector, ...unit, cargoDir: `crates/${unit.crate}`, argv: toolBuildArgs(unit.bin), executable: runnerPlatform === "win" ? `${unit.bin}.exe` : unit.bin, runnerPlatform };
+}
+
+/** The pinned target directory of the Cargo workspace that holds `cargoDir`: its own entry, else the nearest enclosing one (a crate that is a member of a parent workspace). Null when none is pinned. */
+export function pinnedTargetDir(targetDirs, cargoDir) {
+  for (let dir = cargoDir; ; dir = path.posix.dirname(dir)) {
+    if (typeof targetDirs?.[dir] === "string" && targetDirs[dir]) return targetDirs[dir];
+    if (dir === "." || dir === "/" || dir === "") return null;
+  }
+}
+
+const sha256OfFile = (file) => crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+/**
+ * The built binary under `outputDir` (the target directory: the carried receipt's `outputDir` on a broker host, the checkout's pinned target on a direct
+ * one): `<outputDir>/release/<executable>`, a regular file the build just wrote, never a link. Returns its path or throws.
+ */
+export function builtToolBinary({ outputDir, executable }) {
+  if (typeof outputDir !== "string" || !path.isAbsolute(outputDir)) refuse("RK_TOOL_NO_OUTPUT_DIR", `the build reported no absolute output directory (${JSON.stringify(outputDir ?? null)}); the produced binary cannot be located, so nothing was enrolled`);
+  const file = path.join(outputDir, "release", executable);
+  let meta;
+  try { meta = fs.lstatSync(file); } catch (error) { refuse("RK_TOOL_NO_BINARY", `the build succeeded but ${file} does not exist (${error.code ?? error.message}); nothing was enrolled`); }
+  if (meta.isSymbolicLink() || !meta.isFile()) refuse("RK_TOOL_NO_BINARY", `${file} is not a regular file; nothing was enrolled`);
+  return file;
+}
+
+/**
+ * Runs the tool route for one unit of the selected commit's snapshot. `root` is the snapshot, `commonDir` the checkout's git directory. `check(tier)`
+ * is the door's class A run and `stageGuard` its ledger verify around each stage (as runUnitGate takes them); `envExtra` is the Cargo binding
+ * (bindUnitCargo's env) and `targetDirs` its `{ [cargoDir]: checkout target directory }` for a direct host. Everything a test replaces is a parameter:
+ * `run` (the cargo call: managed-cargo's runCargoSync, which carries it through the broker or runs it direct), `enroll`, `resolve`, `dataRoot`.
+ * Returns the exit code (0, or 1 with the reason printed).
+ */
+export async function runUnitTool({
+  selector, root, commonDir, commit, tree, executor, env, platform, check, source = null, stageGuard = null, envExtra = {}, targetDirs = {},
+  resolve = resolveUnit, run = runCargoSync, enroll = enrollQaRunner, enrollProvider = enrollCredentialProvider, dataRoot = undefined, readKnownRed = null,
+  out = console.log, err = console.error, writeReport = null,
+}) {
+  let plan; let unit;
+  try {
+    plan = toolPlan({ selector, platform });
+    unit = resolve(selector, root);
+    const red = knownRedEntry({ unit, root, platform, ...(readKnownRed ? { readText: readKnownRed } : {}) });
+    if (red) refuse("RK_TOOL_KNOWN_RED", `${selector} is listed in ci/known-red.json for ${red.host} (${red.key}: ${red.reason}); a known-red unit is not built. Fix the defect and remove the entry first`);
+  } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
+  const report = { schema: TOOL_REPORT_SCHEMA, unit, commit, tree, executor: executor?.kind ?? null, stages: {} };
+  const save = () => { if (writeReport) writeReport(report); };
+  let stage = "check";
+  try {
+    if (stageGuard && !(await stageGuard.start("check"))) throw new Error("RK_CHECK_ERROR: the snapshot is not the commit's bytes plus the ledger before the check stage");
+    if (await check("compile") !== 0) throw new Error("class A check (compile tier) failed");
+    if (stageGuard && !(await stageGuard.end("check"))) throw new Error("RK_CHECK_ERROR: the check stage's result covers no known bytes");
+    report.stages.check = { ok: true }; save();
+    out(`rightkit-gate: [check] ${selector} passed`);
+
+    stage = TOOL_STAGE;
+    if (stageGuard && !(await stageGuard.start(TOOL_STAGE))) throw new Error(`RK_CHECK_ERROR: the snapshot is not the commit's bytes plus the ledger before the ${TOOL_STAGE} stage`);
+    const doorRun = startRun({ commonDir, commit, tree, stage: TOOL_STAGE });
+    let built;
+    try {
+      const childEnv = { ...env, ...envExtra, ...doorRun.env };
+      const cwd = path.join(root, ...plan.cargoDir.split("/"));
+      out(`rightkit-gate: [tool] ${selector}@${unit.version}: cargo ${plan.argv.join(" ")} (from ${plan.cargoDir}; executor ${executor?.kind ?? "?"})`);
+      const result = await run(plan.argv, { cwd, env: childEnv, encoding: "utf8", maxBuffer: 512 * 1024 * 1024, timeout: BUILD_TIMEOUT_MS, windowsHide: true });
+      if (result?.error || result?.status !== 0) {
+        throw new Error(`${selector}: cargo ${plan.argv.join(" ")} failed (${result?.error?.message ?? `exit ${result?.status}`})\nstdout:\n${String(result?.stdout ?? "").slice(-4000)}\nstderr:\n${String(result?.stderr ?? "").slice(-4000)}`);
+      }
+      // A carried (broker) call names the receipt's output directory; a direct call wrote the checkout target the gate pinned for this workspace.
+      built = builtToolBinary({ outputDir: result.outputDir ?? pinnedTargetDir(targetDirs, plan.cargoDir), executable: plan.executable });
+    } finally { endRun(doorRun); }
+    if (stageGuard && !(await stageGuard.end(TOOL_STAGE))) throw new Error(`RK_CHECK_ERROR: the ${TOOL_STAGE} stage's result covers no known bytes (a snapshot byte changed, a write is outside the ledger, or a cargo call did not complete)`);
+    const builtSha256 = sha256OfFile(built);
+    report.stages.tool = { ok: true, binary: built, binarySha256: builtSha256, version: unit.version }; save();
+    out(`rightkit-gate: [tool] built ${built} (sha256 ${builtSha256})`);
+
+    stage = "enrol";
+    let enrolled;
+    try {
+      const root_ = dataRoot ?? resolveManagedRoots({ env }).dataRoot;
+      enrolled = plan.enrols === "credential-provider"
+        ? enrollProvider({ dataRoot: root_, platform: plan.runnerPlatform, binary: built, version: unit.version })
+        : enroll({ dataRoot: root_, platform: plan.runnerPlatform, runner: built, version: unit.version });
+    } catch (error) {
+      if (error instanceof CredentialProviderError || error?.code?.startsWith?.("RK_CRED_PROVIDER_")) throw new Error(`${error.code}: ${error.message}\nthe built binary is ${built} (sha256 ${builtSha256}); a deliberate replacement of an enrolled version is \`node packages/release/credential-provider.mjs enroll --binary ${built} --version ${unit.version} --platform ${plan.runnerPlatform} --rotate\``);
+      if (error instanceof QaRunnerError || error?.code?.startsWith?.("RK_QA_RUNNER_")) throw new Error(`${error.code}: ${error.message}\nthe built binary is ${built} (sha256 ${builtSha256}); a deliberate replacement of an enrolled version is \`right-release qa runner enroll --runner ${built} --version ${unit.version} --platform ${plan.runnerPlatform} --rotate\``);
+      throw error;
+    }
+    // The copy that was recorded must be the very bytes that were built: a binary swapped between the digest and the copy is refused.
+    if (enrolled.entry.sha256 !== builtSha256) throw new Error(`RK_TOOL_DIGEST_DRIFT: the enrolled copy ${enrolled.runnerFile} has sha256 ${enrolled.entry.sha256}, the build produced ${builtSha256}; the binary changed while it was enrolled, so it is not trusted (enrol it again from a fresh build)`);
+    report.stages.enrol = { ok: true, runner: enrolled.runnerFile, sha256: enrolled.entry.sha256, version: enrolled.entry.version, platform: plan.runnerPlatform, record: enrolled.file, rotated: enrolled.rotated };
+    save();
+    out(`rightkit-gate: [tool] enrolled ${plan.bin} ${enrolled.entry.version} for ${plan.runnerPlatform}: ${enrolled.runnerFile} sha256 ${enrolled.entry.sha256} (record ${enrolled.file})`);
+    if (plan.enrols === "credential-provider") out("rightkit-gate: [tool] updater signing and the admission check resolve this enrolled provider (credential-provider.mjs); PATH is not used on a Mac or Windows host");
+    else out(`rightkit-gate: [tool] the owner admits it with: right-release qa policy approve-runner --runner ${enrolled.runnerFile} --version ${enrolled.entry.version} --platform ${plan.runnerPlatform} --set-by <name>`);
+    out(`rightkit-gate: [tool] ${selector} passed`);
+    return 0;
+  } catch (error) {
+    report.stages[stage] = { ok: false }; save();
+    err(`rightkit-gate: tool ${selector} stopped at ${stage}: ${error.message}`);
+    return 1;
+  }
+}

package/unit-gate.mjs

@@ -69,7 +69,12 @@ export function writeQualification({ report, artifact, unit, commit, tree, runti
     if (!/^[0-9a-f]{64}$/.test(artifact.contentSha256 ?? "")) throw new Error("release needs the qualified npm archive's content digest");
     content.contentSha256 = artifact.contentSha256;
     const excluded = exclusionsFor(unit.name);
-    if (excluded.length) {
+    if (excluded.length && executor?.kind === "direct") {
+      // A Linux direct origin neither builds nor signs the swap helper (publish.yml's build-swap/sign-swap do, hosted): its archive holds neither
+      // entry, and says so. The Mac rule below is unchanged.
+      if (!Array.isArray(artifact.contentExcluded) || artifact.contentExcluded.length) throw new Error(`a direct origin's ${unit.name} archive must hold neither ${excluded.join(" nor ")}`);
+      content.contentExcluded = [];
+    } else if (excluded.length) {
       if (!Array.isArray(artifact.contentExcluded) || [...artifact.contentExcluded].sort().join("\n") !== [...excluded].sort().join("\n")) throw new Error(`release needs the qualified ${unit.name} archive to hold ${excluded.join(" and ")}`);
       content.contentExcluded = [...artifact.contentExcluded].sort();
     }
@@ -348,6 +353,8 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
   }
   // GB-29: a Linux origin has no managed volume; its scratch is the gate's own state directory (XDG state), never a Mac path.
   const scratch = platform === "win32" ? "D:\\scratch" : platform === "linux" ? path.join(env.XDG_STATE_HOME || path.join(env.HOME || "/tmp", ".local", "state"), "rightkit", "scratch") : "/Volumes/D/scratch";
+  // The Linux scratch is a gate-owned state directory that may not exist yet; the bundle itself is still created fresh (non-recursive) by the publisher.
+  if (platform === "linux") fs.mkdirSync(scratch, { recursive: true, mode: 0o700 });
   const bundle = path.join(scratch, `rk-unit-${randomBytes(12).toString("hex")}`);
   const argv = ["--local", unit.kind === "npm" ? "--package" : "--crate", unit.name, "--workspace", root, "--qualify-only", "--bundle", bundle];
   const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
@@ -428,7 +435,7 @@ export async function runUnitGate({ selector, to, root, commonDir, commit, tree,
           // GB-29: the direct-origin qualification is written and verified exactly as the hosted side will. Dispatching it needs the publish workflow's `direct` admission input, which is the
           // reserved publication authorization (GC-T22): nothing is dispatched from a direct host until that input exists.
           const written = directQualification();
-          throw new Error(`RK_DIRECT_RELEASE_HELD: the direct-origin qualification ${written} was written and verified; the committed publish workflow admits \`broker\` only, and adding \`direct\` is the reserved publication authorization (GATE-CONTRACT GC-T22, GC-L01), so nothing was dispatched`);
+          throw new Error(`RK_DIRECT_RELEASE_HELD: the direct-origin qualification ${written} was written and verified; a direct host has no broker dispatch adapter, so dispatch publish.yml from main with admission=direct and this file as the qualification input (rightkit#1341); nothing was dispatched from here`);
         }
         requireBrokerHost(executor); // a direct host has no broker receipts to carry: refuse for that reason, not for the missing receipts
         const qualification = writeQualification({ report, artifact, unit, commit, tree, runtime, executor });