@kungfu-tech/buildchain 4.0.2-alpha.0 → 4.0.2-alpha.10

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

@@ -74,7 +74,7 @@ function publicInputs(inputBlock) {
 function publicOutputs(outputBlock) {
   const forwarded = entries(outputBlock).map((entry) => entry.source.replace(
     /^        value:.*$/m,
-    `        value: \${{ jobs.alpha.outputs.${entry.name} || jobs.stable.outputs.${entry.name} }}`,
+    `        value: \${{ jobs.invoke.outputs.${entry.name} }}`,
   ));
   const routed = [
     ["buildchain-channel", "Selected promotion workflow-shell channel", "channel"],
@@ -214,8 +214,9 @@ function consumerAdmissionJob() {
         id: policy
         env:
           BUILDCHAIN_CONSUMER_ROOT: .buildchain/consumer
+          BUILDCHAIN_INVOCATION_SOURCE_PATH: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/release-candidate-promote.yml' || inputs.publication-publisher-workflow-path }}
           BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: \${{ needs.resolve-promotion.outputs.channel }}
-          BUILDCHAIN_INVOKED_WORKFLOW: .github/workflows/release-candidate-promote.yml
+          BUILDCHAIN_INVOKED_WORKFLOW: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/.release-candidate-promote.yml' || '.github/workflows/release-candidate-promote.yml' }}
           BUILDCHAIN_WORKFLOW_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_RUNTIME_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_STABLE_CONTRACT_LOCK_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
@@ -292,7 +293,7 @@ export function generateChannelPromotionWorkflow(source, { major = 2, shellRouti
     },
   };
   const alphaRoute = validateWorkflowRoute("alpha", routes.alpha, `v${major}-alpha`);
-  const stableRoute = validateWorkflowRoute("stable", routes.stable, `v${major}`);
+  validateWorkflowRoute("stable", routes.stable, `v${major}`);
   const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
   const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
   const outputs = blockBetween(source, "    outputs:\n", "\nconcurrency:\n");
@@ -300,8 +301,7 @@ export function generateChannelPromotionWorkflow(source, { major = 2, shellRouti
   for (const required of ["buildchain-ref", "buildchain-contract-lock-path", "channel", "target-ref", ...internalInputs]) {
     if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
   }
-  const alphaForwarded = routedInputs(inputNames, alphaRoute, major);
-  const stableForwarded = routedInputs(inputNames, stableRoute, major);
+  const invokeForwarded = routedInputs(inputNames, alphaRoute, major);
   return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
 name: Release Candidate Promote
 
@@ -336,7 +336,7 @@ jobs:
       target-ref: \${{ steps.route.outputs.target-ref }}
       router-ref: \${{ steps.router.outputs.ref }}
       router-sha: \${{ steps.router.outputs.sha }}
-      shell-ref: \${{ steps.route.outputs.shell-ref }}
+      shell-ref: \${{ steps.identities.outputs.shell-ref }}
       shell-call-ref: \${{ steps.identities.outputs.shell-call-ref }}
       shell-sha: \${{ steps.identities.outputs.shell-sha }}
       runtime-ref: \${{ steps.route.outputs.runtime-ref }}
@@ -425,32 +425,17 @@ jobs:
         shell: bash
         env:
           GITHUB_TOKEN: \${{ github.token }}
-          CHANNEL: \${{ steps.route.outputs.channel }}
-          SELECTED_SHELL_REF: \${{ steps.route.outputs.shell-ref }}
-          ALPHA_SHELL_REF: ${alphaRoute.logicalRef}
-          ALPHA_SHELL_CALL_REF: ${alphaRoute.callRef}
-          STABLE_SHELL_REF: ${stableRoute.logicalRef}
-          STABLE_SHELL_CALL_REF: ${stableRoute.callRef}
+          SELECTED_SHELL_REF: ${alphaRoute.logicalRef}
         run: |
           set -euo pipefail
-          if [[ "\${CHANNEL}" = "alpha" ]]; then
-            expected_ref="\${ALPHA_SHELL_REF}"
-            call_ref="\${ALPHA_SHELL_CALL_REF}"
-          else
-            expected_ref="\${STABLE_SHELL_REF}"
-            call_ref="\${STABLE_SHELL_CALL_REF}"
-          fi
-          if [[ "\${SELECTED_SHELL_REF}" != "\${expected_ref}" ]]; then
-            echo "::error::Selected promotion shell ref \${SELECTED_SHELL_REF} does not match configured \${expected_ref}"
-            exit 1
-          fi
           node .buildchain/router/scripts/promotion-identity-resolver.mjs \\
             --repository "\${{ steps.router.outputs.repository }}" \\
             --router-ref "\${{ steps.router.outputs.ref }}" \\
             --router-sha "\${{ steps.router.outputs.sha }}" \\
             --shell-ref "\${SELECTED_SHELL_REF}" \\
-            --shell-call-ref "\${call_ref}" \\
+            --shell-call-ref "\${SELECTED_SHELL_REF}" \\
             --runtime-ref "\${{ steps.route.outputs.runtime-ref }}"
+          echo "shell-ref=\${SELECTED_SHELL_REF}" >> "$GITHUB_OUTPUT"
 
       - name: Checkout selected promotion workflow shell
         uses: actions/checkout@v7.0.0
@@ -500,29 +485,21 @@ jobs:
       - name: Verify immutable promotion checkouts
         shell: bash
         env:
-          CHANNEL: \${{ steps.route.outputs.channel }}
-          ALPHA_SHELL_WORKFLOW_PATH: ${alphaRoute.workflowPath}
-          STABLE_SHELL_WORKFLOW_PATH: ${stableRoute.workflowPath}
+          SHELL_WORKFLOW_PATH: ${alphaRoute.workflowPath}
           ROUTER_SHA: \${{ steps.router.outputs.sha }}
           SHELL_SHA: \${{ steps.identities.outputs.shell-sha }}
           RUNTIME_SHA: \${{ steps.identities.outputs.runtime-sha }}
         run: |
           set -euo pipefail
-          if [[ "\${CHANNEL}" = "alpha" ]]; then
-            workflow_path="\${ALPHA_SHELL_WORKFLOW_PATH}"
-          else
-            workflow_path="\${STABLE_SHELL_WORKFLOW_PATH}"
-          fi
-          test -f ".buildchain/shell/\${workflow_path}"
+          test -f ".buildchain/shell/\${SHELL_WORKFLOW_PATH}"
           [[ "$(git -C .buildchain/router rev-parse HEAD)" = "\${ROUTER_SHA}" ]] || { echo "::error::Promotion router checkout moved"; exit 1; }
           [[ "$(git -C .buildchain/shell rev-parse HEAD)" = "\${SHELL_SHA}" ]] || { echo "::error::Promotion shell checkout moved"; exit 1; }
           [[ "$(git -C .buildchain/runtime rev-parse HEAD)" = "\${RUNTIME_SHA}" ]] || { echo "::error::Promotion runtime checkout moved"; exit 1; }
 
 ${consumerAdmissionJob()}
-  alpha:
-    name: Promote with alpha workflow shell
+  invoke:
+    name: Invoke the single v4 publisher adapter
     needs: [resolve-promotion, consumer-admission]
-    if: \${{ needs.resolve-promotion.outputs.channel == 'alpha' }}
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
     permissions:
       actions: write
@@ -534,25 +511,7 @@ ${consumerAdmissionJob()}
       issues: write
       pull-requests: write
     with:
-${alphaForwarded}
-    secrets: inherit
-
-  stable:
-    name: Promote with stable workflow shell
-    needs: [resolve-promotion, consumer-admission]
-    if: \${{ needs.resolve-promotion.outputs.channel == 'stable' }}
-    uses: kungfu-systems/buildchain/${stableRoute.workflowPath}@${stableRoute.callRef}
-    permissions:
-      actions: write
-      artifact-metadata: write
-      attestations: write
-      checks: write
-      contents: write
-      id-token: write
-      issues: write
-      pull-requests: write
-    with:
-${stableForwarded}
+${invokeForwarded}
     secrets: inherit
 `;
 }

package/scripts/release-candidate-resolver.mjs

@@ -13,7 +13,6 @@ import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
 import { v4PublicationQualificationRoot, validateV4PublicationQualificationReceipt } from "../packages/core/v4-publication-qualification.js";
 
 const DEFAULT_WORKFLOW_FILE = "build-surface-fixture.yml";
-
 function env(name, fallback = "") {
   return process.env[name] || fallback;
 }
@@ -21,7 +20,6 @@ function env(name, fallback = "") {
 export function releaseCandidateDownloadEnabled(value = "true") {
   return String(value || "true").trim().toLowerCase() !== "false";
 }
-
 function splitRepository(repository) {
   const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
   if (!match) {
@@ -44,7 +42,9 @@ function assertSha(value, label = "sha") {
 
 export const releaseCandidateRuntimeSha = (passport) =>
   assertSha(passport?.buildchain?.sha, "release candidate Passport Buildchain runtime SHA").toLowerCase();
-
+export const resolveFreshPublicationVersion = ({ sealedBundle, candidateVersion = "" } = {}) =>
+  String(sealedBundle?.manifest?.npm?.version || candidateVersion || "").trim();
+const optionalText = (value) => String(value || "");
 function githubHeaders(token) {
   const headers = {
     accept: "application/vnd.github+json",
@@ -110,13 +110,13 @@ function digestFileSync(filePath, algorithm, encoding) {
   return hash.digest(encoding);
 }
 
-export function selectMergedChannelPullRequest({ pullRequests = [], targetRef, repository }) {
+export function selectMergedChannelPullRequest({ pullRequests = [], targetRef, targetSha = "", repository }) {
   const normalizedTarget = normalizeBranch(targetRef);
   const candidates = pullRequests.filter((pr) => {
-    const baseRef = normalizeBranch(pr.base?.ref || pr.baseRefName || "");
-    const merged = Boolean(pr.merged_at || pr.mergedAt || pr.state === "closed");
-    const sameRepo = !repository || !pr.head?.repo?.full_name || pr.head.repo.full_name === repository;
-    return merged && sameRepo && baseRef === normalizedTarget;
+    const baseRepo = pr.base?.repo?.full_name || pr.baseRepository?.nameWithOwner;
+    const merged = Boolean(pr.merged_at || pr.mergedAt || pr.merged === true);
+    const rooted = !repository || (baseRepo || pr.head?.repo?.full_name) === repository;
+    return merged && rooted && (!targetSha || (pr.merge_commit_sha || pr.mergeCommit?.oid) === targetSha) && normalizeBranch(pr.base?.ref || pr.baseRefName || "") === normalizedTarget;
   });
   candidates.sort((left, right) => {
     const leftTime = Date.parse(left.merged_at || left.updated_at || left.closed_at || "");
@@ -513,11 +513,11 @@ export async function resolveReleaseCandidateArtifacts({
   });
   const channelPullRequest = selectMergedChannelPullRequest({
     pullRequests: Array.isArray(pulls) ? pulls : [],
-    targetRef: normalizedTarget,
+    targetRef: normalizedTarget, targetSha: sha,
     repository: repoInfo.fullName,
   });
   if (!channelPullRequest) {
-    throw new Error(`no same-repository merged channel PR found for ${sha} into ${normalizedTarget}`);
+    throw new Error(`no exact merged channel PR rooted in ${repoInfo.fullName} found for ${sha} into ${normalizedTarget}`);
   }
   let pullRequest = channelPullRequest;
   if (majorGateTarget) {
@@ -725,16 +725,6 @@ 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 manifests = platformManifestPaths.map((manifestPath) => JSON.parse(fs.readFileSync(manifestPath, "utf8")));
-  const generatedRequiredArtifacts = generatePublishRequiredArtifacts({
-    manifests,
-    version: passport.target?.version || "",
-    kind: publishArtifactKind,
-    tarballPaths: npmTarballPaths,
-    mainPackage: publishPackageMain,
-  });
-  const requiredArtifactsPath = path.join(resolvedOutput, "publish-required-artifacts.json");
-  fs.writeFileSync(requiredArtifactsPath, `${JSON.stringify(generatedRequiredArtifacts, null, 2)}\n`);
   const sealedBundle = publishArtifactKind === "npm"
     ? createResolvedPublicationSealedBundle({
         bundleRoot: payloadDir,
@@ -750,9 +740,17 @@ export async function resolveReleaseCandidateArtifacts({
         releaseAssetPaths,
       })
     : undefined;
-  const sealedBundleManifestPath = sealedBundle
-    ? path.join(resolvedOutput, "sealed-bundle.json")
-    : "";
+  const manifests = platformManifestPaths.map((manifestPath) => JSON.parse(fs.readFileSync(manifestPath, "utf8"))), publicationVersion = resolveFreshPublicationVersion({ sealedBundle, candidateVersion: passport.target?.version });
+  const generatedRequiredArtifacts = generatePublishRequiredArtifacts({
+    manifests,
+    version: publicationVersion,
+    kind: publishArtifactKind,
+    tarballPaths: npmTarballPaths,
+    mainPackage: publishPackageMain,
+  });
+  const requiredArtifactsPath = path.join(resolvedOutput, "publish-required-artifacts.json");
+  fs.writeFileSync(requiredArtifactsPath, `${JSON.stringify(generatedRequiredArtifacts, null, 2)}\n`);
+  const sealedBundleManifestPath = sealedBundle ? path.join(resolvedOutput, "sealed-bundle.json") : "";
   if (sealedBundleManifestPath) {
     fs.writeFileSync(sealedBundleManifestPath, `${JSON.stringify(sealedBundle.manifest, null, 2)}\n`);
   }
@@ -772,6 +770,7 @@ export async function resolveReleaseCandidateArtifacts({
       sealedBundleManifest: sealedBundleManifestPath ? outputPath(sealedBundleManifestPath) : "",
     },
     version: passport.target?.version || "",
+    publicationVersion,
     candidateHash: passport.candidateHash || "",
     payloadCount: payloadArtifacts.length,
     platformManifestCount: platformManifestPaths.length,
@@ -811,6 +810,7 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "release-candidate-publication-qualification-path": result.paths?.publicationQualification || "",
     "release-candidate-publication-qualification-root": result.publicationQualificationRoot || "",
     "release-candidate-version": result.version || "",
+    "release-candidate-publication-version": optionalText(result.publicationVersion),
     "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",
     "release-candidate-build-summary-artifact": result.artifacts?.summary || "",
@@ -843,7 +843,6 @@ export async function resolveReleaseCandidateArtifactsCli() {
   console.log(JSON.stringify(result, null, 2));
   return result;
 }
-
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     await resolveReleaseCandidateArtifactsCli();

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

@@ -785,14 +785,13 @@ async function recoverCandidateEvidence({
   for (const artifact of [selected.passport, selected.summary]) initialDownloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   const passport = readOnlyJson(initialDownloads[0].files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "release-candidate-passport.json");
   const buildSummary = readOnlyJson(initialDownloads[1].files.filter((file) => path.basename(file.path) === "build-summary.json"), "build-summary.json");
-  const sidecarFiles = initialDownloads[0].files.filter(
-    (file) =>
-      path.basename(file.path) === "release-candidate-stage-capsules.json",
-  );
-  const stageCapsuleSidecar =
-    sidecarFiles.length === 1
-      ? readOnlyJson(sidecarFiles, "release-candidate-stage-capsules.json")
-      : undefined;
+  const [stageCapsuleFile, publicationQualificationFile] = [
+    "release-candidate-stage-capsules.json",
+    "release-candidate-publication-qualification.json",
+  ].map((name) => initialDownloads[0].files.find((file) => path.basename(file.path) === name));
+  const stageCapsuleSidecar = stageCapsuleFile
+    ? readOnlyJson([stageCapsuleFile], "release-candidate-stage-capsules.json")
+    : undefined;
   const { names: requiredNames, publicationNames } = candidateArtifactNames({ passport, selected, artifacts, artifactPatterns });
   const chosen = artifacts.filter((artifact) => requiredNames.has(artifact.name));
   if (chosen.length !== requiredNames.size) {
@@ -804,7 +803,7 @@ async function recoverCandidateEvidence({
   for (const artifact of chosen.filter((entry) => ![selected.passport.id, selected.summary.id].includes(entry.id))) downloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   return {
     run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-    passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
+    passport, buildSummary, stageCapsuleSidecar, stageCapsuleFile, publicationQualificationFile, chosen, downloads, publicationNames,
   };
 }
 
@@ -822,7 +821,7 @@ export async function resolveRecoveryTransaction({
   transactionId,
   publicationVersion,
 }) {
-  let transaction = publicationVersion
+  let transaction = transactionId && publicationVersion
     ? await readExistingTransaction({
         repoInfo,
         apiUrl,
@@ -878,7 +877,7 @@ export async function resumeFromCandidateRun({
   try {
     const {
       run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-      passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
+      passport, buildSummary, stageCapsuleSidecar, stageCapsuleFile, publicationQualificationFile, chosen, downloads, publicationNames,
     } = await recoverCandidateEvidence({
       repoInfo, runId, artifactName, artifactPatterns, requiredArtifactCount,
       outputDir, apiUrl, token, fetchImpl, archiveDir,
@@ -1023,9 +1022,9 @@ export async function resumeFromCandidateRun({
         sealedBundleRoot: publication.manifest ? outputPath(bundleRoot) : "",
         sealedBundleManifest: publication.manifest ? outputPath(sealedManifestPath) : "",
         recoveryReceipt: outputPath(recoveryReceiptPath),
-        runtimeResumeEvidence: runtimeResumeEvidencePath
-          ? outputPath(runtimeResumeEvidencePath)
-          : "",
+        stageCapsules: stageCapsuleFile ? outputPath(stageCapsuleFile.absolutePath) : "",
+        publicationQualification: publicationQualificationFile ? outputPath(publicationQualificationFile.absolutePath) : "",
+        runtimeResumeEvidence: runtimeResumeEvidencePath ? outputPath(runtimeResumeEvidencePath) : "",
       },
     };
   } finally {
@@ -1077,10 +1076,10 @@ export async function resumeFromCandidateRunCli() {
       "release-candidate-run-url": result.run.url,
       "release-candidate-recovery-receipt-path": result.paths.recoveryReceipt,
       "release-candidate-recovery-root": result.receipt.root,
+      "release-candidate-stage-capsules-path": result.paths.stageCapsules,
+      "release-candidate-publication-qualification-path": result.paths.publicationQualification,
       "v4-runtime-resume-evidence-path": result.paths.runtimeResumeEvidence,
-      "v4-runtime-resume-finalize-command": result.paths.runtimeResumeEvidence
-        ? "node .buildchain/runtime/promotion-shell/scripts/resume-from-candidate-run.mjs finalize"
-        : "",
+      "v4-runtime-resume-finalize-command": result.paths.runtimeResumeEvidence ? "node .buildchain/runtime/promotion-shell/scripts/resume-from-candidate-run.mjs finalize" : "",
       "release-candidate-root": result.candidateRoot,
       "release-candidate-artifact-root": result.artifactRoot,
       "publish-sealed-bundle-root": result.paths.sealedBundleRoot,

package/scripts/v3-v4-capability-catalog.mjs

@@ -23,6 +23,9 @@ const PLATFORM_MARKERS = Object.freeze({
   "self-hosted": /\bself-hosted\b/iu,
   windows: /\bwindows\b/iu,
 });
+const LIVE_V4_PROTECTED_BRANCH = "refs/heads/dev/v4/v4.0";
+const LIVE_V4_PROTECTED_LINEAGE_REF = "refs/remotes/origin/dev/v4/v4.0";
+const PROTECTED_LINEAGE_DEPTH = 256;
 
 export function sha256(value) {
   return `sha256:${crypto.createHash("sha256").update(value).digest("hex")}`;
@@ -47,6 +50,110 @@ export function git(root, args, { trim = true } = {}) {
   return trim ? output.trim() : output;
 }
 
+export function assertCapabilityCutAncestor({
+  root = process.cwd(),
+  revision,
+  descendant = "HEAD",
+  label = "capability cut",
+} = {}) {
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", revision, descendant], {
+      cwd: root,
+      stdio: "ignore",
+    });
+  } catch {
+    throw new Error(
+      `${label} ${revision} must be an ancestor of ${descendant}; regenerate the cut after rebasing instead of relying on a retained local object`,
+    );
+  }
+}
+
+export function ensureCapabilityCutAncestor({
+  root = process.cwd(),
+  revision,
+  descendant = "HEAD",
+  label = "capability cut",
+} = {}) {
+  try {
+    assertCapabilityCutAncestor({ root, revision, descendant, label });
+    return;
+  } catch (error) {
+    if (git(root, ["rev-parse", "--is-shallow-repository"]) !== "true")
+      throw error;
+  }
+  const descendantCommit = git(root, ["rev-parse", `${descendant}^{commit}`]);
+  try {
+    execFileSync(
+      "git",
+      ["fetch", "--no-tags", "--depth=128", "origin", descendantCommit],
+      { cwd: root, stdio: "ignore" },
+    );
+  } catch {
+    throw new Error(
+      `${label} ${revision} ancestry could not be hydrated from ${descendantCommit} through a bounded origin fetch`,
+    );
+  }
+  assertCapabilityCutAncestor({ root, revision, descendant, label });
+}
+
+function protectedV4TreeWitness(root, descendant) {
+  try {
+    execFileSync(
+      "git",
+      [
+        "fetch",
+        "--no-tags",
+        `--depth=${PROTECTED_LINEAGE_DEPTH}`,
+        "origin",
+        `${LIVE_V4_PROTECTED_BRANCH}:${LIVE_V4_PROTECTED_LINEAGE_REF}`,
+      ],
+      { cwd: root, stdio: "ignore" },
+    );
+  } catch {
+    throw new Error(
+      `protected v4 lineage ${LIVE_V4_PROTECTED_BRANCH} could not be hydrated through a bounded origin fetch`,
+    );
+  }
+  const tree = git(root, ["rev-parse", `${descendant}^{tree}`]);
+  return (
+    git(root, [
+      "log",
+      `--max-count=${PROTECTED_LINEAGE_DEPTH}`,
+      "--format=%H %T",
+      LIVE_V4_PROTECTED_LINEAGE_REF,
+    ])
+      .split("\n")
+      .map((row) => row.split(" "))
+      .find(([, candidateTree]) => candidateTree === tree)?.[0] || ""
+  );
+}
+
+export function ensureCapabilityCutLineage({
+  root = process.cwd(),
+  revision,
+  descendant = "HEAD",
+  label = "capability cut",
+} = {}) {
+  try {
+    ensureCapabilityCutAncestor({ root, revision, descendant, label });
+    return { mode: "direct-ancestry", witness: descendant };
+  } catch (directError) {
+    const witness = protectedV4TreeWitness(root, descendant);
+    if (!witness)
+      throw new Error(
+        `${label} ${revision} is not an ancestor of ${descendant}, and ${descendant} has no tree-equivalent commit in the bounded protected v4 lineage`,
+        { cause: directError },
+      );
+    ensureCapabilityCutAncestor({
+      root,
+      revision,
+      descendant: witness,
+      label: `${label} protected-lineage witness`,
+    });
+    return { mode: "protected-tree-equivalent", witness };
+  }
+}
+
 function gitJson(root, revision, relPath) {
   return JSON.parse(
     git(root, ["show", `${revision}:${relPath}`], { trim: false }),

package/scripts/v4-declarative-promotion-admission.mjs

@@ -8,7 +8,10 @@ export function admitV4DeclarativePromotion({
   runtimeRef,
   declarative,
 }) {
-  if (!/^v4(?:$|[-./])/u.test(String(runtimeRef || ""))) {
+  if (
+    declarative !== true &&
+    !/^v4(?:$|[-./])/u.test(String(runtimeRef || ""))
+  ) {
     return Object.freeze({ mode: "legacy", admitted: true });
   }
   if (declarative !== true) {

package/scripts/v4-product-publication-intent.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+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";
+
+function env(name, required = false) {
+  const value = String(process.env[name] || "").trim();
+  if (required && !value) throw new Error(`${name} is required`);
+  return value;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
+}
+
+function packageName() {
+  const declared = env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN");
+  if (declared) return declared;
+  const manifestPath = env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true);
+  const manifest = readJson(manifestPath);
+  const selected = String(manifest?.npm?.name || "").trim();
+  if (!selected)
+    throw new Error("sealed bundle manifest does not declare npm.name");
+  return selected;
+}
+
+function observedVersions(name) {
+  const result = spawnSyncCommand(
+    "npm",
+    [
+      "view",
+      name,
+      "versions",
+      "--json",
+      "--registry=https://registry.npmjs.org/",
+    ],
+    { encoding: "utf8" },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+    if (/\bE404\b|404 Not Found|is not in this registry/iu.test(output))
+      return [];
+    throw new Error(`npm version discovery failed: ${output.trim()}`);
+  }
+  const parsed = JSON.parse(String(result.stdout || "[]"));
+  return Array.isArray(parsed) ? parsed : [parsed].filter(Boolean);
+}
+
+function writeOutput(name, value) {
+  const output = env("GITHUB_OUTPUT");
+  if (!output) return;
+  fs.appendFileSync(output, `${name}=${String(value)}\n`);
+}
+
+export function resolveV4ProductPublicationIntent() {
+  const name = packageName();
+  const sourceSha = env("BUILDCHAIN_SOURCE_SHA", true);
+  const manifest = readJson(env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true));
+  const requiredArtifacts = readJson(
+    env("BUILDCHAIN_REQUIRED_ARTIFACTS_PATH", true),
+  );
+  const channel = env("BUILDCHAIN_CHANNEL", true);
+  const intent = selectV4ProductPublicationIntent({
+    channel,
+    targetRef: env("BUILDCHAIN_TARGET_REF", true),
+    sourceSha,
+    sourceTimestamp: env("BUILDCHAIN_SOURCE_TIMESTAMP", true),
+    repository: env("BUILDCHAIN_REPOSITORY", true),
+    packageName: name,
+    distTag:
+      env("BUILDCHAIN_PUBLISH_DIST_TAG") ||
+      (channel === "alpha" ? "alpha" : "latest"),
+    sealedBundleRoot: manifest.root,
+    requiredArtifactsRoot: v4ContentRoot(
+      "v4-product-required-artifacts",
+      requiredArtifacts,
+    ),
+    candidateVersion: env("BUILDCHAIN_CANDIDATE_VERSION", true),
+    recoveredVersion: env("BUILDCHAIN_RECOVERED_PUBLICATION_VERSION"),
+    observedVersions: observedVersions(name),
+  });
+  const outputPath = path.resolve(
+    env("BUILDCHAIN_PRODUCT_PUBLICATION_INTENT_PATH") ||
+      ".buildchain/release-candidate/v4-product-publication-intent.json",
+  );
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(intent, null, 2)}\n`);
+  writeOutput("version", intent.version);
+  writeOutput("exact-tag", intent.exactTag);
+  writeOutput("intent-path", outputPath);
+  writeOutput("intent-root", intent.intentRoot);
+  return { name, intent, outputPath };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = resolveV4ProductPublicationIntent();
+    process.stdout.write(
+      `v4 product publication intent: ${result.name}@${result.intent.version} (${result.intent.mode})\n`,
+    );
+  } catch (error) {
+    console.error(`v4-product-publication-intent: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/v4-release-candidate-adapter.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function resolveV4ReleaseCandidateAdapter({
+  resumeCandidateRunId = "",
+} = {}) {
+  const mode = String(resumeCandidateRunId || "").trim() ? "recovery" : "fresh";
+  return Object.freeze({
+    mode,
+    script:
+      mode === "recovery"
+        ? "scripts/resume-from-candidate-run.mjs"
+        : "scripts/release-candidate-resolver.mjs",
+  });
+}
+
+export function runV4ReleaseCandidateAdapter({
+  env = process.env,
+  exec = execFileSync,
+} = {}) {
+  const route = resolveV4ReleaseCandidateAdapter({
+    resumeCandidateRunId: env.BUILDCHAIN_RESUME_CANDIDATE_RUN_ID,
+  });
+  exec(process.execPath, [path.join(root, route.script)], {
+    env,
+    stdio: "inherit",
+  });
+  return route;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runV4ReleaseCandidateAdapter();
+}