@rightkit/release 0.6.13 → 0.6.15

package/cargo-shapes.mjs

@@ -0,0 +1,332 @@
+// The ONE versioned command-shape table of the gate's Cargo calls (GB-01, GB-02; audit gate-broker-2026-10-30).
+//
+// RustRight owns the admitted grammar (rustright-policy command_policy.rs `ThinCommandPolicy::classify`, `snapshot_read_only`,
+// `grant_command`, `carried_refusal`, and `normalize_build_request` for the standard aliases). RightKit owns the callers. Both read one
+// vector: docs/contracts/cargo-shapes.fixtures.json of RustRight (schema `rustright.cargo-shapes.fixtures.v1`), copied byte for byte into
+// test-support/vectors/ with its source identity pinned (vectors-source.json). Every row of it is judged here by `classifyCargoArgv`, so
+// the wrapper (cargo-target-shim.mjs), the carried call (snapshot-request.mjs) and the planners (stage-commands.mjs) decide from the same
+// function and cannot drift from the broker: an accepted row reaches the broker's parser, a refused row launches zero processes.
+//
+// `argv` is cargo's argument list without the `cargo` word. Nothing here rewrites a caller's arguments except the five standard aliases at
+// the subcommand position (`b c d r t`), which the broker expands before it classifies (a committed `.cargo/config.toml` `[alias]` can
+// otherwise redefine what was classified). A `fmt` argument is never changed and a plugin restriction is never weakened.
+
+export const COMMAND_SHAPES_SCHEMA = "rightkit.command-shapes/1";
+export const COMMAND_SHAPES_VERSION = 1;
+/** The RustRight vector this table is exercised against (its `schema`); a change of either side is a failing test, not a silent drift. */
+export const COMMAND_SHAPES_VECTOR_SCHEMA = "rustright.cargo-shapes.fixtures.v1";
+
+/** Cargo's standard aliases (rustright cargo_argv.rs CARGO_ALIASES), expanded at the subcommand position before classification. */
+export const CARGO_COMMAND_ALIASES = Object.freeze({ b: "build", c: "check", d: "doc", r: "run", t: "test" });
+export const canonicalCargoCommand = (name) => (typeof name === "string" && Object.hasOwn(CARGO_COMMAND_ALIASES, name) ? CARGO_COMMAND_ALIASES[name] : name);
+
+const VALUE_GLOBALS = new Set(["--manifest-path", "--config", "-C", "-Z", "--color", "--target-dir"]);
+const PLAIN_GLOBALS = new Set(["--locked", "--frozen", "--offline", "--quiet", "-q", "--verbose", "-v"]);
+const VERSION_FLAGS = new Set(["--version", "-V", "-vV"]);
+
+/**
+ * Where the subcommand sits in `argv` (rustright command_policy.rs `command_index`): after an optional `+toolchain` and the global options (the
+ * ones that take a value are skipped with it), before any `--`. `--version`, `-V` and `-vV` are the command. null when there is none.
+ */
+export function cargoCommandIndex(argv) {
+  let i = 0;
+  while (i < argv.length) {
+    const v = argv[i];
+    i += 1;
+    if (v === "--") break;
+    if (v.startsWith("+") && v.length > 1) continue;
+    if (VERSION_FLAGS.has(v)) return i - 1;
+    if (VALUE_GLOBALS.has(v)) { i += 1; continue; }
+    if (PLAIN_GLOBALS.has(v)) continue;
+    if (v.startsWith("--manifest-path=") || v.startsWith("--config=") || v.startsWith("--color=") || v.startsWith("-Z")) continue;
+    if (v.startsWith("-")) continue;
+    return i - 1;
+  }
+  return null;
+}
+
+/**
+ * The cargo subcommand of an argv as sent (an alias stays an alias), read the way Cargo reads it: the broker's reading (`cargoCommandIndex`) plus
+ * Cargo's own `--explain <code>` global, whose value is skipped here (the broker reads that value as the command and refuses it, so this
+ * only ever makes the gate demand MORE evidence, never less). null when there is none.
+ */
+export function cargoSubcommandOf(argv) {
+  const words = [...argv];
+  const end = words.indexOf("--");
+  const own = [];
+  for (let i = 0; i < words.length; i += 1) {
+    if ((end < 0 || i < end) && words[i] === "--explain") { i += 1; continue; }
+    own.push(words[i]);
+  }
+  const i = cargoCommandIndex(own);
+  return i === null ? null : own[i];
+}
+
+/** `argv` with the standard alias at the subcommand position replaced by its canonical command; every other word is kept as sent. */
+export function expandCargoAliases(argv) {
+  const out = [...argv];
+  const i = cargoCommandIndex(out);
+  if (i !== null) out[i] = canonicalCargoCommand(out[i]);
+  return out;
+}
+
+const hasFlag = (argv, flag) => { const end = argv.indexOf("--"); return (end < 0 ? argv : argv.slice(0, end)).includes(flag); };
+const lockPinnedOffline = (argv) => hasFlag(argv, "--frozen") || (hasFlag(argv, "--locked") && hasFlag(argv, "--offline"));
+
+/** Whether a short-flag cluster reaches `-Z` or `-C` (`-Zx`, `-vZx`, `-qvC/dir`); `-j`, `-p`, `-F` take the rest as their value. */
+function shortClusterCarriesZorC(arg) {
+  if (!arg.startsWith("-") || arg.startsWith("--")) return false;
+  for (const c of arg.slice(1)) {
+    if (c === "Z" || c === "C") return true;
+    if (c === "j" || c === "p" || c === "F") return false;
+  }
+  return false;
+}
+function hasConfigOrUnstable(argv) {
+  const end = argv.indexOf("--");
+  return (end < 0 ? argv : argv.slice(0, end)).some((v) => v === "--config" || v.startsWith("--config=") || shortClusterCarriesZorC(v));
+}
+
+// ---- external subcommands the gate sends (only when the host registers them) ----
+
+const DENY_FLAGS = new Set(["--metadata-path", "--config"]);
+/** `deny [--frozen] [--metadata-path <file>] [--config <file>] check`: each option once, spaced, nothing after `check`. Returns the file options or null. */
+function denyCheckFiles(argv) {
+  const index = cargoCommandIndex(argv);
+  if (index === null || argv[index] !== "deny") return null;
+  const files = []; let frozen = false;
+  const rest = argv.slice(index + 1);
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "check") return i === rest.length - 1 ? files : null;
+    if (arg === "--frozen" && !frozen) { frozen = true; continue; }
+    if (DENY_FLAGS.has(arg)) {
+      if (files.some(([seen]) => seen === arg)) return null;
+      const value = rest[i + 1];
+      if (typeof value !== "string" || value === "" || value.startsWith("-")) return null;
+      i += 1; files.push([arg, value]); continue;
+    }
+    return null;
+  }
+  return null;
+}
+/** `audit --db <dir> --no-fetch`, either order, nothing else. Returns the database directory or null. */
+function auditOfflineDb(argv) {
+  const index = cargoCommandIndex(argv);
+  if (index === null || argv[index] !== "audit") return null;
+  let db = null; let noFetch = false;
+  const rest = argv.slice(index + 1);
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--no-fetch" && !noFetch) { noFetch = true; continue; }
+    if (arg === "--db" && db === null) {
+      const value = rest[i + 1];
+      if (typeof value !== "string" || value === "" || value.startsWith("-")) return null;
+      i += 1; db = value; continue;
+    }
+    return null;
+  }
+  return db !== null && noFetch ? db : null;
+}
+/** `about generate --frozen --fail [--config f] [--manifest-path f] [--all-features | --features l] <template>` exactly as the licence notices send it. */
+function aboutNoticesShape(argv) {
+  const index = cargoCommandIndex(argv);
+  if (index === null) return false;
+  const tail = argv.slice(index + 1);
+  if (argv[index] !== "about" || tail.length < 4 || tail[0] !== "generate" || tail[1] !== "--frozen" || tail[2] !== "--fail") return false;
+  const seen = []; let template = false; let features = false;
+  const rest = tail.slice(3);
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--config" || arg === "--manifest-path" || arg === "--features") {
+      const isFeature = arg === "--features";
+      const value = rest[i + 1];
+      if (seen.includes(arg) || (isFeature && features) || typeof value !== "string" || value === "" || value.startsWith("-")) return false;
+      i += 1; features ||= isFeature; seen.push(arg); continue;
+    }
+    if (arg === "--all-features" && !features) { features = true; continue; }
+    if (!arg.startsWith("-") && !template) { template = true; continue; }
+    return false;
+  }
+  return template;
+}
+/** The part of `argv` cargo itself parses: before the subcommand for the deny and about shapes (the rest is the tool's own), all of it otherwise. */
+function cargoOwnArgs(argv) {
+  const index = cargoCommandIndex(argv);
+  return index !== null && (denyCheckFiles(argv) !== null || aboutNoticesShape(argv)) ? argv.slice(0, index) : argv;
+}
+function fmtCheckShape(tail) {
+  if (tail.length === 3 && tail[0] === "-p" && tail[1] !== "" && !tail[1].startsWith("-") && tail[2] === "--check") return true;
+  return tail.length === 2 && tail[0] === "--all" && tail[1] === "--check";
+}
+
+// ---- the package observation (rustright build_rules.rs observation_only_cargo, package arm) ----
+
+const PACKAGE_PLAIN_FLAGS = new Set(["--list", "--locked", "--allow-dirty"]);
+/**
+ * Whether `argv` is the one package form the broker admits as an observation that compiles nothing: no `--`, no `+toolchain`, the subcommand as
+ * the one positional, `-p`/`--package` once with a value that is not a flag (`--package=x` is read, `-p=x` is not), and only `--list`,
+ * `--locked` and `--allow-dirty` besides; it must carry `--list`, `--locked` and one package. Anything else is a compiling package.
+ */
+export function isPackageObservation(argv) {
+  const words = [...argv];
+  if (words.includes("--") || words.some((w) => w.startsWith("+"))) return false;
+  const first = words.find((w) => !w.startsWith("-"));
+  if (first !== "package") return false;
+  let seen = false; let list = false; let locked = false; let packages = 0;
+  for (let i = 0; i < words.length; i += 1) {
+    const w = words[i];
+    if (!w.startsWith("-")) { if (seen || w !== "package") return false; seen = true; continue; }
+    const eq = w.startsWith("--") ? w.indexOf("=") : -1;
+    const name = eq >= 0 ? w.slice(0, eq) : w; const inline = eq >= 0 ? w.slice(eq + 1) : null;
+    if (name === "-p" || name === "--package") {
+      const value = inline ?? words[++i];
+      if (typeof value !== "string" || value === "" || value.startsWith("-")) return false;
+      packages += 1; if (packages > 1) return false;
+      continue;
+    }
+    if (!PACKAGE_PLAIN_FLAGS.has(name) || inline !== null) return false;
+    if (name === "--list") list = true; else if (name === "--locked") locked = true;
+  }
+  return seen && list && locked && packages === 1;
+}
+
+// ---- classification (command_policy.rs cargo_capability) ----
+
+const CONTROL_COMMANDS = new Set(["--version", "-V", "-vV", "version", "help", "locate-project", "read-manifest", "logout", "owner", "yank", "login"]);
+const ANALYSIS_COMMANDS = new Set(["search", "info", "pkgid", "verify-project", "report", "config"]);
+const WORKSPACE_WRITE_COMMANDS = new Set(["new", "init", "update", "vendor", "generate-lockfile", "add", "remove"]);
+/** The built-in commands the broker classifies as compiling (a Capability with `compile: true`): `package` only when it is not the observation. */
+export const BROKER_COMPILE_COMMANDS = Object.freeze(["fix", "run", "package", "publish", "build", "check", "test", "bench", "clippy", "doc", "rustc", "rustdoc"]);
+const CARGO_BUILTINS = new Set(["build", "check", "test", "bench", "clippy", "doc", "run", "install", "rustc", "rustdoc", "clean", "update", "vendor", "generate-lockfile", "add", "remove", "metadata", "tree", "fetch", "fix", "publish", "package", "login", "logout", "owner", "yank", "uninstall", "init", "new", "info", "config", "report", "pkgid", "verify-project", "locate-project", "read-manifest", "search", "help", "version", "fmt", "--version", "-V"]);
+/** External subcommands and their classification once the host registers them (command_policy.rs external_policy). */
+const EXTERNAL = Object.freeze({ about: { compile: false }, outdated: { compile: false }, audit: { compile: false }, deny: { compile: false }, machete: { compile: false }, upgrade: { compile: false }, "set-version": { compile: false }, nextest: { compile: true }, ndk: { compile: true } });
+/** The external subcommands the gate itself sends through the broker: the host registers each (rustright adapter/external registrations). */
+export const GATE_EXTERNAL_COMMANDS = Object.freeze(["deny", "audit", "about", "ndk", "nextest"]);
+
+const MANAGED_TOOL_NAMES = new Set(["cargo", "rustup", "rustc", "rustdoc", "swift", "cmake", "make", "cc", "clang", "gcc", "node", "node-gyp", "pnpm", "npm"]);
+const REDIRECT_LONG = ["--target-dir", "--config", "--cache-dir", "--build-dir", "--toolchain", "--temp-dir", "-Zbuild-std", "-Zconfig"];
+const isRedirectArgument = (a) => REDIRECT_LONG.some((flag) => a === flag || a.startsWith(`${flag}=`));
+const isUnmanagedToolPath = (a) => {
+  const abs = a.startsWith("/") || /^[A-Za-z]:[\\/]/.test(a) || a.startsWith("\\\\");
+  const name = a.split(/[\\/]/).at(-1).toLowerCase().replace(/\.exe$/, "");
+  return abs && MANAGED_TOOL_NAMES.has(name);
+};
+const OWN_FLAG_SUBCOMMANDS = new Set(["about", "outdated", "audit", "deny", "machete"]);
+
+/** rustright request.rs `reject_managed_agent_redirects` for an argv: a redirecting option, a `+toolchain` or an unmanaged tool path before any `--`. */
+function redirectRefused(argv) {
+  const at = argv.findIndex((a) => !a.startsWith("-"));
+  const ownFrom = at >= 0 && OWN_FLAG_SUBCOMMANDS.has(argv[at]) ? at : null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--") break;
+    const cargoFlag = ownFrom === null || i < ownFrom;
+    if ((cargoFlag && isRedirectArgument(argv[i])) || argv[i].startsWith("+") || isUnmanagedToolPath(argv[i])) return true;
+  }
+  return false;
+}
+
+/** The refusal rows: code is the broker's own typed code. */
+const refused = (code, message) => ({ refused: { code, message } });
+
+/**
+ * What the broker's production parser decides for `argv` (cargo's arguments without `cargo`), in rustright's order: normalisation (the standard
+ * aliases, redirect refusals), classification (command, compile) and the carried, grant and carried-refusal predicates.
+ *   - `{ refused: { code, message } }`: the broker answers the typed code and runs zero processes;
+ *   - `{ normalizedArgv, command, compile, carriedReadOnly, grant, carriedRefusal }` (the vector's columns).
+ * `registered` lists the external subcommands the host registers (default none, as in the vector); `deny`, `audit`, `about`, `ndk` and
+ * `nextest` are classified only when registered, as on the broker.
+ */
+export function classifyCargoArgv(argv, { registered = [] } = {}) {
+  const words = [...argv];
+  if (!words.every((w) => typeof w === "string" && w !== "")) return refused("RK_ARGV_INVALID", "Cargo argv must contain non-empty strings");
+  if (redirectRefused(words)) return refused("RK_REDIRECT_REFUSED", "managed agent request cannot redirect cache, build, toolchain, temp, or tool path");
+  const normalizedArgv = expandCargoAliases(words);
+  const index = cargoCommandIndex(normalizedArgv);
+  const command = index === null ? null : normalizedArgv[index];
+  if (command === null) return refused("RK_UNKNOWN_COMMAND", `unregistered managed command: cargo ${normalizedArgv.join(" ")}`.trim());
+  if (command === "install" || command === "uninstall") return refused("RK_COMMAND_DENIED", `agent tool ${command === "install" ? "installation" : "removal"} is denied; managed tools are digest-registered by the operator`);
+  if (command === "clean") return refused("RR_CLEAN_REFUSED", "denied managed command: cargo clean");
+  let compile;
+  if (CONTROL_COMMANDS.has(command) || ANALYSIS_COMMANDS.has(command) || WORKSPACE_WRITE_COMMANDS.has(command) || command === "metadata" || command === "tree" || command === "fetch" || command === "fmt") compile = false;
+  else if (command === "package") compile = !isPackageObservation(normalizedArgv);
+  else if (BROKER_COMPILE_COMMANDS.includes(command)) compile = true;
+  else if (registered.includes(command) && Object.hasOwn(EXTERNAL, command)) compile = EXTERNAL[command].compile;
+  else return refused("RK_UNKNOWN_COMMAND", `unregistered managed command: cargo ${normalizedArgv.join(" ")}`.trim());
+  const carriedRefusalText = hasConfigOrUnstable(cargoOwnArgs(normalizedArgv)) ? "a snapshot-bound request does not carry cargo --config or -Z" : null;
+  return { normalizedArgv, command, compile, carriedReadOnly: snapshotReadOnly(normalizedArgv), grant: grantCommand(normalizedArgv).ok, carriedRefusal: carriedRefusalText !== null, carriedRefusalText };
+}
+
+function offlineReadOnly(argv) {
+  if (hasConfigOrUnstable(cargoOwnArgs(argv))) return false;
+  const index = cargoCommandIndex(argv);
+  if (index === null) return false;
+  switch (canonicalCargoCommand(argv[index])) {
+    case "--version": case "-V": case "version": case "locate-project": case "read-manifest": return true;
+    case "metadata": return hasFlag(argv, "--no-deps") || lockPinnedOffline(argv);
+    case "about": {
+      const end = argv.indexOf("--");
+      const after = argv.slice(index + 1, end < 0 ? undefined : end);
+      const at = after.findIndex((v) => !v.startsWith("-"));
+      return at >= 0 && after[at] === "generate" && lockPinnedOffline(after.slice(at + 1));
+    }
+    default: return false;
+  }
+}
+function classAScan(argv) {
+  if (hasConfigOrUnstable(cargoOwnArgs(argv))) return null;
+  const index = cargoCommandIndex(argv);
+  if (index === null) return null;
+  switch (canonicalCargoCommand(argv[index])) {
+    case "deny": return denyCheckFiles(argv);
+    case "audit": { const db = auditOfflineDb(argv); return db === null ? null : [["--db", db]]; }
+    case "fetch": case "metadata": return hasFlag(argv, "--locked") || hasFlag(argv, "--frozen") ? [] : null;
+    case "fmt": return fmtCheckShape(argv.slice(index + 1)) ? [] : null;
+    case "package": return isPackageObservation(argv) ? [] : null;
+    default: return null;
+  }
+}
+/** What a snapshot-bound (carried) cargo request that compiles nothing may be (command_policy.rs `snapshot_read_only`). */
+export const snapshotReadOnly = (argv) => offlineReadOnly(argv) || classAScan(argv) !== null;
+
+/** What a stage grant's allowlist accepts (command_policy.rs `grant_command`): `{ ok: true }` or `{ ok: false, reason }`. */
+export function grantCommand(argv) {
+  if (hasConfigOrUnstable(argv)) return { ok: false, reason: "a stage grant does not carry cargo --config or -Z" };
+  const index = cargoCommandIndex(argv);
+  if (index === null) return { ok: false, reason: "a stage grant needs a cargo subcommand" };
+  const command = canonicalCargoCommand(argv[index]);
+  if (command === "build" || command === "run") return hasFlag(argv, "--locked") || hasFlag(argv, "--frozen") ? { ok: true } : { ok: false, reason: `a stage grant carries cargo ${argv[index]} only with --locked or --frozen` };
+  if (command === "about") return { ok: false, reason: "a stage grant does not carry cargo about" };
+  if (offlineReadOnly(argv)) return { ok: true };
+  return { ok: false, reason: `a stage grant does not carry cargo ${command} with these arguments` };
+}
+
+/** The version spellings the broker answers uncarried inside a snapshot (command_policy.rs VERSION_ARGUMENTS and `version`), matched as the WHOLE argv. */
+export const VERSION_PROBES = Object.freeze([["-V"], ["--version"], ["-vV"], ["-Vv"], ["--version", "--verbose"], ["-V", "--verbose"], ["-v", "-V"], ["version"]]);
+export const isVersionProbe = (argv) => VERSION_PROBES.some((probe) => probe.length === argv.length && probe.every((w, i) => w === argv[i]));
+
+/**
+ * The decision for a CARRIED call (a snapshot-bound request through the broker): the shape the wrapper, the carried seam and the planners
+ * share. `{ ok: true, argv, compile }` (`argv` with the aliases expanded, the one rewrite) or `{ ok: false, code, message }`, decided
+ * before anything is submitted, so a refused shape launches no process. A carried call must compile or be a carried read-only shape; the
+ * broker refuses everything else (`tree`, `pkgid`, `verify-project`, a bare `metadata`, a `fmt` write form, `help`), so it is never sent.
+ */
+export function carriedShapeDecision(argv, options = {}) {
+  const row = classifyCargoArgv(argv, { registered: GATE_EXTERNAL_COMMANDS, ...options });
+  if (row.refused) return { ok: false, code: row.refused.code, message: `the broker refuses \`cargo ${[...argv].join(" ")}\` (${row.refused.code}: ${row.refused.message}); it is not sent` };
+  if (row.carriedRefusal) return { ok: false, code: "RK_CARGO_BROKER_CARRIED_REFUSED", message: `\`cargo ${[...argv].join(" ")}\`: ${row.carriedRefusalText}; it is not sent` };
+  if (!row.compile && !row.carriedReadOnly) return { ok: false, code: "RK_CARGO_BROKER_READ_ONLY_SHAPE", message: `\`cargo ${[...argv].join(" ")}\` is neither a compile nor a carried read-only shape (metadata --no-deps or --locked/--frozen, fetch --locked, fmt --check, locate-project, read-manifest, deny, audit, package --list); the broker refuses it inside a snapshot, so it is not sent` };
+  return { ok: true, argv: row.normalizedArgv, compile: row.compile };
+}
+
+/**
+ * Whether the broker classifies this argv (cargo's arguments) as a compile: the receipt then carries freshness, attribution and toolchain
+ * evidence (or typed unavailable evidence), and absence is never a success. An argv the broker refuses outright never produces a receipt; if one
+ * is presented anyway it still owes the evidence its compile command names (more evidence is demanded, never less).
+ */
+export function isCompileCommand(argv) {
+  const row = classifyCargoArgv(argv, { registered: GATE_EXTERNAL_COMMANDS });
+  if (!row.refused) return row.compile === true;
+  const sub = canonicalCargoCommand(cargoSubcommandOf(argv));
+  return BROKER_COMPILE_COMMANDS.includes(sub) && !(sub === "package" && isPackageObservation(argv));
+}

