@rightkit/release 0.2.165 → 0.2.172

package/release.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { access, readFile, readdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn, spawnSync } from "./background-process.mjs";
 import { validateRightKitCargoContract } from "./cargo-contract.mjs";
-import { assertQaBackdoorContract } from "./qa-contract.mjs";
+import { assertCargoProfileContract } from "./cargo-profile-contract.mjs";
+import { assertQaAdoption, assertQaBackdoorContract } from "./qa-contract.mjs";
 import { assertLegalReleaseContract } from "./legal-contract.mjs";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
 import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
@@ -28,6 +30,9 @@ import { verifyNsisEmbeddedBinary } from "./nsis-payload.mjs";
 import { terminateProcessTree } from "./heavy-command.mjs";
 import { materializeHardeningEvidence } from "./hardening-evidence.mjs";
 import { signingReceiptPath } from "./signing-receipts.mjs";
+import { MEDIA_SIDECAR_OFFER_NAME, MEDIA_SIDECAR_RECEIPT_NAME, buildMediaSidecarReceipt, macSidecarSigningProblems, mediaSidecarNestedCode, planMediaSidecar, sidecarFileEvidence, validateMediaSidecarConfig, verifyStagedSidecars, writeMediaSidecarNotices } from "./media-sidecar.mjs";
+import { loadSidecarCatalog } from "./media-sidecar-catalog.mjs";
+import { EXTERNAL_BIN_RECEIPT_NAME, buildExternalBinReceipt, externalBinNestedCode, planExternalBin, validateExternalBinConfig, verifyStagedExternalBins } from "./external-bin.mjs";
 import { notarizeAppBundle, validateNotarizationReceipt } from "./macos-notarization.mjs";
 import { MACOS_PORTABLE_SIGNING_CONTRACT } from "./macos-signing-contract.mjs";
 import { fileEvidence } from "./macos-file-evidence.mjs";
@@ -42,6 +47,7 @@ import { assertNoQaControl, assertNoWebBundleMocks } from "./qa-control-scan.mjs
 import { assertNoForbiddenBuildFeatures } from "./qa-build-features.mjs";
 import { assertNoReleaseSwitches, commandTokens, resolveFeatureClosure } from "./release-switch-scan.mjs";
 import { devtoolsEvidence, resolveDevtoolsAllowance } from "./devtools-policy.mjs";
