@rightkit/release 0.6.8 → 0.6.10

package/stage-commands.mjs

@@ -0,0 +1,60 @@
+// What a unit's compile and package broker jobs must have run, derived from the code that builds those commands (local-publish.mjs
+// localTestPlan and the pack argv builders), so the gate (which chooses the receipts to carry) and the hosted admission (which checks
+// the signed requestedArgv of each) share one definition and cannot drift from the stages. EVERY command of a stage must be covered by
+// a signed receipt of its own job; a missing command is a refusal that names it.
+import path from "node:path";
+import { CARGO_METADATA_ARGS, cargoPackageArgs, localTestPlan, npmPackArgs, qualifyFmtArgs } from "./local-publish.mjs";
+import { SWAP_HELPER_CARGO_ARGS, SWAP_HELPER_PACKAGE } from "./swap-helper-bundle.mjs";
+
+/** Stands for the one argument that is a fresh absolute scratch path (`pnpm pack --pack-destination <mkdtemp>`). */
+export const ANY_ABSOLUTE_PATH = Object.freeze({ anyAbsolutePath: true });
+const PNPM = (...argvs) => ({ kind: "adapter", adapter: "rightkit-pnpm", argvs });
+const CARGO = (...argvs) => ({ kind: "cargo", argvs });
+
+/** Readable name of an expected command (scratch paths shown as <scratch>). */
+export const describeCommand = (row) => `${row.kind === "adapter" ? "pnpm" : "cargo"} ${row.argvs[0].map((a) => (typeof a === "string" ? a : "<scratch>")).join(" ")}`;
+
+/**
+ * The commands of the compile and package stages of one unit, one { kind, adapter?, argvs } row per job the stage launches
+ * (`argvs` are the accepted spellings of that one command: cargo metadata retries without --offline). Inputs are what the dispatched
+ * commit holds: `config` = ci/gate.config.json, `manifest` = the npm package's package.json.
+ */
+export function expectedStageCommands({ kind, unit, config, manifest, platform }) {
+  const dir = kind === "npm" ? `packages/${unit.slice("@rightkit/".length)}` : `crates/${unit}`;
+  const plan = localTestPlan({ kind, unit, dir, config, manifest, batch: false, platform });
+  const compile = plan.steps.map((step) => (step.command === "pnpm" ? PNPM(step.args) : CARGO(step.args)));
+  const pack = [];
+  if (kind === "npm") {
+    if (unit === SWAP_HELPER_PACKAGE) {
+      // The swap helper builds and signs a binary, then packs from a scratch copy of its directory.
+      pack.push(CARGO(SWAP_HELPER_CARGO_ARGS), CARGO(["metadata", "--format-version", "1", "--no-deps"]), PNPM(npmPackArgs(ANY_ABSOLUTE_PATH, ANY_ABSOLUTE_PATH)));
+    } else pack.push(PNPM(npmPackArgs(dir, ANY_ABSOLUTE_PATH)));
+  } else {
+    compile.unshift(CARGO(qualifyFmtArgs(unit)));
+    pack.push(CARGO(cargoPackageArgs(unit, true)), CARGO([...CARGO_METADATA_ARGS], CARGO_METADATA_ARGS.filter((arg) => arg !== "--offline")));
+  }
+  return { compile, package: pack };
+}
+
+const argvMatches = (expected, actual) => Array.isArray(actual) && expected.length === actual.length
+  && expected.every((want, i) => (want === ANY_ABSOLUTE_PATH ? typeof actual[i] === "string" && (path.posix.isAbsolute(actual[i]) || /^[A-Za-z]:[\\/]/.test(actual[i])) : want === actual[i]));
+
+/** Whether a signed payload's request is this command: request.kind, adapter (when any) and requestedArgv. */
+export function requestIs(payload, row) {
+  const request = payload?.request;
+  return Boolean(request && typeof request === "object" && request.kind === row.kind && (row.adapter === undefined || request.adapter === row.adapter) && row.argvs.some((argv) => argvMatches(argv, request.requestedArgv)));
+}
+
+/**
+ * Assigns each job (`{ id, payload }`) to a distinct command of the stage. Returns { assigned: Map(id -> row), unmatched: [id...],
+ * missing: [row...] }: a job that is none of the commands is unmatched; a command no job covers is missing.
+ */
+export function assignJobs(rows, jobs) {
+  const free = rows.map((row) => ({ row, taken: false }));
+  const assigned = new Map(), unmatched = [];
+  for (const job of jobs) {
+    const slot = free.find((s) => !s.taken && requestIs(job.payload, s.row));
+    if (slot) { slot.taken = true; assigned.set(job.id, slot.row); } else unmatched.push(job.id);
+  }
+  return { assigned, unmatched, missing: free.filter((s) => !s.taken).map((s) => s.row) };
+}

package/stage-sidecar.mjs

@@ -38,7 +38,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync as nodeSpawnSync } from "./background-process.mjs";
 import { resolveCommand } from "./development.mjs";
