@kungfu-tech/buildchain 4.0.2 → 4.0.3

package/scripts/init-repo.mjs

@@ -366,7 +366,7 @@ jobs:
 }
 
 function workflowYaml({ type, runnerPreset, artifactName }) {
-  return `${nextDevelopmentWorkflowHeader()}# Buildchain v4 lifecycle checkpoints are governed by architecture/v4-platform-stage-checkpoints.json.
+  return `${nextDevelopmentWorkflowHeader()}# Buildchain v4 lifecycle checkpoints are governed by architecture/platform-stage-checkpoints.json.
 # Do not add undeclared runner-only inputs, outputs, environment, or provider effects.
 # Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
 # Persist only @v4 or @v4-alpha; pass temporary train/SHA runtimes through workflow_dispatch.

package/scripts/next-development-review.mjs

@@ -1,3 +1,4 @@
+import { nextPatchDevelopmentVersion } from "../packages/core/publication-development.js";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
@@ -5,14 +6,14 @@ import { pathToFileURL } from "node:url";
 import { verifyVersionStateDelta } from "./verify-version-state-delta.mjs";
 import { readBinaryPublicationEvidence } from "./binary-publication-evidence.mjs";
 import { releaseAssetClient } from "./release-asset-client.mjs";
-import { enqueueNextDevelopmentPullRequest } from "../actions/v4-release-candidate-promote/next-development-queue.js";
+import { enqueueNextDevelopmentPullRequest } from "../actions/release-candidate-promote/next-development-queue.js";
 
 const REPOSITORY = "kungfu-systems/buildchain";
 const WORKFLOW = ".github/workflows/self-build-verify.yml";
 const REVIEWER = "kungfu-origin";
 const SHA = /^[a-f0-9]{40}$/u;
 const BRANCH =
-  /^chore\/next-development\/(4\.\d+\.\d+-alpha\.\d+)-[a-f0-9]{16}$/u;
+  /^chore\/next-development\/((?:0|[1-9]\d*)\.\d+\.\d+-alpha\.\d+)-[a-f0-9]{16}$/u;
 
 export function assertReviewRun(run, { repository, runId, headSha } = {}) {
   if (
@@ -43,7 +44,7 @@ export function assertReviewPull(
     pull.base?.sha !== baseSha ||
     pull.head?.ref !== branch ||
     !BRANCH.test(branch || "") ||
-    !/^dev\/v4\/v4\.\d+$/u.test(pull.base?.ref || "") ||
+    pull.base?.ref !== `dev/v${BRANCH.exec(branch)?.[1].split(".")[0]}/v${BRANCH.exec(branch)?.[1].split(".").slice(0, 2).join(".")}` ||
     pull.state !== "open" ||
     pull.draft ||
     pull.merged_at ||
@@ -114,18 +115,23 @@ export async function verifyNextDevelopmentReview({
   const parents = git("show", "-s", "--format=%P", run.head_sha).split(" ");
   if (parents.length !== 1 || parents[0] !== baseSha)
     throw new Error("next-development must have one exact protected parent");
-  const projection = verifyDelta({ baseSha, headSha: run.head_sha });
-  if (BRANCH.exec(run.head_branch)[1] !== projection.version)
-    throw new Error(
-      "next-development branch version differs from regenerated version",
-    );
   const version = JSON.parse(git("show", `${baseSha}:package.json`)).version;
-  const tag = `v${version}`;
+  const targetVersion = BRANCH.exec(run.head_branch)[1];
+  const stable = targetVersion.endsWith("-alpha.0");
+  const completedStableVersion = version.split("-alpha.")[0];
+  if (stable && nextPatchDevelopmentVersion(completedStableVersion) !== targetVersion)
+    throw new Error("development target is not the completed stable patch successor");
+  const tag = `v${stable ? completedStableVersion : version}`;
   const sourceSha = client.json(`repos/${repository}/commits/${tag}`).sha;
   const settlement = await publication({ repository, tag, sourceSha });
   const publishedTree = settlement.documents.passport.source.treeHash;
-  if (publishedTree !== git("rev-parse", `${baseSha}^{tree}`))
+  if (!stable && publishedTree !== git("rev-parse", `${baseSha}^{tree}`))
     throw new Error("development base is not the completed alpha source tree");
+  if (stable && (settlement.documents.passport.release?.version !== completedStableVersion || settlement.documents.invocation?.target?.channel !== "stable"))
+    throw new Error("stable publication evidence differs from the completed version");
+  const projection = verifyDelta({ baseSha, headSha: run.head_sha, ...(stable ? { completedStableVersion } : {}) });
+  if (targetVersion !== projection.version)
+    throw new Error("next-development branch version differs from regenerated version");
   observe(client, repository, runId, {
     headSha: run.head_sha,
     baseSha,
@@ -175,7 +181,7 @@ export async function approveNextDevelopment({ client, reviewer, plan }) {
     await reviewer.post(endpoint, {
       event: "APPROVE",
       commit_id: plan.headSha,
-      body: `Verified the exact version-only transition by regenerating all tracked bytes from protected base ${plan.baseSha}. Completed alpha receipt: ${plan.publicationReceiptRoot}. Verification run: https://github.com/${plan.repository}/actions/runs/${plan.runId}.`,
+      body: `Verified the exact version-only transition by regenerating all tracked bytes from protected base ${plan.baseSha}. Completed publication receipt: ${plan.publicationReceiptRoot}. Verification run: https://github.com/${plan.repository}/actions/runs/${plan.runId}.`,
     });
   }
   observe(client, plan.repository, plan.runId, plan);

package/scripts/oci-compose-preview.mjs

@@ -0,0 +1,261 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { verifyPublicationSettlement } from "./publication-settlement.mjs";
+import {
+  verifyComposePublication,
+  verifyComposeQualification,
+} from "../packages/core/oci-compose-qualification.js";
+import { releaseTailRoot } from "../packages/core/release-tail-provider-plane.js";
+import { createRegistryClient } from "../actions/release-candidate-promote/oci-registry-client.js";
+import { ociPublicationTag } from "../packages/core/oci-publication-graph.js";
+
+const digest = (bytes) =>
+  `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+function check(condition, message) {
+  if (!condition) throw new Error(`Compose preview: ${message}`);
+}
+function gh(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+const api = (route) => JSON.parse(gh(["api", route]));
+const read = (file) => JSON.parse(fs.readFileSync(file));
+export function createComposePreviewRegistry(environment, fetchImpl = fetch) {
+  const token = environment.BUILDCHAIN_REGISTRY_TOKEN;
+  const actor = environment.GITHUB_ACTOR;
+  check(
+    typeof token === "string" &&
+      token.length > 0 &&
+      typeof actor === "string" &&
+      actor.length > 0,
+    "explicit scoped registry identity required",
+  );
+  return createRegistryClient(token, fetchImpl, actor);
+}
+function output(name, value) {
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+}
+
+export async function promoteComposePreview({
+  context,
+  registry,
+  receipt,
+  fetchManifest,
+}) {
+  const { application, policy } = context;
+  const exact = await fetchManifest(
+    ociPublicationTag(application, context.tag.slice(1)),
+  );
+  check(
+    exact.digest === application.digest,
+    "immutable application digest changed",
+  );
+  const current = await fetchManifest(policy.alias, true);
+  check(
+    current.digest === policy.previousDigest ||
+      current.digest === application.digest,
+    "preview changed since qualification",
+  );
+  const plan = {
+    schema: "kungfu-buildchain-compose-preview-plan/v1",
+    ...context,
+    qualificationRoot: releaseTailRoot(receipt),
+    expectedOld: policy.previousDigest,
+    targetDigest: application.digest,
+    operation: "digest-preserving-preview-promotion",
+  };
+  if (current.digest !== application.digest) {
+    const result = await registry(application, `manifests/${policy.alias}`, {
+      write: true,
+      method: "PUT",
+      body: exact.bytes,
+      headers: {
+        "content-type": exact.mediaType,
+        "content-length": String(exact.bytes.length),
+      },
+    });
+    check(
+      result.status === 201,
+      `preview write uncertain (HTTP ${result.status}); retain the original qualification for readback`,
+    );
+  }
+  const observed = await fetchManifest(policy.alias);
+  check(observed.digest === application.digest, "preview readback mismatch");
+  const body = {
+    schema: "kungfu-buildchain-compose-preview-receipt/v1",
+    repository: context.repository,
+    tag: context.tag,
+    sourceSha: context.sourceSha,
+    publicationReceiptRoot: context.publicationReceiptRoot,
+    planRoot: releaseTailRoot(plan),
+    qualificationRoot: plan.qualificationRoot,
+    previousDigest: policy.previousDigest,
+    application: `${application.repository}@${application.digest}`,
+    alias: `${application.repository}:${policy.alias}`,
+    observedDigest: observed.digest,
+    outcome: "complete",
+  };
+  return { ...body, receiptRoot: releaseTailRoot(body) };
+}
+
+async function run(mode) {
+  const repository = process.env.GITHUB_REPOSITORY,
+    event = read(process.env.GITHUB_EVENT_PATH);
+  check(
+    process.env.GITHUB_EVENT_NAME === "workflow_run" && event.workflow_run?.id,
+    "requires a completed qualification workflow event",
+  );
+  check(
+    /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/u.test(repository),
+    "invalid repository",
+  );
+  const id = String(event.workflow_run.id);
+  check(/^\d+$/u.test(id), "invalid qualification run");
+  const run = api(`repos/${repository}/actions/runs/${id}`),
+    tag = run.head_branch;
+  check(
+    /^v\d+\.\d+\.\d+-alpha\.\d+$/u.test(tag),
+    "qualification must run on an exact alpha tag",
+  );
+  const release = api(`repos/${repository}/releases/tags/${tag}`);
+  check(release.prerelease && !release.draft, "public alpha release required");
+  const root = path.resolve(".buildchain/compose-preview");
+  fs.mkdirSync(path.join(root, "public"), { recursive: true });
+  const names = [
+    "oci-family.json",
+    "oci-publication-readback.json",
+    "buildchain-publication-settlement.json",
+    "buildchain.release.json",
+  ];
+  for (const name of names) {
+    check(
+      release.assets.filter((asset) => asset.name === name).length === 1,
+      `missing exact public asset ${name}`,
+    );
+    gh([
+      "release",
+      "download",
+      tag,
+      "--repo",
+      repository,
+      "--pattern",
+      name,
+      "--dir",
+      path.join(root, "public"),
+      "--clobber",
+    ]);
+  }
+  const [family, readback, settlement, publicPassport] = names.map((name) =>
+    read(path.join(root, "public", name)),
+  );
+  const documents = settlement.documents;
+  const tagged = api(`repos/${repository}/commits/${tag}`).sha;
+  verifyPublicationSettlement(documents, {
+    repository,
+    tag,
+    sourceSha: tagged,
+    publicPassport,
+  });
+  const context = verifyComposePublication({
+    family,
+    readback,
+    documents,
+    repository,
+    tag,
+  });
+  verifyComposeQualification(context, run);
+  const artifactName = `oci-compose-qualification-${id}-${run.run_attempt}`;
+  const artifacts = api(
+    `repos/${repository}/actions/runs/${id}/artifacts?per_page=100`,
+  ).artifacts.filter(
+    (artifact) => artifact.name === artifactName && !artifact.expired,
+  );
+  check(
+    artifacts.length === 1,
+    "qualification artifact is missing or ambiguous",
+  );
+  if (mode === "prepare") {
+    output("artifact-id", artifacts[0].id);
+    output("run-id", id);
+    output("source-sha", tagged);
+    return;
+  }
+  check(mode === "apply", "unsupported mode");
+  const evidenceRoot = path.join(root, "qualification");
+  const receipt = read(path.join(evidenceRoot, "qualification.json"));
+  verifyComposeQualification(context, run, receipt);
+  for (const item of receipt.evidence) {
+    const file = path.join(evidenceRoot, item.path);
+    check(
+      !fs.lstatSync(file).isSymbolicLink() &&
+        fs.statSync(file).size < 2_000_000 &&
+        digest(fs.readFileSync(file)) === item.sha256,
+      "qualification evidence bytes mismatch",
+    );
+  }
+  const { registry } = createComposePreviewRegistry(process.env);
+  async function fetchManifest(ref, allowAbsent = false) {
+    const response = await registry(context.application, `manifests/${ref}`, {
+      headers: {
+        accept:
+          "application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json",
+      },
+    });
+    if (allowAbsent && response.status === 404) return { digest: "none" };
+    check(response.ok, "public registry readback unavailable");
+    const bytes = Buffer.from(await response.arrayBuffer()),
+      value = digest(bytes);
+    check(
+      !response.headers.get("docker-content-digest") ||
+        response.headers.get("docker-content-digest") === value,
+      "registry digest mismatch",
+    );
+    return { bytes, digest: value, mediaType: JSON.parse(bytes).mediaType };
+  }
+  const result = await promoteComposePreview({
+    context,
+    registry,
+    receipt,
+    fetchManifest,
+  });
+  const file = path.join(
+    root,
+    `buildchain-compose-preview-${id}-${run.run_attempt}.json`,
+  );
+  fs.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+  const existing = release.assets.find(
+    (asset) => asset.name === path.basename(file),
+  );
+  if (existing) {
+    const previous = path.join(root, "previous");
+    fs.mkdirSync(previous, { recursive: true });
+    gh([
+      "release",
+      "download",
+      tag,
+      "--repo",
+      repository,
+      "--pattern",
+      path.basename(file),
+      "--dir",
+      previous,
+      "--clobber",
+    ]);
+    check(
+      fs.readFileSync(path.join(previous, path.basename(file)), "utf8") ===
+        fs.readFileSync(file, "utf8"),
+      "existing preview receipt conflict",
+    );
+  } else gh(["release", "upload", tag, file, "--repo", repository]);
+  process.stdout.write(`Verified ${result.alias}@${result.observedDigest}\n`);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  run(process.argv[2]).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });

package/scripts/{v4-platform-stage-checkpoint-rehearsal.mjs → platform-stage-checkpoint-rehearsal.mjs}

@@ -5,14 +5,14 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-import { v4CanonicalBytes } from "../packages/core/v4-canonical-contracts.js";
-import { V4StageCapsuleLocalStore } from "../packages/core/v4-stage-capsule-local-store.js";
-import { v4StageCapsuleBlobRoot } from "../packages/core/v4-stage-capsule-store.js";
+import { domainCanonicalBytes } from "../packages/core/canonical-contracts.js";
+import { StageCapsuleLocalStore } from "../packages/core/stage-capsule-local-store.js";
+import { stageCapsuleBlobRoot } from "../packages/core/stage-capsule-store.js";
 import {
-  emitV4PlatformStageCheckpoint,
-  restoreV4PlatformStageCheckpoint,
-  validateV4PlatformStageCheckpointDeclaration,
-} from "../packages/core/v4-platform-stage-checkpoints.js";
+  emitPlatformStageCheckpoint,
+  restorePlatformStageCheckpoint,
+  validatePlatformStageCheckpointDeclaration,
+} from "../packages/core/platform-stage-checkpoints.js";
 
 const repoRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -32,10 +32,10 @@ function required(name) {
 }
 
 function readDeclaration() {
-  return validateV4PlatformStageCheckpointDeclaration(
+  return validatePlatformStageCheckpointDeclaration(
     JSON.parse(
       fs.readFileSync(
-        path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+        path.join(repoRoot, "architecture/platform-stage-checkpoints.json"),
         "utf8",
       ),
     ),
@@ -49,12 +49,12 @@ function stageFor(declaration, stageId) {
 }
 
 function rooted(label) {
-  return v4StageCapsuleBlobRoot(Buffer.from(`${label}\n`, "utf8"));
+  return stageCapsuleBlobRoot(Buffer.from(`${label}\n`, "utf8"));
 }
 
 function writeJson(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, v4CanonicalBytes(value), { flag: "wx" });
+  fs.writeFileSync(file, domainCanonicalBytes(value), { flag: "wx" });
 }
 
 function emit({ workRoot, platformId, stageId, recordedAt }) {
@@ -87,11 +87,11 @@ function emit({ workRoot, platformId, stageId, recordedAt }) {
   const productionOutputRoots = Object.fromEntries(
     Object.entries(outputs).map(([name, bytes]) => [
       name,
-      v4StageCapsuleBlobRoot(bytes),
+      stageCapsuleBlobRoot(bytes),
     ]),
   );
-  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
-  const result = emitV4PlatformStageCheckpoint({
+  const store = new StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = emitPlatformStageCheckpoint({
     declaration,
     platformId,
     stageId,
@@ -131,8 +131,8 @@ function restore({ workRoot, platformId, stageId, recordedAt }) {
   );
   if (emission.platform !== platformId || emission.stage !== stageId)
     throw new Error("emission identity does not match restore request");
-  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
-  const result = restoreV4PlatformStageCheckpoint({
+  const store = new StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = restorePlatformStageCheckpoint({
     declaration,
     expectedPlatform: platformId,
     expectedStage: stageId,
@@ -201,7 +201,7 @@ else if (action === "rehearse") {
     providerCredentialsUsed: restored.providerCredentialsUsed,
   };
   writeJson(path.join(common.workRoot, "evidence.json"), evidence);
-  process.stdout.write(v4CanonicalBytes(evidence));
+  process.stdout.write(domainCanonicalBytes(evidence));
 } else {
   throw new Error("action must be emit, restore, or rehearse");
 }

package/scripts/{v4-product-publication-intent.mjs → product-publication-intent.mjs}

@@ -5,8 +5,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { spawnSyncCommand } from "../packages/core/spawn-command.js";
-import { selectV4ProductPublicationIntent } from "../packages/core/v4-product-publication.js";
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { selectProductPublicationIntent } from "../packages/core/product-publication.js";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
 
 function env(name, required = false) {
   const value = String(process.env[name] || "").trim();
@@ -59,20 +59,20 @@ function writeOutput(name, value) {
   fs.appendFileSync(output, `${name}=${String(value)}\n`);
 }
 
-export function resolveV4ProductPublicationIntent() {
+export function resolveProductPublicationIntent() {
   const artifactKind = env("BUILDCHAIN_PUBLISH_ARTIFACT_KIND") || "npm";
   const name = packageName(artifactKind);
   const sourceSha = env("BUILDCHAIN_SOURCE_SHA", true);
   const manifestPath = env(
     "BUILDCHAIN_SEALED_BUNDLE_MANIFEST",
-    artifactKind === "npm",
+    artifactKind !== "custom",
   );
   const manifest = manifestPath ? readJson(manifestPath) : null;
   const requiredArtifacts = readJson(
     env("BUILDCHAIN_REQUIRED_ARTIFACTS_PATH", true),
   );
   const channel = env("BUILDCHAIN_CHANNEL", true);
-  const intent = selectV4ProductPublicationIntent({
+  const intent = selectProductPublicationIntent({
     channel,
     targetRef: env("BUILDCHAIN_TARGET_REF", true),
     sourceSha,
@@ -80,11 +80,19 @@ export function resolveV4ProductPublicationIntent() {
     repository: env("BUILDCHAIN_REPOSITORY", true),
     artifactKind,
     packageName: name,
+    ...(manifest?.npmPackages
+      ? {
+          npmPackages: manifest.npmPackages.map((entry) => ({
+            ...entry,
+            sha256: `sha256:${entry.sha256}`,
+          })),
+        }
+      : {}),
     distTag:
       env("BUILDCHAIN_PUBLISH_DIST_TAG") ||
       (channel === "alpha" ? "alpha" : "latest"),
     sealedBundleRoot: manifest?.root,
-    requiredArtifactsRoot: v4ContentRoot(
+    requiredArtifactsRoot: domainContentRoot(
       "v4-product-required-artifacts",
       requiredArtifacts,
     ),
@@ -94,7 +102,7 @@ export function resolveV4ProductPublicationIntent() {
   });
   const outputPath = path.resolve(
     env("BUILDCHAIN_PRODUCT_PUBLICATION_INTENT_PATH") ||
-      ".buildchain/release-candidate/v4-product-publication-intent.json",
+      ".buildchain/release-candidate/product-publication-intent.json",
   );
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, `${JSON.stringify(intent, null, 2)}\n`);
@@ -110,7 +118,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    const result = resolveV4ProductPublicationIntent();
+    const result = resolveProductPublicationIntent();
     process.stdout.write(
       `v4 product publication intent: ${result.name}@${result.intent.version} (${result.intent.mode})\n`,
     );

package/scripts/publication-candidate-kind.mjs

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ociPublicationTag } from "../packages/core/oci-publication-graph.js";
+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: ociPublicationTag(image, 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 });
+}

package/scripts/{v4-publication-rehearsal-fixture.mjs → publication-rehearsal-fixture.mjs}

@@ -6,9 +6,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
-  createV4PublicationRehearsalCapsule,
-  executeV4PublicationRehearsal,
-} from "../packages/core/v4-publication-rehearsal.js";
+  createDomainPublicationRehearsalCapsule,
+  executeDomainPublicationRehearsal,
+} from "../packages/core/publication-rehearsal.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const fixtureRoot = path.join(
@@ -61,7 +61,7 @@ async function generated() {
     path: relative,
     root: files.find((entry) => entry.path === relative).root,
   });
-  const capsule = createV4PublicationRehearsalCapsule({
+  const capsule = createDomainPublicationRehearsalCapsule({
     source: {
       repository: "kungfu-systems/buildchain",
       revision: "bc12cd0ff18a7e1d918777ea093c169349952d34",
@@ -100,7 +100,7 @@ async function generated() {
   });
   const vectors = [];
   for (const platform of ["linux", "macos", "windows"]) {
-    const result = await executeV4PublicationRehearsal({
+    const result = await executeDomainPublicationRehearsal({
       capsule,
       candidateRoot,
       mode: "simulate",