@kungfu-tech/buildchain 4.0.1-alpha.41 → 4.0.1-alpha.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.1-alpha.41",
+  "version": "4.0.1-alpha.42",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -48,6 +48,7 @@
     "./v4-tail-reseal": "./packages/core/v4-tail-reseal.js",
     "./v4-tail-reseal-receipt": "./packages/core/v4-tail-reseal-receipt.js",
     "./v4-publication-rehearsal": "./packages/core/v4-publication-rehearsal.js",
+    "./v4-publication-qualification": "./packages/core/v4-publication-qualification.js",
     "./adopter-delivery-gate": "./packages/core/adopter-delivery-gate.js",
     "./kfd-adopter-category-driver": "./packages/core/kfd-adopter-category-driver.js",
     "./buildchain-delivery-infrastructure": "./packages/core/buildchain-delivery-infrastructure.js",
@@ -114,6 +115,7 @@
     "./site/schemas/v4-publication-rehearsal-capsule-v1.schema.json": "./dist/site/schemas/v4-publication-rehearsal-capsule-v1.schema.json",
     "./site/schemas/v4-adopter-delivery-v1.schema.json": "./dist/site/schemas/v4-adopter-delivery-v1.schema.json",
     "./site/schemas/release-tail-capabilities-v1.schema.json": "./dist/site/schemas/release-tail-capabilities-v1.schema.json",
+    "./site/schemas/v4-publication-qualification-v1.schema.json": "./dist/site/schemas/v4-publication-qualification-v1.schema.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",

package/packages/core/buildchain-contract.js

@@ -166,6 +166,36 @@ function declarativeAuditableDemoSurface(root, pkg, majorLine) {
   });
 }
 
+function v4ReleaseCandidatePromoteSurface(root, majorLine) {
+  return surface(root, {
+    id: "v4-release-candidate-promote-action",
+    kind: "action",
+    path: "actions/v4-release-candidate-promote/action.yml",
+    publicRef: `kungfu-systems/buildchain/actions/v4-release-candidate-promote@${majorLine}`,
+    requiredInputs: [
+      "token", "repository", "source-sha", "version", "tag", "channel",
+      "candidate-passport-path", "stage-capsules-path",
+      "publication-qualification-path",
+    ],
+    requiredOutputs: [
+      "release-passport-path", "release-passport-root", "transaction-state",
+      "declaration-root", "transaction-root", "state-root",
+      "receipt-roots-json",
+    ],
+    breakingDefaults: {
+      statePath: ".buildchain/release-tail/state.json",
+      executionBoundary: "built-in-provider-plane-only",
+    },
+    optionalInputs: ["artifact-paths", "state-path", "failure-after-capability"],
+    guarantees: [
+      "v4 promotion consumes only sealed candidate, Stage Capsule, qualification, and artifact evidence",
+      "GitHub Release, signed-channel commit, activation, readback, and released-evidence synthesis use built-in provider adapters",
+      "durable provider checkpoints resume completed capabilities without replay",
+      "no consumer command, script, shell, checkout, or executable tail hook is accepted",
+    ],
+  });
+}
+
 export function createBuildchainContractWorld({
   root = process.cwd(),
   packageJson = undefined,
@@ -484,7 +514,7 @@ export function createBuildchainContractWorld({
         "Build Images owns encoding, Buildchain owns qualification and receipts, and site repositories own browser loading and accessibility behavior",
         "media qualification does not claim browser playback, responsive layout, reduced-motion behavior, accessibility, or production deployment",
       ],
-    }), declarativeAuditableDemoSurface(root, pkg, majorLine),
+    }), declarativeAuditableDemoSurface(root, pkg, majorLine), v4ReleaseCandidatePromoteSurface(root, majorLine),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",

package/packages/core/buildchain-publication-authority.js