-import { managedHost } from "./managed-cargo.mjs";
+import { directPlatform, managedHost } from "./managed-cargo.mjs";
 import { APPROVAL_MACHO_STRIP_LINKEDIT_V1, APPROVAL_RAW_SHA256, approvalDigest } from "./macho-approval-hash.mjs";
 import {
   bundledFileName, planMediaSidecar, sourceOfferText, stagedFileName, validateMediaSidecarConfig, verifyStagedSidecars, writeMediaSidecarNotices,
@@ -111,7 +111,7 @@ const KEYS = Object.freeze({
   "native-library": ["kind", "library", "version", "catalog", "resourceDir", "licenseDir", "cacheDir", "as", "files", "companions", "source", "platforms"],
   resource: ["kind", "from", "to", "sha256", "machO", "clean", "platforms"],
   command: ["kind", "name", "cmd", "args", "cwd", "output", "externalBin", "dest", "clean", "platforms"],
-  remote: ["kind", "name", "url", "sha256", "dest", "to", "size", "extract", "memberSha256", "executable", "clean", "platforms"],
+  remote: ["kind", "name", "url", "sha256", "dest", "to", "size", "extract", "extractKind", "memberSha256", "executable", "clean", "platforms"],
   cmake: ["kind", "name", "repo", "commit", "target", "output", "cmakeArgs", "platformArgs", "generator", "platformGenerators", "architecture", "cmakeBin", "smoke", "sha256", "dest", "clean", "platforms"],
   prebuilt: ["kind", "name", "from", "manifest", "dest", "platforms"],
 });
@@ -476,10 +476,15 @@ export function validateSidecarManifest(raw, { target, mode = "release" } = {})
       if (item.size !== undefined && (!Number.isSafeInteger(item.size) || item.size <= 0)) errors.push(`${where}: size must be a positive integer (bytes)`);
       if (item.extract !== undefined) { const member = normalizeArchiveMember(item.extract); if (member.error || (!member.byPath && !NAME.test(member.value))) errors.push(`${where}: extract must be the bare file name of one archive member or its archive path (posix, no leading /, no .. segment): ${member.error ?? "invalid file name"}`); }
       if (item.memberSha256 !== undefined && (item.extract === undefined || !SHA256.test(item.memberSha256 ?? ""))) errors.push(`${where}: memberSha256 must be a lowercase 64-hex SHA-256 and needs extract`);
+      if (item.extractKind !== undefined && item.extractKind !== "nsis") errors.push(`${where}: extractKind must be "nsis" (omit it for tar-readable zip/tgz/nupkg archives)`);
+      if (item.extractKind === "nsis") {
+        if (item.extract === undefined) errors.push(`${where}: extractKind "nsis" needs extract (the installer member path, e.g. bin/smartctl.exe)`);
+        if (typeof item.memberSha256 !== "string" || !SHA256.test(item.memberSha256)) errors.push(`${where}: extractKind "nsis" requires memberSha256 (the extracted member's lowercase 64-hex SHA-256); an NSIS member is never staged unpinned`);
+      }
       if (item.executable !== undefined && typeof item.executable !== "boolean") errors.push(`${where}: executable must be a boolean`);
       const clean = cleanOf();
       if (dest && !skipped) claim(dest, where);
-      Object.assign(entry, { name, url: item.url, sha256: item.sha256, dest, ...(item.size ? { size: item.size } : {}), ...(item.extract ? { extract: item.extract } : {}), ...(item.memberSha256 ? { memberSha256: item.memberSha256 } : {}), ...(item.executable ? { executable: true } : {}), ...(clean ? { clean } : {}) });
+      Object.assign(entry, { name, url: item.url, sha256: item.sha256, dest, ...(item.extractKind ? { extractKind: item.extractKind } : {}), ...(item.size ? { size: item.size } : {}), ...(item.extract ? { extract: item.extract } : {}), ...(item.memberSha256 ? { memberSha256: item.memberSha256 } : {}), ...(item.executable ? { executable: true } : {}), ...(clean ? { clean } : {}) });
     } else if (item.kind === "cmake") {
       const name = item.name;
       if (typeof name !== "string" || !NAME.test(name) || /\.exe$/i.test(name) || name !== path.basename(name)) errors.push(`${where}: name must be a bare sidecar name (no path, no .exe, no target triple)`);
@@ -611,6 +616,45 @@ export function defaultExtractMember({ archive, fileName, destDir, run = default
   return out;
 }
 
+/** 7-Zip candidates: an explicit path (deps.sevenZip or RIGHTKIT_SEVEN_ZIP), then `7z` on PATH, then 7z.exe under Program Files on win32. */
+export function sevenZipCandidates({ explicit, env = process.env, platform = process.platform } = {}) {
+  const list = [];
+  if (explicit) list.push(explicit);
+  else if (env.RIGHTKIT_SEVEN_ZIP) list.push(env.RIGHTKIT_SEVEN_ZIP);
+  list.push("7z");
+  if (platform === "win32") for (const base of [env.ProgramFiles ?? "C:\\Program Files", env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)"]) list.push(path.win32.join(base, "7-Zip", "7z.exe"));
+  return [...new Set(list)];
+}
+
+/**
+ * Extract one member of an NSIS installer with 7-Zip (`x -y -o<dir> <installer> <member>`; nothing in the installer is run), then
+ * require its SHA-256 to equal the pinned one. Fails closed, naming the installer digest, member, expected and actual digests, on a
+ * missing tool, a failed extraction, a missing member or any mismatch. Returns the extracted file path under destDir.
+ */
+export function defaultExtractNsisMember({ archive, fileName, destDir, expectedSha256, installerSha256, run = defaultRun, sevenZip, env = process.env, platform = process.platform, readFile = nodeFs.readFileSync, exists = nodeFs.existsSync }) {
+  const wanted = normalizeArchiveMember(fileName);
+  const who = `NSIS installer ${installerSha256 ?? archive} member ${JSON.stringify(fileName)}`;
+  if (wanted.error) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who} ${wanted.error}`);
+  if (!SHA256.test(expectedSha256 ?? "")) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who}: a pinned member sha256 is required`);
+  let tool;
+  let lastError = "not found";
+  for (const candidate of sevenZipCandidates({ explicit: sevenZip, env, platform })) {
+    const result = run(candidate, ["x", "-y", `-o${destDir}`, archive, wanted.value], { cwd: path.dirname(archive) });
+    if (result.error || result.status === null || result.status === undefined) { lastError = result.error?.message ?? "could not start"; continue; }
+    tool = candidate;
+    if (result.status !== 0) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who}: ${candidate} exited ${result.status}; nothing staged`);
+    break;
+  }
+  if (!tool) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who}: 7-Zip is required and was not found (${lastError}); install 7-Zip or set RIGHTKIT_SEVEN_ZIP; nothing staged`);
+  const out = path.join(destDir, ...wanted.value.split("/"));
+  const inside = path.relative(path.resolve(destDir), path.resolve(out));
+  if (!inside || inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside)) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who} resolves outside the extraction directory`);
+  if (!exists(out)) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${who}: member not found after extraction; nothing staged`);
+  const actual = sha256Of(readFile(out));
+  if (actual !== expectedSha256) fail("STAGE_SIDECAR_HASH_MISMATCH", `${who}: sha256 is ${actual}, expected ${expectedSha256}; nothing staged`, { expected: expectedSha256, actual });
+  return out;
+}
+
 async function defaultFetchBytes(url) {
   if (!url.startsWith("https://")) fail("STAGE_SIDECAR_CONFIG_INVALID", `refusing a non-https archive URL: ${url}`);
   const response = await fetch(url);
@@ -1453,7 +1497,9 @@ async function stageRemote(entry, ctx) {
     let memberSha256;
     if (entry.extract) {
       scratch = ctx.makeTempDir();
-      source = await ctx.extractMember({ archive: cached, fileName: entry.extract, destDir: scratch });
+      source = entry.extractKind === "nsis"
+        ? await ctx.extractNsisMember({ archive: cached, fileName: entry.extract, destDir: scratch, expectedSha256: entry.memberSha256, installerSha256: entry.sha256 })
+        : await ctx.extractMember({ archive: cached, fileName: entry.extract, destDir: scratch });
       memberSha256 = sha256Of(fs.readFileSync(source));
       if (entry.memberSha256 && memberSha256 !== entry.memberSha256) fail("STAGE_SIDECAR_HASH_MISMATCH", `${entry.extract} from ${entry.url} is ${memberSha256}, expected ${entry.memberSha256}; nothing staged`, { expected: entry.memberSha256, actual: memberSha256 });
     }
@@ -1462,7 +1508,7 @@ async function stageRemote(entry, ctx) {
     const copied = copyInto(ctx, source, dest, { executable: entry.executable === true });
     const expected = entry.extract ? entry.memberSha256 : entry.sha256;
     if (expected && copied.sha256 !== expected) fail("STAGE_SIDECAR_HASH_MISMATCH", `staged ${entry.dest} is ${copied.sha256}, expected ${expected}`, { expected, actual: copied.sha256 });
-    return [{ kind: "remote", name: entry.name, path: rel(ctx, dest), ...copied, sourceSha256: memberSha256 ?? entry.sha256, url: entry.url, cached: fromCache, externalBin: false, ...(entry.extract ? { archiveSha256: entry.sha256, member: entry.extract } : {}) }];
+    return [{ kind: "remote", name: entry.name, path: rel(ctx, dest), ...copied, sourceSha256: memberSha256 ?? entry.sha256, url: entry.url, cached: fromCache, externalBin: false, ...(entry.extract ? { archiveSha256: entry.sha256, member: entry.extract, memberSha256 } : {}), ...(entry.extractKind ? { extractKind: entry.extractKind } : {}) }];
   } finally {
     if (scratch) ctx.removeDir(scratch);
   }
@@ -1687,10 +1733,13 @@ function wipeStaleStageDir(ctx, plan, produced) {
  * call can reuse (acquireManagedRunLease records a per-process lease file; no RK_* variable carries it to a child), so
  * the only safe behaviour is to refuse early. RIGHTKIT_STAGE_SIDECAR_ALLOW_NESTED=1 opts out.
  */
-export function isNestedBrokerContext(env = process.env) {
+export function isNestedBrokerContext(env = process.env, platform = process.platform) {
+  // A direct (Linux) host has no broker, so no outer broker build to nest in, whatever flag or socket the env carries (heavy-command sets
+  // RIGHTSUITE_HEAVY_WORK_OWNER on every platform).
+  if (directPlatform(platform)) return false;
   if (env?.RIGHTKIT_STAGE_SIDECAR_ALLOW_NESTED === "1") return false;
   const insideTauri = Boolean(env?.TAURI_ENV_PLATFORM || env?.TAURI_ENV_TARGET_TRIPLE);
-  return insideTauri && (managedHost(env ?? {}) || env?.RIGHTSUITE_HEAVY_WORK_OWNER === "1");
+  return insideTauri && (managedHost(env ?? {}, platform) || env?.RIGHTSUITE_HEAVY_WORK_OWNER === "1");
 }
 
 /** True when staging would call `rustright cargo` for a non-skipped entry. */
@@ -1754,6 +1803,7 @@ export async function stageSidecars({ appRoot, manifest, target, deps = {} } = {
     fetchBytes: deps.fetchBytes ?? defaultFetchBytes,
     fetch: deps.fetch ?? ((...args) => globalThis.fetch(...args)),
     extractMember: deps.extractMember ?? ((args) => defaultExtractMember({ ...args, run })),
+    extractNsisMember: deps.extractNsisMember ?? ((args) => defaultExtractNsisMember({ ...args, run, env, sevenZip: deps.sevenZip, readFile: fs.readFileSync, exists: fs.existsSync })),
     loadMediaCatalog: deps.loadMediaCatalog ?? (() => undefined),
     loadNativeCatalog: deps.loadNativeCatalog ?? (() => undefined),
     makeTempDir: deps.makeTempDir ?? (() => nodeFs.mkdtempSync(path.join(os.tmpdir(), "rightkit-stage-"))),

package/test-command.mjs

@@ -21,7 +21,8 @@
 // from the app root. `--suite journeys` selects every chunk of that group. `--runner vitest -- run --project unit` runs
 // the runner once with the arguments after `--` (the watch or one-off case); `-- <args>` after `--suite` is allowed when
 // exactly one suite is selected. Exit code: 0 when every selected suite passed, else the failing suite's exit code.
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { buildLaunch } from "./build-launch.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawn } from "./background-process.mjs";
@@ -39,10 +40,11 @@ export function parseTestArgs(argv) {
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--") { opts.passthrough = argv.slice(i + 1); break; }
-    if (arg === "--config" || arg === "--suite" || arg === "--runner") {
+    if (arg === "--config" || arg === "--suite" || arg === "--runner" || arg === "--platform") {
       const value = argv[i + 1];
       if (!value || value.startsWith("--")) throw new Error(`${arg} needs a value`);
       if (arg === "--suite") opts.suites.push(...value.split(",").filter(Boolean));
+      else if (arg === "--platform") opts.platform = value;
       else opts[arg.slice(2)] = value;
       i += 1;
     } else if (arg === "--list") opts.list = true;
@@ -147,14 +149,16 @@ export function eventPrefix(config) {
  * Run the planned suites in order; stop at the first non-zero exit. `spawnFn` and `log` are injectable.
  * Resolves `{ exitCode, results: [{ suite, exitCode, durationMs }] }`; a spawn error or a signal rejects.
  */
-export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log } = {}) {
+export async function runSuites(plan, { appRoot, prefix = "test", env = process.env, spawnFn = spawn, log = console.log, door = buildLaunch } = {}) {
   const results = [];
   for (const item of plan) {
     const invocation = resolveInvocation(item.step, { appRoot, baseEnv: env, extraArgs: item.extraArgs });
     log(JSON.stringify({ event: `${prefix}_suite_started`, suite: item.name }));
     const started = Date.now();
     const exitCode = await new Promise((resolve, reject) => {
-      const child = spawnFn(invocation.cmd, invocation.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
+      // A test suite goes through the one door (build-launch.mjs): a broker job on a managed host, which builds it under the app's claim.
+      const target = door(invocation.cmd, invocation.args, { env: invocation.env, cwd: invocation.cwd, exists: existsSync });
+      const child = spawnFn(target.command, target.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
       child.once("error", reject);
       child.once("exit", (code, signal) => {
         if (signal) reject(new Error(`${item.name} stopped by ${signal}`));
@@ -172,6 +176,15 @@ export async function runSuites(plan, { appRoot, prefix = "test", env = process.
 export async function main(argv = process.argv.slice(2)) {
   const opts = parseTestArgs(argv);
   const { config, appRoot } = await loadAppConfig(opts.config);
+  // `--platform ios`: the app's declared XCUITest journeys (development.targets.ios.uiTests) on its dev device or simulator.
+  if (opts.platform !== undefined) {
+    if (opts.platform !== "ios") throw new Error(`--platform ${opts.platform}: only ios has platform UI test journeys; other suites are declared in tests.suites`);
+    if (opts.suites.length || opts.runner || opts.passthrough.length) throw new Error("--platform ios runs the declared journeys; it takes no --suite, --runner or arguments");
+    const { runDevelopment } = await import("./development.mjs");
+    const result = runDevelopment({ root: appRoot, platform: "ios", config, uiTests: true, dryRun: opts.list });
+    if (opts.list) console.log(JSON.stringify(result.plan ?? result, null, 2));
+    return 0;
+  }
   const plan = planTests(config, { suites: opts.suites, runner: opts.runner, passthrough: opts.passthrough, appRoot });
   if (opts.list) {
     const view = plan.map((item) => ({ suite: item.name, ...resolveInvocation(item.step, { appRoot, baseEnv: {}, extraArgs: item.extraArgs }), env: undefined }));

package/unit-gate.mjs

@@ -0,0 +1,259 @@
+// RightKit's own units use the same door, but never reuse mutable unit receipts as evidence.
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { localBuildGranted } from "./execution-policy.mjs";
+import { readCargoPackage } from "./crate-graph.mjs";
+import { spawnSync as nodeSpawnSync } from "./background-process.mjs";
+import { endRun, startRun, stagesTo } from "./gate-stages.mjs";
+import { qualificationNonce } from "./provenance-verify.mjs";
+import { assignJobs, describeCommand, expectedStageCommands } from "./stage-commands.mjs";
+
+const GH = process.platform === "win32" ? "C:\\Program Files\\GitHub CLI\\gh.exe" : "/opt/homebrew/bin/gh";
+const defaultRun = (cmd, args, options = {}) => nodeSpawnSync(cmd, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, ...options });
+const defaultReadJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+/**
+ * The gate-owned release of one RightKit unit. Runs only on a broker-managed host and only after this process's check, compile,
+ * package and qualify stages: (1) the unit's local pre-flight through the broker (rk-pipeline preflight: the compile rows the dispatch
+ * adapter admits), (2) the broker-admitted dispatch of publish.yml (rk-pipeline dispatch -> rustright run rightkit-dispatch; the
+ * broker's request id is the run's correlation token), (3) rk-pipeline watch --wait: the exact run (sha, attempt, event, workflow,
+ * token), then its publish-direct upload run, then the registry, (4) the upload run's publication receipt (the sealed bytes the
+ * registry serves: published && registryVerified) read back against the registry itself. A queued dispatch, a missing upload run,
+ * an ambiguous receipt or differing registry bytes is a failure; nothing is retried or re-dispatched here (reconcile rk-pipeline's
+ * state by hand). The local bundle's digest is reported beside the hosted one, never equated with it.
+ */
+export const QUALIFICATION_SCHEMA = "rightkit.unit-qualification/1";
+/** The stages whose broker jobs the hosted admission authenticates (their signed receipts ride in the qualification), and how many
+ * receipts one stage may carry (every command of the stage needs its own; the dispatch input is capped at 65535 characters in all and
+ * each signed envelope is ~3 KB, which writeQualification checks). */
+export const ATTESTED_STAGES = ["compile", "package"];
+export const MAX_STAGE_RECEIPTS = 64;
+const MAX_QUALIFICATION_BYTES = 58_000;
+
+/** `rustright status <id>`: the broker's own record of one job, reduced to what a verifier needs (id + signed envelope). A job the
+ * broker cannot report, or one without a signed envelope, fails the stage: an unauthenticated qualification is worth nothing. */
+/** The commands each stage must have run for this unit, from the same builders the stages use, over the checkout's own config. */
+export function defaultStageCommands({ unit, root, platform, readJson = defaultReadJson }) {
+  const manifest = unit.kind === "npm" ? readJson(path.join(root, "packages", unit.name.slice("@rightkit/".length), "package.json")) : undefined;
+  return expectedStageCommands({ kind: unit.kind, unit: unit.name, config: readJson(path.join(root, "ci", "gate.config.json")), manifest, platform });
+}
+
+export function readBrokerReceipt(id, { run = defaultRun } = {}) {
+  const r = run("rustright", ["status", id], { encoding: "utf8", timeout: 60_000 });
+  if (r.error || r.status !== 0) throw new Error(`the broker cannot report job ${id} (rustright status failed)`);
+  let doc;
+  try { doc = JSON.parse(r.stdout); } catch { throw new Error(`the broker's status of job ${id} is not JSON`); }
+  const receipt = doc?.receipt ?? doc;
+  if (receipt?.id !== id || !receipt.provenance?.payload || !receipt.provenance.signature) throw new Error(`job ${id} has no signed provenance receipt`);
+  return { id, provenance: receipt.provenance };
+}
+/** `<bundle>/qualification.json`: the local stages that passed and the one artifact sha256 they bound, for the dispatcher. */
+export function writeQualification({ report, artifact, unit, commit, tree, runtime, executor, write = fs.writeFileSync }) {
+  for (const stage of ["check", "compile", "package", "qualify"]) if (report.stages?.[stage]?.ok !== true) throw new Error(`release needs stage ${stage} ok before it runs`);
+  if (!artifact?.artifactFile || !/^[0-9a-f]{64}$/.test(artifact.artifactSha256 ?? "")) throw new Error("release needs the qualified artifact");
+  const receipt = { schema: QUALIFICATION_SCHEMA, unit: { kind: unit.kind, name: unit.name, version: unit.version }, commit, tree, runtime, executor: executor?.kind ?? null,
+    stages: Object.fromEntries(["check", "compile", "package", "qualify"].map((s) => [s, { ...report.stages[s] }])), artifactSha256: artifact.artifactSha256, writtenAt: new Date().toISOString() };
+  // The broker's signed receipts for the compile and package stages are what the hosted admission verifies; without them the
+  // booleans above are only this process's say-so.
+  for (const stage of ATTESTED_STAGES) {
+    const list = report.stages[stage].receipts;
+    if (!Array.isArray(list) || list.length < 1 || list.length > MAX_STAGE_RECEIPTS) throw new Error(`release needs 1 to ${MAX_STAGE_RECEIPTS} signed broker receipts of the ${stage} stage (found ${Array.isArray(list) ? list.length : "none"})`);
+  }
+  if (JSON.stringify(receipt).length > MAX_QUALIFICATION_BYTES) throw new Error("the qualification receipt with its broker receipts exceeds the workflow dispatch input limit");
+  const file = path.join(path.dirname(artifact.artifactFile), "qualification.json");
+  write(file, `${JSON.stringify(receipt, null, 2)}\n`);
+  return file;
+}
+
+const requireBrokerHost = (executor) => { if (executor?.kind !== "broker") throw new Error("unit release runs only on a broker-managed host (the hosted qualification is dispatched by the RustRight rightkit-dispatch adapter); a direct host has no gate-owned release route, so no upload was started"); };
+
+export async function releaseUnit({ unit, root, commit, executor, env, artifact, qualification, platform = process.platform, run = defaultRun, readJson = defaultReadJson, out = console.log, scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch", registryBytes = defaultRegistryBytes }) {
+  requireBrokerHost(executor);
+  if (typeof qualification !== "string" || !fs.existsSync(qualification)) throw new Error("release needs the unit qualification receipt (written by the gate after the qualify stage); nothing is dispatched without it");
+  const registry = unit.kind === "npm" ? "npm" : "crates";
+  const pipeline = path.join(root, "scripts", "ci", "rk-pipeline.mjs");
+  const stateFile = platform === "win32" ? "D:\\scratch\\rk-pipeline\\state.json" : "/Volumes/D/scratch/rk-pipeline/state.json";
+  const step = (label, args, { accept = [0], acceptWhen = null } = {}) => {
+    out(`rightkit-gate: [release] ${label}`);
+    const r = run(process.execPath, [pipeline, ...args], { cwd: root, env, stdio: ["ignore", "pipe", "pipe"] });
+    const accepted = r.status === 0 || (accept.includes(r.status) && (!acceptWhen || acceptWhen(r)));
+    if (!accepted) {
+      const said = `${String(r.stdout ?? "")}\n${String(r.stderr ?? "")}`.split("\n").map((l) => l.trim()).filter((l) => l && !l.includes("note:")).slice(-4).join(" | ");
+      throw new Error(`${label} failed (exit ${r.status}): ${said.slice(0, 600)}`);
+    }
+    return r;
+  };
+  const findDispatch = () => {
+    const found = Object.values(readJson(stateFile).dispatches ?? {}).filter((d) => d.unit === unit.name && d.sha === commit && d.registry === registry);
+    if (found.length > 1) throw new Error(`${found.length} dispatch records for ${unit.name} at ${commit.slice(0, 12)} in rk-pipeline state; reconcile before any retry`);
+    return found[0];
+  };
+  // The pipeline canary (rk-release-canary: the candidate's `right-release doctor` against every app on both hosts, versus the
+  // registry's version) runs before the pre-flight. rk-pipeline exits 2 both for "no pipeline canary for this unit" and for any
+  // internal error, so 2 is accepted only when it says the former (reviewer, 2026-10-27); a canary error never reads as no canary.
+  step(`pipeline canary of ${unit.name} (doctor on every app, both hosts, candidate vs registry)`, ["canary", unit.name],
+    { accept: [2], acceptWhen: (r) => /no pipeline canary for this unit/.test(`${r.stdout ?? ""}\n${r.stderr ?? ""}`) });
+  step(`local pre-flight of ${unit.name} through the broker`, ["preflight", unit.name, "--registry", registry]);
+  step(`broker-admitted hosted qualification dispatch of ${unit.name} at ${commit.slice(0, 12)}`, ["dispatch", unit.name, "--registry", registry, "--qualification", qualification]);
+  const dispatched = findDispatch();
+  if (!dispatched?.runId || !dispatched.runAttempt) throw new Error(`no dispatch record with a run for ${unit.name} at ${commit.slice(0, 12)}; nothing is claimed (reconcile rk-pipeline state before any retry)`);
+  step(`waiting for publish.yml run ${dispatched.runId}, its publish-direct upload run and the registry`, ["watch", "--wait"]);
+  const done = findDispatch();
+  if (done?.status !== "published" || done.version !== unit.version || !done.uploadRunId) throw new Error(`${unit.name}: the watch ended without a published record (${done?.status ?? "none"}${done?.conclusion ? `: ${done.conclusion}` : ""}); nothing is claimed`);
+  const receipt = readPublicationReceipt({ uploadRunId: done.uploadRunId, runId: done.runId, runAttempt: done.runAttempt, run, env, scratch });
+  // The receipt is written by the publish-direct UPLOAD run (its runId/runAttempt are that run's: upload.mjs records GITHUB_RUN_ID);
+  // the qualification run it consumed is its `candidate` (reviewed-candidate.mjs prepareQualified: id qualified-<run>-<attempt>,
+  // runId, runAttempt, sourceSha). Both are bound to what rk-pipeline dispatched and watched, plus commit, registry and repository.
+  const candidate = receipt.candidate ?? {};
+  const bound = String(receipt.runId) === String(done.uploadRunId)
+    && receipt.commit === commit && receipt.registry === registry && receipt.repository === "bogusyogi/rightkit" && receipt.dryRun !== true
+    && candidate.source === "qualified" && String(candidate.runId) === String(done.runId) && String(candidate.runAttempt) === String(done.runAttempt) && candidate.sourceSha === commit;
+  if (!bound) {
+    throw new Error(`${unit.name}@${unit.version}: the publication receipt of upload run ${done.uploadRunId} is not that run's receipt for qualification run ${done.runId} attempt ${done.runAttempt} of ${commit.slice(0, 12)} (${registry}); nothing is claimed`);
+  }
+  const rows = (receipt.receipts ?? []).filter((r) => r.unit === unit.name && r.version === unit.version);
+  if (rows.length !== 1) throw new Error(`${unit.name}@${unit.version}: the publication receipt holds ${rows.length} row(s) for this unit; exactly one is required`);
+  const [row] = rows;
+  if (row.published !== true || row.registryVerified !== true || row.outcome !== "published" || !/^[0-9a-f]{64}$/.test(row.sha256 ?? "")) throw new Error(`${unit.name}@${unit.version}: the publication receipt of upload run ${done.uploadRunId} records no verified publication (${row.outcome})`);
+  // Read the registry back independently of the upload run: npm's dist.shasum (sha1) and the served tarball's sha256 (the receipt
+  // row carries sha256 + sha1, not the sha512 integrity); crates: the sparse index cksum (sha256).
+  const served = await registryBytes({ unit, registry, run, env, expected: row, scratch });
+  const same = registry === "npm" ? served.shasum === row.sha1 && served.sha256 === row.sha256 : served.cksum === row.sha256;
+  if (!same) throw new Error(`${unit.name}@${unit.version}: the registry serves different bytes from the upload receipt (served sha256 ${served.sha256 ?? served.cksum ?? "?"}, receipt ${row.sha256})`);
+  return {
+    registry, runId: done.runId, runAttempt: done.runAttempt, requestId: done.requestId ?? null, uploadRunId: done.uploadRunId,
+    hostedSha256: row.sha256, hostedSha1: row.sha1 ?? null, registryVerified: true,
+    localArtifactSha256: artifact?.artifactSha256 ?? null, hostedEqualsLocal: artifact ? artifact.artifactSha256 === row.sha256 : null,
+  };
+}
+
+/** The one `publication-receipt-*` artifact of the upload run, downloaded and parsed. More or fewer than one is ambiguous. */
+export function readPublicationReceipt({ uploadRunId, runId, runAttempt, run, env, scratch }) {
+  const listed = run(GH, ["api", `repos/bogusyogi/rightkit/actions/runs/${uploadRunId}/artifacts`], { env, encoding: "utf8" });
+  if (listed.status !== 0) throw new Error(`cannot list the artifacts of upload run ${uploadRunId}`);
+  // publish-direct names its receipt `publication-receipt-<qualification run id>-<its attempt>-<upload attempt>`.
+  const pattern = new RegExp(`^publication-receipt-${runId}-${runAttempt}-\\d+$`);
+  const names = (JSON.parse(listed.stdout).artifacts ?? []).map((a) => a.name).filter((n) => pattern.test(n));
+  if (names.length !== 1) throw new Error(`upload run ${uploadRunId} has ${names.length} publication receipt artifact(s) for run ${runId} attempt ${runAttempt}; exactly one is required`);
+  const dir = path.join(scratch, "rk-unit-receipts", `${uploadRunId}-${Date.now()}`);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  const fetched = run(GH, ["run", "download", String(uploadRunId), "-R", "bogusyogi/rightkit", "--name", names[0], "--dir", dir], { env, encoding: "utf8" });
+  if (fetched.status !== 0) throw new Error(`cannot download ${names[0]} of upload run ${uploadRunId}`);
+  const file = path.join(dir, "publication-receipt.json");
+  if (!fs.existsSync(file)) throw new Error(`${names[0]} holds no publication-receipt.json`);
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/** What the registry serves for the unit's version: npm dist.integrity + dist.shasum; crates the sparse index cksum. */
+export async function defaultRegistryBytes({ unit, registry, run, env, expected, scratch }) {
+  if (registry === "npm") {
+    const r = run("npm", ["view", `${unit.name}@${unit.version}`, "dist.shasum", "--json", "--prefer-online"], { env, encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`npm view ${unit.name}@${unit.version} failed`);
+    const shasum = JSON.parse(r.stdout);
+    // The served tarball itself, hashed here: `npm pack` downloads exactly what the registry serves for that version.
+    const dir = path.join(scratch, "rk-unit-readback", `${unit.name.replace("/", "__")}-${unit.version}-${Date.now()}`);
+    fs.mkdirSync(dir, { recursive: true });
+    const packed = run("npm", ["pack", `${unit.name}@${unit.version}`, "--pack-destination", dir, "--ignore-scripts"], { env, encoding: "utf8", cwd: dir });
+    if (packed.status !== 0) throw new Error(`npm pack ${unit.name}@${unit.version} failed`);
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith(".tgz"));
+    if (files.length !== 1) throw new Error(`npm pack of ${unit.name}@${unit.version} produced ${files.length} tarball(s)`);
+    return { shasum: typeof shasum === "string" ? shasum : shasum?.["dist.shasum"], sha256: hash(fs.readFileSync(path.join(dir, files[0]))) };
+  }
+  // The sparse index must serve exactly the receipt's sha256 (verifyCargoRegistry throws PUBLICATION_REGISTRY_MISMATCH otherwise).
+  const { verifyCargoRegistry } = await import("./cargo-registry-readback.mjs");
+  await verifyCargoRegistry({ name: unit.name, version: unit.version, sha256: expected.sha256 });
+  return { cksum: expected.sha256 };
+}
+
+
+const hash = (data) => createHash("sha256").update(data).digest("hex");
+
+export function resolveUnit(selector, root, { granted = localBuildGranted, readJson = (p) => JSON.parse(fs.readFileSync(p, "utf8")), readCargo = readCargoPackage } = {}) {
+  const match = /^(npm):(@rightkit\/[a-z0-9-]+)$|^(cargo):(rightkit-[a-z0-9-]+)$/.exec(selector ?? "");
+  if (!match || !granted(root)) throw new Error("unit needs npm:@rightkit/<name> or cargo:rightkit-<name> in the locally granted RightKit repository");
+  const kind = match[1] ?? match[3], name = match[2] ?? match[4];
+  const dir = path.join(root, kind === "npm" ? "packages" : "crates", kind === "npm" ? name.slice("@rightkit/".length) : name);
+  const manifestFile = path.join(dir, kind === "npm" ? "package.json" : "Cargo.toml");
+  if (!fs.realpathSync(manifestFile).startsWith(`${fs.realpathSync(root)}${path.sep}`)) throw new Error("unit manifest escapes the repository");
+  const manifest = kind === "npm" ? readJson(path.join(dir, "package.json")) : readCargo(dir);
+  if (manifest.name !== name || manifest.private === true || manifest.manifest?.package?.publish === false || typeof manifest.version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version)) throw new Error(`invalid canonical manifest for ${selector}`);
+  return { kind, name, version: manifest.version };
+}
+
+/** One invocation reruns all owed stages; reports are never read as admission evidence. */
+export async function runUnitGate({ selector, to, root, commonDir, commit, tree, executor, env, platform, check, loadOwner = () => import("./local-publish.mjs"), out = console.log, err = console.error, releaser = null, resolve = resolveUnit, writeReport, fetchReceipt = readBrokerReceipt, stageCommands = defaultStageCommands }) {
+  const stages = stagesTo(to);
+  if (!stages) { err(`rightkit-gate: invalid unit stage ${to}`); return 2; }
+  let unit;
+  try { unit = resolve(selector, root); } catch (error) { err(`rightkit-gate: BLOCKED: ${error.message}`); return 1; }
+  const scratch = platform === "win32" ? "D:\\scratch" : "/Volumes/D/scratch";
+  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));
+  const runtimeFiles = [...fs.readdirSync(runtimeDir).filter((name) => name.endsWith(".mjs")).sort().map((name) => path.join(runtimeDir, name)), path.join(runtimeDir, "bin", "rightkit-gate.mjs")];
+  const runtime = hash(runtimeFiles.map((file) => `${path.relative(runtimeDir, file)}\0${hash(fs.readFileSync(file))}`).join("\n"));
+  const report = { schema: "rightkit.unit-gate-report/1", unit, commit, tree, runtime, executor: executor.kind, stages: {} };
+  const save = () => { if (writeReport) writeReport(report); };
+  let state, owner, artifact, currentStage, checkTier = null;
+  // A run headed to release has its compile and package broker jobs sent with a nonce bound to this commit, tree, unit and stage
+  // (RIGHTKIT_ATTEST_NONCE), so each job's signed receipt can be verified hosted for exactly that and nothing else.
+  const attested = stages.includes("release") && executor?.kind === "broker";
+  const stageEnv = async (stage, action) => {
+    const run = startRun({ commonDir, commit, tree, stage });
+    const nonce = attested && ATTESTED_STAGES.includes(stage) ? { RIGHTKIT_ATTEST_NONCE: qualificationNonce({ commit, tree, unit: `${unit.kind}:${unit.name}`, stage }) } : {};
+    try { return await action({ ...env, ...nonce, ...run.env }); } finally { endRun(run); }
+  };
+  const receipts = {};
+  const collectReceipts = (stage, ids) => {
+    if (!attested || !ATTESTED_STAGES.includes(stage)) return;
+    // Every job of the stage is fetched; the stage owes a signed receipt for EVERY command it runs (hosted admission requires the same),
+    // so a missing one fails here, before any dispatch, naming it. Jobs that are none of the stage's commands are not carried.
+    const fetched = [...new Set(ids ?? [])].map((id) => fetchReceipt(id));
+    const { assigned, missing } = assignJobs(stageCommands({ unit, root, platform })[stage], fetched.map((r) => ({ id: r.id, payload: r.provenance.payload })));
+    if (missing.length) throw new Error(`the ${stage} stage's ${describeCommand(missing[0])} has no broker job receipt (${missing.length} required command(s) missing)`);
+    receipts[stage] = fetched.filter((r) => assigned.has(r.id));
+  };
+  const verifyArtifact = (result) => {
+    if (!result || result.kind !== unit.kind || result.name !== unit.name || result.version !== unit.version || result.commit !== commit || !/^[0-9a-f]{64}$/.test(result.artifactSha256 ?? "") || hash(fs.readFileSync(result.artifactFile)) !== result.artifactSha256) throw new Error("unit artifact identity or digest differs from the completed stage");
+  };
+  try {
+    for (const stage of stages) {
+      currentStage = stage;
+      // A unit run headed to qualify or release owes the release tier: it runs here, before the compile, and qualify does not run it again.
+      if (stage === "check") { checkTier = stages.includes("qualify") ? "release" : "compile"; if (await check(checkTier) !== 0) throw new Error(`class A check (${checkTier} tier) failed`); }
+      else if (stage === "compile") {
+        owner = await loadOwner();
+        state = await stageEnv(stage, (runEnv) => owner.compileLocalUnit(unit.kind, argv, { env: runEnv }));
+        collectReceipts(stage, owner.localUnitCompileRequests?.(state));
+      } else if (stage === "package") {
+        artifact = await stageEnv(stage, (runEnv) => owner.packageLocalUnit(state, { env: runEnv }));
+        verifyArtifact(artifact);
+        collectReceipts(stage, artifact.brokerRequests);
+      } else if (stage === "qualify") {
+        if (checkTier !== "release" && await check("release") !== 0) throw new Error("release-tier check failed");
+        const qualified = await stageEnv(stage, (runEnv) => owner.qualifyLocalUnit(state, { env: runEnv }));
+        verifyArtifact(qualified);
+        if (!qualified.qualifiedOnly || !qualified.evidencePath || qualified.artifactSha256 !== artifact.artifactSha256) throw new Error("qualification did not bind the packaged artifact");
+        artifact = qualified;
+      }
+      let released = null;
+      if (stage === "release") {
+        // The qualification receipt the dispatcher carries to publish.yml: the hosted run is bound to these bytes and stages.
+        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 });
+        released = await stageEnv(stage, (runEnv) => (releaser ?? releaseUnit)({ unit, root, commit, executor, env: runEnv, artifact, qualification, platform, out }));
+      }
+      report.stages[stage] = { ok: true, ...(stage === "package" || stage === "qualify" ? { artifactFile: artifact.artifactFile, artifactSha256: artifact.artifactSha256 } : {}), ...(receipts[stage] ? { receipts: receipts[stage] } : {}), ...(released ?? {}) };
+      save();
+      out(`rightkit-gate: [${stage}] ${unit.kind}:${unit.name} passed`);
+    }
+    return 0;
+  } catch (error) {
+    if (currentStage) { report.stages[currentStage] = { ok: false }; save(); }
+    err(`rightkit-gate: unit ${selector} stopped: ${error.message}`);
+    return 1;
+  } finally { if (state && owner) await owner.closeLocalUnit(state); }
+}

package/web-build.mjs

@@ -12,10 +12,17 @@
 //
 // A step is `{ cmd | node, args?, cwd?, env?, nodeFlags?, nodeOptions? }` (see command-spec.mjs). `--dry-run` prints the
 // resolved commands and runs nothing. Exit code: 0, or the failing step's exit code.
+//
+// The door (gate-stages.mjs requireDoorRun) is checked before the config is imported: a .mjs config is code, so even a dry run
+// runs only under a live door run. The exported runner checks it again, so no in-process caller spawns a step around it.
+import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { spawnSync } from "./background-process.mjs";
+import { existsSync } from "node:fs";
+import { buildLaunch } from "./build-launch.mjs";
 import { CommandSpecError, loadAppConfig, resolveInvocation, validateStep } from "./command-spec.mjs";
 import { defaultReleaseConfigFile } from "./release-config.mjs";
+import { requireDoorRun } from "./gate-stages.mjs";
 
 export function parseWebBuildArgs(argv) {
   const opts = { config: defaultReleaseConfigFile(), dryRun: false };
@@ -41,23 +48,48 @@ export function planWebBuild(config) {
   return steps.map((step, index) => validateStep(step, `web.build[${index}]`));
 }
 
-/** Run the steps in order; `spawnSyncFn` and `log` are injectable. Returns the exit code. */
-export function runWebBuild(steps, { appRoot, env = process.env, dryRun = false, spawnSyncFn = spawnSync, log = console.log } = {}) {
+/**
+ * The door refusal for a web build of the app at `appRoot`, or null under a live door run. Outside a git repository nothing can be
+ * bound to a commit: refused. `spawnSyncFn` runs git; `requireDoor` is gate-stages.mjs requireDoorRun.
+ */
+export function webBuildDoorRefusal({ appRoot, env = process.env, spawnSyncFn = spawnSync, requireDoor = requireDoorRun }) {
+  const gitOut = (a) => { const r = spawnSyncFn("git", a, { cwd: appRoot, encoding: "utf8" }); return r.status === 0 ? String(r.stdout).trim() : ""; };
+  const common = gitOut(["rev-parse", "--git-common-dir"]);
+  if (!common) return "right-release web-build runs only inside a git repository, under a door run";
+  return requireDoor({ env, commonDir: path.resolve(appRoot, common), commit: gitOut(["rev-parse", "HEAD"]), command: "right-release web-build" });
+}
+
+function doorError(refusal) { const error = new Error(refusal); error.code = "RK_DOOR"; return error; }
+
+/**
+ * Run the steps in order under a live door run; `spawnSyncFn`, `requireDoor` and `log` are injectable. Returns the exit code. The
+ * door is checked here as well as in main: this is the only place a step is spawned.
+ */
+export function runWebBuild(steps, { appRoot, env = process.env, dryRun = false, spawnSyncFn = spawnSync, requireDoor = requireDoorRun, log = console.log, door = buildLaunch } = {}) {
+  const refusal = webBuildDoorRefusal({ appRoot, env, spawnSyncFn, requireDoor });
+  if (refusal) throw doorError(refusal);
   for (const step of steps) {
     const invocation = resolveInvocation(step, { appRoot, baseEnv: env });
     log(`${dryRun ? "[dry-run] " : ""}${[invocation.cmd, ...invocation.args].join(" ")}`);
     if (dryRun) continue;
-    const result = spawnSyncFn(invocation.cmd, invocation.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
+    // A web build is a build: through the one door (build-launch.mjs), a broker job on a managed host.
+    const target = door(invocation.cmd, invocation.args, { env: invocation.env, cwd: invocation.cwd, exists: existsSync });
+    const result = spawnSyncFn(target.command, target.args, { cwd: invocation.cwd, env: invocation.env, stdio: "inherit" });
     if (result.error) throw result.error;
     if (result.status !== 0) return result.status ?? 1;
   }
   return 0;
 }
 
-export async function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2), { env = process.env, requireDoor = requireDoorRun, spawnSyncFn = spawnSync, loadConfig = loadAppConfig, log = console.log } = {}) {
   const opts = parseWebBuildArgs(argv);
-  const { config, appRoot } = await loadAppConfig(opts.config);
-  return runWebBuild(planWebBuild(config), { appRoot, dryRun: opts.dryRun });
+  // A web build is a compile: like right-release build, the direct entry runs only under a door run (rightkit-gate --to compile runs
+  // class A first). The door is checked before the config is imported, since a .mjs config is code; a dry run is no exception.
+  const appRoot = path.dirname(path.resolve(opts.config));
+  const refusal = webBuildDoorRefusal({ appRoot, env, spawnSyncFn, requireDoor });
+  if (refusal) throw doorError(refusal);
+  const { config } = await loadConfig(opts.config);
+  return runWebBuild(planWebBuild(config), { appRoot, env, dryRun: opts.dryRun, spawnSyncFn, requireDoor, log });
 }
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {