@rightkit/release 0.2.20 → 0.2.21

package/cli/right-release.mjs

@@ -47,6 +47,13 @@ if (first === "--version" || first === "-v") {
   } else {
     run("release.mjs", rest.includes("--upload") || rest.includes("--publish") ? rest : [...rest, "--upload"]);
   }
+} else if (first === "model") {
+  const rest = args.slice(1);
+  if (rest[0] !== "promote") {
+    console.error("right-release model: expected promote");
+    process.exit(2);
+  }
+  run("model-promote.mjs", rest.slice(1));
 } else if (first === "lsclean") {
   runBinary("bash", [path.join(packageRoot, "lsclean.sh"), ...args.slice(1)]);
 } else if (first === "generate-dmg-background") {
@@ -113,6 +120,8 @@ Commands:
   release [--platform mac|win] --tier patch|update   Build/package through the signed release lane
   publish [--platform mac|win] --tier patch|update   Release plus R2 upload + RightApps registration
   publish cargo --crate <name> [--dry-run]           Test, inspect, scan, and publish one crates.io package
+  model promote --authority heardright --config <file> [--dry-run]
+                                                      Sign and promote one runtime/model artifact
   doctor [--platform mac|win]                        Inspect one app's release config
   doctor --all                                       Verify all Right Suite app release contracts
   suite-doctor                                       Verify all local Right Suite repositories

package/model-promote.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  buildRuntimeArtifactManifest,
+  signRuntimeArtifactManifest,
+} from "./runtime-artifact-manifest.mjs";
+import { loadReleaseToken } from "./release-token.mjs";
+import { registerRightAppsRelease } from "./rightapps-register.mjs";
+
+export const RUNTIME_ARTIFACT_TRUSTED_KEY_ID = "rightkit-runtime-artifacts-2026-07";
+const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const UPLOAD = path.join(TOOL_ROOT, "upload-large.mjs");
+
+export async function promoteRuntimeArtifact(input, deps = {}) {
+  const metadata = deps.metadata ?? fileMetadata;
+  const upload = deps.upload;
+  const register = deps.register;
+  const { config } = input;
+  assertPromotionConfig(config);
+  if (input.authority !== "heardright") throw new Error("model promotion authority must be heardright");
+  if (input.keyId !== RUNTIME_ARTIFACT_TRUSTED_KEY_ID) throw new Error(`untrusted runtime artifact key id: ${input.keyId}`);
+  if (!input.privateKey) throw new Error("runtime artifact signing key is required");
+
+  const [artifact, evidence] = await Promise.all([
+    metadata(input.artifactFile),
+    metadata(input.evidenceFile),
+  ]);
+  assertMetadata(artifact, config.artifact, "artifact");
+  if (evidence.sha256 !== config.evidence.sha256) throw new Error("evidence SHA-256 does not match promotion config");
+
+  const manifest = buildRuntimeArtifactManifest({
+    ...config.manifest,
+    filename: config.artifact.filename,
+    sha256: artifact.sha256,
+    sizeBytes: artifact.sizeBytes,
+    promotion: {
+      ...config.manifest.promotion,
+      authorityAppKey: input.authority,
+      evidenceSha256: evidence.sha256,
+    },
+  });
+  const envelope = signRuntimeArtifactManifest(manifest, input.privateKey, input.keyId);
+  const isR2 = manifest.distribution.delivery !== "bundled";
+  const steps = isR2
+    ? ["upload immutable object", "register signed envelope", "replace stable pointer"]
+    : ["register signed envelope"];
+  if (input.dryRun) return { envelope, steps };
+  if (typeof register !== "function") throw new Error("RightApps registration boundary is required");
+  if (isR2 && typeof upload !== "function") throw new Error("R2 upload boundary is required");
+
+  if (isR2) {
+    await upload({
+      purpose: "object",
+      file: input.artifactFile,
+      key: manifest.object.r2Key,
+      lane: manifest.distribution.delivery,
+    });
+  }
+  await register(envelope);
+  if (isR2) {
+    await upload({
+      purpose: "pointer",
+      content: `${JSON.stringify(envelope)}\n`,
+      key: manifest.pointerKey,
+      lane: manifest.distribution.delivery,
+    });
+  }
+  return { envelope, steps };
+}
+
+export function defaultWindowsRuntimeArtifactSigningKeyFile(env = process.env) {
+  const appData = env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+  return path.join(appData, "RightKit", "runtime-artifact-signing-key.pem");
+}
+
+export async function loadRuntimeArtifactSigningKey({ env = process.env, platform = process.platform, explicitFile } = {}) {
+  const direct = env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY;
+  if (direct?.trim()) return direct.replace(/\\n/g, "\n");
+  const configuredFile = explicitFile || env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE;
+  if (configuredFile) return readNonemptySecret(path.resolve(configuredFile));
+  if (platform === "win32") return readNonemptySecret(defaultWindowsRuntimeArtifactSigningKeyFile(env));
+  throw new Error("RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY or RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE is required");
+}
+
+export function runtimeArtifactUploadEnv(source = process.env) {
+  const env = { ...source };
+  delete env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY;
+  delete env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE;
+  delete env.RIGHTAPPS_RELEASE_TOKEN;
+  delete env.RIGHTAPPS_RELEASE_TOKEN_FILE;
+  return env;
+}
+
+async function main() {
+  if (process.argv.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
+    printHelp();
+    return;
+  }
+  const args = parseArgs(process.argv.slice(2));
+  const configPath = path.resolve(args.config);
+  const configRoot = path.dirname(configPath);
+  const raw = JSON.parse(await readFile(configPath, "utf8"));
+  assertExactKeys(raw, ["artifact", "evidence", "manifest"], "promotion config");
+  assertExactKeys(raw.artifact, ["file", "filename", "sha256", "sizeBytes"], "artifact");
+  assertExactKeys(raw.evidence, ["file", "sha256"], "evidence");
+  const config = {
+    artifact: {
+      filename: raw.artifact.filename,
+      sha256: raw.artifact.sha256,
+      sizeBytes: raw.artifact.sizeBytes,
+    },
+    evidence: { sha256: raw.evidence.sha256 },
+    manifest: raw.manifest,
+  };
+  const privateKey = await loadRuntimeArtifactSigningKey({ explicitFile: args.signingKeyFile });
+  const releaseToken = args.dryRun ? null : await loadReleaseToken();
+  const runtime = {
+    metadata: fileMetadata,
+    upload: defaultUpload,
+    register: (envelope) => registerRuntimeArtifact(envelope, releaseToken),
+  };
+  const result = await promoteRuntimeArtifact({
+    authority: args.authority,
+    keyId: args.keyId,
+    privateKey,
+    artifactFile: path.resolve(configRoot, raw.artifact.file),
+    evidenceFile: path.resolve(configRoot, raw.evidence.file),
+    config,
+    dryRun: args.dryRun,
+  }, runtime);
+  const manifest = result.envelope.manifest;
+  console.log(`${args.dryRun ? "[dry-run] " : ""}runtime artifact promotion validated`);
+  console.log(`  app/kind: ${manifest.entitlement.appKey}/${manifest.artifactKind}`);
+  console.log(`  target: ${manifest.target.os}/${manifest.target.arch}`);
+  console.log(`  delivery: ${manifest.distribution.delivery}`);
+  console.log(`  object sha256: ${manifest.object.sha256}`);
+  console.log(`  pointer: ${manifest.pointerKey ?? "bundled"}`);
+  console.log(`  order: ${result.steps.join(" -> ")}`);
+}
+
+function printHelp() {
+  console.log(`right-release model promote --authority heardright --config <promotion.json> [options]
+
+The JSON config has exactly:
+  artifact: { file, filename, sha256, sizeBytes }
+  evidence: { file, sha256 }
+  manifest: { artifactKind, entitlement, distribution, target, versions, provenance,
+              promotion: { promotionId, promotedAt } }
+artifact.file and evidence.file resolve relative to the config; artifact.sha256,
+artifact.sizeBytes, and evidence.sha256 must exactly match those files.
+
+Options:
+  --dry-run                 Validate real files and sign, without R2 or RightApps mutations
+  --signing-key-file <pem>  Override the protected PEM path
+  --key-id <id>             Must equal ${RUNTIME_ARTIFACT_TRUSTED_KEY_ID}
+
+Signing key inputs (never printed): RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY or
+RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE. Windows defaults to
+%APPDATA%/RightKit/runtime-artifact-signing-key.pem. Live promotion also uses
+the durable RIGHTAPPS_RELEASE_TOKEN boundary.`);
+}
+
+function parseArgs(args) {
+  let authority = "";
+  let config = "";
+  let signingKeyFile;
+  let keyId = process.env.RIGHTKIT_RUNTIME_ARTIFACT_KEY_ID || RUNTIME_ARTIFACT_TRUSTED_KEY_ID;
+  let dryRun = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--authority") authority = args[++i] ?? "";
+    else if (arg === "--config") config = args[++i] ?? "";
+    else if (arg === "--signing-key-file") signingKeyFile = args[++i] ?? "";
+    else if (arg === "--key-id") keyId = args[++i] ?? "";
+    else if (arg === "--dry-run") dryRun = true;
+    else throw new Error(`unknown model promote argument: ${arg}`);
+  }
+  if (!config) throw new Error("model promote requires --config <path>");
+  if (!authority) throw new Error("model promote requires --authority heardright");
+  return { authority, config, signingKeyFile, keyId, dryRun };
+}
+
+async function fileMetadata(file) {
+  const info = await stat(file);
+  if (!info.isFile() || info.size <= 0) throw new Error(`promotion input is not a nonempty file: ${file}`);
+  const hash = createHash("sha256");
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(file);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", resolve);
+  });
+  return { sha256: hash.digest("hex"), sizeBytes: info.size };
+}
+
+async function defaultUpload({ file, content, key, lane }) {
+  const bucketAlias = lane === "private-r2" ? "private" : "public";
+  const env = runtimeArtifactUploadEnv();
+  if (file) return run(process.execPath, [UPLOAD, file, key, bucketAlias], env);
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "rightkit-runtime-pointer-"));
+  const pointerFile = path.join(tempRoot, "manifest.json");
+  try {
+    await writeFile(pointerFile, content, { encoding: "utf8", mode: 0o600 });
+    await run(process.execPath, [UPLOAD, pointerFile, key, bucketAlias], env);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function registerRuntimeArtifact(envelope, releaseToken) {
+  return registerRightAppsRelease("/v1/admin/apps/runtime-artifacts", envelope, { token: releaseToken });
+}
+
+function run(command, args, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: process.cwd(), env, stdio: "inherit", windowsHide: true });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited ${code}`)));
+  });
+}
+
+async function readNonemptySecret(file) {
+  const value = await readFile(file, "utf8");
+  if (!value.trim()) throw new Error(`runtime artifact signing key file is empty: ${file}`);
+  return value;
+}
+
+function assertPromotionConfig(value) {
+  assertExactKeys(value, ["artifact", "evidence", "manifest"], "promotion config");
+  assertExactKeys(value.artifact, ["filename", "sha256", "sizeBytes"], "artifact");
+  assertExactKeys(value.evidence, ["sha256"], "evidence");
+  assertExactKeys(value.manifest, [
+    "artifactKind", "entitlement", "distribution", "target", "versions", "provenance", "promotion",
+  ], "manifest config");
+  assertExactKeys(value.manifest.promotion, ["promotionId", "promotedAt"], "manifest config promotion");
+}
+
+function assertMetadata(actual, expected, label) {
+  if (actual.sha256 !== expected.sha256) throw new Error(`${label} SHA-256 does not match promotion config`);
+  if (actual.sizeBytes !== expected.sizeBytes) throw new Error(`${label} size does not match promotion config`);
+}
+
+function assertExactKeys(value, expected, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const allowed = new Set(expected);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`${label} has unknown field ${key}`);
+  for (const key of expected) if (!Object.hasOwn(value, key)) throw new Error(`${label}.${key} is required`);
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(`right-release model promote: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/model-promote.test.mjs