@@ -58,6 +58,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/release-tail.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "caller-bound", "caller-bound", "fixed"],
   [".github/workflows/release-verify.yml", "governance-write"],
   [".github/workflows/stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/v4-declarative-release-tail-dogfood.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "none", "fixed", "fixed"],
 ]);
 
 export function buildchainPublicationAuthorityDescriptors() {

package/packages/core/index.js

@@ -646,6 +646,7 @@ export {
 export * from "./release-propagation.js";
 export * from "./v4-floating-consumer-policy.js";
 export * from "./v4-runtime-ref-resume-authority.js";
+export * from "./v4-publication-qualification.js";
 
 export {
   RELEASE_ACTIVATION_CONTRACT,

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

@@ -0,0 +1,222 @@
+import crypto from "node:crypto";
+
+export const V4_PUBLICATION_QUALIFICATION_SCHEMA =
+  "kungfu.buildchain.v4-publication-qualification/v1";
+
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const FORBIDDEN_EXECUTION_KEYS = new Set([
+  "cmd",
+  "command",
+  "eval",
+  "executable",
+  "javascript",
+  "run",
+  "script",
+  "shell",
+]);
+
+export class V4PublicationQualificationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "V4PublicationQualificationError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new V4PublicationQualificationError(code, message);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function v4PublicationQualificationRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonical(value)).digest("hex")}`;
+}
+
+export function assertNoV4ExecutionFields(value, location = "$") {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) =>
+      assertNoV4ExecutionFields(entry, `${location}[${index}]`),
+    );
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, entry] of Object.entries(value)) {
+    if (FORBIDDEN_EXECUTION_KEYS.has(key.toLowerCase())) {
+      fail(
+        "execution-field-forbidden",
+        `v4 declarative publication forbids ${location}.${key}`,
+      );
+    }
+    assertNoV4ExecutionFields(entry, `${location}.${key}`);
+  }
+}
+
+function exactRoot(value, label) {
+  const root = String(value || "").toLowerCase();
+  if (!ROOT.test(root))
+    fail("schema-invalid", `${label} must be a sha256 root`);
+  return root;
+}
+
+function exactSha(value, label) {
+  const sha = String(value || "").toLowerCase();
+  if (!SHA.test(sha))
+    fail("schema-invalid", `${label} must be an exact Git SHA`);
+  return sha;
+}
+
+function normalizedArtifacts(artifacts) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    fail(
+      "schema-invalid",
+      "publication qualification requires typed artifacts",
+    );
+  }
+  const normalized = artifacts
+    .map((artifact) => {
+      const value = {
+        role: String(artifact?.role || ""),
+        platform: String(artifact?.platform || ""),
+        artifactRoot: exactRoot(artifact?.artifactRoot, "artifactRoot"),
+        manifestRoot: exactRoot(artifact?.manifestRoot, "manifestRoot"),
+      };
+      if (!value.role || !value.platform)
+        fail("schema-invalid", "artifact role and platform are required");
+      return value;
+    })
+    .sort((left, right) =>
+      `${left.role}\0${left.platform}`.localeCompare(
+        `${right.role}\0${right.platform}`,
+      ),
+    );
+  if (
+    new Set(normalized.map(({ role, platform }) => `${role}\0${platform}`))
+      .size !== normalized.length
+  ) {
+    fail("schema-invalid", "artifact role/platform bindings must be unique");
+  }
+  return normalized;
+}
+
+export function createV4PublicationQualificationReceipt({
+  repository,
+  candidateRoot,
+  sourceSha,
+  sourceRoot,
+  policyDigest,
+  artifacts,
+  issuedAt,
+  expiresAt,
+}) {
+  const body = {
+    schema: V4_PUBLICATION_QUALIFICATION_SCHEMA,
+    repository: String(repository || ""),
+    candidateRoot: exactRoot(candidateRoot, "candidateRoot"),
+    sourceSha: exactSha(sourceSha, "sourceSha"),
+    sourceRoot: exactRoot(sourceRoot, "sourceRoot"),
+    policyDigest: exactRoot(policyDigest, "policyDigest"),
+    artifacts: normalizedArtifacts(artifacts),
+    issuedAt: String(issuedAt || ""),
+    expiresAt: String(expiresAt || ""),
+  };
+  if (!/^[^/\s]+\/[^/\s]+$/u.test(body.repository))
+    fail("schema-invalid", "repository must be owner/repo");
+  const issued = Date.parse(body.issuedAt);
+  const expires = Date.parse(body.expiresAt);
+  if (
+    !Number.isFinite(issued) ||
+    !Number.isFinite(expires) ||
+    expires <= issued
+  )
+    fail("schema-invalid", "qualification freshness interval is invalid");
+  assertNoV4ExecutionFields(body);
+  const artifactRoot = v4PublicationQualificationRoot(body.artifacts);
+  const receipt = { ...body, artifactRoot };
+  return {
+    ...receipt,
+    receiptRoot: v4PublicationQualificationRoot(receipt),
+  };
+}
+
+export function validateV4PublicationQualificationReceipt(
+  receipt,
+  {
+    repository,
+    candidateRoot,
+    sourceSha,
+    sourceRoot,
+    artifactRoot,
+    policyDigest,
+    evaluatedAt = new Date().toISOString(),
+  } = {},
+) {
+  if (!receipt)
+    fail("qualification-missing", "qualification receipt is required");
+  assertNoV4ExecutionFields(receipt);
+  const recreated = createV4PublicationQualificationReceipt(receipt);
+  if (
+    receipt.artifactRoot !== recreated.artifactRoot ||
+    receipt.receiptRoot !== recreated.receiptRoot
+  ) {
+    fail(
+      "qualification-tampered",
+      "qualification receipt root does not verify",
+    );
+  }
+  if (repository && receipt.repository !== repository)
+    fail("repository-mismatch", "qualification repository does not match");
+  if (candidateRoot && receipt.candidateRoot !== candidateRoot)
+    fail("candidate-mismatch", "qualification candidate root does not match");
+  if (sourceSha && receipt.sourceSha !== sourceSha)
+    fail("source-mismatch", "qualification source SHA does not match");
+  if (sourceRoot && receipt.sourceRoot !== sourceRoot)
+    fail("source-mismatch", "qualification source root does not match");
+  if (artifactRoot && receipt.artifactRoot !== artifactRoot)
+    fail("artifact-mismatch", "qualification artifact root does not match");
+  if (policyDigest && receipt.policyDigest !== policyDigest)
+    fail("policy-mismatch", "qualification policy digest does not match");
+  const evaluated = Date.parse(evaluatedAt);
+  if (!Number.isFinite(evaluated))
+    fail("schema-invalid", "evaluatedAt is invalid");
+  if (
+    evaluated < Date.parse(receipt.issuedAt) ||
+    evaluated >= Date.parse(receipt.expiresAt)
+  )
+    fail(
+      "qualification-stale",
+      "qualification receipt is outside its freshness window",
+    );
+  return Object.freeze({
+    ok: true,
+    receiptRoot: receipt.receiptRoot,
+    artifactRoot: receipt.artifactRoot,
+  });
+}
+
+export function assertV4DeclarativePromotionInputs(inputs) {
+  const forbidden = Object.entries(inputs || {}).filter(
+    ([name, value]) =>
+      /(command|cmd|script|shell|run)$/iu.test(name) &&
+      String(value || "").trim() !== "",
+  );
+  if (forbidden.length > 0) {
+    fail(
+      "legacy-command-input-forbidden",
+      `v4 declarative publication rejects: ${forbidden
+        .map(([name]) => name)
+        .sort()
+        .join(", ")}`,
+    );
+  }
+}

