@kungfu-tech/buildchain 4.0.2-alpha.43 → 4.0.2-alpha.45

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/paper-agent-entry.js

@@ -13,7 +13,13 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
-import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
+import {
+  mergeNextDevelopmentAgentInstructions,
+  NEXT_DEVELOPMENT_AGENT_SECTION_START,
+  NEXT_DEVELOPMENT_AGENT_SECTION_END,
+  NEXT_DEVELOPMENT_LOCAL_COMMAND,
+} from "./next-development-projection.js";
+import { NEXT_DEVELOPMENT_ADR } from "./next-development-transition.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -149,6 +155,24 @@ export function createPaperAgentEntry({
   };
 }
 
+function mergePaperNextDevelopmentInstructions(current) {
+  const merged = mergeNextDevelopmentAgentInstructions(current);
+  const start = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_START);
+  const end = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_END);
+  const section = merged.slice(start, end)
+    .replace(
+      `\`${NEXT_DEVELOPMENT_ADR}\``,
+      `[Buildchain next-development ADR](https://github.com/kungfu-systems/buildchain/blob/v4/${NEXT_DEVELOPMENT_ADR})`,
+    )
+    .replace(
+      NEXT_DEVELOPMENT_LOCAL_COMMAND,
+      NEXT_DEVELOPMENT_LOCAL_COMMAND.replace(
+        "node scripts/", "node node_modules/@kungfu-tech/buildchain/scripts/",
+      ),
+    );
+  return `${merged.slice(0, start)}${section}${merged.slice(end)}`;
+}
+
 export function paperAgentEntryFiles({
   cwd,
   buildchainVersion,
@@ -169,7 +193,7 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergeNextDevelopmentAgentInstructions(
+      mergePaperNextDevelopmentInstructions(
         mergePaperAgentEntryInstructions(currentAgents, {
           developmentRef: resolvedDevelopmentRef,
         }),

package/packages/core/paper.js

@@ -410,7 +410,7 @@ jobs:
 `;
 }
 
-function scaffoldVerifyWorkflow(buildchainSha) {
+function scaffoldVerifyWorkflow(buildchainSha, buildchainVersion = "") {
   return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
@@ -423,7 +423,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+${buildchainVersion.startsWith("4.") ? "  actions: read\n  contents: read\n  pull-requests: read" : "  contents: read"}
 
 jobs:
   check:
@@ -621,7 +621,7 @@ function scaffoldFiles({
     artifactPaths: "_build/main.pdf",
     releasePassportProductName: title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha, buildchainVersion);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion,
@@ -756,7 +756,7 @@ function migrationFiles({
     artifactPaths: config.publication.artifactPaths.join(","),
     releasePassportProductName: config.publication.title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha, runtimeIdentity.version);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion: runtimeIdentity.version,

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";
+  "7297279bce5344b8fc58688be5c1933a823306c82dac7dccfabdf07de41d652f";
 export const V4_DOMAIN_WASM_SHA256 =
-  "b37c330e9366b7e9cf9dc4b7573b1e9495212dd9520e8b8ec6cdc3fd0ab7cafd";
+  "3a4909bb4b2bbd2676eac83f259c22faf1ce43479036992c5e53d5e2dcc512ce";

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";
@@ -102,3 +103,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/release-candidate-resolver.mjs

@@ -7,7 +7,7 @@ import { execFileSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
-import { createResolvedPublicationSealedBundle } from "./publication-candidate-sealer.mjs";
+import { resolveCandidatePublicationBundle } from "./publication-candidate-sealer.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
 import { v4PublicationQualificationRoot, validateV4PublicationQualificationReceipt } from "../packages/core/v4-publication-qualification.js";
@@ -725,23 +725,12 @@ export async function resolveReleaseCandidateArtifacts({
     const noun = publishArtifactKind === "npm" ? "npm package tarballs" : "platform manifests";
     throw new Error(`expected at least ${minimumPayloadCount} downloaded ${noun}, found ${downloadedRequiredArtifactCount}`);
   }
-  const sealedBundle = publishArtifactKind === "npm"
-    ? createResolvedPublicationSealedBundle({
-        bundleRoot: payloadDir,
-        repository: repoInfo.fullName,
-        sourceSha: passport.source?.headSha,
-        sourceTreeSha: passport.source?.treeHash,
-        runtimeSha: releaseCandidateRuntimeSha(passport),
-        releaseCandidateRoot: passport.candidateHash,
-        npmArtifacts: npmTarballPaths.map((tarballPath) => ({
-          path: tarballPath,
-          ...readNpmPackageArtifact({ tarballPath, mainPackage: publishPackageMain }),
-        })),
-        releaseAssetPaths,
-      })
-    : undefined;
+  const sealedBundle = resolveCandidatePublicationBundle({ kind: publishArtifactKind, payloadDir, passport,
+    runtimeSha: releaseCandidateRuntimeSha(passport), releaseAssetPaths,
+    npmArtifacts: npmTarballPaths.map((tarballPath) => ({ path: tarballPath,
+      ...readNpmPackageArtifact({ tarballPath, mainPackage: publishPackageMain }) })) });
   const manifests = platformManifestPaths.map((manifestPath) => JSON.parse(fs.readFileSync(manifestPath, "utf8"))), publicationVersion = resolveFreshPublicationVersion({ sealedBundle, candidateVersion: passport.target?.version });
-  const generatedRequiredArtifacts = generatePublishRequiredArtifacts({
+  const generatedRequiredArtifacts = sealedBundle?.requiredArtifacts || generatePublishRequiredArtifacts({
     manifests,
     version: publicationVersion,
     kind: publishArtifactKind,

package/scripts/resume-from-candidate-run.mjs

@@ -6,6 +6,8 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { resolveOciCandidate, resolveRecoveredPublicationVersion, resolveRecoveredCandidateVersion } from "./publication-candidate-kind.mjs";
+export { resolveRecoveredPublicationVersion, resolveRecoveredCandidateVersion } from "./publication-candidate-kind.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 import { compareSemver } from "./publication-registry-hydrate.mjs";
 import { normalizeAnchorProvenance, normalizeCandidateRun, recoverCandidateProvenance } from "./release-candidate-anchor-provenance.mjs";
@@ -695,22 +697,6 @@ export function createRecoveredPublicationCandidate({
   };
   return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
 }
-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;
-}
 export function createRecoveredPublication({ downloads, bundleRoot, repository, passport, candidateRuntimeSha, publishArtifactKind, publishPackageMain, releasePatterns, platformManifests, channel, targetRef = "", candidateRef = "", rematerializeOnResume = false }) {
   const allFiles = downloads.flatMap((download) => download.files.map((file) => ({ path: path.relative(bundleRoot, file.absolutePath).split(path.sep).join("/"),
     size: file.size, sha256: file.sha256.replace(/^sha256:/, ""), absolutePath: file.absolutePath })))
@@ -718,6 +704,13 @@ export function createRecoveredPublication({ downloads, bundleRoot, repository,
   const kind = String(publishArtifactKind || "npm");
   const releaseMatchers = splitPatterns(releasePatterns).map(patternMatcher);
   const releaseAssets = allFiles.filter((file) => releaseMatchers.some((matcher) => matcher.test(path.basename(file.path))));
+  if (kind === "oci") {
+    createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
+    const sealed = resolveOciCandidate({ payloadRoot: bundleRoot, passport });
+    return { manifest: sealed.manifest, bundleRoot: sealed.root, npmArtifacts: [], allFiles, releaseAssets,
+      version: sealed.manifest.version, candidateVersion: sealed.manifest.version,
+      publishRequiredArtifacts: sealed.requiredArtifacts };
+  }
   if (kind !== "npm") {
     createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
     const version = String(passport.target?.version || "").trim();
@@ -1019,7 +1012,7 @@ export async function resumeFromCandidateRun({
         npmTarballs: tarballs,
         releaseAssets: publication.releaseAssets.map((asset) => outputPath(asset.absolutePath)),
         publishRequiredArtifacts: outputPath(requiredArtifactsPath),
-        sealedBundleRoot: publication.manifest ? outputPath(bundleRoot) : "",
+        sealedBundleRoot: publication.manifest ? outputPath(publication.bundleRoot || bundleRoot) : "",
         sealedBundleManifest: publication.manifest ? outputPath(sealedManifestPath) : "",
         recoveryReceipt: outputPath(recoveryReceiptPath),
         stageCapsules: stageCapsuleFile ? outputPath(stageCapsuleFile.absolutePath) : "",

package/scripts/site-capability-metadata.mjs

@@ -206,6 +206,7 @@ export function nodeApiMeta(exportName) {
     "./publication-artifact": { group: "reusable-build", summary: "Publication artifact manifest, source bundle, and publication passport APIs." },
     "./publication-package": { group: "reusable-build", summary: "Publication npm package synthesis APIs for Buildchain-managed paper release presets." },
     "./publication-reproducibility": { group: "reusable-build", summary: "Two-clean-build publication byte reproducibility receipt APIs." },
+    "./oci-publication": { group: "reusable-build", summary: "Sealed OCI image family verification, provenance, and smoke evidence APIs." },
     "./publication-sealed-bundle": { group: "reusable-build", summary: "Build-once publication bundle manifests and exact-byte resume verification APIs." },
     "./paper": { group: "reusable-build", summary: "Unified Paper work, fleet, scaffold, preflight, npm bootstrap, build, Alpha, status, and resume planning APIs." },
     "./publication-authority": { group: "release-passport-trust", summary: "Sealed publication authority registry, runner provenance, control-plane audit, admission, and independent verification APIs." },