package/cargo-target-shim.mjs

@@ -30,9 +30,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "./background-process.mjs";
+import { spawnBrokerClient } from "./broker-client.mjs";
 import { fileURLToPath } from "node:url";
 import { SCAN_TOKEN_ENV, appendLedger } from "./cargo-ledger.mjs";
 import { BROKER_REFUSAL_STATUS, runBrokerCargo } from "./snapshot-broker.mjs";
+import { carriedScanRefusal } from "./snapshot-metadata.mjs";
+import { carriedShapeDecision } from "./cargo-shapes.mjs";
 
 export const SHIM_MAP_SCHEMA = "rightkit.cargo-target-shim/3";
 // Exit status of a refusal: cargo's own error status, so every caller reads it as a failed cargo.
@@ -48,6 +51,16 @@ const PLUGIN = new Set(["deny", "audit"]);
 const BOUND = new Set([...COMPILE, ...LOCKED, ...LOCKFILE]);
 // Commands that read no workspace at all: run unchanged.
 const PASSTHROUGH = new Set(["version", "help"]);
+/** The subcommands the wrapper binds or passes through (the contract test pins each to the broker's classification). */
+export const WRAPPER_COMMANDS = Object.freeze({ get bound() { return [...BOUND]; }, get passthrough() { return [...PASSTHROUGH]; } });
+// Cargo's built-in command aliases. The broker classifies only the full names (command_policy.rs: b, c, t, r, d are RK_UNKNOWN_COMMAND), so a
+// broker-mode call is expanded to the full name BEFORE it is classified and sent (the signed argv digest is over the argv as sent).
+const ALIASES = Object.freeze({ b: "build", c: "check", t: "test", r: "run", d: "doc" });
+// The only requests the broker lets run uncarried inside a snapshot (command_policy.rs uncarried_snapshot_probe: VERSION_ARGUMENTS and `version`).
+const VERSION_PROBES = Object.freeze([["-V"], ["--version"], ["-vV"], ["-Vv"], ["--version", "--verbose"], ["-V", "--verbose"], ["-v", "-V"], ["version"]]);
+// The read-only commands the broker admits to a carried request only in carriedScanRefusal's exact shapes (snapshot-metadata.mjs).
+const CARRIED_SHAPE = new Set(["metadata", "deny", "audit", "fmt"]);
+const insideOf = (child, parent) => { const rel = path.relative(parent, child); return rel === "" || !(rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)); };
 // Global options that take a value (`--color always`, `--explain E0001`); the subcommand is the first word after them.
 const GLOBAL_VALUE = new Set(["--color", "--explain"]);
 // Options that move the working directory, the configuration or the output (a short cluster holding C or Z too).