package/scripts/check-inventory.mjs

@@ -759,8 +759,8 @@ const registeredActionIds = (workflowRegistry.actions || []).map((entry) => entr
 const readmeActionIndex = fs.readFileSync(path.join(root, "README.md"), "utf8");
 const mapActionIndex = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
 const retrospectiveActionIndex = fs.readFileSync(path.join(root, ".github/retrospectives/2026-07-10-buildchain-consolidation.md"), "utf8");
-if (registeredActionIds.length !== 7) {
-  throw new Error(`workflow-registry.json must expose the seven current action entries, got ${registeredActionIds.length}`);
+if (registeredActionIds.length !== 8) {
+  throw new Error(`workflow-registry.json must expose the eight current action entries, got ${registeredActionIds.length}`);
 }
 for (const actionId of registeredActionIds) {
   if (!readmeActionIndex.includes(`actions/${actionId}`) || !mapActionIndex.includes(`actions/${actionId}`)) {

package/scripts/generate-release-candidate-passport.mjs

@@ -8,6 +8,7 @@ import { scanV4FloatingConsumerPolicy, v4ConsumerPolicyScannerRoot } from "../pa
 import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
 import { V4_STAGE_CAPSULE_CONTRACT, V4_STAGE_CAPSULE_IDENTITY_CONTRACT, v4StageCapsuleIdentityRoot, v4StageCapsuleRoot, validateV4StageCapsule } from "../packages/core/v4-stage-capsule.js";
 import { v4RuntimeResumeDocumentRoot } from "../packages/core/v4-runtime-ref-resume-authority.js";
+import { createV4PublicationQualificationReceipt } from "../packages/core/v4-publication-qualification.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
 const env = (name, fallback = "") => process.env[name] || fallback;
@@ -32,7 +33,20 @@ export function createReleaseCandidateStageCapsules({
   const coordinateByPlatform = new Map(
     coordinates.artifacts.map((entry) => [entry.platformId, entry]),
   );
-  const qualificationRoot = passport.controllerReceipts?.[0]?.receiptDigest;
+  const qualificationArtifacts = passport.platformMatrix.map((platform) => {
+    const coordinate = coordinateByPlatform.get(platform.platformId);
+    if (!coordinate || coordinate.name !== platform.artifactName) throw new Error(`Stage Capsule coordinate missing for ${platform.platformId}`);
+    const manifest = readJsonFile(platform.manifestPath);
+    return { role: platform.artifactName, platform: platform.platformId, artifactRoot: coordinate.digest, manifestRoot: v4ContentRoot("stage-capsule-artifact-manifest", manifest) };
+  });
+  const qualificationExpiresAt = coordinates.artifacts.map((entry) => entry.expiresAt).sort((left, right) => Date.parse(left) - Date.parse(right))[0];
+  const qualificationReceipt = createV4PublicationQualificationReceipt({
+    repository: passport.repository, candidateRoot: `sha256:${passport.candidateHash}`,
+    sourceSha: passport.source.headSha, sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+    policyDigest: passport.consumerPolicy.receiptRoot, artifacts: qualificationArtifacts,
+    issuedAt: passport.createdAt || new Date(Date.parse(qualificationExpiresAt) - 86_400_000).toISOString(), expiresAt: qualificationExpiresAt,
+  });
+  const qualificationRoot = qualificationReceipt.receiptRoot;
   const entries = passport.platformMatrix
     .map((platform) => {
       const coordinate = coordinateByPlatform.get(platform.platformId);
@@ -93,6 +107,9 @@ export function createReleaseCandidateStageCapsules({
         platform: platform.platformId,
         artifactName: coordinate.name,
         artifactDigest: coordinate.digest,
+        publicationArtifact: qualificationArtifacts.find(
+          ({ platform: platformId }) => platformId === platform.platformId,
+        ),
         artifact: coordinate,
         capsule,
       };
@@ -112,6 +129,8 @@ export function createReleaseCandidateStageCapsules({
       treeSha: passport.source.treeHash,
     },
     consumerPolicyReceiptRoot: passport.consumerPolicy.receiptRoot,
+    publicationQualificationRoot: qualificationRoot,
+    publicationQualificationReceipt: qualificationReceipt,
     capsules: entries,
   };
   return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
@@ -150,12 +169,16 @@ function writeReleaseCandidateStageCapsules({
     stageCapsulesPath,
     `${JSON.stringify(stageCapsules, null, 2)}\n`,
   );
+  const qualificationPath = path.join(path.dirname(outputPath), "release-candidate-publication-qualification.json");
+  fs.writeFileSync(qualificationPath, `${JSON.stringify(stageCapsules.publicationQualificationReceipt, null, 2)}\n`);
   return {
     path: path
       .relative(process.cwd(), stageCapsulesPath)
       .split(path.sep)
       .join("/"),
     root: stageCapsules.root,
+    qualificationPath: path.relative(process.cwd(), qualificationPath).split(path.sep).join("/"),
+    qualificationRoot: stageCapsules.publicationQualificationRoot,
   };
 }
 
@@ -246,6 +269,8 @@ export function generateReleaseCandidatePassportCli() {
     }),
     "release-candidate-stage-capsules-path": stageCapsules.path,
     "release-candidate-stage-capsules-root": stageCapsules.root,
+    "release-candidate-publication-qualification-path": stageCapsules.qualificationPath,
+    "release-candidate-publication-qualification-root": stageCapsules.qualificationRoot,
   });
   return passport;
 }

package/scripts/generate-site-bundle.mjs

@@ -66,10 +66,15 @@ const RELEASE_TAIL_CAPABILITIES_SCHEMA =
   "schemas/release-tail-capabilities-v1.schema.json";
 const RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE =
   "contracts/release-tail-capabilities-v1.schema.json";
+const V4_PUBLICATION_QUALIFICATION_SCHEMA =
+  "schemas/v4-publication-qualification-v1.schema.json";
+const V4_PUBLICATION_QUALIFICATION_SCHEMA_SOURCE =
+  "contracts/v4-publication-qualification-v1.schema.json";
 const PUBLICATION_REHEARSAL_SITE_SCHEMAS = [
   V4_PUBLICATION_REHEARSAL_SCHEMA,
   V4_ADOPTER_DELIVERY_SCHEMA,
   RELEASE_TAIL_CAPABILITIES_SCHEMA,
+  V4_PUBLICATION_QUALIFICATION_SCHEMA,
 ];
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
@@ -102,6 +107,7 @@ function siteFileBytes(name, value) {
   if (name === DEV_DELIVERY_AUTHORITY_SCHEMA) return readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE);
   if (name === V4_COMPATIBILITY_FACTS_SCHEMA) return readText(V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE);
   if (name === V4_PUBLICATION_REHEARSAL_SCHEMA) return readText(V4_PUBLICATION_REHEARSAL_SCHEMA_SOURCE);
+  if (name === V4_PUBLICATION_QUALIFICATION_SCHEMA) return readText(V4_PUBLICATION_QUALIFICATION_SCHEMA_SOURCE);
   if (name === V4_ADOPTER_DELIVERY_SCHEMA) return readText(V4_ADOPTER_DELIVERY_SCHEMA_SOURCE);
   if (name === RELEASE_TAIL_CAPABILITIES_SCHEMA) return readText(RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE);
   return stableJson(value);

package/scripts/release-candidate-resolver.mjs

@@ -9,6 +9,8 @@ import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
 import { createResolvedPublicationSealedBundle } 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";
 
 const DEFAULT_WORKFLOW_FILE = "build-surface-fixture.yml";
 
@@ -434,6 +436,42 @@ function findDownloadedFile(root, filename) {
   return "";
 }
 
+function resolveV4PublicationEvidence(passportDir, passport, outputPath) {
+  const stageCapsulesPath = findDownloadedFile(passportDir, "release-candidate-stage-capsules.json");
+  const publicationQualificationPath = findDownloadedFile(passportDir, "release-candidate-publication-qualification.json");
+  if (!passport.consumerPolicy?.receiptRoot) {
+    return {
+      paths: {
+        stageCapsules: stageCapsulesPath ? outputPath(stageCapsulesPath) : "",
+        publicationQualification: publicationQualificationPath ? outputPath(publicationQualificationPath) : "",
+      },
+      publicationQualificationRoot: "",
+    };
+  }
+  if (!stageCapsulesPath || !publicationQualificationPath) {
+    throw new Error("v4 release candidate is missing Stage Capsules or publication qualification receipt");
+  }
+  const stageCapsules = JSON.parse(fs.readFileSync(stageCapsulesPath, "utf8"));
+  const qualification = JSON.parse(fs.readFileSync(publicationQualificationPath, "utf8"));
+  validateV4PublicationQualificationReceipt(qualification, {
+    repository: passport.repository,
+    candidateRoot: `sha256:${passport.candidateHash}`,
+    sourceSha: passport.source.headSha,
+    sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+    artifactRoot: v4PublicationQualificationRoot(stageCapsules.capsules.map(({ publicationArtifact }) => publicationArtifact)),
+    policyDigest: passport.consumerPolicy.receiptRoot,
+  });
+  if (stageCapsules.publicationQualificationRoot !== qualification.receiptRoot) throw new Error("Stage Capsules do not bind the publication qualification receipt");
+  if (stageCapsules.capsules.some(({ capsule }) => capsule.identity.qualificationRoot !== qualification.receiptRoot)) throw new Error("a Stage Capsule does not bind the publication qualification receipt");
+  return {
+    paths: {
+      stageCapsules: outputPath(stageCapsulesPath),
+      publicationQualification: outputPath(publicationQualificationPath),
+    },
+    publicationQualificationRoot: qualification.receiptRoot,
+  };
+}
+
 export async function resolveReleaseCandidateArtifacts({
   repository,
   targetRef,
@@ -667,6 +705,7 @@ export async function resolveReleaseCandidateArtifacts({
     throw new Error("downloaded release-candidate artifacts did not contain release-candidate-passport.json and build-summary.json");
   }
   const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
+  const v4Publication = resolveV4PublicationEvidence(passportDir, passport, outputPath);
   const platformManifestPaths = findDownloadedFiles(payloadDir, "manifest.json");
   const githubArtifactAttestationPolicyPaths = findDownloadedFiles(
     payloadDir,
@@ -722,6 +761,7 @@ export async function resolveReleaseCandidateArtifacts({
     paths: {
       passport: outputPath(passportPath),
       buildSummary: outputPath(buildSummaryPath),
+      ...v4Publication.paths,
       payloads: outputPath(payloadDir),
       platformManifests: platformManifestPaths.map(outputPath),
       githubArtifactAttestationPolicies: githubArtifactAttestationPolicyPaths.map(outputPath),
@@ -738,6 +778,7 @@ export async function resolveReleaseCandidateArtifacts({
     githubArtifactAttestationPolicyCount: githubArtifactAttestationPolicyPaths.length,
     npmTarballCount: npmTarballPaths.length,
     publishRequiredArtifacts: generatedRequiredArtifacts,
+    publicationQualificationRoot: v4Publication.publicationQualificationRoot,
   };
 }
 
@@ -766,6 +807,9 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "promote-only-release-candidate": String(result.enabled === true),
     "release-candidate-passport-path": result.paths?.passport || "",
     "release-candidate-build-summary-path": result.paths?.buildSummary || "",
+    "release-candidate-stage-capsules-path": result.paths?.stageCapsules || "",
+    "release-candidate-publication-qualification-path": result.paths?.publicationQualification || "",
+    "release-candidate-publication-qualification-root": result.publicationQualificationRoot || "",
     "release-candidate-version": result.version || "",
     "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",

package/scripts/site-capability-metadata.mjs

@@ -230,6 +230,7 @@ export function nodeApiMeta(exportName) {
     "./v4-tail-reseal": { group: "release-passport-trust", summary: "Effect-pure retained Stage Capsule validation and explicit Warrant-, credential-, and release-tail-fenced macOS reseal planning APIs." },
     "./v4-tail-reseal-receipt": { group: "release-passport-trust", summary: "Four-platform byte readback, standard candidate Passport binding, and terminal v4 tail-reseal receipt APIs." },
     "./v4-publication-rehearsal": { group: "release-passport-trust", summary: "Content-addressed v4 publication rehearsal capsules, shared production release-tail execution, replay, provider observation, and fail-closed verification APIs." },
+    "./v4-publication-qualification": { group: "release-passport-trust", summary: "Sealed v4 candidate, source, artifact, policy, freshness, and command-free promotion admission APIs." },
     "./adopter-delivery-gate": { group: "reusable-build", summary: "Protocol-neutral adopter delivery gate, driver interface, artifact profiles, and canonical result APIs." },
     "./kfd-adopter-category-driver": { group: "kfd-trust", summary: "Published KFD adopter-category driver and exact package-cut verification APIs." },
     "./buildchain-delivery-infrastructure": { group: "reusable-build", summary: "Public delivery-infrastructure instance creation and KFD verification APIs." },

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+
+import { assertV4DeclarativePromotionInputs } from "../packages/core/v4-publication-qualification.js";
+
+export function admitV4DeclarativePromotion({
+  inputs,
+  runtimeRef,
+  declarative,
+}) {
+  if (!/^v4(?:$|[-./])/u.test(String(runtimeRef || ""))) {
+    return Object.freeze({ mode: "legacy", admitted: true });
+  }
+  if (declarative !== true) {
+    const error = new Error(
+      "Buildchain v4 release-candidate-promote requires declarative-release-tail=true",
+    );
+    error.code = "v4-declarative-release-tail-required";
+    throw error;
+  }
+  assertV4DeclarativePromotionInputs(inputs);
+  return Object.freeze({ mode: "v4-declarative", admitted: true });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = admitV4DeclarativePromotion({
+      inputs: JSON.parse(process.env.BUILDCHAIN_PROMOTION_INPUTS_JSON || "{}"),
+      runtimeRef: process.env.BUILDCHAIN_RUNTIME_REF,
+      declarative: process.env.BUILDCHAIN_DECLARATIVE_RELEASE_TAIL === "true",
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(
+      `v4-declarative-promotion-admission: ${error.code || "rejected"}: ${error.message}\n`,
+    );
+    process.exitCode = 1;
+  }
+}