@rightkit/release 0.2.20 → 0.2.22

package/asr-artifact-adoption.mjs

@@ -0,0 +1,68 @@
+import { isDeepStrictEqual } from "node:util";
+
+import { verifyRuntimeArtifactEnvelope } from "./runtime-artifact-manifest.mjs";
+
+const ASR_AUTHORITY = "heardright";
+const ASR_CONSUMER = "scraperight";
+const ASR_KIND = "asr-model";
+
+export function assertAsrArtifactAdoption({ authorityEnvelope, consumerEnvelope, publicKey, trustedKeyId }) {
+  const authority = verifyTrusted(authorityEnvelope, publicKey, trustedKeyId);
+  const consumer = verifyTrusted(consumerEnvelope, publicKey, trustedKeyId);
+
+  assertManifestRole(authority, ASR_AUTHORITY, "authority");
+  assertManifestRole(consumer, ASR_CONSUMER, "consumer");
+  for (const manifest of [authority, consumer]) {
+    if (manifest.artifactKind !== ASR_KIND) throw new Error("ASR adoption manifest must be an asr-model");
+    if (manifest.promotion.authorityAppKey !== ASR_AUTHORITY) throw new Error("ASR promotion authority must be heardright");
+  }
+
+  assertSame(authority.target, consumer.target, "target");
+  assertSame(authority.object.filename, consumer.object.filename, "object.filename");
+  assertSame(authority.object.sha256, consumer.object.sha256, "object.sha256");
+  assertSame(authority.object.sizeBytes, consumer.object.sizeBytes, "object.sizeBytes");
+  for (const field of ["runtime", "model", "tokenizer", "preprocessing", "license", "provenance"]) {
+    assertSame(authority.versions[field], consumer.versions[field], `versions.${field}`);
+  }
+  assertSame(authority.provenance, consumer.provenance, "provenance");
+  assertSame(authority.promotion, consumer.promotion, "promotion");
+  return {
+    sha256: authority.object.sha256,
+    promotionId: authority.promotion.promotionId,
+    target: authority.target,
+  };
+}
+
+export function assertAsrAdapterPair(authority, consumer) {
+  assertAdapter(authority, ASR_AUTHORITY, "authority");
+  assertAdapter(consumer, ASR_CONSUMER, "consumer");
+  for (const [field, expected] of [
+    ["authorityAppKey", ASR_AUTHORITY],
+    ["artifactKind", ASR_KIND],
+    ["delivery", "private-r2"],
+    ["entitlementTier", "pro"],
+  ]) {
+    assertSame(authority[field], expected, `authority adapter ${field}`);
+    assertSame(consumer[field], expected, `consumer adapter ${field}`);
+  }
+  return true;
+}
+
+function verifyTrusted(envelope, publicKey, trustedKeyId) {
+  if (envelope?.signature?.keyId !== trustedKeyId) throw new Error("untrusted runtime artifact key id");
+  return verifyRuntimeArtifactEnvelope(envelope, publicKey);
+}
+
+function assertManifestRole(manifest, appKey, role) {
+  if (manifest.entitlement.appKey !== appKey) throw new Error(`${role} manifest must belong to ${appKey}`);
+}
+
+function assertAdapter(value, appKey, role) {
+  if (!value || value.schema !== 1 || value.appKey !== appKey || value.role !== role) {
+    throw new Error(`invalid ${role} ASR adapter`);
+  }
+}
+
+function assertSame(left, right, field) {
+  if (!isDeepStrictEqual(left, right)) throw new Error(`ASR drift: ${field}`);
+}

package/asr-artifact-adoption.test.mjs

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import test from "node:test";
+
+import { assertAsrAdapterPair, assertAsrArtifactAdoption } from "./asr-artifact-adoption.mjs";
+import { buildRuntimeArtifactManifest, signRuntimeArtifactManifest } from "./runtime-artifact-manifest.mjs";
+
+const digest = "a".repeat(64);
+const notice = "b".repeat(64);
+const evidence = "c".repeat(64);
+const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+
+function envelope(appKey, overrides = {}) {
+  const manifest = buildRuntimeArtifactManifest({
+    artifactKind: "asr-model",
+    entitlement: { appKey, tier: "pro" },
+    distribution: { delivery: "private-r2", bucket: "rightapps-updates" },
+    target: { os: "windows", arch: "x86_64" },
+    filename: "parakeet-unified-en-0.6b.tar.zst",
+    sha256: digest,
+    sizeBytes: 1234,
+    versions: {
+      runtime: "rightkit-asr@0.1.0",
+      model: "parakeet-unified-en-0.6b",
+      tokenizer: "sha256:tokenizer-v1",
+      preprocessing: "heardright-frontend-v1",
+      license: "CC-BY-4.0",
+      provenance: "nvidia/parakeet-tdt-0.6b-v3",
+    },
+    provenance: {
+      source: "https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3",
+      sourceRevision: "revision-1",
+      licenseId: "CC-BY-4.0",
+      noticeSha256: notice,
+    },
+    promotion: {
+      authorityAppKey: "heardright",
+      promotionId: "hr-asr-2026-07-14",
+      promotedAt: "2026-07-14T00:00:00.000Z",
+      evidenceSha256: evidence,
+    },
+    ...overrides,
+  });
+  return signRuntimeArtifactManifest(manifest, privateKey, "rightkit-runtime-artifacts-2026-07");
+}
+
+test("accepts app-scoped pointers with one exact HeardRight-certified ASR identity", () => {
+  const result = assertAsrArtifactAdoption({
+    authorityEnvelope: envelope("heardright"),
+    consumerEnvelope: envelope("scraperight"),
+    publicKey,
+    trustedKeyId: "rightkit-runtime-artifacts-2026-07",
+  });
+
+  assert.equal(result.sha256, digest);
+  assert.equal(result.promotionId, "hr-asr-2026-07-14");
+});
+
+test("rejects a validly signed ScrapeRight manifest with ASR drift", () => {
+  const drifted = envelope("scraperight", {
+    versions: {
+      runtime: "rightkit-asr@0.1.1",
+      model: "parakeet-unified-en-0.6b",
+      tokenizer: "sha256:tokenizer-v1",
+      preprocessing: "heardright-frontend-v1",
+      license: "CC-BY-4.0",
+      provenance: "nvidia/parakeet-tdt-0.6b-v3",
+    },
+  });
+
+  assert.throws(() => assertAsrArtifactAdoption({
+    authorityEnvelope: envelope("heardright"),
+    consumerEnvelope: drifted,
+    publicKey,
+    trustedKeyId: "rightkit-runtime-artifacts-2026-07",
+  }), /ASR drift: versions\.runtime/);
+});
+
+test("rejects wrong roles, authority, target, signature key, and artifact kind", () => {
+  const base = {
+    authorityEnvelope: envelope("heardright"),
+    consumerEnvelope: envelope("scraperight"),
+    publicKey,
+    trustedKeyId: "rightkit-runtime-artifacts-2026-07",
+  };
+  assert.throws(() => assertAsrArtifactAdoption({ ...base, authorityEnvelope: envelope("scraperight") }), /authority manifest must belong to heardright/);
+  assert.throws(() => assertAsrArtifactAdoption({ ...base, consumerEnvelope: envelope("heardright") }), /consumer manifest must belong to scraperight/);
+  assert.throws(() => assertAsrArtifactAdoption({ ...base, trustedKeyId: "rotated-without-app-update" }), /untrusted runtime artifact key id/);
+  assert.throws(() => assertAsrArtifactAdoption({
+    ...base,
+    consumerEnvelope: envelope("scraperight", { target: { os: "darwin", arch: "aarch64" } }),
+  }), /ASR drift: target/);
+  assert.throws(() => assertAsrArtifactAdoption({
+    ...base,
+    consumerEnvelope: envelope("scraperight", { artifactKind: "ocr-model" }),
+  }), /must be an asr-model/);
+});
+
+test("rejects a consumer signed by a different key", () => {
+  const other = generateKeyPairSync("ed25519");
+  const consumer = signRuntimeArtifactManifest(
+    envelope("scraperight").manifest,
+    other.privateKey,
+    "rightkit-runtime-artifacts-2026-07",
+  );
+  assert.throws(() => assertAsrArtifactAdoption({
+    authorityEnvelope: envelope("heardright"),
+    consumerEnvelope: consumer,
+    publicKey,
+    trustedKeyId: "rightkit-runtime-artifacts-2026-07",
+  }), /signature verification failed/);
+});
+
+test("locks the thin app adapters to HeardRight authority and private Pro delivery", () => {
+  const authority = {
+    schema: 1, appKey: "heardright", role: "authority", authorityAppKey: "heardright",
+    artifactKind: "asr-model", delivery: "private-r2", entitlementTier: "pro",
+  };
+  const consumer = { ...authority, appKey: "scraperight", role: "consumer" };
+  assert.equal(assertAsrAdapterPair(authority, consumer), true);
+  assert.throws(() => assertAsrAdapterPair(authority, { ...consumer, authorityAppKey: "scraperight" }), /ASR drift/);
+});

package/cargo-contract.mjs

@@ -101,11 +101,34 @@ function assertNoRightKitOverrides(parsed, label, source) {
   }
 }
 
+// `tomllib` is Python 3.11+. Windows pins `py -3.11`, but a bare `python3` on macOS is the system
+// 3.9, which has no tomllib — so every app's release:doctor died on a stock Mac, and reported the
+// manifest as invalid TOML when the real problem was the interpreter. Probe for one that can.
+let tomlRunner;
+function resolveTomlRunner() {
+  if (tomlRunner) return tomlRunner;
+  const probe = "import sys,tomllib";
+  const candidates =
+    process.platform === "win32"
+      ? [["py", ["-3.11"]], ["py", ["-3"]], ["python", []]]
+      : [["python3.13", []], ["python3.12", []], ["python3.11", []], ["python3", []]];
+  for (const [command, prefix] of candidates) {
+    const check = spawnSync(command, [...prefix, "-c", probe], { encoding: "utf8", windowsHide: true });
+    if (check.status === 0) {
+      tomlRunner = { command, prefix };
+      return tomlRunner;
+    }
+  }
+  throw new Error(
+    "no Python with tomllib found (needs 3.11+). Install one, or put it on PATH: the release " +
+      "contract reads Cargo manifests through it.",
+  );
+}
+
 function readToml(file, label) {
   const script = "import json,pathlib,sys,tomllib; json.dump(tomllib.loads(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8')),sys.stdout,default=str)";
-  const command = process.platform === "win32" ? "py" : "python3";
-  const args = process.platform === "win32" ? ["-3.11", "-c", script, file] : ["-c", script, file];
-  const result = spawnSync(command, args, { encoding: "utf8", windowsHide: true });
+  const { command, prefix } = resolveTomlRunner();
+  const result = spawnSync(command, [...prefix, "-c", script, file], { encoding: "utf8", windowsHide: true });
   if (result.status !== 0) throw new Error(`${label} is not valid TOML: ${String(result.stderr ?? "").trim()}`);
   return JSON.parse(result.stdout);
 }

package/cli/right-release.mjs

@@ -44,9 +44,18 @@ if (first === "--version" || first === "-v") {
   const rest = args.slice(1);
   if (rest[0] === "cargo") {
     run("publish-cargo.mjs", rest.slice(1));
+  } else if (rest[0] === "swift") {
+    run("publish-swift.mjs", rest.slice(1));
   } 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 +122,9 @@ 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
+  publish swift [--scope <s>] [--url <u>] [--dry-run] Test, archive, scan, and publish RightKitSwift to a Swift registry
+  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;
+  });
+}