@kungfu-tech/buildchain 4.0.2-alpha.44 → 4.0.2-alpha.46

package/packages/core/oci-publication-bundle.js

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+
+export const OCI_FAMILY_SCHEMA = "kungfu-buildchain-oci-family/v1";
+const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+const namePattern = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+
+export function sealOciPublicationBundle({ bundleRoot, body }) {
+  const manifest = {
+    ...body,
+    root: v4ContentRoot("oci-publication-family", body),
+  };
+  verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: body.repository,
+    sourceSha: body.sourceSha,
+    version: body.version,
+  });
+  return manifest;
+}
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(`OCI bundle: ${message}`);
+}
+
+export function ociBundleFile(root, relative) {
+  requireValue(
+    typeof relative === "string" &&
+      relative.length > 0 &&
+      !relative.includes("\\") &&
+      !path.isAbsolute(relative) &&
+      !relative.split(/[\\/]/u).some((p) => p === ".." || p === "." || !p),
+    "unsafe file path",
+  );
+  const base = fs.realpathSync(root);
+  let current = base;
+  for (const segment of relative.split("/")) {
+    current = path.join(current, segment);
+    requireValue(
+      !fs.lstatSync(current).isSymbolicLink(),
+      "symlinks are forbidden",
+    );
+  }
+  requireValue(
+    fs.statSync(current).isFile() &&
+      fs.realpathSync(current).startsWith(`${base}${path.sep}`),
+    "file escapes bundle",
+  );
+  return current;
+}
+
+function fileDigest(file) {
+  const hash = crypto.createHash("sha256"),
+    buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, "r");
+  try {
+    for (;;) {
+      const size = fs.readSync(fd, buffer);
+      if (!size) break;
+      hash.update(buffer.subarray(0, size));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function verifyImageProvenance(image, config, sourceSha, version) {
+  const labels = config.config?.Labels || {};
+  requireValue(
+    image.content &&
+      /^[0-9a-f]{40}$/u.test(image.content.sourceSha) &&
+      typeof image.content.version === "string" &&
+      image.content.version.length > 0,
+    "missing image content provenance",
+  );
+  requireValue(
+    labels["org.opencontainers.image.revision"] === image.content.sourceSha &&
+      labels["org.opencontainers.image.version"] === image.content.version,
+    "image content provenance mismatch",
+  );
+  if (image.action === "built")
+    requireValue(
+      image.content.sourceSha === sourceSha &&
+        image.content.version === version,
+      "built image is not from the candidate source",
+    );
+  if (image.contractMajor !== undefined)
+    requireValue(
+      Number.isInteger(image.contractMajor) &&
+        image.contractMajor > 0 &&
+        labels["io.kungfu.image.contract-major"] ===
+          String(image.contractMajor),
+      "image contract major mismatch",
+    );
+  if (image.parentDigest)
+    requireValue(
+      digestPattern.test(image.parentDigest) &&
+        labels["io.kungfu.image.parent-digest"] === image.parentDigest,
+      "image parent digest mismatch",
+    );
+  if (image.content.materialSha)
+    requireValue(
+      /^[0-9a-f]{40}$/u.test(image.content.materialSha) &&
+        labels["io.kungfu.buildchain.release-material-sha"] ===
+          image.content.materialSha,
+      "image material provenance mismatch",
+    );
+}
+
+export function verifyOciPublicationBundle({
+  bundleRoot,
+  manifest,
+  repository,
+  sourceSha,
+  version,
+}) {
+  requireValue(
+    manifest?.schema === OCI_FAMILY_SCHEMA,
+    "unsupported manifest schema",
+  );
+  const { root, ...body } = manifest;
+  const computed = v4ContentRoot("oci-publication-family", body);
+  requireValue(root === computed, "manifest root mismatch");
+  requireValue(
+    manifest.repository === repository &&
+      manifest.sourceSha === sourceSha &&
+      manifest.version === version,
+    "candidate identity mismatch",
+  );
+  requireValue(
+    /^[a-z0-9-]+\/[a-z0-9._-]+$/u.test(repository),
+    "invalid repository",
+  );
+  requireValue(
+    Array.isArray(manifest.images) && manifest.images.length > 0,
+    "empty image family",
+  );
+  const expected = manifest.expectedImages;
+  requireValue(
+    Array.isArray(expected) &&
+      expected.length === new Set(expected).size &&
+      expected.every((n) => namePattern.test(n)),
+    "invalid expected image family",
+  );
+  const actual = manifest.images.map((i) => i.name).sort();
+  requireValue(
+    JSON.stringify(actual) === JSON.stringify([...expected].sort()),
+    "incomplete or duplicate image family",
+  );
+  const files = new Map();
+  for (const image of manifest.images) {
+    requireValue(
+      image.repository === `ghcr.io/${repository}/${image.name}`,
+      "destination must belong to the consumer repository",
+    );
+    requireValue(
+      digestPattern.test(image.digest) &&
+        ["built", "reused"].includes(image.action),
+      "invalid image identity",
+    );
+    requireValue(
+      /^linux\/(amd64|arm64)$/u.test(image.platform),
+      "unsupported image platform",
+    );
+    const prefix = image.layout;
+    const descriptorFile = (descriptor) => {
+      requireValue(
+        digestPattern.test(descriptor.digest) &&
+          Number.isSafeInteger(descriptor.size) &&
+          descriptor.size >= 0,
+        "invalid OCI descriptor",
+      );
+      const relative = `${prefix}/blobs/sha256/${descriptor.digest.slice(7)}`;
+      const file = ociBundleFile(bundleRoot, relative);
+      requireValue(
+        fs.statSync(file).size === descriptor.size,
+        "OCI blob size mismatch",
+      );
+      if (!files.has(file))
+        requireValue(
+          fileDigest(file) === descriptor.digest,
+          "OCI blob digest mismatch",
+        );
+      files.set(file, descriptor);
+      return file;
+    };
+    const layout = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/oci-layout`)),
+    );
+    requireValue(
+      layout.imageLayoutVersion === "1.0.0",
+      "unsupported OCI layout",
+    );
+    const index = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/index.json`)),
+    );
+    const selected = (index.manifests || []).filter(
+      (descriptor) =>
+        descriptor.digest === image.digest &&
+        (descriptor.annotations?.["org.opencontainers.image.ref.name"] ===
+          image.name ||
+          index.manifests.length === 1),
+    );
+    requireValue(
+      index.schemaVersion === 2 && selected.length === 1,
+      "OCI index must select one exact image manifest",
+    );
+    const document = JSON.parse(fs.readFileSync(descriptorFile(selected[0])));
+    requireValue(
+      document.schemaVersion === 2 &&
+        [
+          "application/vnd.oci.image.manifest.v1+json",
+          "application/vnd.docker.distribution.manifest.v2+json",
+        ].includes(document.mediaType) &&
+        Array.isArray(document.layers),
+      "unsupported OCI image manifest",
+    );
+    const config = JSON.parse(fs.readFileSync(descriptorFile(document.config)));
+    requireValue(
+      `${config.os}/${config.architecture}` === image.platform,
+      "OCI platform mismatch",
+    );
+    verifyImageProvenance(image, config, sourceSha, version);
+    for (const layer of document.layers) descriptorFile(layer);
+    const smokeFile = ociBundleFile(bundleRoot, image.smoke.path);
+    requireValue(
+      fileDigest(smokeFile) === image.smoke.sha256,
+      "smoke evidence digest mismatch",
+    );
+    const smoke = JSON.parse(fs.readFileSync(smokeFile));
+    requireValue(
+      smoke.passed === true && smoke.image === image.name,
+      "smoke qualification failed",
+    );
+  }
+  return { root: computed, manifest, bundleRoot: fs.realpathSync(bundleRoot) };
+}