@@ -76,12 +89,29 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
     sub = w;
     break;
   }
+  const broker = map.mode === "broker";
+  if (broker && sub !== null && Object.hasOwn(ALIASES, sub)) { words[i] = ALIASES[sub]; sub = ALIASES[sub]; }
   const end = sub === null ? -1 : words.indexOf("--", i + 1);
   const own = sub === null ? [] : words.slice(i + 1, end < 0 ? undefined : end);
   const globals = words.slice(toolchain ? 1 : 0, sub === null ? undefined : i);
   if (sub === "fmt" && !own.includes("--check")) return refusal("RK_CARGO_UNBOUND_COMMAND", "`cargo fmt` without --check rewrites tracked files; a snapshot compile changes no file of the commit");
-  if (sub === null || PASSTHROUGH.has(sub)) return { exec: { args: words, env: withCargo({ ...env }) } };
+  if (sub === null || PASSTHROUGH.has(sub)) {
+    // Inside the snapshot the broker runs only a version probe uncarried; `help`, `--list` and anything else would be refused there (and is
+    // never sent as a root request from the snapshot), so the wrapper refuses it first. A snapshot it cannot place is treated as inside.
+    if (broker && !VERSION_PROBES.some((probe) => probe.length === words.length && probe.every((w, k) => w === words[k]))) {
+      let inside = true;
+      try { if (map.broker?.snapshot?.path) inside = insideOf(realpath(cwd), realpath(map.broker.snapshot.path)); } catch { inside = true; }
+      if (inside) return refusal("RK_CARGO_BROKER_UNCARRIED", `\`cargo ${words.join(" ")}\` reads no workspace but is not a version probe; the broker refuses an uncarried call inside the snapshot (only ${VERSION_PROBES.map((p) => p.join(" ")).join(", ")}), so it is never sent`);
+    }
+    return { exec: { args: words, env: withCargo({ ...env }) } };
+  }
   if (!BOUND.has(sub)) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` is not a command a snapshot compile binds (${[...BOUND].join(", ")}; or ${[...PASSTHROUGH].join(", ")}, which read no workspace): an alias, plugin, clean, install, publish or lock rewrite is refused`);
