@rightkit/release 0.2.69 → 0.2.71

package/build-release.mjs

@@ -23,6 +23,7 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout, dirtyBuildInputs, resolveReleaseBuildInputs } from "./release-invocation.mjs";
+import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
 import { commandOutputPortable, releaseEnvironment, resolveReleaseLayout, runBuildStateMachine, verifySealedRelease, watchProgress } from "./release-state.mjs";
 import { acquireCacheLease, acquireSuiteBuildSlot, applyCachePrune, assertWriteVolumeFloors, inspectCache, inspectWriteVolumes, markCacheEntrySuccessful, planCachePrune, readCachePolicy, resolveCacheLayout, resolveSharedCacheIdentity, resolveSharedCacheRoot } from "./cache-policy.mjs";
 import { createTargetBridge } from "./target-bridge.mjs";
@@ -48,7 +49,7 @@ const PIPELINE_FINGERPRINT = createHash("sha256")
   .slice(0, 16);
 
 /** Assemble preflight inputs from the app's own files (mirrors release.mjs). */
-function buildPreflight({ config, configPath, appRoot, repoRoot, platform }) {
+function buildPreflight({ config, configPath, appRoot, repoRoot, platform, nativeLayout }) {
   let version;
   try {
     version = JSON.parse(readFileSync(path.join(appRoot, "package.json"), "utf8")).version;
@@ -65,10 +66,7 @@ function buildPreflight({ config, configPath, appRoot, repoRoot, platform }) {
     // collision is already enforced downstream, and duplicating it here would
     // reject a legitimate resume of an in-flight build.
     version: undefined,
-    cargoLockPaths: [
-      path.join(appRoot, "src-tauri", "Cargo.lock"),
-      path.join(appRoot, "Cargo.lock"),
-    ],
+    cargoLockPaths: nativeLayout?.lockCandidates ?? [],
   });
 }
 
@@ -152,7 +150,10 @@ try {
   }
   const target = config.targets?.[platform];
   if (!target?.package) fail(`${config.app} has no ${platform} package command`);
-  if (platform === "win") assertNsisInPlaceUpgradeContract(appRoot, target.nsisUpgradeContract);
+  const nativeLayout = resolveNativeCargoLayout({ appRoot, config });
+  if (platform === "win" && target.signingContract === "windows-raw-exe-authenticode-before-nsis-v1") {
+    assertNsisInPlaceUpgradeContract(appRoot, target.nsisUpgradeContract);
+  }
   const { requiredInputs, buildInputs } = resolveReleaseBuildInputs({ repoRoot, appRoot, configPath, config, target });
   const dirtyInputs = dirtyBuildInputs(repoRoot, buildInputs, commit);
   if (dirtyInputs.length > 0) fail(`dirty files can change the packaged app; resolve them before release:\n${dirtyInputs.map((file) => `- ${file}`).join("\n")}`);
@@ -170,12 +171,12 @@ try {
     receiptInputs: ["raw-exe", "installer", "embedding"].map((phase) => path.join(receiptRoot, `windows-${phase}.json`)),
   } : null;
   if (signingIdentity) inputHashes[".right-release/signing-identity.json"] = hashFileText(JSON.stringify(signingIdentity));
-  const cargoLock = requiredInputs.find((file) => /Cargo\.lock$/i.test(file));
-  const cargoToml = requiredInputs.find((file) => /Cargo\.toml$/i.test(file));
+  const cargoLock = nativeLayout.lockPath;
+  const cargoToml = nativeLayout.manifestPath;
   // A broker-managed host is not identified by RIGHTKIT_BUILD_BROKER_SOCKET alone:
   // that variable is exported by login shells only, while the managed cargo shim is
   // on PATH for every shell. Detecting on the variable alone made agent (non-login)
-  // shells take the Cache V2 branch, bridge src-tauri/target into the release cache,
+  // shells take the Cache V2 branch, bridge resolved native target into release cache,
   // and then lose CARGO_TARGET_DIR to the broker's unconditional override — so the
   // app bundle landed in the broker workspace and packaging failed on an empty cache.
   const managedCargoTarget = brokerManagedHost(process.env) ? resolveTargetRoot(cargoToml) : null;
@@ -204,7 +205,7 @@ try {
   // Preflight BEFORE any compile. These preconditions used to be discovered one
   // per build cycle, minutes deep, with errors that named a symptom instead of a
   // cause. Blocking problems stop here, in seconds, naming the fix.
-  const preflight = buildPreflight({ config, configPath, appRoot, repoRoot: layout.repoRoot, platform });
+  const preflight = buildPreflight({ config, configPath, appRoot, repoRoot: layout.repoRoot, platform, nativeLayout });
   const preflightBlockers = preflightFailures(preflight);
   if (preflightBlockers.length > 0) {
     fail(`preflight found ${preflightBlockers.length} blocking problem(s):\n${formatPreflight(preflightBlockers)}`);
@@ -256,7 +257,7 @@ try {
     tools: toolVersions,
     createdAt: new Date().toISOString(),
   };
-  const targetLink = path.join(appRoot, "src-tauri", "target");
+  const targetLink = nativeLayout.targetLink;
   // ownedRoot is the per-app cache parent holding every fingerprint dir, so a
   // link left by an earlier fingerprint is recognised as ours and repointed
   // instead of hard-stopping the build.
@@ -329,7 +330,7 @@ try {
         checkpoint(stateRoot, "hardened");
       },
       seal: async ({ sealedDir }) => {
-        sealRelease({ configRoot: appRoot, managedCargoTarget, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity });
+        sealRelease({ configRoot: appRoot, managedCargoTarget, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity });
         verifySealedRelease(sealedDir);
         if (cacheMode === "shared") markCacheEntrySuccessful({ layout: sharedLayout });
         checkpoint(stateRoot, "sealed");
@@ -369,20 +370,24 @@ function sqlCipherFeatures(text) {
     .filter((value) => /sqlcipher|openssl/i.test(value));
 }
 
-function sealRelease({ configRoot, managedCargoTarget, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity }) {
+function sealRelease({ configRoot, managedCargoTarget, nativeLayout, sealedDir, releaseId, config, target, platform, commit, inputHashes, toolVersions, cacheKey, signingIdentity }) {
   // Every app's right-release.config.mjs names installer/updater artifacts
-  // relative to the local `src-tauri/target`. On a broker-managed host that
+  // relative to its resolved native target. On a broker-managed host that
   // directory is never populated (the broker owns CARGO_TARGET_DIR and
   // targetBridge.ensure() deliberately leaves a real local directory alone,
   // see target-bridge.mjs) so those paths must resolve against the broker's
   // own target root instead, or every managed build fails at seal after a
   // full compile, sign, and notarize.
   const targetPrefix = "src-tauri/target/";
+  const effectiveTargetPrefix = nativeLayout?.targetPrefix ?? targetPrefix;
   const resolveArtifactPath = (file) => {
     const normalized = file.replaceAll(path.win32.sep, "/");
     if (managedCargoTarget && normalized.startsWith(targetPrefix)) {
       return path.join(managedCargoTarget, normalized.slice(targetPrefix.length));
     }
+    if (managedCargoTarget && effectiveTargetPrefix !== targetPrefix && normalized.startsWith(effectiveTargetPrefix)) {
+      return path.join(managedCargoTarget, normalized.slice(effectiveTargetPrefix.length));
+    }
     return path.resolve(configRoot, file);
   };
   const sources = new Map();

package/cache-command.mjs

@@ -13,6 +13,7 @@ import {
   resolveSharedCacheRoot,
 } from "./cache-policy.mjs";
 import { resolveReleaseLayout } from "./release-state.mjs";
+import { resolveNativeCargoLayout } from "./native-cargo-layout.mjs";
 import { brokerManagedHost } from "./cargo-contract.mjs";
 
 // On a broker-managed host, CARGO_TARGET_DIR is not Cache V2's to own: the build
@@ -59,14 +60,16 @@ export async function runCacheCommand(args = process.argv.slice(2), { env = proc
     if (!config?.app) throw new Error("cache migrate config must expose app");
     const appRoot = path.dirname(configFile);
     const configuredTarget = config.targets?.[platform] ?? {};
-    const lockPath = path.join(appRoot, "src-tauri", "Cargo.lock");
-    const identity = resolveSharedCacheIdentity({ cargoLockPath: lockPath, cargoTomlPath: path.join(appRoot, "src-tauri", "Cargo.toml"), rustcVerbose: env.RIGHT_RELEASE_RUSTC_VERBOSE, targetTriple: configuredTarget.cargoTarget ?? configuredTarget.targetTriple ?? configuredTarget.rustTarget ?? env.TAURI_ENV_TARGET_TRIPLE, profile: configuredTarget.profile ?? "release" });
+    const nativeLayout = resolveNativeCargoLayout({ appRoot, config });
+    const lockPath = nativeLayout.lockPath;
+    if (!lockPath) throw new Error(`cache migrate could not find Cargo.lock for ${nativeLayout.manifestPath}`);
+    const identity = resolveSharedCacheIdentity({ cargoLockPath: lockPath, cargoTomlPath: nativeLayout.manifestPath, rustcVerbose: env.RIGHT_RELEASE_RUSTC_VERBOSE, targetTriple: configuredTarget.cargoTarget ?? configuredTarget.targetTriple ?? configuredTarget.rustTarget ?? env.TAURI_ENV_TARGET_TRIPLE, profile: configuredTarget.profile ?? "release" });
     const fingerprint = env.RIGHT_RELEASE_CACHE_KEY || identity.fingerprint;
     const layout = resolveCacheLayout({ cacheRoot, platform, architecture: identity.architecture, app: config.app, fingerprint, kind: "release" });
     const dryRun = !rest.includes("--apply");
-    const legacy = resolveReleaseLayout({ repoRoot: findRepoRoot(appRoot), configPath: configFile });
+    const legacy = resolveReleaseLayout({ repoRoot: findRepoRoot(appRoot), configPath: configFile, config, nativeLayout });
     const legacyTargetRoot = path.join(legacy.vaultRoot, "cache", "cargo-target", platform, fingerprint);
-    const result = migrateLegacyCache({ legacyRoot: path.join(appRoot, "src-tauri", "target"), legacyTargetRoot, legacyCargoHome: path.join(legacy.vaultRoot, "cache", "cargo-home"), legacyReleaseLockPath: path.join(legacy.vaultRoot, "locks", `${platform}.lock.json`), layout, app: config.app, dryRun });
+    const result = migrateLegacyCache({ legacyRoot: nativeLayout.targetLink, legacyTargetRoot, legacyCargoHome: path.join(legacy.vaultRoot, "cache", "cargo-home"), legacyReleaseLockPath: path.join(legacy.vaultRoot, "locks", `${platform}.lock.json`), layout, app: config.app, dryRun });
     return output({ schema: 1, command, cacheRoot, ...result }, json, stdout);
   }
   throw new Error("right-release cache: expected status, prune, or migrate");

package/native-cargo-layout.mjs

@@ -0,0 +1,239 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const DEFAULT_MANIFEST = path.join("src-tauri", "Cargo.toml");
+const LOCK_SOURCES = new Set(["manifest", "workspace", "root"]);
+
+/**
+ * Resolve every path which is derived from a native Cargo manifest in one
+ * place.  RightRelease historically assumed src-tauri; retaining that
+ * default keeps existing applications source-compatible while allowing a
+ * workspace package to opt into its real manifest.
+ */
+export function resolveNativeCargoLayout({
+  appRoot,
+  config,
+  nativeAssembly = config?.nativeAssembly,
+  exists = existsSync,
+  read = (file) => readFileSync(file, "utf8"),
+  requireManifest = false,
+  requireLock = false,
+} = {}) {
+  if (!appRoot) throw new TypeError("native Cargo layout requires appRoot");
+  const resolvedAppRoot = path.resolve(appRoot);
+  const declaredManifest = nativeAssembly?.cargoManifest ?? nativeAssembly?.manifest;
+  const manifestPath = resolveDeclaredPath(resolvedAppRoot, declaredManifest || DEFAULT_MANIFEST);
+  if (requireManifest && !exists(manifestPath)) throw new Error(`native Cargo manifest missing: ${manifestPath}`);
+
+  const manifestText = readIfPresent(manifestPath, exists, read);
+  const manifestDir = path.dirname(manifestPath);
+  const parsed = parseCargoManifest(manifestText);
+  const explicitWorkspace = nativeAssembly?.workspaceRoot ?? nativeAssembly?.cargoWorkspaceRoot;
+  const workspaceRoot = explicitWorkspace
+    ? normalizeWorkspaceRoot(resolveDeclaredPath(resolvedAppRoot, explicitWorkspace), exists)
+    : discoverWorkspaceRoot({ appRoot: resolvedAppRoot, manifestPath, manifestDir, manifestText, exists, read });
+
+  const lock = resolveCargoLock({
+    appRoot: resolvedAppRoot,
+    manifestPath,
+    manifestDir,
+    workspaceRoot,
+    nativeAssembly,
+    exists,
+  });
+  if (requireLock && !lock.path) {
+    throw new Error(`native Cargo.lock missing (checked ${lock.candidates.join(", ")})`);
+  }
+
+  const targetDeclaration = nativeAssembly?.targetDir
+    ?? nativeAssembly?.targetRoot
+    ?? nativeAssembly?.cargoTargetDir;
+  const targetLink = resolveDeclaredPath(resolvedAppRoot, targetDeclaration || path.join(relativeFromRoot(resolvedAppRoot, workspaceRoot), "target"));
+  const targetPrefix = relativePrefix(resolvedAppRoot, targetLink);
+  const manifestPrefix = relativePrefix(resolvedAppRoot, manifestDir);
+  const workspacePrefix = relativePrefix(resolvedAppRoot, workspaceRoot);
+  const targetPrefixes = [...new Set([
+    targetPrefix,
+    manifestPrefix ? `${manifestPrefix}target/` : "",
+    workspacePrefix ? `${workspacePrefix}target/` : "",
+  ].filter(Boolean))].sort((left, right) => right.length - left.length);
+  const layout = {
+    appRoot: resolvedAppRoot,
+    manifestPath,
+    cargoManifest: manifestPath,
+    manifestDir,
+    manifestPrefix,
+    workspaceRoot,
+    cargoWorkspaceRoot: workspaceRoot,
+    workspacePrefix,
+    lockPath: lock.path,
+    cargoLock: lock.path,
+    lockSource: lock.source,
+    lockCandidates: lock.candidates,
+    targetRoot: targetLink,
+    targetDir: targetLink,
+    targetLink,
+    targetPrefix,
+    targetPrefixes,
+    targetRootPrefix: targetPrefix,
+    native: Boolean(nativeAssembly),
+    fallback: !declaredManifest,
+    manifest: parsed,
+  };
+  layout.resolveArtifactPath = (file) => resolveNativeArtifactPath(layout, file);
+  return layout;
+}
+
+export const resolveCargoLayout = resolveNativeCargoLayout;
+export const resolveNativeCargoManifest = resolveNativeCargoLayout;
+export const resolveCargoManifest = resolveNativeCargoLayout;
+
+export function resolveNativeArtifactPath(layout, file) {
+  if (!layout?.appRoot) throw new TypeError("native artifact resolution requires a Cargo layout");
+  if (!file) throw new TypeError("native artifact path is required");
+  const value = String(file).replaceAll("\\", "/");
+  const targetPrefixes = layout.targetPrefixes ?? [layout.targetPrefix];
+  for (const prefixValue of targetPrefixes) {
+    const targetPrefix = stripTrailingSlash(prefixValue || "");
+    if (targetPrefix && (value === targetPrefix || value.startsWith(`${targetPrefix}/`))) {
+      return path.join(layout.targetRoot, value.slice(targetPrefix.length).replace(/^\/+/, ""));
+    }
+  }
+  return path.resolve(layout.appRoot, file);
+}
+
+export function parseCargoManifest(text = "") {
+  const cleaned = String(text)
+    .replace(/\/\/.*$/gm, "")
+    .replace(/#.*$/gm, "");
+  const workspaceSection = section(cleaned, "workspace");
+  const packageSection = section(cleaned, "package");
+  return {
+    hasWorkspace: workspaceSection != null,
+    workspacePath: stringValue(workspaceSection?.workspace),
+    packageWorkspace: stringValue(packageSection?.workspace),
+    packageName: stringValue(packageSection?.name),
+  };
+}
+
+export function findCargoLock({ manifestPath, appRoot, workspaceRoot, nativeAssembly, exists = existsSync } = {}) {
+  const resolvedAppRoot = path.resolve(appRoot || path.dirname(manifestPath || DEFAULT_MANIFEST));
+  const resolvedManifest = path.resolve(manifestPath || path.join(resolvedAppRoot, DEFAULT_MANIFEST));
+  const manifestDir = path.dirname(resolvedManifest);
+  return resolveCargoLock({
+    appRoot: resolvedAppRoot,
+    manifestPath: resolvedManifest,
+    manifestDir,
+    workspaceRoot: path.resolve(workspaceRoot || manifestDir),
+    nativeAssembly,
+    exists,
+  });
+}
+
+export const resolveCargoLockPath = findCargoLock;
+
+function resolveCargoLock({ appRoot, manifestPath, manifestDir, workspaceRoot, nativeAssembly, exists }) {
+  const declaredPath = nativeAssembly?.cargoLockPath
+    ?? nativeAssembly?.cargoLockFile
+    ?? nativeAssembly?.lockfilePath
+    ?? nativeAssembly?.lockPath;
+  const declared = nativeAssembly?.cargoLock ?? nativeAssembly?.lockfile ?? nativeAssembly?.lockSource;
+  const sourceDeclaration = nativeAssembly?.cargoLockSource ?? nativeAssembly?.lockSource;
+  const source = normalizeLockSource(sourceDeclaration ?? (typeof declared === "string" && LOCK_SOURCES.has(declared) ? declared : undefined));
+  if (declaredPath || (declared && !LOCK_SOURCES.has(String(declared)))) {
+    const explicit = declaredPath || declared;
+    const explicitPath = resolveDeclaredPath(appRoot, explicit);
+    return { path: exists(explicitPath) ? explicitPath : undefined, source: "explicit", candidates: [explicitPath] };
+  }
+  const roots = {
+    manifest: manifestDir,
+    workspace: workspaceRoot,
+    root: appRoot,
+  };
+  const orderedSources = source ? [source] : [workspaceRoot !== manifestDir ? "workspace" : "manifest", "manifest", "root"];
+  const candidates = [];
+  for (const candidateSource of orderedSources) {
+    const candidate = path.join(roots[candidateSource], "Cargo.lock");
+    if (!candidates.includes(candidate)) candidates.push(candidate);
+  }
+  const found = candidates.find((candidate) => exists(candidate));
+  return { path: found, source: found ? orderedSources[candidates.indexOf(found)] : undefined, candidates };
+}
+
+function discoverWorkspaceRoot({ appRoot, manifestPath, manifestDir, manifestText, exists, read }) {
+  const parsed = parseCargoManifest(manifestText);
+  const declaredWorkspace = parsed.workspacePath ?? parsed.packageWorkspace;
+  if (declaredWorkspace) {
+    return normalizeWorkspaceRoot(resolveDeclaredPath(manifestDir, declaredWorkspace), exists);
+  }
+  if (parsed.hasWorkspace) return manifestDir;
+  let current = manifestDir;
+  for (;;) {
+    const candidate = path.join(current, "Cargo.toml");
+    if (candidate !== manifestPath && exists(candidate) && parseCargoManifest(readIfPresent(candidate, exists, read)).hasWorkspace) return current;
+    if (current === appRoot) break;
+    const parent = path.dirname(current);
+    if (parent === current || !isWithin(appRoot, parent)) break;
+    current = parent;
+  }
+  return manifestDir;
+}
+
+function normalizeWorkspaceRoot(candidate, exists) {
+  const resolved = path.resolve(candidate);
+  if (path.basename(resolved).toLowerCase() === "cargo.toml") return path.dirname(resolved);
+  if (exists(resolved) && !path.extname(resolved)) return resolved;
+  if (exists(path.join(resolved, "Cargo.toml"))) return resolved;
+  return resolved;
+}
+
+function section(text, name) {
+  const expression = new RegExp(`(?:^|\\n)\\s*\\[${escapeRegExp(name)}\\]\\s*\\n([\\s\\S]*?)(?=\\n\\s*\\[|$)`, "m");
+  const match = text.match(expression);
+  if (!match) return undefined;
+  const values = {};
+  for (const line of match[1].split("\n")) {
+    const assignment = line.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*(.*?)\s*$/);
+    if (assignment) values[assignment[1]] = assignment[2];
+  }
+  return values;
+}
+
+function stringValue(value) {
+  const match = String(value ?? "").match(/^['\"]([^'\"]+)['\"]$/);
+  return match?.[1];
+}
+
+function normalizeLockSource(value) {
+  if (value == null) return undefined;
+  const normalized = String(value).toLowerCase();
+  return LOCK_SOURCES.has(normalized) ? normalized : undefined;
+}
+
+function resolveDeclaredPath(root, value) {
+  if (path.isAbsolute(String(value))) return path.normalize(String(value));
+  return path.resolve(root, String(value));
+}
+
+function relativeFromRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative || ".";
+}
+
+function relativePrefix(root, candidate) {
+  const relative = path.relative(root, candidate).replaceAll("\\", "/");
+  return relative && relative !== "." ? `${relative.replace(/\/+$/, "")}/` : "";
+}
+
+function stripTrailingSlash(value) { return String(value).replace(/\/+$/, ""); }
+
+function readIfPresent(file, exists, read) {
+  try { return exists(file) ? read(file) : ""; } catch { return ""; }
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function escapeRegExp(value) { return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }

package/native-release-finalization.mjs

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export const NATIVE_FINALIZATION_SCHEMA = 1;
+export const NATIVE_PROVENANCE_SCHEME = "rightkit-release";
+
+const PLACEHOLDER = /(?:placeholder|fabricat|pending|unknown|example|dummy|todo|changeme)/i;
+const STATUS = new Set(["complete", "completed", "pass", "passed", "verified"]);
+
+export function sha256Bytes(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function sha256File(file) {
+  return sha256Bytes(readFileSync(file));
+}
+
+export function normalizeDigest(value, label = "digest") {
+  const digest = String(value ?? "").toLowerCase().replace(/^sha256:/, "");
+  if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error(`${label} must be a SHA-256 hex digest`);
+  return digest;
+}
+
+export function canonicalSignedArtifacts(artifacts = []) {
+  if (!Array.isArray(artifacts)) throw new TypeError("signedArtifacts must be an array");
+  return artifacts.map((artifact) => {
+    if (typeof artifact === "string") return { path: artifact };
+    if (!artifact || typeof artifact !== "object") throw new TypeError("signed artifact must be a path or object");
+    const value = { ...artifact };
+    if (!value.path && value.file) value.path = value.file;
+    if (!value.path) throw new Error("signed artifact path is required");
+    if (value.sha256 != null) value.sha256 = normalizeDigest(value.sha256, `signed artifact ${value.path}`);
+    if (value.sizeBytes != null && (!Number.isSafeInteger(value.sizeBytes) || value.sizeBytes < 0)) {
+      throw new Error(`signed artifact size must be a non-negative integer: ${value.path}`);
+    }
+    return {
+      path: String(value.path).replaceAll("\\", "/"),
+      ...(value.sha256 ? { sha256: value.sha256 } : {}),
+      ...(value.sizeBytes != null ? { sizeBytes: value.sizeBytes } : {}),
+    };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function canonicalPackageIdentity(identity = {}) {
+  if (typeof identity === "string") identity = { name: identity };
+  if (!identity || typeof identity !== "object" || Array.isArray(identity)) throw new TypeError("package identity must be an object");
+  const result = {};
+  for (const key of ["name", "path", "kind", "version", "target", "platform", "architecture"]) {
+    if (identity[key] != null) result[key] = String(identity[key]).replaceAll("\\", "/");
+  }
+  if (Array.isArray(identity.artifacts)) {
+    result.artifacts = identity.artifacts.map((value) => String(value).replaceAll("\\", "/")).sort();
+  }
+  if (!Object.keys(result).length) throw new Error("package identity must include a stable name, path, kind, or artifact list");
+  return result;
+}
+
+/**
+ * Mint identity from signed files and package identity.  Archive bytes are
+ * included when available; before packaging, identity remains bound to the
+ * signed artifact set plus stable package identity and is completed later by
+ * createNativeFinalizationReceipt.
+ */
+export function mintNativeProvenance({
+  app,
+  version,
+  platform,
+  architecture,
+  targetTriple,
+  signedArtifacts = [],
+  packageIdentity,
+  archiveSha256,
+} = {}) {
+  const identity = canonicalPackageIdentity(packageIdentity);
+  const signed = canonicalSignedArtifacts(signedArtifacts);
+  if (!app || !version || !platform || !architecture) throw new Error("native provenance identity is incomplete");
+  const archive = archiveSha256 == null ? undefined : normalizeDigest(archiveSha256, "archiveSha256");
+  const payload = {
+    app: String(app),
+    version: String(version),
+    platform: String(platform),
+    architecture: String(architecture),
+    ...(targetTriple ? { targetTriple: String(targetTriple) } : {}),
+    signedArtifacts: signed,
+    packageIdentity: identity,
+    ...(archive ? { archiveSha256: archive } : {}),
+  };
+  const digest = sha256Bytes(JSON.stringify(payload));
+  const pathParts = [app, version, platform, architecture].map((value) => encodeURIComponent(String(value)));
+  return `${NATIVE_PROVENANCE_SCHEME}://${pathParts.join("/")}/${digest}`;
+}
+
+export function validateNativeProvenance(value, { expectedScheme = NATIVE_PROVENANCE_SCHEME } = {}) {
+  const provenance = String(value ?? "");
+  if (!provenance.startsWith(`${expectedScheme}://`)) {
+    throw new Error(`native finalizer provenance must use ${expectedScheme}://`);
+  }
+  if (PLACEHOLDER.test(provenance)) throw new Error("native finalizer returned placeholder provenance");
+  const digest = provenance.slice(provenance.lastIndexOf("/") + 1);
+  normalizeDigest(digest, "native provenance identity");
+  return provenance;
+}
+
+export function finalizationArchive(file, { root } = {}) {
+  const resolved = root && !path.isAbsolute(String(file)) ? path.resolve(root, file) : path.resolve(String(file));
+  if (!existsSync(resolved)) throw new Error(`native finalization archive missing: ${resolved}`);
+  const stat = statSync(resolved);
+  if (!stat.isFile()) throw new Error(`native finalization archive is not a file: ${resolved}`);
+  return {
+    path: root ? path.relative(root, resolved).replaceAll("\\", "/") : resolved.replaceAll("\\", "/"),
+    sha256: sha256File(resolved),
+    sizeBytes: stat.size,
+  };
+}
+
+export function createNativeFinalizationReceipt({
+  app,
+  version,
+  platform,
+  architecture,
+  targetTriple,
+  signedArtifacts = [],
+  packageIdentity,
+  archive,
+  archivePath,
+  archiveSha256,
+  finalizerOutput,
+  root,
+  now = new Date().toISOString(),
+} = {}) {
+  const identity = canonicalPackageIdentity(packageIdentity);
+  const signed = canonicalSignedArtifacts(signedArtifacts);
+  let resolvedArchive = archive;
+  if (!resolvedArchive && archivePath) resolvedArchive = finalizationArchive(archivePath, { root });
+  if (resolvedArchive) {
+    const archiveFile = resolvedArchive.path || resolvedArchive.file;
+    const digest = resolvedArchive.sha256 ?? archiveSha256;
+    if (!digest) throw new Error("native finalization archive digest is required");
+    if (archiveFile && root) {
+      const observed = finalizationArchive(archiveFile, { root });
+      if (normalizeDigest(digest, "archiveSha256") !== observed.sha256) throw new Error("native finalization archive digest does not match archive bytes");
+      resolvedArchive = observed;
+    }
+    resolvedArchive = {
+      ...resolvedArchive,
+      ...(archiveFile ? { path: String(archiveFile).replaceAll("\\", "/") } : {}),
+      sha256: normalizeDigest(digest, "archiveSha256"),
+      ...(resolvedArchive.sizeBytes != null ? { sizeBytes: resolvedArchive.sizeBytes } : {}),
+    };
+  } else if (archiveSha256) {
+    resolvedArchive = { sha256: normalizeDigest(archiveSha256, "archiveSha256") };
+  } else {
+    throw new Error("native finalization receipt requires final archive digest");
+  }
+  const provenance = mintNativeProvenance({
+    app,
+    version,
+    platform,
+    architecture,
+    targetTriple,
+    signedArtifacts: signed,
+    packageIdentity: identity,
+    archiveSha256: resolvedArchive.sha256,
+  });
+  const output = finalizerOutput && typeof finalizerOutput === "object" ? finalizerOutput : {};
+  if (output.provenance != null) validateNativeProvenance(output.provenance);
+  if (output.signedArtifacts != null || output.signed != null) {
+    const observed = canonicalSignedArtifacts(output.signedArtifacts ?? output.signed);
+    if (JSON.stringify(observed) !== JSON.stringify(signed)) throw new Error("native finalizer signed artifact identity mismatch");
+  }
+  if (output.packageIdentity != null || output.package != null) {
+    const observed = canonicalPackageIdentity(output.packageIdentity ?? output.package);
+    if (JSON.stringify(observed) !== JSON.stringify(identity)) throw new Error("native finalizer package identity mismatch");
+  }
+  const outputArchiveDigest = output.archiveSha256 ?? output.archive?.sha256 ?? output.archive?.digest;
+  if (outputArchiveDigest != null && normalizeDigest(outputArchiveDigest, "finalizer archiveSha256") !== resolvedArchive.sha256) {
+    throw new Error("native finalizer archive digest does not match final archive");
+  }
+  const receipt = {
+    schema: NATIVE_FINALIZATION_SCHEMA,
+    kind: "rightkit-native-finalization",
+    status: "verified",
+    app: String(app),
+    version: String(version),
+    platform: String(platform),
+    architecture: String(architecture),
+    ...(targetTriple ? { targetTriple: String(targetTriple) } : {}),
+    provenance,
+    signedArtifacts: signed,
+    packageIdentity: identity,
+    archive: resolvedArchive,
+    archiveSha256: resolvedArchive.sha256,
+    finalizedAt: now,
+  };
+  validateNativeFinalizationOutput(receipt, { requireArchive: true });
+  return receipt;
+}
+
+export function validateNativeFinalizationOutput(output, {
+  expectedProvenance,
+  expectedArchiveSha256,
+  expectedSignedArtifacts,
+  expectedPackageIdentity,
+  requireArchive = false,
+} = {}) {
+  if (!output || typeof output !== "object" || Array.isArray(output)) throw new Error("native finalizer output must be an object");
+  if (output.schema != null && output.schema !== NATIVE_FINALIZATION_SCHEMA) throw new Error(`unsupported native finalizer schema: ${output.schema}`);
+  const status = String(output.status ?? "").toLowerCase();
+  if (!STATUS.has(status)) throw new Error("native finalizer output must have complete, pass, or verified status");
+  const provenance = validateNativeProvenance(output.provenance);
+  if (expectedProvenance && provenance !== expectedProvenance) throw new Error("native finalizer provenance identity mismatch");
+  const signed = canonicalSignedArtifacts(output.signedArtifacts ?? output.signed ?? []);
+  if (expectedSignedArtifacts) {
+    const expected = canonicalSignedArtifacts(expectedSignedArtifacts);
+    if (JSON.stringify(signed) !== JSON.stringify(expected)) throw new Error("native finalizer signed artifact identity mismatch");
+  }
+  if (expectedPackageIdentity) {
+    const actual = canonicalPackageIdentity(output.packageIdentity ?? output.package ?? {});
+    const expected = canonicalPackageIdentity(expectedPackageIdentity);
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error("native finalizer package identity mismatch");
+  }
+  const archiveValue = output.archiveSha256 ?? output.archive?.sha256 ?? output.archive?.digest;
+  if (requireArchive && !archiveValue) throw new Error("native finalizer output must bind final archive digest");
+  const archiveSha256 = archiveValue ? normalizeDigest(archiveValue, "archiveSha256") : undefined;
+  if (expectedArchiveSha256 && archiveSha256 !== normalizeDigest(expectedArchiveSha256, "expected archiveSha256")) {
+    throw new Error("native finalizer archive digest mismatch");
+  }
+  if (output.archive?.path != null && PLACEHOLDER.test(String(output.archive.path))) throw new Error("native finalizer archive path is a placeholder");
+  return { ...output, provenance, signedArtifacts: signed, ...(archiveSha256 ? { archiveSha256 } : {}) };
+}
+
+export const validateNativeFinalization = validateNativeFinalizationOutput;
+export const mintRightKitProvenance = mintNativeProvenance;
+
+export function readNativeFinalizationOutput(file) {
+  if (!file) throw new TypeError("native finalizer output path is required");
+  if (!existsSync(file)) throw new Error(`native finalizer output missing: ${file}`);
+  let output;
+  try { output = JSON.parse(readFileSync(file, "utf8")); } catch (error) { throw new Error(`native finalizer output is not valid JSON: ${file}: ${error.message}`); }
+  return validateNativeFinalizationOutput(output);
+}
+
+export const finalizeNativeRelease = createNativeFinalizationReceipt;
+
+export function resolveNativeFinalizerConfig(nativeAssembly) {
+  const finalizer = nativeAssembly?.finalizer;
+  if (!finalizer) return undefined;
+  if (typeof finalizer === "string") return { cmd: finalizer, args: [] };
+  if (!finalizer || typeof finalizer !== "object" || Array.isArray(finalizer)) throw new Error("nativeAssembly.finalizer must be a command object");
+  const command = finalizer.command ?? finalizer;
+  if (!command?.cmd || typeof command.cmd !== "string" || !Array.isArray(command.args ?? [])) throw new Error("nativeAssembly.finalizer must declare cmd and args");
+  return {
+    ...finalizer,
+    cmd: command.cmd,
+    args: [...(command.args ?? [])].map(String),
+    output: finalizer.output ?? finalizer.receipt ?? finalizer.receiptPath ?? finalizer.outputFile,
+  };
+}