+import { runAndroidRelease, validateAndroidTarget } from "./android-release.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const HARDENING_SCAN = path.resolve(TOOL_ROOT, "hardeningscan.mjs");
@@ -87,6 +93,7 @@ const SWIFT_PRIVATE_PARALLEL_DEV_MAC = {
 };
 const SWIFT_PRIVATE_JOBS = new Map([
   ["ci.yml", new Map([["ci", SWIFT_PRIVATE_ANY_PROFILE], ["dev-artifact-mac", SWIFT_PRIVATE_PARALLEL_DEV_MAC], ["test", SWIFT_PRIVATE_NODE_PROFILE]])],
+  ["swift-check.yml", new Map([["swift-check", SWIFT_PRIVATE_ANY_PROFILE]])],
   ["qualification.yml", new Map([["qualification", SWIFT_PRIVATE_ANY_PROFILE]])],
   ["release-candidate.yml", new Map([["candidate", SWIFT_PRIVATE_ANY_PROFILE]])],
   ["regenerate.yml", new Map([["regenerate", SWIFT_PRIVATE_ANY_PROFILE]])],
@@ -158,6 +165,16 @@ const config = (await import(pathToFileURL(configPath))).default;
 if (!config) usage(2, `config did not export default: ${configPath}`);
 if (config.schema !== 1) fail(`unsupported config schema: ${config.schema ?? "<missing>"} (expected 1)`);
 
+// Hosted-workflow policy patterns: defined before the top-level await below uses them.
+const SIGN_EXISTING_SECRETS = new Set(["APPLE_CERTIFICATE_BASE64", "APPLE_CERTIFICATE_PASSWORD", "APPLE_KEYCHAIN_PASSWORD"]);
+const SIGN_EXISTING_ACTIONS = new Set(["actions/checkout", "actions/setup-node", "pnpm/action-setup", "actions/download-artifact", "actions/upload-artifact"]);
+const SIGN_EXISTING_RIGHT_RELEASE_COMMANDS = new Set(["ownership", "sign-dev-artifact"]);
+const SIGN_EXISTING_BUILD_RE = /\b(?:cargo|rustc|xcodebuild|tauri|cmake|msbuild|gradle|notarytool|stapler)\b|swift build|right-release build|--release\b|\b(?:npm|pnpm|yarn) (?:run|build)\b/;
+const SIGN_EXISTING_GUARD = "  private-repo-guard:\n    runs-on: ubuntu-24.04\n    steps:\n      - name: Refuse private repository\n        if: ${{ github.event.repository.private }}\n        run: exit 1\n";
+const SIGN_EXISTING_JOB_HEAD = /^(?:    #[^\n]*\n)*    needs: \[private-repo-guard\]\n    if: \$\{\{ github\.event_name == 'workflow_dispatch' && github\.ref_name == github\.event\.repository\.default_branch \}\}\n    environment: [A-Za-z0-9][A-Za-z0-9._-]*\n    runs-on: (?:macos|xcode)-[A-Za-z0-9._-]+\n(?:    timeout-minutes: \d+\n)?    permissions:\n      contents: read\n      actions: read\n    steps:\n/;
+// Head of the managed `supersede` job (the span starts at the preceding newline, before the job key line).
+const SUPERSEDE_JOB_HEAD = /^\n  supersede:\n    needs: \[private-repo-guard\]\n    if: \$\{\{ github\.event_name == 'push' && github\.ref_name == github\.event\.repository\.default_branch \}\}\n    runs-on: ubuntu-[0-9.]+\n    timeout-minutes: \d+\n    permissions:\n      contents: read\n      actions: write\n    steps:\n/;
+
 const root = path.dirname(configPath);
 const workdir = path.resolve(root, config.workdir ?? ".");
 const nativeLayout = resolveNativeCargoLayout({ appRoot: root, config });
@@ -168,6 +185,10 @@ if (!(resolveProjectType({ appRoot: root, config, target: config.targets?.[opts.
   await validateRightKitPackageContract(root, config.app, config.hostedWorkflows);
 }
 validateRightKitCargoContract(root, RIGHTKIT_CARGO_ALLOWED, config.app ?? path.basename(root));
+// One standard dev profile and panic = "unwind" in every app (templates/cargo-profiles.toml).
+assertCargoProfileContract(root, config.app ?? path.basename(root));
+// RightKit QA is mandatory for every app (also SwiftPM apps without a package.json): no QA lane refuses the release.
+assertQaAdoption({ appRoot: root, app: config.app });
 const target = config.targets?.[opts.platform];
 if (!target) fail(`${config.app ?? "app"} has no ${opts.platform} release target`);
 const legalContract = config.legal
@@ -177,6 +198,16 @@ if (target.signed !== true) {
   fail(`${config.app ?? "app"} ${opts.platform} must declare signed: true; unsigned release targets are forbidden`);
 }
 let macSigning; // validated macOS sign.prePackageFiles / sign.nestedCode (mac only)
+let mediaSidecarConfig = null; // validated targets.<mac|win>.mediaSidecar (rightkit-ffmpeg decode sidecar)
+if (target.mediaSidecar !== undefined) {
+  if (opts.platform !== "mac" && opts.platform !== "win") fail(`${config.app ?? "app"} ${opts.platform} does not support mediaSidecar (mac and win only)`);
+  try { mediaSidecarConfig = validateMediaSidecarConfig(target.mediaSidecar, { platform: opts.platform }); } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
+}
+let externalBinConfig = null; // validated targets.<mac|win>.externalBin (generic Tauri externalBin sidecars, #270)
+if (target.externalBin !== undefined) {
+  if (opts.platform !== "mac" && opts.platform !== "win") fail(`${config.app ?? "app"} ${opts.platform} does not support externalBin (mac and win only)`);
+  try { externalBinConfig = validateExternalBinConfig(target.externalBin, { platform: opts.platform, reservedNames: mediaSidecarConfig?.tools ?? [] }); } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} ${error.message}`); }
+}
 if (opts.platform === "win") {
   const isNsis = target.signingContract === WINDOWS_NSIS_SIGNING_CONTRACT;
   const isPortable = target.signingContract === WINDOWS_PORTABLE_SIGNING_CONTRACT;
@@ -198,7 +229,10 @@ if (opts.platform === "mac") {
   if (target.signingContract !== MACOS_PORTABLE_SIGNING_CONTRACT) fail(`${config.app ?? "app"} mac must declare signingContract: ${MACOS_PORTABLE_SIGNING_CONTRACT}`);
   if (!target.prePackage?.cmd) fail(`${config.app ?? "app"} mac must declare prePackage to materialize Developer ID signing files`);
   if (!target.sign?.prePackageFiles?.length) fail(`${config.app ?? "app"} mac must declare at least one sign.prePackageFiles`);
-  try { macSigning = validateMacSigningConfig(target.sign, { root }); } catch (error) { fail(`${config.app ?? "app"} mac ${error.message}`); }
+  const macSignConfig = mediaSidecarConfig || externalBinConfig
+    ? { ...target.sign, nestedCode: { ...(mediaSidecarConfig ? mediaSidecarNestedCode(mediaSidecarConfig) : {}), ...(externalBinConfig ? externalBinNestedCode(externalBinConfig) : {}), ...(target.sign.nestedCode ?? {}) } }
+    : target.sign;
+  try { macSigning = validateMacSigningConfig(macSignConfig, { root }); } catch (error) { fail(`${config.app ?? "app"} mac ${error.message}`); }
   if (!target.notarize?.file) fail(`${config.app ?? "app"} mac must declare notarize.file`);
   if (target.notarize.appBeforePackage && !target.notarize.app) fail(`${config.app ?? "app"} mac notarize.appBeforePackage requires notarize.app`);
   if (target.notarize.staple === false && (target.notarize.app || /\.(dmg|pkg)$/i.test(target.notarize.file))) {
@@ -214,6 +248,10 @@ if (opts.platform === "mac") {
     } catch (error) { fail(`${config.app ?? "app"} mac targets.mac.dmg.spec: ${error.message}`); }
   }
 }
+let androidTarget; // validated Android AAB target (android only; see android-release.mjs)
+if (opts.platform === "android") {
+  try { androidTarget = validateAndroidTarget(target, { root }); } catch (error) { fail(`${config.app ?? "app"} android ${error.message}`); }
+}
 if (opts.upload && target.publishBlocked) fail(`${config.app ?? "app"} ${opts.platform} publish blocked: ${target.publishBlocked}`);
 /**
  * Assemble preflight inputs from the app's own files. Kept here (not in
@@ -316,6 +354,7 @@ try {
     { label: "nativeAssembly.packageHook", command: nativeAssembly?.packageHook },
     { label: "nativeAssembly.finalizer", command: nativeFinalizer },
     { label: "target.postSign", command: target.postSign },
+    { label: "target.gradle", command: target.gradle },
   ] });
 } catch (error) { fail(error.message); }
 
@@ -337,7 +376,7 @@ try {
       rust: config.releaseSwitches?.rust,
       features: config.releaseSwitches?.features ?? [],
       triple: target.cargoTarget ?? target.targetTriple ?? target.rustTarget,
-      commandTexts: [target.prePackage, target.package, nativeAssembly?.packageHook, nativeFinalizer, target.postSign],
+      commandTexts: [target.prePackage, target.package, nativeAssembly?.packageHook, nativeFinalizer, target.postSign, target.gradle],
     });
     if (closure.skipped) console.log(`right-release: feature closure skipped (${closure.skipped})`);
     else treeText = closure.treeText;
@@ -346,7 +385,7 @@ try {
     console.log(`right-release: dry run: ${error.message}`);
   }
   // remoteHost: rightkit-daemon `remote` is refused in the closure unless the app declares releaseSwitches.remoteHost: true.
-  const closureInput = { treeText, remoteHost: config.releaseSwitches?.remoteHost, commands: [target.prePackage, target.package, nativeAssembly?.packageHook, nativeFinalizer, target.postSign].filter(Boolean).map((c) => commandTokens(c)) };
+  const closureInput = { treeText, remoteHost: config.releaseSwitches?.remoteHost, commands: [target.prePackage, target.package, nativeAssembly?.packageHook, nativeFinalizer, target.postSign, target.gradle].filter(Boolean).map((c) => commandTokens(c)) };
   if (releaseSwitchInventoryText != null) {
     assertNoReleaseSwitches({ ...closureInput, sourceRoot: root, inventoryText: releaseSwitchInventoryText, appForbid: config.releaseSwitches?.forbid ?? [] }, "source switch inventory");
   } else if (treeText != null || closureInput.commands.length) {
@@ -360,7 +399,7 @@ try {
 const releaseLock = acquireReleaseLock(root, config.app ?? path.basename(root), opts.platform, opts.tier);
 const mode = "package";
 const command = target.package;
-if (!command && !packageCommandOptional(target, resolveProjectType({ appRoot: root, config, target }))) fail(`${config.app ?? "app"} has no ${opts.platform} ${mode} command`);
+if (!command && opts.platform !== "android" && !packageCommandOptional(target, resolveProjectType({ appRoot: root, config, target }))) fail(`${config.app ?? "app"} has no ${opts.platform} ${mode} command`);
 if (opts.upload && !target.publish && !target.upload) {
   fail(`${config.app ?? "app"} has no ${opts.platform} upload config`);
 }
@@ -397,8 +436,14 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
   if (!built.dryRun) assertNoQaControlBinaries("msix package", [options.out], { requireBinary: true });
 } else if (opts.platform === "win") {
   const rawFiles = target.sign.prePackageFiles.map((p) => path.resolve(root, p));
+  const sidecarPlan = await prepareMediaSidecar(root);
+  const externalPlan = await prepareExternalBin(root);
   await runCommand(target.prePackage, root);
   for (const file of rawFiles) await mustExist(file, `missing raw EXE signing artifact: ${file}`);
+  const sidecarPre = sidecarPlan && !opts.dryRun ? verifyStagedSidecars(sidecarPlan) : [];
+  const externalPre = externalPlan && !opts.dryRun ? verifyExternalBins(externalPlan) : [];
+  const sidecarFiles = [...sidecarPre, ...externalPre].map((file) => file.stagedPath);
+  assertNoQaControlBinaries("windows media sidecar and externalBin", sidecarFiles, { prePack: true });
   // Before signing and packaging: the raw EXE is uncompressed, so a QA control server is visible here.
   assertNoQaControlBinaries("windows raw EXE", rawFiles, { requireBinary: true, prePack: true });
   // The marker must reach its FINAL value before signing. Tauri rewrites it during
@@ -410,7 +455,15 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
   for (const receipt of bundleMarkerReceipts) {
     console.log(`right-release: bundle marker ${receipt.bundle} ${receipt.alreadyPatched ? "already applied" : "applied"} at offset ${receipt.offset} in ${path.basename(receipt.file)}`);
   }
-  await signWindows(rawFiles, "raw-exe", root);
+  await signWindows([...rawFiles, ...sidecarFiles], "raw-exe", root);
+  if (sidecarPlan && !opts.dryRun) {
+    const signed = Object.fromEntries(sidecarPre.map((file) => [file.tool, sidecarFileEvidence(file.stagedPath)]));
+    writeMediaSidecarReceipt(root, buildMediaSidecarReceipt(sidecarPlan, sidecarPre, signed));
+  }
+  if (externalPlan && !opts.dryRun) {
+    const signed = Object.fromEntries(externalPre.map((file) => [file.tool, sidecarFileEvidence(file.stagedPath)]));
+    writeExternalBinReceipt(root, buildExternalBinReceipt(externalPlan, externalPre, signed));
+  }
   if (nativeAssembly?.packageHook && !hasNativeTargetSpecificPrePackage(target, nativeAssembly.packageHook)) {
     await runCommand(nativeAssembly.packageHook, root);
   }
@@ -424,6 +477,8 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
     });
   }
 } else if (opts.platform === "mac") {
+  const sidecarPlan = await prepareMediaSidecar(root, { stage: runMacPhase("prepackage") });
+  const externalPlan = await prepareExternalBin(root, { stage: runMacPhase("prepackage") });
   if (runMacPhase("prepackage")) await runCommand(target.prePackage, root);
   // Resolve after prePackage: with storage governance the artifact may live only in RIGHT_RELEASE_ARTIFACT_DIR.
   const signingEntries = macSigning.entries.map((entry) => ({ ...entry, file: resolveReleaseArtifactPath(root, entry.file) }));
@@ -437,9 +492,29 @@ if (opts.platform === "win" && target.signingContract === MSIX_SIGNING_CONTRACT)
   }
   if (runMacPhase("sign")) {
     await signMacos(signingEntries, root, "signing", macSigning.nestedCode);
+    if (sidecarPlan && !opts.dryRun) {
+      const app = signingEntries.find((entry) => /\.app\/?$/.test(entry.file));
+      if (!app) fail("mediaSidecar on macOS needs an .app entry in sign.prePackageFiles");
+      writeMediaSidecarReceipt(root, finishMacSidecar(sidecarPlan, app.file, root));
+    }
+    if (externalPlan && !opts.dryRun) {
+      const app = signingEntries.find((entry) => /\.app\/?$/.test(entry.file));
+      if (!app) fail("externalBin on macOS needs an .app entry in sign.prePackageFiles");
+      writeExternalBinReceipt(root, finishMacExternalBin(externalPlan, app.file, root));
+    }
     // Opt-in (notarize.appBeforePackage): staple the .app itself before the package step copies it into the DMG.
     if (target.notarize.appBeforePackage) await notarizeAppBeforePackage(root);
   }
+} else if (opts.platform === "android") {
+  // Gradle bundleRelease with upload-key signing (secrets by file path only), then the in-process AAB scan, signer pin and receipt.
+  await runAndroidRelease({
+    root, app: config.app ?? path.basename(root), target: androidTarget, dryRun: opts.dryRun,
+    runGradle: (gradle, env) => runCommand(gradle, root, { env }),
+    resolveArtifact: (declared) => resolveReleaseArtifactPath(root, declared),
+    scanFiles: (label, files, scanOptions) => assertNoQaControlBinaries(label, files, scanOptions),
+    receiptDir: path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(root, ".right-release", "receipts")),
+    allowContentOnlyDevtools: devtoolsAllowance.mode === "content-only",
+  });
 } else if (nativeAssembly) {
   if (nativeAssembly.packageHook) await runCommand(nativeAssembly.packageHook, root);
   if (nativeFinalizer) {
@@ -995,6 +1070,83 @@ function swiftPrivateSecretRefusal({ source, workflow, manifest, lanes, name, in
   return null;
 }
 
+// @rightkit/ci `sign-existing` lane (0.2.49, Orthic-Labs/rightkit#257): signs an already-qualified artifact of another run.
+// It is accepted only in its exact rendered shape: workflow_dispatch only; jobs private-repo-guard and sign-existing only;
+// the default-branch gate behind the private-repo guard; the protected environment; contents: read and actions: read
+// (workflow and job); exactly the three Apple Developer ID secrets, referenced inside the sign-existing job only; pinned
+// allowlisted actions; and no build, notarization or release step. Returns null when the shape matches, else the reason.
+
+function signExistingRefusal(source) {
+  const jobsAt = source.indexOf("\njobs:\n");
+  if (jobsAt < 0) return "it declares no jobs";
+  const head = source.slice(0, jobsAt + 1);
+  const jobs = source.slice(jobsAt + 7);
+  const onBlock = /^on:\n((?:[ \t]+[^\n]*\n|\n)*)/m.exec(head)?.[1] ?? "";
+  const triggers = [...onBlock.matchAll(/^  ([A-Za-z_]+):/gm)].map((match) => match[1]);
+  if (triggers.length !== 1 || triggers[0] !== "workflow_dispatch") return "it must be triggered by workflow_dispatch only";
+  if (!/^permissions:\n  contents: read\n  actions: read\n(?!  )/m.test(head)) return "workflow permissions must be exactly contents: read and actions: read";
+  const names = [...jobs.matchAll(/^  ([A-Za-z0-9_-]+):[ \t]*$/gm)].map((match) => match[1]);
+  if (names.join(",") !== "private-repo-guard,sign-existing") return `jobs must be exactly private-repo-guard and sign-existing, got ${names.join(", ") || "none"}`;
+  const marker = "\n  sign-existing:\n";
+  const guard = jobs.slice(0, jobs.indexOf(marker) + 1);
+  if (!guard.startsWith(SIGN_EXISTING_GUARD) || guard.length !== SIGN_EXISTING_GUARD.length + (guard.endsWith("\n\n") ? 1 : 0)) return "the private-repo-guard job is not the managed guard";
+  const sign = jobs.slice(jobs.indexOf(marker) + marker.length);
+  if (!SIGN_EXISTING_JOB_HEAD.test(sign)) return "the sign-existing job must need only private-repo-guard, run only for workflow_dispatch on the default branch in an environment on a macOS runner, with job permissions exactly contents: read and actions: read";
+  const secrets = [...source.matchAll(/\bsecrets\.([A-Z0-9_]+)/gi)].map((match) => match[1]);
+  const signSecrets = [...sign.matchAll(/\bsecrets\.([A-Z0-9_]+)/gi)].map((match) => match[1]);
+  if (secrets.length !== signSecrets.length || new Set(secrets).size !== SIGN_EXISTING_SECRETS.size || secrets.some((name) => !SIGN_EXISTING_SECRETS.has(name))) return "it must reference exactly the three Apple Developer ID secrets, inside the sign-existing job";
+  for (const [, action] of sign.matchAll(/^\s*(?:- )?uses: (\S+)/gm)) {
+    const [name, pin] = action.split("@");
+    if (!SIGN_EXISTING_ACTIONS.has(name) || !/^[0-9a-f]{40}$/.test(pin ?? "")) return `action ${action} is not an allowed commit-pinned action`;
+  }
+  for (const [, command] of source.matchAll(/right-release\s+([A-Za-z][A-Za-z-]*)/g)) {
+    if (!SIGN_EXISTING_RIGHT_RELEASE_COMMANDS.has(command)) return `right-release ${command} is not allowed; the lane only signs an existing artifact`;
+  }
+  if (!/right-release sign-dev-artifact /.test(sign)) return "it must run right-release sign-dev-artifact";
+  const build = SIGN_EXISTING_BUILD_RE.exec(sign);
+  if (build) return `it must not build, notarize or release (found ${JSON.stringify(build[0])})`;
+  return null;
+}
+
+// The checks above are a denylist backstop. The authority is byte equality with what @rightkit/ci renders for this repository's
+// manifest: an extra step (for example one that copies a secret into `env:` and posts it somewhere, or one that interpolates
+// `${{ inputs.* }}` straight into `run:`) passes every pattern above but can never equal the managed render.
+// The renderer comes from this monorepo's own packages/ci when present, else from the repository's installed @rightkit/ci; with
+// neither the file is refused, because an unverifiable sign-existing.yml must not be accepted.
+async function loadRightKitCiRenderer(root) {
+  const candidates = [pathToFileURL(fileURLToPath(new URL("../ci/sync.mjs", import.meta.url))).href];
+  try {
+    candidates.push(pathToFileURL(createRequire(path.join(root, "package.json")).resolve("@rightkit/ci/sync.mjs")).href);
+  } catch {
+    // not installed in the repository; the sibling candidate may still apply
+  }
+  for (const href of candidates) {
+    try {
+      if (href.startsWith("file:") && !existsSync(fileURLToPath(href))) continue;
+      const loaded = await import(href);
+      if (typeof loaded.renderLanes === "function") return loaded.renderLanes;
+    } catch {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+async function signExistingRenderRefusal(root, manifest, source) {
+  const renderLanes = await loadRightKitCiRenderer(root);
+  if (!renderLanes) return "the @rightkit/ci renderer is not available (install @rightkit/ci as a devDependency), so the file cannot be compared with its managed render";
+  let expected;
+  try {
+    expected = renderLanes(manifest, root).find((lane) => lane.filename === "sign-existing.yml")?.content;
+  } catch (error) {
+    return `the manifest does not render a sign-existing lane (${error.message})`;
+  }
+  if (typeof expected !== "string") return "the manifest does not render a sign-existing lane";
+  if (source.replace(/\r\n?/g, "\n") !== expected.replace(/\r\n?/g, "\n")) return "the file is not byte-for-byte the @rightkit/ci render of this repository's .rightgit.json (run right-git sync); extra, changed or reordered steps are refused";
+  return null;
+}
+
+
 async function validateHostedWorkflows(root, appName, workflows, policy) {
   if (policy !== "right-git-ci-only") {
     fail(`${appName} hosted workflow files are forbidden: ${workflows.join(", ")}`);
@@ -1008,15 +1160,15 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
   }
   const lanes = manifest?.lanes;
   // Mirrors the `lanes` enum in @rightkit/ci manifest.schema.json.
-  const safeLanes = new Set(["ci", "qualification", "package-smoke", "release-candidate", "publish-npm", "publish-package-managers", "regenerate"]);
+  const safeLanes = new Set(["ci", "swift-check", "qualification", "package-smoke", "release-candidate", "publish-npm", "publish-package-managers", "regenerate", "sign-existing"]);
   if (manifest?.schemaVersion !== 1
     || manifest?.compile !== "github-actions-only"
     || !Array.isArray(lanes)
     || lanes.length === 0
-    || !lanes.includes("ci")
+    || !(lanes.includes("ci") || lanes.includes("swift-check"))
     || new Set(lanes).size !== lanes.length
     || lanes.some((lane) => !safeLanes.has(lane))) {
-    fail(`${appName} right-git-ci-only policy requires compile=github-actions-only plus unique .rightgit.json lanes drawn from [${[...safeLanes].map((lane) => `"${lane}"`).join(", ")}] and including "ci"`);
+    fail(`${appName} right-git-ci-only policy requires compile=github-actions-only plus unique .rightgit.json lanes drawn from [${[...safeLanes].map((lane) => `"${lane}"`).join(", ")}] and including "ci" or "swift-check"`);
   }
   const expectedWorkflows = lanes.map((lane) => `${lane}.yml`).sort();
   if (JSON.stringify(workflows) !== JSON.stringify(expectedWorkflows)) {
@@ -1056,7 +1208,8 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
       `${job}:\\n    needs: \\[candidate\\]\\n    if: \\$\\{\\{ startsWith\\(github\\.ref, 'refs\\/tags\\/v'\\)(?: \\|\\| \\(github\\.event_name == 'workflow_dispatch' && inputs\\.signed_qualification == true\\))? \\}\\}`,
     );
     const admittedSigningGate = (job) => new RegExp(
-      `${job}:\\n    needs: \\[admission, candidate\\]\\n    if: \\$\\{\\{ needs\\.admission\\.outputs\\.signed_qualification == 'true' \\}\\}`,
+      // `, dev-qualification` (@rightkit/ci candidate.devQualification, #107) only adds a gate.
+      `${job}:\\n    needs: \\[admission, candidate(?:, dev-qualification)?\\]\\n    if: \\$\\{\\{ needs\\.admission\\.outputs\\.signed_qualification == 'true' \\}\\}`,
     );
     const protectedWindowsSigning = workflow === "release-candidate.yml"
       && manifest?.candidate?.signWindows === true
@@ -1083,6 +1236,16 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
       && /git push origin "HEAD:refs\/heads\/\$branch"\n/.test(regenerateSource)
       && !/git push(?![^\n]*"HEAD:refs\/heads\/\$branch")/.test(regenerateSource);
     const allowedRegeneratePermissions = new Set(["contents", "pull-requests"]);
+    // @rightkit/ci `supersede` job (one CI run per repo, #338): `actions: write` is accepted only for the
+    // job whose head matches the managed shape exactly (push to the default branch only, needs only
+    // private-repo-guard, contents: read plus actions: write, no action `uses:`), and only in ci.yml when
+    // the manifest has not opted into `concurrency.mainPushes: "queue"` (which renders no such job).
+    const supersedeSpan = workflow === "ci.yml" ? jobSpan("supersede") : null;
+    const supersedeSource = supersedeSpan ? source.slice(supersedeSpan.start, supersedeSpan.end) : "";
+    const protectedSupersede = workflow === "ci.yml"
+      && manifest?.concurrency?.mainPushes !== "queue"
+      && SUPERSEDE_JOB_HEAD.test(supersedeSource)
+      && !/^\s*-?\s*uses:/m.test(supersedeSource);
     const devMacSpan = workflow === "ci.yml" ? jobSpan("dev-mac-sign") : null;
     const devMacSource = devMacSpan ? source.slice(devMacSpan.start, devMacSpan.end) : "";
     // `mac: "notarize"` additionally allows the notary API key secrets; the
@@ -1093,6 +1256,16 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
     const protectedDevMacSigning = workflow === "ci.yml"
       && (manifest?.devArtifact?.mac === "sign" || manifest?.devArtifact?.mac === "notarize")
       && /dev-mac-sign:\n(?:    #[^\n]*\n)*    needs: \[ci\]\n    if: \$\{\{ github\.event_name == 'push' && github\.ref_name == github\.event\.repository\.default_branch \}\}\n    environment: /.test(devMacSource);
+    // @rightkit/ci `sign-existing` lane: any deviation from the exact managed shape is refused outright.
+    const signExistingSpan = workflow === "sign-existing.yml" ? jobSpan("sign-existing") : null;
+    let protectedSignExisting = false;
+    if (workflow === "sign-existing.yml") {
+      const reason = manifest?.signExisting && typeof manifest.signExisting === "object"
+        ? (signExistingRefusal(source) ?? await signExistingRenderRefusal(root, manifest, source))
+        : "the manifest declares no signExisting";
+      if (reason !== null) fail(`${appName} right-git managed sign-existing.yml is not the protected sign-existing shape: ${reason}`);
+      protectedSignExisting = true;
+    }
     // @rightkit/ci `swift.privatePackages` credential: allowed only in the workflow/job pairs and on the
     // env lines listed with SWIFT_PRIVATE_JOBS; swiftPrivateSecretRefusal explains every other reference.
     const releaseChain = workflow === "release-candidate.yml" ? manifest?.candidate?.releaseChain : undefined;
@@ -1116,12 +1289,14 @@ async function validateHostedWorkflows(root, appName, workflows, policy) {
     const refusedSecrets = requestedSecrets
       .filter(({ name, index }) => !(protectedMacosSigning && inside(index, macosSpan) && allowedMacosSecrets.has(name))
         && !(protectedDevMacSigning && inside(index, devMacSpan) && allowedDevMacSecrets.has(name))
+        && !(protectedSignExisting && inside(index, signExistingSpan) && SIGN_EXISTING_SECRETS.has(name))
         && !(protectedReleasePublish && inside(index, publishSpan) && allowedReleaseSecrets.has(name)))
       .map(({ name, index }) => swiftPrivateSecretRefusal({ source, workflow, manifest, lanes, name, index }))
       .filter((reason) => reason !== null);
     if (/^\s*permissions:\s*write-all\s*$/mi.test(source)
       || writePermissions.some(({ name, index }) => {
         if (protectedRegenerate && inside(index, regenerateSpan) && allowedRegeneratePermissions.has(name)) return false;
+        if (protectedSupersede && inside(index, supersedeSpan) && name === "actions") return false;
         return name === "id-token"
           ? !(protectedWindowsSigning && inside(index, windowsSpan))
           : name !== "contents" || !protectedReleasePublish || !inside(index, publishSpan);
@@ -1164,6 +1339,99 @@ function expandEnv(value) {
   return String(value).replace(/%([^%]+)%/g, (_, name) => process.env[name] ?? "");
 }
 
+// rightkit-ffmpeg decode sidecar (media-sidecar.mjs): plan from the catalog the app compiled against, write the LGPL
+// notices and the source offer, optionally run the app's stage command, and (before signing) check the staged files.
+async function prepareMediaSidecar(root, { stage = true } = {}) {
+  if (!mediaSidecarConfig) return null;
+  let plan;
+  try {
+    const loaded = loadSidecarCatalog({ config: mediaSidecarConfig, root, manifestPath: nativeLayout.manifestPath });
+    plan = planMediaSidecar({ config: mediaSidecarConfig, ...loaded, root });
+  } catch (error) { fail(`${config.app ?? "app"} ${opts.platform} mediaSidecar: [${error.code ?? "ERROR"}] ${error.message}`); }
+  console.log(`right-release: media sidecar ${plan.rows.map((row) => row.id).join(", ")}`);
+  if (opts.dryRun) {
+    console.log(`dry-run: would write ${plan.notices.length + 1} notice file(s) to ${mediaSidecarConfig.notices.dir} and expect ${plan.files.map((file) => path.basename(file.stagedPath)).join(", ")} in ${mediaSidecarConfig.stageDir}`);
+    return plan;
+  }
+  if (stage) {
+    try { writeMediaSidecarNotices(plan); } catch (error) { fail(`mediaSidecar: [${error.code ?? "ERROR"}] ${error.message}`); }
+    if (mediaSidecarConfig.stage) await runCommand(mediaSidecarConfig.stage, root);
+  }
+  return plan;
+}
+
+function finishMacSidecar(plan, appPath, root) {
+  let preSign;
+  const signed = {};
+  const checked = [];
+  try { preSign = verifyStagedSidecars(plan); } catch (error) { fail(`mediaSidecar: [${error.code ?? "ERROR"}] ${error.message}`); }
+  for (const file of plan.files) {
+    const inBundle = path.join(appPath, ...file.bundlePath.split("/"));
+    if (!existsSync(inBundle)) fail(`mediaSidecar: ${file.tool} is not inside the built app at ${file.bundlePath}; list it under Tauri externalBin`);
+    signed[file.tool] = sidecarFileEvidence(inBundle);
+    checked.push({ file: inBundle, sha256: signed[file.tool].sha256 });
+  }
+  const nestedReceipt = path.resolve(path.dirname(macosReceiptPath(root, "signing")), "macos-signing-nested.json");
+  let nested;
+  try { nested = JSON.parse(readFileSync(nestedReceipt, "utf8")); } catch { fail(`mediaSidecar: missing nested macOS signing receipt ${nestedReceipt}`); }
+  const problems = macSidecarSigningProblems(nested, checked);
+  if (problems.length) fail(`mediaSidecar: sidecar signing evidence rejected: ${problems.join("; ")}`);
+  const bundled = readdirSync(appPath, { recursive: true }).map(String);
+  if (!bundled.some((entry) => path.basename(entry) === MEDIA_SIDECAR_OFFER_NAME)) {
+    fail(`mediaSidecar: ${MEDIA_SIDECAR_OFFER_NAME} is not inside the built app; add ${mediaSidecarConfig.notices.dir} to the Tauri bundle resources`);
+  }
+  return buildMediaSidecarReceipt(plan, preSign, signed);
+}
+
+// Generic Tauri externalBin sidecars (external-bin.mjs, #270): the app's own stage command writes <name>-<triple>[.exe].
+async function prepareExternalBin(root, { stage = true } = {}) {
+  if (!externalBinConfig) return null;
+  const plan = planExternalBin({ config: externalBinConfig, root });
+  console.log(`right-release: externalBin ${plan.files.map((file) => path.basename(file.stagedPath)).join(", ")}`);
+  if (opts.dryRun) {
+    console.log(`dry-run: would expect ${plan.files.map((file) => path.basename(file.stagedPath)).join(", ")} in ${externalBinConfig.stageDir}`);
+    return plan;
+  }
+  if (stage && externalBinConfig.stage) await runCommand(externalBinConfig.stage, root);
+  return plan;
+}
+
+function verifyExternalBins(plan) {
+  try { return verifyStagedExternalBins(plan); } catch (error) { fail(`externalBin: [${error.code ?? "ERROR"}] ${error.message}`); }
+}
+
+function finishMacExternalBin(plan, appPath, root) {
+  const preSign = verifyExternalBins(plan);
+  const signed = {};
+  const checked = [];
+  for (const file of plan.files) {
+    const inBundle = path.join(appPath, ...file.bundlePath.split("/"));
+    if (!existsSync(inBundle)) fail(`externalBin: ${file.tool} is not inside the built app at ${file.bundlePath}; list it under Tauri externalBin`);
+    signed[file.tool] = sidecarFileEvidence(inBundle);
+    checked.push({ file: inBundle, sha256: signed[file.tool].sha256 });
+  }
+  const nestedReceipt = path.resolve(path.dirname(macosReceiptPath(root, "signing")), "macos-signing-nested.json");
+  let nested;
+  try { nested = JSON.parse(readFileSync(nestedReceipt, "utf8")); } catch { fail(`externalBin: missing nested macOS signing receipt ${nestedReceipt}`); }
+  const problems = macSidecarSigningProblems(nested, checked);
+  if (problems.length) fail(`externalBin: signing evidence rejected: ${problems.join("; ")}`);
+  return buildExternalBinReceipt(plan, preSign, signed);
+}
+
+function writeExternalBinReceipt(root, receipt) {
+  const file = path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(root, ".right-release", "receipts"), EXTERNAL_BIN_RECEIPT_NAME);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+  console.log(`right-release: externalBin receipt ${file}`);
+}
+
+function writeMediaSidecarReceipt(root, receipt) {
+  const file = path.resolve(process.env.RIGHT_RELEASE_STATE_ROOT ?? path.join(root, ".right-release", "receipts"), MEDIA_SIDECAR_RECEIPT_NAME);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+  console.log(`right-release: media sidecar receipt ${file}`);
+}
+
 async function signWindows(files, phase, root) {
   const args = [SIGN_WINDOWS];
   const receipt = windowsReceiptPath(root, phase);
@@ -1181,13 +1449,13 @@ function windowsReceiptPath(root, phase) {
   return signingReceiptPath({ appRoot: root, target, platform: "win", phase, stateRoot: process.env.RIGHT_RELEASE_STATE_ROOT });
 }
 
-// A signing step with per-file settings (entitlements, codesign options) goes to sign-macos.mjs as a manifest;
+// A signing step with per-file settings (entitlements, codesign options, a stable identifier) goes to sign-macos.mjs as a manifest;
 // a step with only defaults keeps the historical positional invocation.
 function macSignInvocation(items, receiptPath, extra = []) {
   if (opts.dryRun || !items.some(hasNonDefaultSettings)) return [SIGN_MACOS, ...extra, "--receipt", receiptPath, ...items.map((item) => item.file)];
   const manifest = path.resolve(path.dirname(receiptPath), `${path.basename(receiptPath, ".json")}.manifest.json`);
   mkdirSync(path.dirname(manifest), { recursive: true });
-  writeFileSync(manifest, `${JSON.stringify({ schema: 1, entries: items.map((item) => ({ file: item.file, ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options ?? [] })) }, null, 2)}\n`);
+  writeFileSync(manifest, `${JSON.stringify({ schema: 1, entries: items.map((item) => ({ file: item.file, ...(item.identifier ? { identifier: item.identifier } : {}), ...(item.entitlements ? { entitlements: item.entitlements } : {}), options: item.options ?? [] })) }, null, 2)}\n`);
   return [SIGN_MACOS, ...extra, "--receipt", receiptPath, "--manifest", manifest];
 }