+  // Broker mode: metadata, deny, audit and fmt ride only in the exact shapes the broker admits as carried read-only requests (the one rule,
+  // snapshot-metadata.mjs carriedScanRefusal). Nothing is added to the argv and nothing is dropped: a call of another shape is refused.
+  if (broker && CARRIED_SHAPE.has(sub)) {
+    const shaped = i === 0 ? carriedScanRefusal(words, { checkout: map.broker?.checkout ?? null }) : `a +toolchain or global option before \`${sub}\` is not carried`;
+    if (shaped !== null) return refusal("RK_CARGO_BROKER_READ_ONLY_SHAPE", `\`cargo ${words.join(" ")}\` is not a shape the broker carries (${shaped})`);
+  }
   if (LOCKED.has(sub) && ![...globals, ...own].some((w) => w === "--locked" || w === "--frozen")) return refusal("RK_CARGO_UNBOUND_COMMAND", `\`cargo ${sub}\` without --locked or --frozen may write a Cargo.lock; a snapshot compile changes no file of the commit and writes nothing outside its bound outputs`);
   if (!PLUGIN.has(sub)) for (const w of own) if (REDIRECT.test(w)) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes ${w}, which moves its working directory, configuration or output; a snapshot compile's outputs must be the checkout's`);
   const valueOf = (name) => {
@@ -90,11 +120,16 @@ export function decideCargoInvocation({ args, cwd, env, map, locate, realpath =
     return own[at].includes("=") ? own[at].slice(name.length + 1) : (own[at + 1] ?? "");
   };
   const manifestPath = valueOf("--manifest-path");
-  const broker = map.mode === "broker";
   // The RustRight client submits the call from the working directory and refuses to rewrite it (attestation), and the broker pins the
   // output: a manifest path or a target directory of the caller's has no place in a broker call.
   if (broker && manifestPath !== undefined) return refusal("RK_CARGO_BROKER_MANIFEST_PATH", `\`cargo ${sub}\` passes --manifest-path; a broker call runs from the workspace's own directory (the client refuses to rewrite the invocation), so run it there`);
   if (broker && valueOf("--target-dir") !== undefined) return refusal("RK_CARGO_REDIRECT", `\`cargo ${sub}\` passes --target-dir; the broker pins a snapshot compile's output directory`);