package/packages/core/publication-sealed-bundle.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -19,7 +20,10 @@ function requiredString(value, label) {
 
 function safeRelativePath(value, label) {
   const normalized = requiredString(value, label).replaceAll("\\", "/");
-  if (normalized.startsWith("/") || normalized.split("/").some((part) => part === ".." || part === "")) {
+  if (
+    normalized.startsWith("/") ||
+    normalized.split("/").some((part) => part === ".." || part === "")
+  ) {
     throw new Error(`${label} must be a safe relative path`);
   }
   return normalized;
@@ -41,7 +45,8 @@ function sha256File(filePath) {
   const chunk = Buffer.allocUnsafe(8 * 1024 * 1024);
   try {
     let bytesRead = 0;
-    while ((bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytesRead));
+    while ((bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)) > 0)
+      hash.update(chunk.subarray(0, bytesRead));
   } finally {
     fs.closeSync(descriptor);
   }
@@ -60,8 +65,16 @@ function normalizeFile(entry, label) {
   };
 }
 
+function fileInventory(files, label) {
+  return (files || []).map((entry, index) => normalizeFile(entry, `${label}[${index}]`))
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
 function candidatePayload(candidate) {
-  if (candidate?.contract !== PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT || Number(candidate?.schemaVersion) !== 1) {
+  if (
+    candidate?.contract !== PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT ||
+    Number(candidate?.schemaVersion) !== 1
+  ) {
     throw new Error("publication artifact candidate contract mismatch");
   }
   const { candidateDigest: _candidateDigest, ...payload } = candidate;
@@ -91,9 +104,7 @@ export function createPublicationSealedBundle({
   githubReleaseRequired = true,
 } = {}) {
   const { digest } = candidatePayload(candidate);
-  const files = (candidate.files || [])
-    .map((entry, index) => normalizeFile(entry, `candidate.files[${index}]`))
-    .sort((left, right) => left.path.localeCompare(right.path));
+  const files = fileInventory(candidate.files, "candidate.files");
   if (new Set(files.map((entry) => entry.path)).size !== files.length) {
     throw new Error("publication sealed bundle candidate paths must be unique");
   }
@@ -119,6 +130,7 @@ export function createPublicationSealedBundle({
       sha256: npmTarball.sha256,
       integrity: requiredString(npmIntegrity, "npmIntegrity"),
     },
+    ...(candidate.npmPackages ? { npmPackages: candidate.npmPackages } : {}),
     releaseAssets,
     completion: {
       githubReleaseRequired: Boolean(githubReleaseRequired),
@@ -130,8 +142,55 @@ export function createPublicationSealedBundle({
   };
 }
 
+function verifyNpmPackageSet(manifest, files, resolvedRoot) {
+  const npmPackages = manifest.npmPackages;
+  if (JSON.stringify(npmPackages) !== JSON.stringify(manifest.candidate.npmPackages)) {
+    throw new Error("publication sealed bundle npm package inventory differs from candidate");
+  }
+  if (npmPackages) {
+    if (
+      !Array.isArray(npmPackages) ||
+      npmPackages.length < 2 ||
+      new Set(npmPackages.map((entry) => entry.name)).size !== npmPackages.length ||
+      new Set(npmPackages.map((entry) => entry.path)).size !== npmPackages.length
+    ) {
+      throw new Error("publication sealed bundle npm package inventory must be unique");
+    }
+    for (const entry of npmPackages) {
+      const file = selectFile(files, entry.path, "npmPackages.path");
+      const absolutePath = path.resolve(resolvedRoot, file.path);
+      const metadata = JSON.parse(
+        execFileSync("tar", ["-xOf", absolutePath, "package/package.json"], {
+          encoding: "utf8",
+        }),
+      );
+      const integrity = `sha512-${crypto.createHash("sha512").update(fs.readFileSync(absolutePath)).digest("base64")}`;
+      if (
+        entry.name !== metadata.name ||
+        entry.version !== metadata.version ||
+        entry.size !== file.size ||
+        entry.sha256 !== file.sha256 ||
+        entry.integrity !== integrity
+      ) {
+        throw new Error("publication sealed bundle npm package identity or integrity mismatch");
+      }
+    }
+    const main = npmPackages.filter((entry) => entry.role === "main");
+    if (
+      main.length !== 1 ||
+      Object.keys(manifest.npm).some((key) => main[0][key] !== manifest.npm[key])
+    ) {
+      throw new Error("publication sealed bundle npm main package mismatch");
+    }
+  }
+  return npmPackages;
+}
+
 export function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) {
-  if (manifest?.contract !== PUBLICATION_SEALED_BUNDLE_CONTRACT || Number(manifest?.schemaVersion) !== 1) {
+  if (
+    manifest?.contract !== PUBLICATION_SEALED_BUNDLE_CONTRACT ||
+    Number(manifest?.schemaVersion) !== 1
+  ) {
     throw new Error("publication sealed bundle contract mismatch");
   }
   const resolvedRoot = path.resolve(requiredString(bundleRoot, "bundleRoot"));
@@ -139,12 +198,8 @@ export function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) {
   if (normalizeSha256(manifest.root, "manifest.root") !== digest) {
     throw new Error("publication sealed bundle root mismatch");
   }
-  const files = (manifest.files || [])
-    .map((entry, index) => normalizeFile(entry, `manifest.files[${index}]`))
-    .sort((left, right) => left.path.localeCompare(right.path));
-  const candidateFiles = (manifest.candidate.files || [])
-    .map((entry, index) => normalizeFile(entry, `candidate.files[${index}]`))
-    .sort((left, right) => left.path.localeCompare(right.path));
+  const files = fileInventory(manifest.files, "manifest.files");
+  const candidateFiles = fileInventory(manifest.candidate.files, "candidate.files");
   if (JSON.stringify(files) !== JSON.stringify(candidateFiles)) {
     throw new Error("publication sealed bundle file inventory differs from candidate");
   }
@@ -169,6 +224,7 @@ export function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) {
   ) {
     throw new Error("publication sealed bundle npm tarball inventory mismatch");
   }
+  const npmPackages = verifyNpmPackageSet(manifest, files, resolvedRoot);
   const releaseAssets = (manifest.releaseAssets || []).map((entry, index) => {
     const selected = selectFile(files, entry.path, `manifest.releaseAssets[${index}].path`);
     const normalized = normalizeFile(entry, `manifest.releaseAssets[${index}]`);
@@ -194,6 +250,14 @@ export function verifyPublicationSealedBundle({ bundleRoot, manifest } = {}) {
       ...entry,
       absolutePath: path.resolve(resolvedRoot, entry.path),
     })),
+    ...(npmPackages
+      ? {
+          npmPackages: npmPackages.map((entry) => ({
+            ...entry,
+            absolutePath: path.resolve(resolvedRoot, entry.path),
+          })),
+        }
+      : {}),
     manifest,
   };
 }

package/packages/core/release-tail-product-capabilities.js

@@ -17,6 +17,15 @@ export const RELEASE_TAIL_PRODUCT_CAPABILITIES = Object.freeze([
     receiptKind: "product-package-publication",
     transactionState: "publishing",
   }),
+  Object.freeze({
+    id: "product.oci.publish",
+    executor: "provider-adapter",
+    adapter: "oci-image-family",
+    effectKind: "oci-family-publication",
+    observationKind: "oci-family-readback",
+    receiptKind: "oci-family-publication",
+    transactionState: "publishing",
+  }),
   Object.freeze({
     id: "product.release-refs.converge",
     executor: "provider-adapter",

package/packages/core/v4-canonical-contracts.js

@@ -58,6 +58,7 @@ const ROOT_DOMAINS = new Set([
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
   "v4-product-required-artifacts",
+  "oci-publication-family",
   "v4-product-publication-intent",
   "v4-product-publication-operation",
   "v4-product-publication-plan",

package/packages/core/v4-domain-wasm-artifact.js

@@ -2,6 +2,6 @@
 export const V4_DOMAIN_WASM_ABI_VERSION = 1;
 export const V4_DOMAIN_WASM_RUSTC = "rustc 1.96.0 (ac68faa20 2026-05-25)";
 export const V4_DOMAIN_WASM_SOURCE_SHA256 =
-  "07d45b2767e22007d3d41fa32c8a2dba28d9c88c11a2b28863e82d54be3a2933";
+  "bec17d9c47ab0ab8bdc379827f4bfb98fc95d41ee538c0558be538b86e06c775";
 export const V4_DOMAIN_WASM_SHA256 =
-  "b37c330e9366b7e9cf9dc4b7573b1e9495212dd9520e8b8ec6cdc3fd0ab7cafd";
+  "76600d4a9cfba5ac318c9b3be69e2a4e304faee714d2e72b1fba288f945c09f0";

package/packages/core/v4-product-publication.js

@@ -13,6 +13,7 @@ export function selectV4ProductPublicationIntent({
   repository,
   artifactKind = "npm",
   packageName,
+  npmPackages,
   distTag,
   sealedBundleRoot,
   requiredArtifactsRoot,
@@ -27,6 +28,7 @@ export function selectV4ProductPublicationIntent({
     sourceTimestamp,
     repository,
     artifactKind,
+    ...(npmPackages === undefined ? {} : { npmPackages }),
     ...(packageName === undefined ? {} : { packageName }),
     ...(distTag === undefined ? {} : { distTag }),
     ...(sealedBundleRoot === undefined ? {} : { sealedBundleRoot }),

package/scripts/check-v4-release-topology.mjs

@@ -233,13 +233,21 @@ function workflowSnapshot(relative) {
     .map((job) => {
       const block = jobBlock(source, job.id);
       const uses = job.uses || null;
+      // A built-in publisher still requires mutation authority when the caller supplies its envelope.
+      const inheritedPublisher =
+        !/^    permissions:/mu.test(block) &&
+        /uses:.*actions\/v4-release-candidate-promote/u.test(block);
       return {
         id: job.id,
         kind: uses ? "reusable-call" : "runner",
         uses,
         permissions: {
-          contents: permission(block, "contents"),
-          idToken: permission(block, "id-token"),
+          contents:
+            permission(block, "contents") ||
+            (inheritedPublisher ? "inherited" : null),
+          idToken:
+            permission(block, "id-token") ||
+            (inheritedPublisher ? "inherited" : null),
         },
         carriers: {
           artifactDownload: /uses:\s+actions\/download-artifact@/u.test(block),
@@ -247,8 +255,10 @@ function workflowSnapshot(relative) {
           jobOutput: /GITHUB_OUTPUT/u.test(block),
         },
         mutationSignals: [
-          /contents:\s*write/u.test(block) && "contents-write",
-          /id-token:\s*write/u.test(block) && "oidc-write",
+          (/contents:\s*write/u.test(block) || inheritedPublisher) &&
+            "contents-write",
+          (/id-token:\s*write/u.test(block) || inheritedPublisher) &&
+            "oidc-write",
           /(?:promote-buildchain-ref|v4-release-candidate-promote)/u.test(
             block,
           ) && "promotion-runtime",

package/scripts/generate-channel-promotion-workflow.mjs

@@ -316,16 +316,7 @@ ${secrets.trimEnd()}
     outputs:
 ${publicOutputs(outputs)}
 
-permissions:
-  actions: write
-  artifact-metadata: write
-  attestations: write
-  checks: write
-  contents: write
-  id-token: write
-  issues: write
-  pull-requests: write
-
+# Provider authority is inherited from the explicit caller envelope.
 jobs:
   resolve-promotion:
     name: Resolve promotion workflow shell and runtime
@@ -503,15 +494,7 @@ ${consumerAdmissionJob()}
     name: Invoke the single v4 publisher adapter
     needs: [resolve-promotion, consumer-admission]
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
-    permissions:
-      actions: write
-      artifact-metadata: write
-      attestations: write
-      checks: write
-      contents: write
-      id-token: write
-      issues: write
-      pull-requests: write
+    # Provider authority is inherited from the explicit caller envelope.
     with:
 ${invokeForwarded}
     secrets: inherit

package/scripts/generate-v4-universal-workflow-facades.mjs

@@ -216,11 +216,17 @@ function applyPublicationFacadePatches(source, relative) {
   return source;
 }
 
+function inheritPublicationProviderAuthority(source, relative) {
+  if (relative !== ".github/workflows/.release-candidate-promote.yml") return source;
+  return source.replace("permissions:\n  contents: read\n", "# Provider authority is inherited from the explicit caller envelope.\n")
+    .replace("    permissions:\n      actions: read\n      checks: write\n      contents: write\n      id-token: write\n      pull-requests: write\n", "    # Provider authority is inherited from the explicit caller envelope.\n");
+}
+
 export function migrateV4UniversalWorkflowFacade(source, relative) {
-  return rewriteRepositoryWorkflowPaths(root, applyPublicationFacadePatches(guardCompatibilityJobs(
+  return rewriteRepositoryWorkflowPaths(root, inheritPublicationProviderAuthority(applyPublicationFacadePatches(guardCompatibilityJobs(
     addUniversalInput(addRuntimeBootstrapDependencies(source, relative), relative),
     relative,
-  ), relative));
+  ), relative), relative));
 }
 
 function verify(source, relative) {

package/scripts/publication-candidate-kind.mjs

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { verifyOciPublicationBundle } from "../packages/core/oci-publication-bundle.js";
+
+export function resolveOciCandidate({ payloadRoot, passport }) {
+  const matches = [];
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink())
+        throw new Error("OCI candidate cannot contain symlinks");
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.name === "oci-family.json") matches.push(file);
+    }
+  }
+  visit(payloadRoot);
+  if (matches.length !== 1)
+    throw new Error("OCI candidate requires exactly one sealed image family");
+  const manifest = JSON.parse(fs.readFileSync(matches[0]));
+  const bundleRoot = path.dirname(matches[0]);
+  const verified = verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: passport.repository,
+    sourceSha: passport.source.headSha,
+    version: passport.target.version,
+  });
+  return {
+    root: bundleRoot,
+    manifest: verified.manifest,
+    requiredArtifacts: manifest.images.map((image) => ({
+      kind: "oci",
+      name: image.repository,
+      ref: `v${manifest.version}`,
+      digest: image.digest,
+      platform: image.platform,
+      required: true,
+    })),
+  };
+}
+
+export function resolveRecoveredPublicationVersion({
+  artifactVersion,
+  channel,
+  rematerializeOnResume = false,
+} = {}) {
+  const version = String(artifactVersion || "").trim(),
+    match = version.match(
+      /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,
+    );
+  if (!match)
+    throw new Error(
+      `recovered npm artifact has invalid publication version: ${version || "<empty>"}`,
+    );
+  return channel === "release" && rematerializeOnResume ? match[1] : version;
+}
+export function resolveRecoveredCandidateVersion({
+  artifactVersion,
+  publicationVersion,
+  channel,
+  rematerializeOnResume = false,
+  targetRef = "",
+  candidateRef = "",
+} = {}) {
+  const version = String(artifactVersion || "").trim(),
+    target = String(targetRef || "").replace(/^refs\/heads\//u, ""),
+    candidate = String(candidateRef || "").replace(/^refs\/heads\//u, "");
+  if (channel !== "release" || !rematerializeOnResume) return version;
+  const prefix = `publish-gate/${target}/`;
+  if (!target || !candidate.startsWith(prefix))
+    throw new Error(
+      `stable recovery candidate ref must descend from ${prefix || "publish-gate/<target>/"}`,
+    );
+  const candidateVersion = candidate.slice(prefix.length);
+  if (!/^\d+\.\d+\.\d+-alpha\.\d+$/u.test(candidateVersion))
+    throw new Error(
+      `stable recovery candidate ref must bind an exact alpha version, got ${candidateVersion || "<empty>"}`,
+    );
+  if (candidateVersion.replace(/-alpha\.\d+$/u, "") !== publicationVersion)
+    throw new Error(
+      `stable recovery candidate ${candidateVersion} does not match publication ${publicationVersion || "<empty>"}`,
+    );
+  if (
+    (version.match(
+      /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,
+    )?.[1] || "") !== publicationVersion
+  )
+    throw new Error(
+      `recovered npm artifact version ${version || "<empty>"} does not match publication ${publicationVersion}`,
+    );
+  return candidateVersion;
+}

package/scripts/publication-candidate-sealer.mjs

@@ -1,3 +1,4 @@
+import { resolveOciCandidate } from "./publication-candidate-kind.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -69,7 +70,7 @@ export function createResolvedPublicationSealedBundle({
   });
   const main = resolvedNpmArtifacts.find((entry) => entry.metadata.role === "main")
     || (resolvedNpmArtifacts.length === 1 ? resolvedNpmArtifacts[0] : undefined);
-  if (!main) throw new Error("candidate npm payload set has no unique main package tarball");
+  if (!main || resolvedNpmArtifacts.filter((entry) => entry.metadata.role === "main").length > 1) throw new Error("candidate npm payload set has no unique main package tarball");
   const selectedReleaseAssets = (releaseAssetPaths.length > 0
     ? releaseAssetPaths
     : resolvedNpmArtifacts.map((entry) => entry.file.absolutePath))
@@ -88,6 +89,12 @@ export function createResolvedPublicationSealedBundle({
     releaseCandidateRoot: `sha256:${normalizeSha256(releaseCandidateRoot, "releaseCandidateRoot")}`,
     files: files.map(({ path: filePath, size, sha256 }) => ({ path: filePath, size, sha256 })),
   };
+  if (resolvedNpmArtifacts.length > 1) {
+    candidatePayload.npmPackages = resolvedNpmArtifacts.map(({file, metadata}) => ({
+      name: metadata.name, version: metadata.ref, role: metadata.role,
+      path: file.path, size: file.size, sha256: file.sha256, integrity: metadata.integrity,
+    }));
+  }
   const candidate = {
     ...candidatePayload,
     candidateDigest: publicationArtifactCandidateDigest(candidatePayload),
@@ -102,3 +109,11 @@ export function createResolvedPublicationSealedBundle({
   });
   return { root: resolvedRoot, manifest, npmArtifacts: resolvedNpmArtifacts, files };
 }
+
+export function resolveCandidatePublicationBundle({ kind, payloadDir, passport, runtimeSha, npmArtifacts, releaseAssetPaths }) {
+  if (kind === "oci") return resolveOciCandidate({ payloadRoot: payloadDir, passport });
+  if (kind !== "npm") return undefined;
+  return createResolvedPublicationSealedBundle({ bundleRoot: payloadDir, repository: passport.repository,
+    sourceSha: passport.source?.headSha, sourceTreeSha: passport.source?.treeHash,
+    runtimeSha, releaseCandidateRoot: passport.candidateHash, npmArtifacts, releaseAssetPaths });
+}