@rightkit/release 0.2.165 → 0.2.173

package/rightkit-sync.mjs

@@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url";
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
 const rightkitRoot = path.resolve(packageRoot, "..", "..");
 const VERSIONS_FILE = path.join(packageRoot, "rightkit-versions.json");
-const USER_AGENT = "rightkit-sync/1 (https://github.com/Orthic-Labs/rightkit)";
+const USER_AGENT = "rightkit-sync/1 (https://github.com/bogusyogi/rightkit)";
 
 const field = (toml, key) => toml.match(new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m"))?.[1] ?? null;
 
@@ -166,6 +166,32 @@ export async function syncRightkitVersions({ check = false, fetchImpl = fetch, f
   return { changes, unpublished, copies, written };
 }
 
+/** Stage source versions into the feed BEFORE packing, so the rightkit-versions.json a tarball ships lists
+ * the very version it ships with (the feed is otherwise written after publish and lags by one release).
+ * Synchronous and offline: a unit below its staged version is skipped (never lowered); published pins stay
+ * allowed through the same retainPublished rule as stageVersion. Refreshes the consumer copies. */
+export function stageSourceVersions(entries, { file = VERSIONS_FILE, root = rightkitRoot, log = (line) => process.stdout.write(`${line}\n`) } = {}) {
+  const versions = JSON.parse(readFileSync(file, "utf8"));
+  const next = structuredClone(versions); const changes = [];
+  for (const { registry, name, version } of entries) {
+    const [stagedKey] = versionKeys(registry);
+    if (typeof name !== "string" || !name.trim()) throw new Error("stageSourceVersions requires a package or crate name");
+    if (typeof version !== "string" || !SEMVER.test(version)) throw new Error(`invalid semver: ${version}`);
+    const current = next[stagedKey]?.[name] ?? next[registry]?.[name] ?? null;
+    if (current && compareVersions(version, current) <= 0) continue;
+    retainPublished(next, { registry, name, version }, [current, next.registry?.[registry]?.[name]], undefined);
+    next[stagedKey] ??= {};
+    next[stagedKey][name] = version;
+    next[stagedKey] = Object.fromEntries(Object.entries(next[stagedKey]).sort(([a], [b]) => a.localeCompare(b)));
+    changes.push({ registry, name, from: current, to: version });
+  }
+  const written = JSON.stringify(next) !== JSON.stringify(versions);
+  if (written) writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`);
+  const copies = syncConsumerCopies(root);
+  for (const change of changes) log(`${change.registry} ${change.name}: ${change.from ?? "unlisted"} -> ${change.to} (staged before pack)`);
+  return { changes, copies, written };
+}
+
 /** Record one just-published version (the registry index can lag the upload) and refresh the copies.
  * Called by right-release after a verified cargo or npm publish; never fails the publish itself unless `strict` is set. */
 export function recordPublished({ registry, name, version }, { file = VERSIONS_FILE, root = rightkitRoot, log = (line) => process.stdout.write(`${line}\n`), strict = false } = {}) {

package/rightkit-versions.json

@@ -15,27 +15,27 @@
   "stagedNpm": {
     "@rightkit/app-update": "0.2.5",
     "@rightkit/ax": "0.3.2",
-    "@rightkit/ci": "0.2.45",
+    "@rightkit/ci": "0.2.49",
     "@rightkit/doc-render": "0.1.6",
     "@rightkit/hooks": "0.1.2",
-    "@rightkit/i18n": "0.1.0",
-    "@rightkit/legal": "0.3.1",
-    "@rightkit/legal-ui": "0.2.2",
+    "@rightkit/i18n": "0.1.1",
+    "@rightkit/legal": "0.5.0",
+    "@rightkit/legal-ui": "0.3.0",
     "@rightkit/license": "0.2.0",
     "@rightkit/logs": "0.1.4",
     "@rightkit/media-ui": "0.3.4",
-    "@rightkit/onboarding": "0.3.3",
+    "@rightkit/onboarding": "0.5.0",
     "@rightkit/outdated": "0.2.0",
-    "@rightkit/pdf-ui": "0.1.6",
+    "@rightkit/pdf-ui": "0.1.8",
     "@rightkit/platform-ui": "0.2.8",
-    "@rightkit/qa": "0.4.8",
-    "@rightkit/qa-chrome": "0.1.6",
-    "@rightkit/react-shell": "0.6.4",
-    "@rightkit/release": "0.2.164",
-    "@rightkit/settings-ui": "0.4.4",
+    "@rightkit/qa": "0.4.9",
+    "@rightkit/qa-chrome": "0.1.8",
+    "@rightkit/react-shell": "0.6.8",
+    "@rightkit/release": "0.2.173",
+    "@rightkit/settings-ui": "0.5.0",
     "@rightkit/tauri": "0.2.1",
     "@rightkit/tauri-shell": "0.1.1",
-    "@rightkit/theme": "0.2.3"
+    "@rightkit/theme": "0.2.4"
   },
   "legacyNpm": {
     "@rightkit/ax": [
@@ -92,14 +92,16 @@
       "0.1.2",
       "0.1.3",
       "0.2.0",
-      "0.2.1"
+      "0.2.1",
+      "0.2.2"
     ],
     "@rightkit/hooks": [
       "0.1.0",
       "0.1.1"
     ],
     "@rightkit/legal": [
-      "0.3.0"
+      "0.3.0",
+      "0.3.1"
     ],
     "@rightkit/license": [
       "0.1.6",
@@ -205,7 +207,10 @@
       "0.2.160",
       "0.2.161",
       "0.2.162",
-      "0.2.163"
+      "0.2.163",
+      "0.2.164",
+      "0.2.165",
+      "0.2.172"
     ],
     "@rightkit/qa": [
       "0.1.0",
@@ -224,7 +229,8 @@
       "0.4.4",
       "0.4.5",
       "0.4.6",
-      "0.4.7"
+      "0.4.7",
+      "0.4.8"
     ],
     "@rightkit/app-shell": [
       "0.1.0",
@@ -256,7 +262,8 @@
       "0.1.0",
       "0.2.0",
       "0.2.1",
-      "0.2.2"
+      "0.2.2",
+      "0.2.3"
     ],
     "@rightkit/settings-ui": [
       "0.1.0",
@@ -275,7 +282,8 @@
       "0.4.0",
       "0.4.1",
       "0.4.2",
-      "0.4.3"
+      "0.4.3",
+      "0.4.4"
     ],
     "@rightkit/onboarding": [
       "0.1.0",
@@ -285,7 +293,8 @@
       "0.2.3",
       "0.3.0",
       "0.3.1",
-      "0.3.2"
+      "0.3.2",
+      "0.3.3"
     ],
     "@rightkit/doc-render": [
       "0.1.0",
@@ -313,7 +322,8 @@
       "0.1.2",
       "0.1.3",
       "0.1.4",
-      "0.1.5"
+      "0.1.5",
+      "0.1.6"
     ],
     "@rightkit/qa-chrome": [
       "0.1.0",
@@ -321,7 +331,8 @@
       "0.1.2",
       "0.1.3",
       "0.1.4",
-      "0.1.5"
+      "0.1.5",
+      "0.1.6"
     ],
     "@rightkit/updates": [
       "0.2.4"
@@ -335,7 +346,16 @@
     ],
     "@rightkit/ci": [
       "0.2.43",
-      "0.2.44"
+      "0.2.44",
+      "0.2.45"
+    ],
+    "@rightkit/react-shell": [
+      "0.6.4",
+      "0.6.5",
+      "0.6.6"
+    ],
+    "@rightkit/i18n": [
+      "0.1.0"
     ]
   },
   "cargo": {
@@ -356,16 +376,16 @@
     "rightkit-tauri": "0.1.0"
   },
   "stagedCargo": {
-    "rightkit-agent-tools": "0.1.3",
+    "rightkit-agent-tools": "0.1.4",
     "rightkit-agents": "0.1.0",
     "rightkit-app-settings": "0.2.0",
     "rightkit-asr": "0.2.1",
     "rightkit-audio": "0.2.3",
-    "rightkit-automation": "0.3.0",
+    "rightkit-automation": "0.4.1",
     "rightkit-browser": "0.3.1",
     "rightkit-cache": "0.2.0",
     "rightkit-channel-memory": "0.1.0",
-    "rightkit-child-process": "0.4.0",
+    "rightkit-child-process": "0.4.3",
     "rightkit-compose": "0.1.0",
     "rightkit-contracts": "0.1.5",
     "rightkit-crash": "0.3.0",
@@ -373,19 +393,21 @@
     "rightkit-daemon": "0.2.3",
     "rightkit-db": "0.4.0",
     "rightkit-device": "0.1.3",
-    "rightkit-embed": "0.4.0",
+    "rightkit-docs": "0.1.0",
+    "rightkit-embed": "0.5.0",
     "rightkit-ffmpeg": "0.2.6",
     "rightkit-file-watch": "0.4.0",
-    "rightkit-fs": "0.4.0",
-    "rightkit-fsindex": "0.2.1",
-    "rightkit-hotkeys": "0.1.0",
+    "rightkit-fs": "0.4.3",
+    "rightkit-fsindex": "0.3.0",
+    "rightkit-hooks": "0.1.0",
+    "rightkit-hotkeys": "0.1.1",
     "rightkit-http": "0.3.0",
     "rightkit-job-queue": "0.3.1",
     "rightkit-license": "0.2.0",
     "rightkit-llm": "0.2.1",
     "rightkit-logs": "0.3.0",
-    "rightkit-mcp": "0.5.3",
-    "rightkit-models": "0.3.2",
+    "rightkit-mcp": "0.6.0",
+    "rightkit-models": "0.4.4",
     "rightkit-oauth": "0.5.0",
     "rightkit-ocr": "0.2.2",
     "rightkit-onnx": "0.2.3",
@@ -393,8 +415,8 @@
     "rightkit-ownership": "0.2.1",
     "rightkit-pdf": "0.3.0",
     "rightkit-playback": "0.2.1",
-    "rightkit-qa": "0.4.0",
-    "rightkit-qa-driver": "0.4.0",
+    "rightkit-qa": "0.6.4",
+    "rightkit-qa-driver": "0.5.0",
     "rightkit-record": "0.3.0",
     "rightkit-review": "0.2.0",
     "rightkit-sandbox": "0.4.0",
@@ -426,16 +448,16 @@
   },
   "registry": {
     "cargo": {
-      "rightkit-agent-tools": "0.1.3",
+      "rightkit-agent-tools": "0.1.4",
       "rightkit-agents": "0.1.0",
       "rightkit-app-settings": "0.2.0",
       "rightkit-asr": "0.2.1",
       "rightkit-audio": "0.2.3",
-      "rightkit-automation": "0.3.0",
+      "rightkit-automation": "0.4.1",
       "rightkit-browser": "0.3.1",
       "rightkit-cache": "0.2.0",
       "rightkit-channel-memory": "0.1.0",
-      "rightkit-child-process": "0.4.0",
+      "rightkit-child-process": "0.4.1",
       "rightkit-compose": "0.1.0",
       "rightkit-contracts": "0.1.5",
       "rightkit-control": "0.3.0",
@@ -444,20 +466,22 @@
       "rightkit-daemon": "0.2.3",
       "rightkit-db": "0.4.0",
       "rightkit-device": "0.1.3",
-      "rightkit-embed": "0.4.0",
+      "rightkit-docs": "0.1.0",
+      "rightkit-embed": "0.5.0",
       "rightkit-ffmpeg": "0.2.6",
       "rightkit-file-watch": "0.4.0",
       "rightkit-framed-sidecar": "0.2.0",
-      "rightkit-fs": "0.4.0",
-      "rightkit-fsindex": "0.2.1",
-      "rightkit-hotkeys": "0.1.0",
+      "rightkit-fs": "0.4.1",
+      "rightkit-fsindex": "0.3.0",
+      "rightkit-hooks": "0.1.0",
+      "rightkit-hotkeys": "0.1.1",
       "rightkit-http": "0.3.0",
       "rightkit-job-queue": "0.3.1",
       "rightkit-jobs": "0.3.0",
       "rightkit-license": "0.2.0",
       "rightkit-llm": "0.2.1",
       "rightkit-logs": "0.3.0",
-      "rightkit-mcp": "0.5.3",
+      "rightkit-mcp": "0.6.0",
       "rightkit-media": "0.2.6",
       "rightkit-models": "0.3.2",
       "rightkit-oauth": "0.5.0",
@@ -469,8 +493,8 @@
       "rightkit-pdf": "0.3.0",
       "rightkit-playback": "0.2.1",
       "rightkit-process": "0.4.0",
-      "rightkit-qa": "0.4.0",
-      "rightkit-qa-driver": "0.4.0",
+      "rightkit-qa": "0.6.1",
+      "rightkit-qa-driver": "0.5.0",
       "rightkit-qts": "0.2.6",
       "rightkit-qts-ggml": "0.1.2",
       "rightkit-qts-ggml-sys": "0.1.2",
@@ -500,29 +524,29 @@
       "@rightkit/app-shell": "0.6.2",
       "@rightkit/app-update": "0.2.5",
       "@rightkit/ax": "0.3.2",
-      "@rightkit/ci": "0.2.45",
+      "@rightkit/ci": "0.2.49",
       "@rightkit/doc-render": "0.1.6",
       "@rightkit/git": "0.2.42",
       "@rightkit/hooks": "0.1.2",
-      "@rightkit/i18n": "0.1.0",
-      "@rightkit/legal": "0.3.1",
-      "@rightkit/legal-ui": "0.2.2",
+      "@rightkit/i18n": "0.1.1",
+      "@rightkit/legal": "0.5.0",
+      "@rightkit/legal-ui": "0.3.0",
       "@rightkit/license": "0.2.0",
       "@rightkit/logs": "0.1.4",
       "@rightkit/media-ui": "0.3.4",
-      "@rightkit/onboarding": "0.3.3",
+      "@rightkit/onboarding": "0.5.0",
       "@rightkit/outdated": "0.2.0",
-      "@rightkit/pdf-ui": "0.1.6",
+      "@rightkit/pdf-ui": "0.1.8",
       "@rightkit/platform-ui": "0.2.8",
-      "@rightkit/qa": "0.4.8",
-      "@rightkit/qa-chrome": "0.1.6",
-      "@rightkit/react-shell": "0.6.4",
-      "@rightkit/release": "0.2.164",
-      "@rightkit/settings-ui": "0.4.4",
+      "@rightkit/qa": "0.4.9",
+      "@rightkit/qa-chrome": "0.1.8",
+      "@rightkit/react-shell": "0.6.8",
+      "@rightkit/release": "0.2.172",
+      "@rightkit/settings-ui": "0.5.0",
       "@rightkit/shell": "0.1.1",
       "@rightkit/tauri": "0.2.1",
       "@rightkit/tauri-shell": "0.1.1",
-      "@rightkit/theme": "0.2.3",
+      "@rightkit/theme": "0.2.4",
       "@rightkit/updates": "0.2.5"
     }
   },
@@ -545,7 +569,8 @@
       "0.2.6",
       "0.2.7",
       "0.3.0",
-      "0.3.1"
+      "0.3.1",
+      "0.3.2"
     ],
     "rightkit-audio": [
       "0.1.0",
@@ -563,7 +588,8 @@
       "0.2.2",
       "0.3.0",
       "0.3.1",
-      "0.3.2"
+      "0.3.2",
+      "0.4.0"
     ],
     "rightkit-jobs": [
       "0.2.1",
@@ -581,7 +607,8 @@
       "0.4.0",
       "0.5.0",
       "0.5.1",
-      "0.5.2"
+      "0.5.2",
+      "0.5.3"
     ],
     "rightkit-media": [
       "0.2.2",
@@ -619,7 +646,11 @@
       "0.2.12",
       "0.2.14",
       "0.2.16",
-      "0.3.0"
+      "0.3.0",
+      "0.4.0",
+      "0.5.0",
+      "0.6.0",
+      "0.6.1"
     ],
     "rightkit-sandbox": [
       "0.1.0",
@@ -680,7 +711,9 @@
       "0.2.0",
       "0.3.0",
       "0.3.1",
-      "0.3.2"
+      "0.3.2",
+      "0.4.0",
+      "0.4.1"
     ],
     "rightkit-service": [
       "0.1.0",
@@ -718,7 +751,8 @@
     ],
     "rightkit-fsindex": [
       "0.1.0",
-      "0.2.0"
+      "0.2.0",
+      "0.2.1"
     ],
     "rightkit-asr": [
       "0.0.2",
@@ -760,10 +794,24 @@
     ],
     "rightkit-qa-driver": [
       "0.3.0",
-      "0.3.1"
+      "0.3.1",
+      "0.4.0",
+      "0.4.1"
     ],
     "rightkit-agent-tools": [
-      "0.1.2"
+      "0.1.2",
+      "0.1.3"
+    ],
+    "rightkit-automation": [
+      "0.3.0",
+      "0.4.0"
+    ],
+    "rightkit-child-process": [
+      "0.4.0",
+      "0.4.1"
+    ],
+    "rightkit-hotkeys": [
+      "0.1.0"
     ]
   }
 }

package/runtime-budget-classes.json

@@ -1,6 +1,14 @@
 {
   "schema": 1,
   "heldResource": {
+    "rightkit-agent-tools": {
+      "ceilings": null,
+      "requiredScale": null
+    },
+    "rightkit-agents": {
+      "ceilings": null,
+      "requiredScale": null
+    },
     "rightkit-asr": {
       "ceilings": null,
       "requiredScale": null
@@ -17,10 +25,22 @@
       "ceilings": null,
       "requiredScale": null
     },
+    "rightkit-hotkeys": {
+      "ceilings": null,
+      "requiredScale": null
+    },
+    "rightkit-mcp": {
+      "ceilings": null,
+      "requiredScale": null
+    },
     "rightkit-ocr": {
       "ceilings": null,
       "requiredScale": null
     },
+    "rightkit-onnx": {
+      "ceilings": null,
+      "requiredScale": null
+    },
     "rightkit-record": {
       "ceilings": null,
       "requiredScale": null
@@ -29,6 +49,14 @@
       "ceilings": null,
       "requiredScale": null
     },
+    "rightkit-tts": {
+      "ceilings": null,
+      "requiredScale": null
+    },
+    "rightkit-tts-qwen": {
+      "ceilings": null,
+      "requiredScale": null
+    },
     "rightkit-vad": {
       "ceilings": null,
       "requiredScale": null

package/runtime-budgets.mjs

@@ -345,6 +345,9 @@ function checkEvidence(m, index, budget, crateDir, { exists, readFile }) {
 
 const stripComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
 
+// `use`, `pub use` and `pub(crate) use` declarations, including multi-line `{ ... }` lists: an import cannot start work.
+const stripImports = (text) => text.replace(/^[ \t]*(?:pub(?:\([^)]*\))?\s+)?use\s[^;]*;/gm, "");
+
 /** Source with `#[cfg(test)]` modules removed (brace-balanced), for scanning shipped code only. */
 function withoutTestModules(text) {
   const out = [];
@@ -380,7 +383,7 @@ function rustFiles(dir) {
 export function scanContinuousFiles(crateDir) {
   const files = {};
   for (const file of rustFiles(path.join(crateDir, "src")).sort()) {
-    const text = stripComments(withoutTestModules(fs.readFileSync(file, "utf8")));
+    const text = stripImports(stripComments(withoutTestModules(fs.readFileSync(file, "utf8"))));
     const ids = Object.entries(CONTINUOUS_PATTERNS).filter(([, pattern]) => pattern.test(text)).map(([id]) => id);
     if (ids.length) files[path.relative(crateDir, file).split(path.sep).join("/")] = ids;
   }

package/sign-candidate.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// right-release sign-candidate: sign the EXACT bytes of an unsigned release candidate instead of rebuilding from source
+// (Orthic-Labs/rightkit#320, SwiftRight SR0 7a). The candidate job's artifact (MSIX / .exe on Windows, .app or loose executables on
+// macOS) is the signing input. Steps: verify every file's sha256 against the candidate receipt (refuse on any mismatch, missing or
+// unrecorded file), sign in place (Windows: Azure Artifact Signing through sign-windows.mjs; macOS: Developer ID through
+// sign-dev-artifact), confirm each signed file changed, and write a receipt binding candidate sha -> signed sha. It never builds,
+// notarizes or publishes, and a signing job calls it instead of `right-release build`.
+//
+// Candidate receipt (same shape as the dev artifact payload metadata): { schema: 1, files: [{ path, sha256 }] }, paths relative to --artifact.
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { fileEvidence } from "./macos-file-evidence.mjs";
+import { readMsixSignerSubject } from "./msix-signer.mjs";
+import { signDevArtifact, verifyDevArtifactPayload } from "./sign-dev-artifact.mjs";
+
+export const SIGN_CANDIDATE_CONTRACT = "rightkit-sign-candidate-v1";
+export const SIGN_CANDIDATE_SCHEMA = 1;
+
+export class SignCandidateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SignCandidateError";
+    this.code = code;
+  }
+}
+
+const fail = (code, message) => { throw new SignCandidateError(code, message); };
+const toPosix = (value) => value.split(path.sep).join("/");
+const USAGE = "usage: right-release sign-candidate --platform win|mac --artifact <dir> --candidate-receipt <receipt.json> --out <binding.json> [--manifest <sign.json>] [--publisher <subject>] [--dry-run]";
+
+const defaultSignWindows = ({ files, env, run }) => {
+  const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "sign-windows.mjs");
+  const tempDir = mkdtempSync(path.join(os.tmpdir(), "sign-candidate-"));
+  try {
+    const result = run(process.execPath, [script, "--receipt", path.join(tempDir, "authenticode.json"), ...files], { env, encoding: "utf8", windowsHide: true, shell: false });
+    if (result.error || result.status !== 0) fail("SIGN_CANDIDATE_SIGNING_FAILED", `sign-windows failed: ${`${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim() || result.error?.message}`);
+  } finally { rmSync(tempDir, { recursive: true, force: true }); }
+};
+
+/**
+ * Sign an existing candidate. Injectable for tests: `signWindows({ files })`, `signMac(options)` (defaults to signDevArtifact),
+ * `evidenceOf`, `readSigner`. Returns the binding receipt (also written to `outPath`). With `dryRun` only the hash check runs.
+ */
+export function signCandidate({
+  platform, artifact, receiptPath, outPath, manifestPath, publisher, dryRun = false,
+  env = process.env, run = spawnSync, hostPlatform = process.platform,
+  evidenceOf = fileEvidence, readSigner = readMsixSignerSubject,
+  signWindows = (options) => defaultSignWindows({ ...options, env, run }),
+  signMac = (options) => signDevArtifact(options),
+} = {}) {
+  if (!platform || !artifact || !receiptPath || !outPath) fail("SIGN_CANDIDATE_USAGE", USAGE);
+  if (platform !== "win" && platform !== "mac") fail("SIGN_CANDIDATE_USAGE", `--platform must be win or mac: ${JSON.stringify(platform)}`);
+  if (platform === "mac" && !manifestPath) fail("SIGN_CANDIDATE_USAGE", "--manifest <sign.json> is required for --platform mac (fixed identifier per file)");
+  const root = path.resolve(artifact);
+  if (!existsSync(root)) fail("SIGN_CANDIDATE_MISSING", `artifact directory does not exist: ${root}`);
+  const receiptFile = path.resolve(receiptPath);
+  if (!existsSync(receiptFile)) fail("SIGN_CANDIDATE_MISSING", `candidate receipt does not exist: ${receiptFile}`);
+
+  // Bytes must be the qualified candidate: every recorded hash is checked before anything is signed.
+  let candidate;
+  try { candidate = verifyDevArtifactPayload(root, receiptFile); } catch (error) {
+    fail(`SIGN_CANDIDATE_${String(error.code ?? "RECEIPT_INVALID").replace(/^SIGN_DEV_ARTIFACT_/, "")}`, error.message);
+  }
+  const candidateSha = new Map([...candidate.recorded].map(([file, item]) => [path.relative(root, file), item.sha256]));
+  const receiptSha256 = evidenceOf(receiptFile).sha256;
+  if (dryRun) return { schema: SIGN_CANDIDATE_SCHEMA, dryRun: true, platform, files: [...candidateSha].map(([rel, sha256]) => ({ path: toPosix(rel), candidateSha256: sha256 })) };
+  if (platform === "win" && hostPlatform !== "win32") fail("SIGN_CANDIDATE_PLATFORM", "--platform win must run on Windows");
+  if (platform === "mac" && hostPlatform !== "darwin") fail("SIGN_CANDIDATE_PLATFORM", "--platform mac must run on macOS");
+
+  let files;
+  let signing;
+  if (platform === "win") {
+    const absolute = [...candidateSha.keys()].map((rel) => path.resolve(root, rel));
+    signWindows({ files: absolute });
+    files = [...candidateSha].map(([rel, sha]) => {
+      const signedSha256 = evidenceOf(path.resolve(root, rel)).sha256;
+      if (signedSha256 === sha) fail("SIGN_CANDIDATE_UNCHANGED", `${toPosix(rel)} was not changed by signing`);
+      let signer;
+      if (/\.msix(bundle)?$/i.test(rel)) {
+        signer = readSigner(path.resolve(root, rel));
+        if (publisher && signer !== publisher) fail("SIGN_CANDIDATE_PUBLISHER_MISMATCH", `${toPosix(rel)} is signed as ${JSON.stringify(signer)}, expected ${JSON.stringify(publisher)} (a subject change changes the package family name)`);
+      }
+      return { path: toPosix(rel), candidateSha256: sha, signedSha256, ...(signer ? { signerSubject: signer } : {}) };
+    });
+    signing = "azure-artifact-signing";
+  } else {
+    // The candidate receipt doubles as the payload metadata, so work on a copy and keep the candidate receipt as submitted.
+    const workDir = mkdtempSync(path.join(os.tmpdir(), "sign-candidate-"));
+    try {
+      const metadata = path.join(workDir, "payload.json");
+      copyFileSync(receiptFile, metadata);
+      const evidence = signMac({ artifact: root, manifestPath, metadataPath: metadata, evidencePath: path.join(workDir, "evidence.json"), env, run, platform: hostPlatform });
+      const signedByPath = new Map(evidence.files.map((file) => [file.path, file]));
+      files = [...candidateSha].map(([rel, sha]) => {
+        const key = toPosix(rel);
+        const record = signedByPath.get(key);
+        if (record) {
+          if (record.sha256Before !== sha) fail("SIGN_CANDIDATE_HASH_MISMATCH", `${key}: signing started from ${record.sha256Before}, candidate receipt says ${sha}`);
+          return { path: key, candidateSha256: sha, signedSha256: record.sha256After, identifier: record.identifier, teamIdentifier: record.teamIdentifier };
+        }
+        const unchanged = evidenceOf(path.resolve(root, rel)).sha256;
+        if (unchanged !== sha) fail("SIGN_CANDIDATE_HASH_MISMATCH", `${key} is not in the sign manifest but changed during signing`);
+        return { path: key, candidateSha256: sha, signedSha256: unchanged, unsigned: true };
+      });
+      signing = `developer-id:${evidence.teamIdentifier}`;
+    } finally { rmSync(workDir, { recursive: true, force: true }); }
+  }
+
+  const binding = {
+    schema: SIGN_CANDIDATE_SCHEMA, contract: SIGN_CANDIDATE_CONTRACT, platform, signing,
+    rebuilt: false, built: false, notarized: false, published: false,
+    candidateReceiptSha256: receiptSha256, artifact: root, files,
+  };
+  const absoluteOut = path.resolve(outPath);
+  mkdirSync(path.dirname(absoluteOut), { recursive: true });
+  writeFileSync(absoluteOut, `${JSON.stringify(binding, null, 2)}\n`);
+  return binding;
+}
+
+/** Validate a binding receipt: contract, no rebuild, every file bound candidate sha -> signed sha. Throws SIGN_CANDIDATE_BINDING_INVALID. */
+export function validateCandidateBinding(binding, expected = {}) {
+  const bad = (message) => fail("SIGN_CANDIDATE_BINDING_INVALID", `candidate binding receipt: ${message}`);
+  if (!binding || binding.schema !== SIGN_CANDIDATE_SCHEMA || binding.contract !== SIGN_CANDIDATE_CONTRACT) bad("unrecognized contract");
+  if (binding.rebuilt !== false) bad("signed bytes were rebuilt, not derived from the candidate");
+  if (!Array.isArray(binding.files) || !binding.files.length) bad("no files");
+  for (const file of binding.files) {
+    for (const key of ["candidateSha256", "signedSha256"]) if (!/^[0-9a-f]{64}$/.test(file?.[key] ?? "")) bad(`${file?.path}.${key} must be a SHA-256`);
+    if (!file.unsigned && file.candidateSha256 === file.signedSha256) bad(`${file.path} was not changed by signing`);
+  }
+  if (expected.platform && binding.platform !== expected.platform) bad(`platform ${binding.platform} is not ${expected.platform}`);
+  if (expected.candidateSha256s) {
+    const bound = new Set(binding.files.map((file) => file.candidateSha256));
+    for (const sha of expected.candidateSha256s) if (!bound.has(sha)) bad(`candidate ${sha} is not bound`);
+  }
+  return binding;
+}
+
+export function main(args = process.argv.slice(2), options = {}) {
+  const take = (flag) => {
+    const index = args.indexOf(flag);
+    if (index < 0) return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) fail("SIGN_CANDIDATE_USAGE", `${flag} requires a value`);
+    return value;
+  };
+  try {
+    const result = signCandidate({
+      platform: take("--platform"), artifact: take("--artifact"), receiptPath: take("--candidate-receipt"), outPath: take("--out"),
+      manifestPath: take("--manifest"), publisher: take("--publisher"), dryRun: args.includes("--dry-run"), ...options,
+    });
+    console.log(result.dryRun ? `dry-run: candidate hashes verified; would sign ${result.files.map((file) => file.path).join(", ")}` : `signed ${result.files.length} candidate file(s) (${result.signing}); binding receipt written`);
+  } catch (error) {
+    console.error(`right-release sign-candidate: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();