+  // GB-01: in broker mode the one command-shape table (cargo-shapes.mjs) decides what the broker would admit inside a snapshot, before anything is
+  // sent: tree, pkgid and verify-project (no non-writing policy at RustRight), a bare metadata and the other shapes it refuses are refused here, typed.
+  if (broker) {
+    const decision = carriedShapeDecision(words);
+    if (!decision.ok) return refusal(decision.code, decision.message);
+  }
   let workspace;
   try {
     const manifest = locate(manifestPath === undefined ? null : path.resolve(cwd, manifestPath), cwd, toolchain);
@@ -135,7 +170,7 @@ export function installCargoShim({ base, snapshotRoot, targetDirs, broker = null
   const sorted = Object.fromEntries(Object.entries(workspaces).sort(([a], [b]) => (a < b ? -1 : 1)));
   const identityHash = createHash("sha256").update(JSON.stringify({ realCargo: realCargo ?? null, node, workspaces: sorted, ...(broker ? { mode, section: broker.section } : {}) })).update(fs.readFileSync(self));
   // The broker half of the wrapper is part of its identity: any change to the code that carries and verifies a call is another wrapper.
-  if (broker) for (const name of ["snapshot-broker.mjs", "snapshot-request.mjs", "provenance-verify.mjs", "cargo-ledger.mjs"]) identityHash.update(fs.readFileSync(new URL(`./${name}`, import.meta.url)));
+  if (broker) for (const name of ["snapshot-broker.mjs", "snapshot-request.mjs", "snapshot-metadata.mjs", "provenance-verify.mjs", "cargo-ledger.mjs"]) identityHash.update(fs.readFileSync(new URL(`./${name}`, import.meta.url)));
   const identity = identityHash.digest("hex");
   const dir = path.join(base, `rk-cargo-shim-${identity.slice(0, 16)}`);
   const bin = path.join(dir, "bin");
@@ -229,10 +264,14 @@ export function runShim(argv, { env = process.env, cwd = process.cwd(), spawn =
   // A call that reads no workspace (version, help) runs as it is: the real cargo in direct mode, the host's cargo or the client in broker mode.
   const viaClient = broker && !map.realCargo;
   const command = viaClient ? map.broker.client : map.realCargo;
-  const r = spawn(command, viaClient ? ["cargo", ...decision.exec.args] : decision.exec.args, { cwd, env: decision.exec.env, stdio: "inherit" });
+  const spawnOpts = { cwd, env: decision.exec.env, stdio: "inherit" };
+  const r = viaClient ? spawnBrokerClient(spawn, command, ["cargo", ...decision.exec.args], spawnOpts, { platform: map.broker.platform }) : spawn(command, decision.exec.args, spawnOpts);
   if (r.error) return refuse({ code: "RK_CARGO_SHIM_ERROR", message: `${command} did not start (${r.error.message})` });
   record({ ...base, status: "ran", exit: r.status ?? null });
   return r.status ?? (r.signal ? 128 : SHIM_REFUSAL_STATUS);
 }
 
-if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) process.exit(runShim(process.argv.slice(2)));
+// Run as the wrapper only when this file is the entry. Imported by another module (carried-cargo.mjs, through managed-cargo.mjs), the entry
+// may be anything, `node -e` arguments included, so a path that cannot be resolved is no wrapper run.
+const invokedAsWrapper = (() => { try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (invokedAsWrapper) process.exit(runShim(process.argv.slice(2)));

package/cargo-target.mjs

@@ -19,6 +19,7 @@
 // `.rightkit-qa-bin` stash) and run from there.
 import { realpathSync } from "node:fs";
 import { execFileSync } from "./background-process.mjs";
+import { carriedOutputDir } from "./carried-cargo.mjs";
 import { runCargoSync } from "./managed-cargo.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,6 +27,8 @@ import { fileURLToPath } from "node:url";
 export function resolveTargetRoot(manifestPath, options = {}) {
   if (!manifestPath) throw new Error("resolveTargetRoot requires a Cargo.toml manifest path");
   const execute = options.execFileSync ?? execFileSync;
+  // A stage's carrier names the output directory from a signed receipt it already holds (a read-only metadata call is not a snapshot request the broker accepts yet).
+  if (!options.execFileSync) { const receipt = carriedOutputDir(options.env ?? process.env, manifestPath); if (receipt) return path.resolve(receipt); }
   let output;
   try {
     const args = ["metadata", "--offline", "--format-version", "1", "--no-deps", "--manifest-path", manifestPath];
@@ -35,6 +38,8 @@ export function resolveTargetRoot(manifestPath, options = {}) {
       const result = runCargoSync(args, { cwd: path.dirname(manifestPath), encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
       if (result.error) throw result.error;
       if (result.status !== 0) throw new Error(String(result.stderr ?? "").trim() || `exited ${result.status}`);
+      // A carried call (a snapshot stage's, carried-cargo.mjs): the output directory is the signed receipt's, not what the call prints.
+      if (typeof result.outputDir === "string") return path.resolve(result.outputDir);
       output = result.stdout;
     }
   } catch (error) {

package/carried-adapter-run.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// `node carried-adapter-run.mjs <adapter> -- <args>`: one pnpm, node or QA step of a snapshot stage on a broker host, carried
+// (carried-cargo.mjs runCarriedAdapter) from this process's working directory. build-launch.mjs hands such a step to this entry instead of
+// to the RustRight client, so the step is one signed, ledgered adapter request (rustright#190) with its compiles nested under it, the
+// counterpart of carried-cargo-run.mjs for Cargo.
+//
+// The step's own environment arrives in this process's environment: build-launch.mjs sets RUSTRIGHT_ADAPTER_ENV to exactly the names the step
+// declares (adapter-env.mjs adapterEnvLaunch) and those variables' values. runCarriedAdapter reads the same list back (forwardedAdapterEnv),
+// refuses a reserved or unset name with its code (a ledgered refusal, status 101), and binds the forwarded values into the request core the
+// gate recomputes. A step that declares no env has no RUSTRIGHT_ADAPTER_ENV, so the request carries an empty environment.
+//
+// `node carried-adapter-run.mjs --skip-install <pnpm args>` runs nothing: a snapshot stage's dependencies were installed by the gate, so a
+// step that only installs them is skipped with a log line (build-launch.mjs snapshotInstallSkip).
+import { carriedCargoMapOf, runCarriedAdapter } from "./carried-cargo.mjs";
+
+const [first, ...rest] = process.argv.slice(2);
+if (first === "--skip-install") {
+  process.stderr.write(`rightkit-gate: snapshot route: skipped \`pnpm ${rest.join(" ")}\`: the gate already installed this snapshot's dependencies (a stage never installs into the commit's snapshot)\n`);
+  process.exit(0);
+}
+const separator = rest.indexOf("--");
+const adapter = first;
+const args = separator >= 0 ? rest.slice(separator + 1) : [];
+const carried = carriedCargoMapOf(process.env);
+if (!adapter || separator !== 0 || !carried?.map) {
+  process.stderr.write(`rightkit-gate: RK_ADAPTER_CARRIER_MISSING: ${!adapter || separator !== 0 ? "usage: carried-adapter-run.mjs <adapter> -- <args>" : (carried?.error ?? "no carried map in the environment")}; a snapshot stage's step is never sent to the client around its carrier\n`);
+  process.exit(101);
+}
+const result = runCarriedAdapter(adapter, args, { cwd: process.cwd(), env: process.env, stdio: "inherit" }, { map: carried.map });
+if (result.error) process.stderr.write(`rightkit-gate: ${result.error.message}\n`);
+process.exit(result.status ?? 1);

package/carried-cargo-run.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// `node carried-cargo-run.mjs <cargo args>`: one Cargo call of a snapshot stage on a broker host, carried (carried-cargo.mjs) from
+// this process's working directory. build-launch.mjs hands a configured `cargo` or `rustright cargo` step to this entry instead of
+// to the RustRight client, so a config step is carried the same way on every platform (Windows included: no .cmd or shim is involved).
+import { runCargoSync } from "./managed-cargo.mjs";
+
+const result = runCargoSync(process.argv.slice(2), { cwd: process.cwd(), env: process.env, stdio: "inherit", windowsHide: true });
+if (result.error) process.stderr.write(`rightkit-gate: ${result.error.message}\n`);
+process.exit(result.status ?? 1);