@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import { createHash, generateKeyPairSync } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import {
+  RUNTIME_ARTIFACT_TRUSTED_KEY_ID,
+  defaultWindowsRuntimeArtifactSigningKeyFile,
+  loadRuntimeArtifactSigningKey,
+  promoteRuntimeArtifact,
+  runtimeArtifactUploadEnv,
+} from "./model-promote.mjs";
+
+const { privateKey } = generateKeyPairSync("ed25519");
+const artifactDigest = "a".repeat(64);
+const evidenceDigest = "b".repeat(64);
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+
+function request(overrides = {}) {
+  return {
+    authority: "heardright",
+    privateKey,
+    keyId: RUNTIME_ARTIFACT_TRUSTED_KEY_ID,
+    artifactFile: "C:/fixtures/parakeet.onnx",
+    evidenceFile: "C:/fixtures/eval.json",
+    config: {
+      artifact: {
+        filename: "parakeet.onnx",
+        sha256: artifactDigest,
+        sizeBytes: 42,
+      },
+      evidence: { sha256: evidenceDigest },
+      manifest: {
+        artifactKind: "asr-model",
+        entitlement: { appKey: "scraperight", tier: "pro" },
+        distribution: { delivery: "private-r2", bucket: "rightapps-updates" },
+        target: { os: "windows", arch: "x86_64" },
+        versions: {
+          runtime: "rightkit-asr-0.1.0",
+          model: "parakeet-tdt-0.6b-v3",
+          tokenizer: "sentencepiece-2026-07-14",
+          preprocessing: "rightkit-asr-0.1.0",
+          license: "cc-by-4.0",
+          provenance: "heardright-approved-2026-07-14",
+        },
+        provenance: {
+          source: "https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3",
+          sourceRevision: "0123456789abcdef",
+          licenseId: "CC-BY-4.0",
+          noticeSha256: "c".repeat(64),
+        },
+        promotion: {
+          promotionId: "hr-asr-2026-07-14-001",
+          promotedAt: "2026-07-14T12:00:00.000Z",
+        },
+      },
+    },
+    ...overrides,
+  };
+}
+
+function boundaries(events) {
+  return {
+    metadata: async (file) => file.endsWith("eval.json")
+      ? { sha256: evidenceDigest, sizeBytes: 10 }
+      : { sha256: artifactDigest, sizeBytes: 42 },
+    upload: async ({ purpose }) => { events.push(`upload:${purpose}`); },
+    register: async () => { events.push("register"); },
+  };
+}
+
+test("uploads immutable object, registers signed envelope, then replaces stable pointer", async () => {
+  const events = [];
+  const result = await promoteRuntimeArtifact(request(), boundaries(events));
+
+  assert.deepEqual(events, ["upload:object", "register", "upload:pointer"]);
+  assert.equal(result.envelope.signature.keyId, RUNTIME_ARTIFACT_TRUSTED_KEY_ID);
+  assert.equal(result.envelope.manifest.object.sha256, artifactDigest);
+  assert.equal(result.envelope.manifest.promotion.evidenceSha256, evidenceDigest);
+  assert.match(result.envelope.manifest.pointerKey, /\/current\/manifest\.json$/);
+});
+
+test("dry-run validates and signs without invoking process or network boundaries", async () => {
+  const events = [];
+  const result = await promoteRuntimeArtifact(request({ dryRun: true }), boundaries(events));
+  assert.deepEqual(events, []);
+  assert.deepEqual(result.steps, ["upload immutable object", "register signed envelope", "replace stable pointer"]);
+  assert.equal(result.envelope.signature.algorithm, "Ed25519");
+});
+
+test("never registers or publishes a pointer after immutable upload failure", async () => {
+  const events = [];
+  const deps = boundaries(events);
+  deps.upload = async ({ purpose }) => {
+    events.push(`upload:${purpose}`);
+    throw new Error("R2 failed");
+  };
+  await assert.rejects(promoteRuntimeArtifact(request(), deps), /R2 failed/);
+  assert.deepEqual(events, ["upload:object"]);
+});
+
+test("never publishes a pointer when RightApps registration fails", async () => {
+  const events = [];
+  const deps = boundaries(events);
+  deps.register = async () => {
+    events.push("register");
+    throw new Error("registration failed");
+  };
+  await assert.rejects(promoteRuntimeArtifact(request(), deps), /registration failed/);
+  assert.deepEqual(events, ["upload:object", "register"]);
+});
+
+test("fails before mutation on digest, authority, key-id, or lane contradiction", async () => {
+  const badRequests = [
+    request({ authority: "scraperight" }),
+    request({ keyId: "untrusted-key" }),
+    request({ config: { ...request().config, artifact: { ...request().config.artifact, sha256: "d".repeat(64) } } }),
+    request({ config: {
+      ...request().config,
+      manifest: {
+        ...request().config.manifest,
+        entitlement: { appKey: "scraperight", tier: "public" },
+        distribution: { delivery: "public-r2", bucket: "rightapps-downloads" },
+      },
+    } }),
+    request({ config: {
+      ...request().config,
+      manifest: {
+        ...request().config.manifest,
+        promotion: {
+          ...request().config.manifest.promotion,
+          authorityAppKey: "scraperight",
+        },
+      },
+    } }),
+  ];
+  for (const input of badRequests) {
+    const events = [];
+    await assert.rejects(promoteRuntimeArtifact(input, boundaries(events)));
+    assert.deepEqual(events, []);
+  }
+});
+
+test("right-release routes model promote to the portable promotion lane", () => {
+  const result = spawnSync(process.execPath, [path.join(packageRoot, "cli/right-release.mjs"), "model", "promote", "--authority", "heardright"], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /model promote requires --config/);
+  assert.doesNotMatch(result.stderr, /unknown command/);
+});
+
+test("model promote help documents the portable config and secure key inputs", () => {
+  const result = spawnSync(process.execPath, [path.join(packageRoot, "cli/right-release.mjs"), "model", "promote", "--help"], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /artifact\.file/);
+  assert.match(result.stdout, /evidence\.sha256/);
+  assert.match(result.stdout, /RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE/);
+  assert.match(result.stdout, /RIGHTAPPS_RELEASE_TOKEN/);
+});
+
+test("portable CLI dry-run validates real files and signs without network mutation or secret output", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "rightkit-model-promote-test-"));
+  try {
+    const artifact = Buffer.from("tiny model fixture");
+    const evidence = Buffer.from('{"certified":true}');
+    const testKeys = generateKeyPairSync("ed25519");
+    const keyPem = testKeys.privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    await Promise.all([
+      writeFile(path.join(root, "model.onnx"), artifact),
+      writeFile(path.join(root, "evidence.json"), evidence),
+      writeFile(path.join(root, "key.pem"), keyPem, { mode: 0o600 }),
+    ]);
+    const config = {
+      artifact: {
+        file: "model.onnx",
+        filename: "model.onnx",
+        sha256: createHash("sha256").update(artifact).digest("hex"),
+        sizeBytes: artifact.length,
+      },
+      evidence: {
+        file: "evidence.json",
+        sha256: createHash("sha256").update(evidence).digest("hex"),
+      },
+      manifest: request().config.manifest,
+    };
+    await writeFile(path.join(root, "promotion.json"), JSON.stringify(config));
+
+    const result = spawnSync(process.execPath, [
+      path.join(packageRoot, "cli/right-release.mjs"), "model", "promote",
+      "--authority", "heardright",
+      "--config", path.join(root, "promotion.json"),
+      "--signing-key-file", path.join(root, "key.pem"),
+      "--dry-run",
+    ], { cwd: root, encoding: "utf8", windowsHide: true });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /\[dry-run\] runtime artifact promotion validated/);
+    assert.match(result.stdout, /upload immutable object -> register signed envelope -> replace stable pointer/);
+    assert.doesNotMatch(`${result.stdout}${result.stderr}`, /BEGIN PRIVATE KEY/);
+    assert.doesNotMatch(`${result.stdout}${result.stderr}`, /Uploading|POST https:/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("uses the canonical Windows signing-key path and supports a Keychain-fed PEM environment value", async () => {
+  assert.equal(
+    defaultWindowsRuntimeArtifactSigningKeyFile({ APPDATA: "C:/Users/test/AppData/Roaming" }),
+    path.join("C:/Users/test/AppData/Roaming", "RightKit", "runtime-artifact-signing-key.pem"),
+  );
+  assert.equal(
+    await loadRuntimeArtifactSigningKey({ env: { RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY: "line1\\nline2" }, platform: "darwin" }),
+    "line1\nline2",
+  );
+});
+
+test("does not forward signing or RightApps credentials into the Wrangler uploader process", () => {
+  const env = runtimeArtifactUploadEnv({
+    CLOUDFLARE_API_TOKEN: "cloudflare-token",
+    RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY: "private-pem",
+    RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE: "key.pem",
+    RIGHTAPPS_RELEASE_TOKEN: "release-token",
+    RIGHTAPPS_RELEASE_TOKEN_FILE: "release.token",
+  });
+  assert.equal(env.CLOUDFLARE_API_TOKEN, "cloudflare-token");
+  assert.equal(env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY, undefined);
+  assert.equal(env.RIGHTKIT_RUNTIME_ARTIFACT_PRIVATE_KEY_FILE, undefined);
+  assert.equal(env.RIGHTAPPS_RELEASE_TOKEN, undefined);
+  assert.equal(env.RIGHTAPPS_RELEASE_TOKEN_FILE, undefined);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/release",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Portable Right Suite release CLI/SDK: signed installers, updater artifacts, patch/update routing, hardening, R2 publish, and RightApps registration.",
   "type": "module",
   "bin": {
@@ -14,6 +14,11 @@
     "*.py"
   ],
   "sideEffects": false,
+  "scripts": {
+    "test": "node --test *.test.mjs",
+    "doctor:all": "node --test right-suite-contract.test.mjs",
+    "verify:standalone": "node standalone-clone-verify.mjs"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -23,8 +28,5 @@
     "url": "git+https://github.com/adrdsouza/claude.git",
     "directory": "tools/rightkit/packages/release"
   },
-  "scripts": {
-    "test": "node --test *.test.mjs",
-    "doctor:all": "node --test right-suite-contract.test.mjs"
-  }
-}
+  "packageManager": "pnpm@11.12.0"
+}

package/publish-update.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { pruneReleaseObjects } from "./prune-r2.mjs";
 import { loadReleaseToken } from "./release-token.mjs";
+import { registerRightAppsRelease } from "./rightapps-register.mjs";
 
 const TOOL_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const UPLOAD = path.join(TOOL_ROOT, "upload-large.mjs");
@@ -272,18 +273,12 @@ function patchInstallerKey(artifact) {
 }
 
 async function register(route, body) {
-  if (!releaseToken) fail("RIGHTAPPS_RELEASE_TOKEN is required to register an update");
-  const response = await fetch(`${API_BASE}${route}`, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${releaseToken}`,
-      "content-type": "application/json",
-      "x-store-slug": process.env.RIGHTAPPS_STORE_SLUG || "rightapps",
-    },
-    body: JSON.stringify(body),
-  });
-  if (!response.ok) fail(`registration failed: ${response.status} ${await response.text()}`);
-  console.log(await response.text());
+  try {
+    const response = await registerRightAppsRelease(route, body, { token: releaseToken });
+    if (response !== null) console.log(typeof response === "string" ? response : JSON.stringify(response));
+  } catch (error) {
+    fail(error.message);
+  }
 }
 
 function fail(message) {

package/right-suite-contract.test.mjs

@@ -310,7 +310,7 @@ test("Cargo version contract rejects staged versions that mismatch canonical man
 test("RightKit exposes one current version manifest", () => {
   assert.equal(existsSync(versionsPath), true, "rightkit-versions.json must be the single current-version source");
   assert.match(versions.packageManager, /^pnpm@\d+\.\d+\.\d+$/);
-  assert.equal(versions.npm["@rightkit/release"], "0.2.20");
+  assert.equal(versions.npm["@rightkit/release"], "0.2.21");
   assert.equal(versions.npm["@rightkit/license"], "0.1.5");
   assert.equal(versions.npm["@rightkit/logs"], "0.1.3");
   assert.equal(versions.npm["@rightkit/tauri"], "0.1.0");

package/rightapps-register.mjs

@@ -0,0 +1,31 @@
+const DEFAULT_API_BASE = "https://api.spoares.com";
+const REGISTRATION_ROUTES = new Set([
+  "/v1/admin/apps/patches",
+  "/v1/admin/apps/releases",
+  "/v1/admin/apps/runtime-artifacts",
+]);
+
+export async function registerRightAppsRelease(route, body, {
+  token,
+  env = process.env,
+  fetchImpl = fetch,
+} = {}) {
+  if (!token?.trim()) throw new Error("RIGHTAPPS_RELEASE_TOKEN release token is required for RightApps registration");
+  if (!REGISTRATION_ROUTES.has(route)) {
+    throw new Error("RightApps registration route is not approved");
+  }
+  const apiBase = (env.RIGHTAPPS_API_URL || DEFAULT_API_BASE).replace(/\/$/, "");
+  const response = await fetchImpl(`${apiBase}${route}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token.trim()}`,
+      "content-type": "application/json",
+      "x-store-slug": env.RIGHTAPPS_STORE_SLUG || "rightapps",
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`RightApps registration failed: ${response.status} ${text}`);
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}

package/rightapps-register.test.mjs

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerRightAppsRelease } from "./rightapps-register.mjs";
+
+test("registers through the shared durable release-token boundary", async () => {
+  const calls = [];
+  const response = await registerRightAppsRelease("/v1/admin/apps/runtime-artifacts", { schema: 1 }, {
+    token: "durable-token",
+    env: { RIGHTAPPS_API_URL: "https://rightapps.example", RIGHTAPPS_STORE_SLUG: "rightapps" },
+    fetchImpl: async (url, init) => {
+      calls.push({ url, init });
+      return { ok: true, text: async () => '{"id":"registered"}' };
+    },
+  });
+  assert.deepEqual(response, { id: "registered" });
+  assert.equal(calls[0].url, "https://rightapps.example/v1/admin/apps/runtime-artifacts");
+  assert.equal(calls[0].init.headers.authorization, "Bearer durable-token");
+});
+
+test("rejects absent durable token and non-admin registration paths before network", async () => {
+  let called = false;
+  const fetchImpl = async () => { called = true; };
+  await assert.rejects(registerRightAppsRelease("/v1/admin/apps/runtime-artifacts", {}, { token: "", fetchImpl }), /release token/i);
+  await assert.rejects(registerRightAppsRelease("https://evil.invalid", {}, { token: "token", fetchImpl }), /route/i);
+  await assert.rejects(registerRightAppsRelease("/v1/admin/apps/../../evil", {}, { token: "token", fetchImpl }), /route/i);
+  assert.equal(called, false);
+});

package/rightkit-versions.json

@@ -4,7 +4,7 @@
   "npm": {
     "@rightkit/license": "0.1.5",
     "@rightkit/logs": "0.1.3",
-    "@rightkit/release": "0.2.20",
+    "@rightkit/release": "0.2.21",
     "@rightkit/tauri": "0.1.0",
     "@rightkit/updates": "0.2.3"
   },

package/runtime-artifact-manifest.mjs

@@ -0,0 +1,247 @@
+import { sign as edSign, verify as edVerify } from "node:crypto";
+
+export const RUNTIME_ARTIFACT_SCHEMA = 1;
+export const RUNTIME_ARTIFACT_KINDS = Object.freeze([
+  "asr-model",
+  "ocr-model",
+  "ort-runtime",
+  "media-runtime",
+  "tokenizer",
+  "preprocessing",
+]);
+export const RIGHT_SUITE_APP_KEYS = Object.freeze([
+  "viewright",
+  "heardright",
+  "mailright",
+  "scraperight",
+  "coderight",
+]);
+
+const TARGET_OSES = new Set(["windows", "darwin", "linux", "ios"]);
+const TARGET_ARCHES = new Set(["x86_64", "aarch64", "universal"]);
+const VERSION_FIELDS = Object.freeze([
+  "runtime",
+  "model",
+  "tokenizer",
+  "preprocessing",
+  "license",
+  "provenance",
+]);
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export function buildRuntimeArtifactManifest(input) {
+  const entitlement = cloneObject(input.entitlement);
+  const target = cloneObject(input.target);
+  const manifest = {
+    schema: RUNTIME_ARTIFACT_SCHEMA,
+    artifactKind: input.artifactKind,
+    entitlement,
+    distribution: cloneObject(input.distribution),
+    target,
+    object: {
+      r2Key: "",
+      filename: input.filename,
+      sha256: input.sha256,
+      sizeBytes: input.sizeBytes,
+    },
+    pointerKey: "",
+    versions: cloneObject(input.versions),
+    provenance: cloneObject(input.provenance),
+    promotion: cloneObject(input.promotion),
+  };
+  if (manifest.distribution?.delivery === "bundled") {
+    manifest.object.r2Key = null;
+    manifest.pointerKey = null;
+  } else {
+    manifest.object.r2Key = runtimeArtifactObjectKey(manifest);
+    manifest.pointerKey = runtimeArtifactManifestPointerKey(manifest);
+  }
+  return validateRuntimeArtifactManifest(manifest);
+}
+
+export function runtimeArtifactObjectKey(value) {
+  const appKey = value?.entitlement?.appKey;
+  const digest = value?.object?.sha256 ?? value?.sha256;
+  const filename = value?.object?.filename ?? value?.filename;
+  assertAppKey(appKey, "entitlement.appKey");
+  assertSha256(digest, "object.sha256");
+  assertFilename(filename);
+  return `${appKey}/runtime-artifacts/objects/sha256/${digest}/${filename}`;
+}
+
+export function runtimeArtifactManifestPointerKey(value) {
+  const appKey = value?.entitlement?.appKey;
+  const kind = value?.artifactKind;
+  const os = value?.target?.os;
+  const arch = value?.target?.arch;
+  assertAppKey(appKey, "entitlement.appKey");
+  if (!RUNTIME_ARTIFACT_KINDS.includes(kind)) fail("artifactKind is unsupported");
+  if (!TARGET_OSES.has(os)) fail("target.os is unsupported");
+  if (!TARGET_ARCHES.has(arch)) fail("target.arch is unsupported");
+  return `${appKey}/runtime-artifacts/${kind}/${os}/${arch}/current/manifest.json`;
+}
+
+export function validateRuntimeArtifactManifest(value) {
+  assertPlainObject(value, "manifest");
+  assertExactKeys(value, [
+    "schema", "artifactKind", "entitlement", "distribution", "target", "object", "pointerKey",
+    "versions", "provenance", "promotion",
+  ], "manifest");
+  if (value.schema !== RUNTIME_ARTIFACT_SCHEMA) fail("schema must be 1");
+  if (!RUNTIME_ARTIFACT_KINDS.includes(value.artifactKind)) fail("artifactKind is unsupported");
+
+  assertPlainObject(value.entitlement, "entitlement");
+  assertExactKeys(value.entitlement, ["appKey", "tier"], "entitlement");
+  assertAppKey(value.entitlement.appKey, "entitlement.appKey");
+  if (!["pro", "public", "bundled"].includes(value.entitlement.tier)) fail("entitlement.tier is unsupported");
+
+  assertPlainObject(value.distribution, "distribution");
+  assertExactKeys(value.distribution, ["delivery", "bucket"], "distribution");
+  const laneContracts = {
+    "private-r2": { tier: "pro", bucket: "rightapps-updates" },
+    "public-r2": { tier: "public", bucket: "rightapps-downloads" },
+    bundled: { tier: "bundled", bucket: null },
+  };
+  const lane = laneContracts[value.distribution.delivery];
+  if (!lane) fail("distribution.delivery is unsupported");
+  if (value.entitlement.tier !== lane.tier || value.distribution.bucket !== lane.bucket) {
+    fail("distribution lane contradicts entitlement tier or bucket");
+  }
+  if (["asr-model", "ocr-model", "tokenizer"].includes(value.artifactKind)
+      && (value.distribution.delivery !== "private-r2" || value.entitlement.tier !== "pro")) {
+    fail("model artifacts must use private-r2 with Pro entitlement");
+  }
+
+  assertPlainObject(value.target, "target");
+  assertExactKeys(value.target, ["os", "arch"], "target");
+  if (!TARGET_OSES.has(value.target.os)) fail("target.os is unsupported");
+  if (!TARGET_ARCHES.has(value.target.arch)) fail("target.arch is unsupported");
+
+  assertPlainObject(value.object, "object");
+  assertExactKeys(value.object, ["r2Key", "filename", "sha256", "sizeBytes"], "object");
+  assertFilename(value.object.filename);
+  assertSha256(value.object.sha256, "object.sha256");
+  if (!Number.isSafeInteger(value.object.sizeBytes) || value.object.sizeBytes <= 0) fail("object.sizeBytes must be a positive safe integer");
+  if (value.distribution.delivery === "bundled") {
+    if (value.object.r2Key !== null || value.pointerKey !== null) fail("bundled artifacts must not claim R2 keys");
+  } else {
+    if (value.object.r2Key !== runtimeArtifactObjectKey(value)) fail("object.r2Key contradicts its immutable SHA-256 object key");
+    if (value.pointerKey !== runtimeArtifactManifestPointerKey(value)) fail("pointerKey must be the replace-only stable current manifest key");
+  }
+
+  assertPlainObject(value.versions, "versions");
+  assertExactKeys(value.versions, VERSION_FIELDS, "versions");
+  for (const field of VERSION_FIELDS) assertNonempty(value.versions[field], `versions.${field}`);
+
+  assertPlainObject(value.provenance, "provenance");
+  assertExactKeys(value.provenance, ["source", "sourceRevision", "licenseId", "noticeSha256"], "provenance");
+  assertHttpsUrl(value.provenance.source, "provenance.source");
+  assertNonempty(value.provenance.sourceRevision, "provenance.sourceRevision");
+  assertNonempty(value.provenance.licenseId, "provenance.licenseId");
+  assertSha256(value.provenance.noticeSha256, "provenance.noticeSha256");
+  if (normalizeLicense(value.versions.license) !== normalizeLicense(value.provenance.licenseId)) {
+    fail("license version contradicts provenance licenseId");
+  }
+
+  assertPlainObject(value.promotion, "promotion");
+  assertExactKeys(value.promotion, ["authorityAppKey", "promotionId", "promotedAt", "evidenceSha256"], "promotion");
+  assertAppKey(value.promotion.authorityAppKey, "promotion.authorityAppKey");
+  assertNonempty(value.promotion.promotionId, "promotion.promotionId");
+  const promotedAt = new Date(value.promotion.promotedAt);
+  if (Number.isNaN(promotedAt.getTime()) || promotedAt.toISOString() !== value.promotion.promotedAt) fail("promotion.promotedAt must be an exact ISO-8601 UTC timestamp");
+  assertSha256(value.promotion.evidenceSha256, "promotion.evidenceSha256");
+  return value;
+}
+
+export function canonicalRuntimeArtifactManifest(manifest) {
+  validateRuntimeArtifactManifest(manifest);
+  return JSON.stringify(sortDeep(manifest));
+}
+
+export function signRuntimeArtifactManifest(manifest, privateKey, keyId) {
+  assertNonempty(keyId, "signature.keyId");
+  const canonical = Buffer.from(canonicalRuntimeArtifactManifest(manifest), "utf8");
+  return {
+    manifest,
+    signature: {
+      algorithm: "Ed25519",
+      keyId,
+      value: edSign(null, canonical, privateKey).toString("base64url"),
+    },
+  };
+}
+
+export function verifyRuntimeArtifactEnvelope(value, publicKey) {
+  assertPlainObject(value, "envelope");
+  assertExactKeys(value, ["manifest", "signature"], "envelope");
+  validateRuntimeArtifactManifest(value.manifest);
+  assertPlainObject(value.signature, "signature");
+  assertExactKeys(value.signature, ["algorithm", "keyId", "value"], "signature");
+  if (value.signature.algorithm !== "Ed25519") fail("signature algorithm must be Ed25519");
+  assertNonempty(value.signature.keyId, "signature.keyId");
+  assertNonempty(value.signature.value, "signature.value");
+  let signature;
+  try {
+    signature = Buffer.from(value.signature.value, "base64url");
+  } catch {
+    fail("signature is not base64url");
+  }
+  if (signature.length !== 64 || !edVerify(null, Buffer.from(canonicalRuntimeArtifactManifest(value.manifest), "utf8"), publicKey, signature)) {
+    fail("signature verification failed");
+  }
+  return value.manifest;
+}
+
+function sortDeep(value) {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortDeep(value[key])]));
+  }
+  return value;
+}
+
+function assertExactKeys(value, expected, label) {
+  const expectedSet = new Set(expected);
+  for (const key of Object.keys(value)) if (!expectedSet.has(key)) fail(`${label} has unknown field ${key}`);
+  for (const key of expected) if (!Object.hasOwn(value, key)) fail(`${label}.${key} is required`);
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) fail(`${label} must be a plain object`);
+}
+
+function assertAppKey(value, label) {
+  if (!RIGHT_SUITE_APP_KEYS.includes(value)) fail(`${label} is not a Right Suite app`);
+}
+
+function assertFilename(value) {
+  assertNonempty(value, "object.filename");
+  if (value === "." || value === ".." || value.includes("/") || value.includes("\\") || value.includes("..")) fail("object.filename must be one safe basename");
+}
+
+function assertSha256(value, label) {
+  if (typeof value !== "string" || !SHA256.test(value)) fail(`${label} must be lowercase SHA-256`);
+}
+
+function assertNonempty(value, label) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0) fail(`${label} must be a nonempty exact string`);
+}
+
+function assertHttpsUrl(value, label) {
+  assertNonempty(value, label);
+  let url;
+  try { url = new URL(value); } catch { fail(`${label} must be an HTTPS URL`); }
+  if (url.protocol !== "https:") fail(`${label} must be an HTTPS URL`);
+}
+
+function normalizeLicense(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function cloneObject(value) {
+  return value && typeof value === "object" ? structuredClone(value) : value;
+}
+
+function fail(message) {
+  throw new Error(`invalid runtime artifact manifest: ${message}`);
+}

package/runtime-artifact-manifest.test.mjs

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import test from "node:test";
+
+import {
+  buildRuntimeArtifactManifest,
+  runtimeArtifactManifestPointerKey,
+  runtimeArtifactObjectKey,
+  signRuntimeArtifactManifest,
+  validateRuntimeArtifactManifest,
+  verifyRuntimeArtifactEnvelope,
+} from "./runtime-artifact-manifest.mjs";
+
+const digest = "a".repeat(64);
+const evidenceDigest = "b".repeat(64);
+
+function validManifest(overrides = {}) {
+  return buildRuntimeArtifactManifest({
+    artifactKind: "asr-model",
+    filename: "parakeet-tdt-v3.onnx",
+    sha256: digest,
+    sizeBytes: 42,
+    entitlement: { appKey: "scraperight", tier: "pro" },
+    distribution: { delivery: "private-r2", bucket: "rightapps-updates" },
+    target: { os: "windows", arch: "x86_64" },
+    versions: {
+      runtime: "onnxruntime-1.22.0",
+      model: "parakeet-tdt-0.6b-v3",
+      tokenizer: "sentencepiece-2026-07-14",
+      preprocessing: "rightkit-asr-0.1.0",
+      license: "cc-by-4.0",
+      provenance: "heardright-approved-2026-07-14",
+    },
+    provenance: {
+      source: "https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3",
+      sourceRevision: "0123456789abcdef",
+      licenseId: "CC-BY-4.0",
+      noticeSha256: "c".repeat(64),
+    },
+    promotion: {
+      authorityAppKey: "heardright",
+      promotionId: "hr-asr-2026-07-14-001",
+      promotedAt: "2026-07-14T12:00:00.000Z",
+      evidenceSha256: evidenceDigest,
+    },
+    ...overrides,
+  });
+}
+
+test("builds exact stable-pointer and immutable content-addressed object keys", () => {
+  const manifest = validManifest();
+  assert.equal(
+    manifest.pointerKey,
+    "scraperight/runtime-artifacts/asr-model/windows/x86_64/current/manifest.json",
+  );
+  assert.equal(
+    manifest.object.r2Key,
+    `scraperight/runtime-artifacts/objects/sha256/${digest}/parakeet-tdt-v3.onnx`,
+  );
+  assert.equal(runtimeArtifactManifestPointerKey(manifest), manifest.pointerKey);
+  assert.equal(runtimeArtifactObjectKey(manifest), manifest.object.r2Key);
+  assert.equal(validateRuntimeArtifactManifest(manifest), manifest);
+});
+
+test("signs and verifies the canonical manifest with Ed25519", () => {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const envelope = signRuntimeArtifactManifest(validManifest(), privateKey, "rightapps-runtime-2026-01");
+  assert.equal(envelope.signature.algorithm, "Ed25519");
+  assert.equal(verifyRuntimeArtifactEnvelope(envelope, publicKey).artifactKind, "asr-model");
+
+  const tampered = structuredClone(envelope);
+  tampered.manifest.object.sizeBytes += 1;
+  assert.throws(() => verifyRuntimeArtifactEnvelope(tampered, publicKey), /signature verification failed/);
+});
+
+test("fails closed on missing or contradictory digest, provenance, version, scope, and promotion metadata", () => {
+  const mutations = [
+    (m) => delete m.versions.tokenizer,
+    (m) => { m.versions.license = ""; },
+    (m) => delete m.provenance.sourceRevision,
+    (m) => { m.provenance.licenseId = "MIT"; },
+    (m) => { m.entitlement.tier = "free"; },
+    (m) => { m.object.sha256 = "d".repeat(64); },
+    (m) => { m.object.sizeBytes = 0; },
+    (m) => { m.pointerKey = "scraperight/runtime-artifacts/asr-model/windows/x86_64/v1/manifest.json"; },
+    (m) => { m.promotion.authorityAppKey = "unknown"; },
+    (m) => { m.promotion.evidenceSha256 = "not-a-digest"; },
+  ];
+  for (const mutate of mutations) {
+    const manifest = structuredClone(validManifest());
+    mutate(manifest);
+    assert.throws(() => validateRuntimeArtifactManifest(manifest));
+  }
+});
+
+test("rejects unknown fields and path traversal instead of guessing", () => {
+  const extra = structuredClone(validManifest());
+  extra.secretUrl = "https://example.invalid/token";
+  assert.throws(() => validateRuntimeArtifactManifest(extra), /unknown field/);
+  assert.throws(() => validManifest({ filename: "../model.onnx" }), /filename/);
+});
+
+test("requires an explicit compatible entitlement and delivery lane per artifact", () => {
+  const publicMedia = validManifest({
+    artifactKind: "media-runtime",
+    entitlement: { appKey: "scraperight", tier: "public" },
+    distribution: { delivery: "public-r2", bucket: "rightapps-downloads" },
+  });
+  assert.equal(publicMedia.distribution.delivery, "public-r2");
+
+  const bundledOrt = validManifest({
+    artifactKind: "ort-runtime",
+    entitlement: { appKey: "viewright", tier: "bundled" },
+    distribution: { delivery: "bundled", bucket: null },
+  });
+  assert.equal(bundledOrt.pointerKey, null);
+  assert.equal(bundledOrt.object.r2Key, null);
+
+  assert.throws(() => validManifest({
+    entitlement: { appKey: "scraperight", tier: "public" },
+    distribution: { delivery: "public-r2", bucket: "rightapps-downloads" },
+  }), /model.*private-r2.*pro/i);
+  assert.throws(() => validManifest({
+    artifactKind: "media-runtime",
+    entitlement: { appKey: "scraperight", tier: "public" },
+    distribution: { delivery: "private-r2", bucket: "rightapps-updates" },
+  }), /contradict/);
+});

package/standalone-clone-verify.mjs

@@ -0,0 +1,131 @@
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_APPS = Object.freeze([
+  { key: "viewright", remote: "https://github.com/bogusyogi/viewright.git", appDir: "." },
+  { key: "scraperight", remote: "https://github.com/bogusyogi/scraperight.git", appDir: "." },
+  { key: "heardright", remote: "https://github.com/bogusyogi/heardright.git", appDir: "tauri-app-next" },
+  { key: "mailright", remote: "https://github.com/bogusyogi/mailright.git", appDir: "." },
+  { key: "coderight", remote: "https://github.com/bogusyogi/coderight.git", appDir: "apps/coderight-tauri" },
+]);
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    windowsHide: true,
+    maxBuffer: 16 * 1024 * 1024,
+    env: { ...process.env, CI: "1", GIT_TERMINAL_PROMPT: "0" },
+  });
+  return {
+    command: [command, ...args].join(" "),
+    status: result.status,
+    stdout: String(result.stdout ?? "").trim().slice(-8000),
+    stderr: String(result.stderr ?? "").trim().slice(-8000),
+    error: result.error?.message,
+  };
+}
+
+function runPnpm(args, cwd, command) {
+  if (process.platform !== "win32" || command !== "pnpm") return run(command, args, cwd);
+  for (const entry of String(process.env.PATH ?? "").split(path.delimiter)) {
+    const cli = path.join(entry.replace(/^"|"$/g, ""), "node_modules", "pnpm", "bin", "pnpm.mjs");
+    if (existsSync(cli)) return run(process.execPath, [cli, ...args], cwd);
+  }
+  throw new Error("pnpm installation could not be resolved from PATH");
+}
+
+function requireSuccess(result, label) {
+  if (result.status !== 0) {
+    throw new Error(`${label} failed (${result.status ?? "spawn error"})\n${result.stderr || result.stdout || result.error || "no output"}`);
+  }
+}
+
+function assertGeneratedWorkRoot(workRoot, tempParent) {
+  const parent = path.resolve(tempParent);
+  const candidate = path.resolve(workRoot);
+  if (path.dirname(candidate) !== parent || !path.basename(candidate).startsWith("rightkit-standalone-")) {
+    throw new Error(`refusing cleanup outside generated standalone directory: ${candidate}`);
+  }
+}
+
+export async function verifyStandaloneClones({
+  apps = DEFAULT_APPS,
+  evidencePath = path.resolve("standalone-clone-evidence.json"),
+  tempParent = tmpdir(),
+  pnpmCommand = "pnpm",
+} = {}) {
+  mkdirSync(tempParent, { recursive: true });
+  const workRoot = mkdtempSync(path.join(path.resolve(tempParent), "rightkit-standalone-"));
+  const evidence = { schemaVersion: 1, generatedAt: new Date().toISOString(), workRoot, apps: [] };
+
+  try {
+    for (const app of apps) {
+      const cloneRoot = path.join(workRoot, app.key);
+      const clone = run("git", ["clone", "--depth", "1", "--single-branch", app.remote, cloneRoot], workRoot);
+      requireSuccess(clone, `${app.key} clone`);
+      const appRoot = path.resolve(cloneRoot, app.appDir);
+      if (!appRoot.startsWith(`${path.resolve(cloneRoot)}${path.sep}`) && appRoot !== path.resolve(cloneRoot)) {
+        throw new Error(`${app.key} package root escapes its clone`);
+      }
+      if (!existsSync(path.join(appRoot, "package.json"))) throw new Error(`${app.key} package root does not exist: ${app.appDir}`);
+      const pkg = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8"));
+      const expectedPnpm = String(pkg.packageManager ?? "").match(/^pnpm@(\d+\.\d+\.\d+)$/)?.[1];
+      if (!expectedPnpm) throw new Error(`${app.key} must pin an exact pnpm packageManager`);
+      const pnpmVersion = runPnpm(["--version"], appRoot, pnpmCommand);
+      requireSuccess(pnpmVersion, `${app.key} pnpm version`);
+      if (pnpmVersion.stdout !== expectedPnpm) {
+        throw new Error(`${app.key} requires pnpm ${expectedPnpm}, found ${pnpmVersion.stdout}`);
+      }
+      const install = runPnpm(["install", "--frozen-lockfile"], appRoot, pnpmCommand);
+      requireSuccess(install, `${app.key} pnpm install`);
+      const doctor = runPnpm(["release:doctor"], appRoot, pnpmCommand);
+      requireSuccess(doctor, `${app.key} release:doctor`);
+      const revision = run("git", ["rev-parse", "HEAD"], cloneRoot);
+      requireSuccess(revision, `${app.key} revision`);
+      evidence.apps.push({
+        key: app.key,
+        remote: app.remote,
+        appDir: app.appDir,
+        revision: revision.stdout,
+        packageManager: pkg.packageManager,
+        clone,
+        install,
+        doctor,
+      });
+      mkdirSync(path.dirname(path.resolve(evidencePath)), { recursive: true });
+      writeFileSync(path.resolve(evidencePath), `${JSON.stringify(evidence, null, 2)}\n`, "utf8");
+    }
+    return evidence;
+  } finally {
+    assertGeneratedWorkRoot(workRoot, tempParent);
+    rmSync(workRoot, { recursive: true, force: true });
+  }
+}
+
+function parseArgs(argv) {
+  let evidencePath = path.resolve("standalone-clone-evidence.json");
+  let selectedKeys = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--evidence") evidencePath = path.resolve(argv[++index]);
+    else if (argv[index] === "--app") selectedKeys.push(argv[++index]);
+    else throw new Error(`unknown argument: ${argv[index]}`);
+  }
+  const apps = selectedKeys.length ? DEFAULT_APPS.filter(({ key }) => selectedKeys.includes(key)) : DEFAULT_APPS;
+  if (apps.length !== (selectedKeys.length || DEFAULT_APPS.length)) throw new Error("unknown or duplicate --app value");
+  return { apps, evidencePath };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  try {
+    const evidence = await verifyStandaloneClones(parseArgs(process.argv.slice(2)));
+    for (const app of evidence.apps) process.stdout.write(`[standalone] ${app.key} ${app.revision.slice(0, 12)} install+doctor passed\n`);
+    process.stdout.write(`[standalone] evidence ${path.resolve(parseArgs(process.argv.slice(2)).evidencePath)}\n`);
+  } catch (error) {
+    process.stderr.write(`[standalone] ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/standalone-clone-verify.test.mjs

@@ -0,0 +1,76 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+import { verifyStandaloneClones } from "./standalone-clone-verify.mjs";
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, encoding: "utf8", windowsHide: true });
+  assert.equal(result.status, 0, `${command} ${args.join(" ")}\n${result.stderr}`);
+}
+
+test("standalone verifier clones, installs, doctors from a nested app root, and removes only its own temp tree", async (t) => {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "rightkit-standalone-fixture-"));
+  t.after(() => rmSync(fixtureRoot, { recursive: true, force: true }));
+  const source = path.join(fixtureRoot, "source");
+  const outsideSentinel = path.join(fixtureRoot, "keep.txt");
+  mkdirSync(path.join(source, "apps", "desktop"), { recursive: true });
+  writeFileSync(outsideSentinel, "keep", "utf8");
+  writeFileSync(path.join(source, "apps", "desktop", "package.json"), JSON.stringify({
+    name: "standalone-fixture",
+    private: true,
+    packageManager: "pnpm@11.12.0",
+    scripts: { "release:doctor": "node doctor.mjs" },
+  }), "utf8");
+  writeFileSync(path.join(source, "apps", "desktop", "pnpm-lock.yaml"), "lockfileVersion: '9.0'\nsettings:\n  autoInstallPeers: true\n  excludeLinksFromLockfile: false\nimporters:\n  .: {}\n", "utf8");
+  writeFileSync(path.join(source, "apps", "desktop", "doctor.mjs"), "process.stdout.write('fixture doctor passed\\n')\n", "utf8");
+  run("git", ["init", "-q"], source);
+  run("git", ["config", "user.email", "fixture@example.test"], source);
+  run("git", ["config", "user.name", "Fixture"], source);
+  run("git", ["add", "."], source);
+  run("git", ["commit", "-qm", "fixture"], source);
+
+  const evidencePath = path.join(fixtureRoot, "evidence.json");
+  const result = await verifyStandaloneClones({
+    apps: [{ key: "fixture", remote: source, appDir: "apps/desktop" }],
+    evidencePath,
+    tempParent: fixtureRoot,
+  });
+
+  assert.equal(result.apps[0].install.status, 0);
+  assert.equal(result.apps[0].doctor.status, 0);
+  assert.match(result.apps[0].doctor.stdout, /fixture doctor passed/);
+  assert.equal(existsSync(result.workRoot), false, "generated clone tree must be removed");
+  assert.equal(readFileSync(outsideSentinel, "utf8"), "keep", "cleanup must not escape the generated tree");
+  assert.deepEqual(JSON.parse(readFileSync(evidencePath, "utf8")).apps.map(({ key }) => key), ["fixture"]);
+});
+
+test("release package exposes the local standalone verification lane", () => {
+  const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+  assert.equal(pkg.scripts["verify:standalone"], "node standalone-clone-verify.mjs");
+});
+
+test("standalone verifier rejects a package root that escapes its clone", async (t) => {
+  const fixtureRoot = mkdtempSync(path.join(tmpdir(), "rightkit-standalone-escape-"));
+  t.after(() => rmSync(fixtureRoot, { recursive: true, force: true }));
+  const source = path.join(fixtureRoot, "source");
+  mkdirSync(source, { recursive: true });
+  writeFileSync(path.join(source, "README.md"), "fixture", "utf8");
+  run("git", ["init", "-q"], source);
+  run("git", ["config", "user.email", "fixture@example.test"], source);
+  run("git", ["config", "user.name", "Fixture"], source);
+  run("git", ["add", "."], source);
+  run("git", ["commit", "-qm", "fixture"], source);
+
+  await assert.rejects(
+    verifyStandaloneClones({
+      apps: [{ key: "fixture", remote: source, appDir: ".." }],
+      evidencePath: path.join(fixtureRoot, "evidence.json"),
+      tempParent: fixtureRoot,
+    }),
+    /package root escapes its clone/,
+  );
+});