@rightkit/release 0.4.0 → 0.4.1

package/runtime-budgets.mjs

@@ -59,6 +59,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "./background-process.mjs";
 import { parse } from "smol-toml";
+import { RUNTIME_BUDGET_CRATES } from "./runtime-budget-crates.mjs";
 import { singleHostOfPolicy } from "./publication-gate.mjs";
 import { findWorkspaceRoot, lockClosure, pathDependencyDirs, readCargoPackage } from "./crate-graph.mjs";
 
@@ -68,18 +69,7 @@ export const RUNTIME_BUDGET_FILE = "runtime-budget.json";
 export const RUNTIME_BUDGET_EVIDENCE_DIR = "runtime-budget.evidence";
 export const RUNTIME_BUDGET_SCHEMA = 1;
 
-export const RUNTIME_BUDGET_CRATES = Object.freeze([
-  "rightkit-fsindex",
-  "rightkit-file-watch",
-  "rightkit-job-queue",
-  "rightkit-daemon",
-  "rightkit-cache",
-  "rightkit-sync",
-  "rightkit-logs",
-  "rightkit-tauri-shell",
-  "rightkit-qa",
-  "rightkit-send",
-]);
+export { RUNTIME_BUDGET_CRATES };
 
 export const BUDGET_FIGURES = Object.freeze(["residentMemoryBytes", "idleCpuPercent", "wakeupsPerSecond", "diskOpsPerSecond"]);
 const FIGURE_LABEL = Object.freeze({
@@ -260,17 +250,86 @@ const posix = (p) => p.split(path.sep).join("/");
 /**
  * The git pathspecs (relative to the workspace root) whose change makes a measurement stale: the
  * crate's src, benches, Cargo.toml (features) and build.rs, plus src, Cargo.toml and build.rs of every
- * workspace crate it reaches through `path` dependencies (transitively). Returns { root, specs }.
+ * workspace crate it reaches through `path` dependencies (transitively). Returns { root, specs, problems }.
+ * Callers must refuse incomplete metadata rather than using a partial dependency scope.
  */
 export function measuredPathspecs(crateDir, deps = {}) {
-  const root = findWorkspaceRoot(crateDir, deps) ?? path.resolve(crateDir);
+  const { exists = existsSync, readFile = readFileSync } = deps;
+  const problems = [];
+  // Workspace discovery deliberately tolerates bad ancestor manifests elsewhere. Freshness cannot:
+  // a swallowed read/parse failure could hide inherited dependencies and shrink the measured graph.
+  const checkedRead = (file, encoding) => {
+    try {
+      const contents = readFile(file, encoding);
+      if (path.basename(file) === "Cargo.toml") parse(contents);
+      return contents;
+    } catch (error) {
+      problems.push(`cannot read dependency metadata ${file}: ${error.message}`);
+      throw error;
+    }
+  };
+  const checked = { exists, readFile: checkedRead };
+  let root = path.resolve(crateDir);
   const specs = [];
   const add = (dir, names) => { for (const name of names) specs.push(posix(path.relative(root, path.join(dir, name)))); };
-  add(path.resolve(crateDir), CRATE_PATHS);
-  let dependencies = [];
-  try { dependencies = pathDependencyDirs(crateDir, deps); } catch { /* unreadable manifest: the crate paths alone */ }
-  for (const dir of dependencies) add(dir, DEPENDENCY_PATHS);
-  return { root, specs: [...new Set(specs)] };
+  try {
+    root = findWorkspaceRoot(crateDir, checked) ?? root;
+    add(path.resolve(crateDir), CRATE_PATHS);
+    const dependencies = pathDependencyDirs(crateDir, checked);
+    const workspace = exists(path.join(root, "Cargo.toml")) ? parse(checkedRead(path.join(root, "Cargo.toml"), "utf8")).workspace : undefined;
+    for (const dir of [path.resolve(crateDir), ...dependencies]) {
+      const manifestPath = path.join(dir, "Cargo.toml");
+      if (!exists(manifestPath)) {
+        // A manifest-free standalone path has no Cargo graph. A declared path dependency must exist.
+        if (dir !== path.resolve(crateDir)) problems.push(`dependency manifest is missing: ${manifestPath}`);
+        continue;
+      }
+      const manifest = parse(checkedRead(manifestPath, "utf8"));
+      if (!nonEmpty(manifest.package?.name)) problems.push(`dependency manifest has no package.name: ${manifestPath}`);
+      const holders = [manifest, ...Object.values(manifest.target ?? {})];
+      for (const holder of holders) {
+        for (const key of ["dependencies", "build-dependencies", ...(dir === path.resolve(crateDir) ? ["dev-dependencies"] : [])]) {
+          for (const [name, spec] of Object.entries(holder?.[key] ?? {})) {
+            if (spec && typeof spec === "object" && spec.workspace === true && workspace?.dependencies?.[name] === undefined) {
+              problems.push(`workspace dependency ${name} cannot be resolved for ${manifestPath}`);
+            }
+          }
+        }
+      }
+    }
+    for (const dir of dependencies) add(dir, DEPENDENCY_PATHS);
+  } catch (error) {
+    if (!problems.length) problems.push(`cannot resolve measured dependency paths for ${crateDir}: ${error.message}`);
+  }
+  return { root, specs: [...new Set(specs)], problems: [...new Set(problems)] };
+}
+
+// lockClosure compares reachable entries, but its permissive parser can return an empty/partial graph.
+// Require the root and every reachable edge before allowing equality to establish freshness.
+function completeLockClosure(contents, name) {
+  const packages = parse(contents).package;
+  if (!Array.isArray(packages)) throw new Error("missing [[package]] entries");
+  const roots = packages.filter((entry) => entry.name === name);
+  if (!roots.length) throw new Error(`missing package ${name}`);
+  const seen = new Set();
+  const pending = [...roots];
+  while (pending.length) {
+    const entry = pending.pop();
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    if (!nonEmpty(entry.name) || !nonEmpty(entry.version)) throw new Error(`incomplete package identity for ${entry.name ?? name}`);
+    if (entry.dependencies !== undefined && !Array.isArray(entry.dependencies)) throw new Error(`invalid dependencies for ${entry.name}`);
+    for (const edge of entry.dependencies ?? []) {
+      if (!nonEmpty(edge)) throw new Error(`invalid dependency edge for ${entry.name}`);
+      const match = /^(\S+)(?: (\S+))?(?: \(([^)]+)\))?$/.exec(edge);
+      if (!match) throw new Error(`invalid dependency ${edge} of ${entry.name}`);
+      const candidates = packages.filter((candidate) => candidate.name === match[1]
+        && (!match[2] || candidate.version === match[2]) && (!match[3] || candidate.source === match[3]));
+      if (!candidates.length) throw new Error(`unresolved dependency ${edge} of ${entry.name}`);
+      pending.push(...candidates);
+    }
+  }
+  return lockClosure(contents, name);
 }
 
 /**
@@ -289,7 +348,8 @@ export function measurementStaleness(commit, crateDir, git = defaultGit, deps =
   const known = git(["cat-file", "-t", commit], crateDir);
   if (known.status !== 0 || known.stdout !== "commit") return `commit ${commit.slice(0, 12)} is not a commit in this repository (shallow clone?)`;
   if (git(["merge-base", "--is-ancestor", commit, "HEAD"], crateDir).status !== 0) return `commit ${commit.slice(0, 12)} is not an ancestor of HEAD`;
-  const { root, specs } = measuredPathspecs(crateDir, { exists, readFile });
+  const { root, specs, problems } = measuredPathspecs(crateDir, { exists, readFile });
+  if (problems.length) return `cannot resolve measured dependency graph: ${problems.join("; ")}`;
   // `git diff <commit>` (no second revision) compares the working tree to the commit.
   const changed = git(["diff", "--name-only", commit, "--", ...specs], root);
   if (changed.status !== 0) return "cannot diff the crate against the measured commit";
@@ -298,17 +358,29 @@ export function measurementStaleness(commit, crateDir, git = defaultGit, deps =
   if (untracked.status !== 0) return "cannot list untracked crate files";
   if (untracked.stdout !== "") return `untracked files since the measurement: ${untracked.stdout.split("\n").slice(0, 5).join(", ")}`;
   let name = null;
-  try { name = readCargoPackage(crateDir, { exists, readFile }).name; } catch { /* no manifest: nothing to resolve in the lock */ }
+  try {
+    if (exists(path.join(crateDir, "Cargo.toml"))) {
+      name = readCargoPackage(crateDir, { exists, readFile }).name;
+      if (!nonEmpty(name)) return `cannot resolve Cargo.lock: ${path.join(crateDir, "Cargo.toml")} has no package.name`;
+    }
+  } catch (error) { return `cannot resolve Cargo.lock package identity: ${error.message}`; }
   if (name) {
     const lockPath = path.join(root, "Cargo.lock");
-    const now = exists(lockPath) ? readFile(lockPath, "utf8") : null;
+    let now;
+    try { now = exists(lockPath) ? readFile(lockPath, "utf8") : null; }
+    catch (error) { return `cannot read Cargo.lock ${lockPath}: ${error.message}`; }
     const then = git(["show", `${commit}:./Cargo.lock`], root);
     const had = then.status === 0;
     if (now === null && had) return "Cargo.lock was removed since the measurement";
     if (now !== null && !had) return "Cargo.lock did not exist at the measured commit";
+    if (now === null && !had) {
+      // A failed show alone cannot distinguish an absent lock from an unreadable Git object.
+      const listed = git(["ls-tree", commit, "--", "Cargo.lock"], root);
+      if (listed.status !== 0 || listed.stdout !== "") return "cannot establish that Cargo.lock was absent at the measured commit";
+    }
     if (now !== null) {
       try {
-        if (JSON.stringify(lockClosure(now, name)) !== JSON.stringify(lockClosure(then.stdout, name))) {
+        if (JSON.stringify(completeLockClosure(now, name)) !== JSON.stringify(completeLockClosure(then.stdout, name))) {
           return `Cargo.lock changed in the dependency graph of ${name} since commit ${commit.slice(0, 12)}`;
         }
       } catch (error) { return `cannot compare Cargo.lock: ${error.message}`; }
@@ -500,7 +572,14 @@ export function statusApiDeclared(api, source) {
  * `evidence` is the release gate evidence for it (the host-policy authority). `requireInstalled`
  * (adoption) additionally needs a fresh in-ceiling installed-app measurement, optionally for `app`.
  */
-export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requireInstalled = false, app, heldResource = false }, { readFile = readFileSync, exists = existsSync, git = defaultGit } = {}) {
+export function evaluateRuntimeBudget(options, deps = {}) {
+  return evaluateRuntimeBudgetOwned(options, deps);
+}
+
+// Private owner mode: no caller-supplied boolean can weaken publication or adoption.
+const STRUCTURE_ONLY = Symbol("runtime-budget-structure-only");
+function evaluateRuntimeBudgetOwned({ crate, crateDir, version, evidence, requireInstalled = false, app, heldResource = false }, { readFile = readFileSync, exists = existsSync, git = defaultGit } = {}, mode) {
+  const structural = mode === STRUCTURE_ONLY;
   const file = path.join(crateDir, RUNTIME_BUDGET_FILE);
   if (!exists(file)) return { ok: false, problems: [`${RUNTIME_BUDGET_FILE} is missing (docs/RUNTIME-BUDGETS.md)`] };
   let budget;
@@ -574,7 +653,7 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
 
   // Measurements.
   const records = Array.isArray(budget.measurements) ? budget.measurements : [];
-  if (records.length === 0) problems.push("no measurements recorded (a declared ceiling is not evidence)");
+  if (!structural && records.length === 0) problems.push("no measurements recorded (a declared ceiling is not evidence)");
   const valid = [];
   records.forEach((m, index) => {
     const bad = validateMeasurement(m, index);
@@ -583,7 +662,7 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
     if (evidenceProblems.length) problems.push(...evidenceProblems); else valid.push({ m, index });
   });
   const counted = valid.filter(({ m }) => m.crateVersion === version);
-  if (valid.length && nonEmpty(version) && counted.length === 0) {
+  if (!structural && valid.length && nonEmpty(version) && counted.length === 0) {
     problems.push(`no measurement for version ${version} (recorded: ${[...new Set(valid.map(({ m }) => m.crateVersion))].join(", ")})`);
   }
   // Why a measurement fails one figure, or null. A delta-basis figure of a synthetic measurement is gated on
@@ -608,7 +687,7 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
     }
     return null;
   };
-  for (const { m, index } of counted) {
+  for (const { m, index } of (structural ? valid : counted)) {
     for (const key of BUDGET_FIGURES) {
       const failure = figureFailure(m, key);
       if (failure) problems.push(`measurement[${index}] on ${m.host.os}/${m.host.arch} ${failure}`);
@@ -616,6 +695,14 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
   }
   const withinCeilings = (m) => BUDGET_FIGURES.every((key) => ceilings[key] !== undefined && (usesDelta(m, key) ? deltaCeilings[key] !== undefined && figureFailure(m, key) === null : m.observed[key] === null ? figureUnavailableOn(m.host?.os, key) : m.observed[key] <= ceilings[key]));
   const atScale = (m) => requiredScale !== null && m.dataScale.unit === requiredScale.unit && m.dataScale.count >= requiredScale.minCount;
+  if (structural) {
+    if (!Array.isArray(budget.measurements)) problems.push("measurements must be an array");
+    const scope = measuredPathspecs(crateDir, { exists, readFile });
+    problems.push(...scope.problems);
+    for (const key of deltaFigures) if (!nonEmpty(budget.deltaSources?.[key])) problems.push(`deltaSources.${key} must name its ceiling source`);
+    if (budget.deltaSources !== undefined && (!budget.deltaSources || typeof budget.deltaSources !== "object" || Array.isArray(budget.deltaSources) || Object.keys(budget.deltaSources).some((key) => !deltaFigures.includes(key)))) problems.push("deltaSources must name only declared delta figures");
+    for (const { m, index } of valid) if (!atScale(m)) problems.push(`measurement[${index}] is below required scale`);
+  }
   const staleness = new Map();
   const stale = (m) => {
     if (!staleness.has(m.commit)) staleness.set(m.commit, measurementStaleness(m.commit, crateDir, git, { exists, readFile }));
@@ -624,7 +711,7 @@ export function evaluateRuntimeBudget({ crate, crateDir, version, evidence, requ
 
   // Required hosts: one fresh, in-ceiling, at-scale measurement of this version on each.
   // A held-resource crate defers measurement to adoption: no per-host publish measurement is required.
-  const required = heldResource ? [] : requiredBudgetHosts(budget, evidence);
+  const required = heldResource || structural ? [] : requiredBudgetHosts(budget, evidence);
   for (const host of required) {
     const onHost = counted.filter(({ m }) => m.host.os === host);
     if (onHost.length === 0) { problems.push(`no ${HOSTS[host]} measurement for version ${version} (required hosts: ${required.map((h) => HOSTS[h]).join(" and ")}${required.length > 1 ? "; apps ship on both and the release gate requires both unless a darwin-only policy with a reason is recorded" : `; ${required[0]}-only policy: ${String((evidence ?? budget).hostPolicyReason).trim()}`})`); continue; }
@@ -728,7 +815,17 @@ export function heldResourceProblems({ crate, crateDir, meta }, { readFile = rea
  * naming every matched pattern), "held-resource" (resources table, adoption-time proof) or always-on
  * (runtime-budget.json, fully checked). `readFile`, `exists` and `git` are injectable.
  */
-export function runtimeBudgetCheck({ crate, crateDir, version, evidence, requireInstalled = false, app }, deps = {}) {
+export function runtimeBudgetCheck(options, deps = {}) {
+  return runtimeBudgetCheckOwned(options, deps);
+}
+
+/** Source structure only; grants no runtime qualification or semantic admission. */
+export function runtimeBudgetStructureCheck(options, deps = {}) {
+  const result = runtimeBudgetCheckOwned({ ...options, requireInstalled: false }, deps, STRUCTURE_ONLY);
+  return { ...result, name: "runtime-budget-structure" };
+}
+
+function runtimeBudgetCheckOwned({ crate, crateDir, version, evidence, requireInstalled = false, app }, deps = {}, mode) {
   const { readFile = readFileSync, exists = existsSync } = deps;
   let pkg;
   try { pkg = readCargoPackage(crateDir, { exists, readFile }); } catch (error) {
@@ -775,9 +872,9 @@ export function runtimeBudgetCheck({ crate, crateDir, version, evidence, require
     return fail(crate, crateDir, [`undeclared: none of ${RUNTIME_BUDGET_FILE}, continuous = false with a continuous_reason, or continuous = "held-resource" with resources`],
       `declare the crate (docs/RUNTIME-BUDGETS.md)`);
   }
-  const result = evaluateRuntimeBudget({ crate, crateDir, version: version ?? pkg.version, evidence, requireInstalled, app }, deps);
+  const result = evaluateRuntimeBudgetOwned({ crate, crateDir, version: version ?? pkg.version, evidence, requireInstalled, app }, deps, mode);
   if (result.ok) {
-    return { name: RUNTIME_BUDGET_CHECK, status: "ok", detail: `${crate} ${version ?? pkg.version} has measured runtime budgets on every required host` };
+    return { name: RUNTIME_BUDGET_CHECK, status: "ok", detail: mode === STRUCTURE_ONLY ? `${crate} ${version ?? pkg.version} runtime budget structure is valid; qualification is separate` : `${crate} ${version ?? pkg.version} has measured runtime budgets on every required host` };
   }
   return fail(crate, crateDir, result.problems);
 }

package/stage-sidecar.mjs

@@ -73,6 +73,28 @@ const MODES = new Set(["dev", "release"]);
 const PROFILE = /^[a-z][a-z0-9_-]*$/;
 const PLATFORMS = new Set(["mac", "win", "linux"]);
 const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/** One path segment of an archive member path: no glob metacharacters, no separators, no drive colon. */
+const MEMBER_SEGMENT = /^[A-Za-z0-9_.+@~-]+$/;
+
+/**
+ * Normalize and guard a requested archive member. A bare file name (no `/`) selects the one member with that base name; a path
+ * (contains `/`) selects the one member with exactly that archive path. A leading `./` is stripped. Absolute paths, drive
+ * prefixes, backslashes, empty, `.` and `..` segments and glob metacharacters are refused. Returns { value, byPath } or
+ * { error }. The member never influences where the extracted file is written.
+ */
+export function normalizeArchiveMember(member) {
+  if (typeof member !== "string" || !member) return { error: "must be a non-empty string" };
+  if (member.includes("\\")) return { error: "must not contain a backslash" };
+  const value = member.startsWith("./") ? member.slice(2) : member;
+  if (value.startsWith("/")) return { error: "must not be an absolute path" };
+  if (/^[A-Za-z]:/.test(value)) return { error: "must not start with a drive prefix" };
+  const segments = value.split("/");
+  if (segments.some((segment) => segment === "")) return { error: "must not contain an empty segment" };
+  if (segments.some((segment) => segment === "." || segment === "..")) return { error: "must not contain a '.' or '..' segment" };
+  // A bare file name keeps today's matching (any characters but the refused ones above); a path is held to a strict segment alphabet so it can never act as a tar glob.
+  if (segments.length > 1 && !segments.every((segment) => MEMBER_SEGMENT.test(segment))) return { error: "has a segment with characters outside A-Z a-z 0-9 _ . + @ ~ -" };
+  return { value, byPath: segments.length > 1 };
+}
 const KEYS = Object.freeze({
   "cargo-bin": ["kind", "package", "bin", "name", "profile", "features", "manifestPath", "sha256", "dest", "clean", "platforms"],
   ffmpeg: ["kind", "variant", "variants", "tools", "notices", "catalog", "stage", "bundleDir", "sources", "probe", "platforms"],
@@ -390,7 +412,7 @@ export function validateSidecarManifest(raw, { target, mode = "release" } = {})
       if (item.dest === undefined && item.to === undefined) errors.push(`${where}: dest (or to) is required`);
       const dest = destOf(item.dest ?? item.to, item.dest === undefined ? "to" : "dest");
       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 && (typeof item.extract !== "string" || !NAME.test(item.extract))) errors.push(`${where}: extract must be the bare file name of one archive member (no path)`);
+      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.executable !== undefined && typeof item.executable !== "boolean") errors.push(`${where}: executable must be a boolean`);
       const clean = cleanOf();
@@ -499,15 +521,28 @@ export function defaultRun(command, args, { cwd, env = process.env } = {}) {
   });
 }
 
-/** Default archive member extraction (bsdtar reads tgz and zip/nupkg): the one member whose basename is `fileName`. */
+/**
+ * Default archive member extraction (bsdtar reads tgz and zip/nupkg). A bare `fileName` selects the one member whose basename it is;
+ * a `fileName` containing `/` selects the one member whose full archive path equals it (case-sensitive, leading `./` ignored on both
+ * sides), so archives with the same base name in several directories (ORT DirectML nupkgs) can be addressed. The returned file is
+ * always under `destDir`; callers copy it to their own declared output name, so the member path never decides where anything is written.
+ */
 export function defaultExtractMember({ archive, fileName, destDir, run = defaultRun }) {
+  const wanted = normalizeArchiveMember(fileName);
+  if (wanted.error) fail("STAGE_SIDECAR_EXTRACT_FAILED", `archive member ${JSON.stringify(fileName)} ${wanted.error}`);
   const listing = run("tar", ["-tf", archive], { cwd: path.dirname(archive) });
   if (listing.status !== 0) fail("STAGE_SIDECAR_EXTRACT_FAILED", `cannot list ${archive}`);
-  const members = String(listing.stdout).split(/\r?\n/).map((line) => line.trim()).filter((line) => line && path.posix.basename(line) === fileName);
-  if (members.length !== 1) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${archive} has ${members.length} members named ${fileName}, expected exactly one`);
+  const lines = String(listing.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const members = wanted.byPath
+    ? lines.filter((line) => (line.startsWith("./") ? line.slice(2) : line) === wanted.value)
+    : lines.filter((line) => path.posix.basename(line) === wanted.value);
+  if (members.length !== 1) fail("STAGE_SIDECAR_EXTRACT_FAILED", `${archive} has ${members.length} members ${wanted.byPath ? "at the path" : "named"} ${wanted.value}, expected exactly one`);
   const extracted = run("tar", ["-xf", archive, "-C", destDir, members[0]], { cwd: path.dirname(archive) });
   if (extracted.status !== 0) fail("STAGE_SIDECAR_EXTRACT_FAILED", `cannot extract ${members[0]} from ${archive}`);
-  return path.join(destDir, ...members[0].split("/"));
+  const out = path.join(destDir, ...members[0].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", `member ${members[0]} of ${archive} resolves outside the extraction directory`);
+  return out;
 }
 
 async function defaultFetchBytes(url) {
@@ -900,6 +935,10 @@ async function stageOnnxRuntimeSlice(entry, ctx, loaded, t, { destDir } = {}) {
   });
   for (const { source } of notices) if (!fs.existsSync(source)) fail("STAGE_SIDECAR_NOTICE_MISSING", `notice file not found: ${source}`);
 
+  // The archive member is the catalog's archive.member (an archive path) when present, else the library file name; the output name never comes from it.
+  const member = row.archive.member ?? row.artifactFileName;
+  const memberCheck = normalizeArchiveMember(member);
+  if (memberCheck.error) fail("STAGE_SIDECAR_NOT_APPROVED", `the ${where} row ${row.id} has an invalid archive member ${JSON.stringify(member)}: ${memberCheck.error}`);
   const outName = entry.as ?? row.artifactFileName;
   const dest = path.resolve(appRoot, destDir ?? entry.resourceDir, outName);
   if (fs.existsSync(dest) && sha256Of(fs.readFileSync(dest)) === row.sha256) {
@@ -915,9 +954,9 @@ async function stageOnnxRuntimeSlice(entry, ctx, loaded, t, { destDir } = {}) {
     }
     const scratch = ctx.makeTempDir();
     try {
-      const library = await ctx.extractMember({ archive, fileName: row.artifactFileName, destDir: scratch });
+      const library = await ctx.extractMember({ archive, fileName: member, destDir: scratch });
       const actual = sha256Of(fs.readFileSync(library));
-      if (actual !== row.sha256) fail("STAGE_SIDECAR_HASH_MISMATCH", `${row.artifactFileName} extracted as ${actual}, the catalog pins ${row.sha256}; nothing staged`, { expected: row.sha256, actual });
+      if (actual !== row.sha256) fail("STAGE_SIDECAR_HASH_MISMATCH", `${member} extracted as ${actual}, the catalog pins ${row.sha256}; nothing staged`, { expected: row.sha256, actual });
       copyInto(ctx, library, dest, { executable: false });
     } finally {
       ctx.removeDir(scratch);
@@ -1042,7 +1081,7 @@ async function ensureCachedDownload(ctx, { url, sha256, size }) {
 
 /**
  * A pinned https download. `dest` is copied only from the verified cache entry. With `extract` the download is an archive
- * (zip, tgz): the one member whose base name is `extract` is unpacked (digest-checked against `memberSha256` when given) and
+ * (zip, tgz): the one member whose base name is `extract` (or, when `extract` contains `/`, whose archive path equals it) is unpacked (digest-checked against `memberSha256` when given) and
  * only that member is staged, so no `command` entry or shell is needed to unpack it.
  */
 async function stageRemote(entry, ctx) {

package/swap-helper-bundle.mjs

@@ -1,7 +1,11 @@
 // The Developer-ID-signed `bin/darwin/rightkit-swap` that @rightkit/release ships (Orthic-Labs/rightkit#258).
-// rightkit-swap is the bin target of crates/rightkit-fs (renamex_np RENAME_SWAP). CI has no Apple signing secrets, so
-// @rightkit/release is published through `right-release publish npm --local` on the Mac, which calls
-// `prepareSwapHelper` before packing. install-app calls `assertShippedSwapHelperSigned` before it trusts the helper.
+// rightkit-swap is the bin target of crates/rightkit-fs (renamex_np RENAME_SWAP). Two signing routes produce it:
+// (a) local publish — `right-release publish npm --local` on the Mac calls `prepareSwapHelper` before packing;
+// (b) CI qualification — `publish.yml` build-swap -> sign-swap -> pack (docs/CI.md), where sign-swap imports the
+// Developer ID from the `release` environment secrets. Route (b) stays blocked until root provisions
+// APPLE_CERTIFICATE_BASE64/APPLE_CERTIFICATE_PASSWORD there; exporting that identity needs an Aqua login session
+// (SSH export fails errSecInteractionNotAllowed/-25308 & the signing agent has no key-export capability — never
+// retry either). install-app calls `assertShippedSwapHelperSigned` before it trusts the helper.
 import crypto from "node:crypto";
 import nodeFs from "node:fs";
 import path from "node:path";

package/bin/darwin/rightkit-swap.sign.json

@@ -1,6 +0,0 @@
-{
-  "schema": 1,
-  "sha256": "a41ce13fd3bac31db0230d70bed20db0ed9bf554bdae2255bdf2064589b48f29",
-  "identity": "Developer ID Application: Adrian D'souza (6KLGD3LLKF)",
-  "codesign": "strict-valid"
-}