@kungfu-tech/buildchain 2.14.2 → 2.14.3-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.2",
+  "version": "2.14.3-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -38,6 +38,7 @@
     "./release-candidate": "./packages/core/release-candidate.js",
     "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
     "./release-passport": "./packages/core/release-passport.js",
+    "./release-passport-contract": "./packages/core/release-passport-contract.js",
     "./release-propagation": "./packages/core/release-propagation.js",
     "./surface-manifest": "./packages/core/surface-manifest.js",
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
@@ -57,6 +58,8 @@
     "./site/kfd-upstream-aggregate.json": "./dist/site/kfd-upstream-aggregate.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
+    "./site/release-passport-check-manifest.json": "./dist/site/release-passport-check-manifest.json",
+    "./site/schemas/release-passport-v1.schema.json": "./dist/site/schemas/release-passport-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",
@@ -104,7 +107,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "1.0.0-alpha.21",
+    "@kungfu-tech/kfd": "1.0.0-alpha.29",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/buildchain-contract.js

@@ -89,6 +89,7 @@ export function createBuildchainContractWorld({
     "publication-artifact",
     "paper-release",
     "release-candidate-promote",
+    ".release-candidate-promote",
     "release-propagation",
   ]);
   const hasCompleteControllerSource = [...controllerWorkflowIds]
@@ -173,11 +174,17 @@ export function createBuildchainContractWorld({
       requiredInputs: ["channel"],
       requiredOutputs: ["promoted-sha", "built-source-sha", "release-candidate-artifact"],
       breakingDefaults: {
+        channelDefault: "auto",
+        alphaShellDefault: `${majorLine}-alpha`,
+        stableShellDefault: majorLine,
         promoteOnlyReleaseCandidate: true,
         requiredStatusCheck: "check / check",
       },
       optionalInputs: [
+        "buildchain-channel",
         "buildchain-ref",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-stable-contract-lock-path",
         "release-candidate-workflow-file",
         "release-candidate-workflow-name",
         "publish-required-artifacts-json",
@@ -210,6 +217,9 @@ export function createBuildchainContractWorld({
         ],
       },
       guarantees: [
+        "one declarative promotion job selects matching alpha or stable workflow shell, runtime, and contract lock",
+        "router, shell, runtime, lock, publication channel, target ref, and override identities are bound before candidate download",
+        "train and exact-SHA runtime overrides remain limited to trusted workflow_dispatch actors",
         "promotion reuses PR-stage release-candidate artifacts",
         "promotion does not run the heavy native build matrix",
         "built source and promotion channel SHA are recorded separately",
@@ -218,6 +228,37 @@ export function createBuildchainContractWorld({
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes",
       ],
     }),
+    surface(root, {
+      id: "advanced-release-candidate-promote",
+      kind: "workflow",
+      path: ".github/workflows/.release-candidate-promote.yml",
+      publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.release-candidate-promote.yml@${majorLine}`,
+      requiredInputs: ["channel"],
+      requiredOutputs: ["promoted-sha", "built-source-sha", "release-candidate-artifact"],
+      breakingDefaults: {
+        promoteOnlyReleaseCandidate: true,
+        requiredStatusCheck: "check / check",
+      },
+      optionalInputs: [
+        "buildchain-ref",
+        "buildchain-contract-lock-path",
+        "promotion-router-ref",
+        "promotion-router-sha",
+        "promotion-shell-ref",
+        "promotion-shell-sha",
+        "promotion-runtime-ref",
+        "promotion-runtime-sha",
+        "promotion-contract-lock-path",
+        "promotion-contract-lock-digest",
+        "promotion-publication-channel",
+        "promotion-target-ref",
+        "promotion-override-used",
+      ],
+      guarantees: [
+        "advanced promotion verifies routed shell, runtime, lock, publication channel, and target bindings before candidate resolution",
+        "promotion reuses PR-stage release-candidate artifacts and does not run the heavy native build matrix",
+      ],
+    }),
     surface(root, {
       id: "web-surface",
       kind: "workflow",

package/packages/core/buildchain-kfd-claims.js

@@ -82,6 +82,7 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
 
 const WORKFLOW_AND_ACTION_FILES = Object.freeze([
   ".github/workflows/.build.yml",
+  ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
   ".github/workflows/release-propagation.yml",
@@ -372,6 +373,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "packages/core/buildchain-contract.js",
         "scripts/buildchain-contract-lock.mjs",
         ".github/workflows/.build.yml",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/reusable-build-surface.md",
       ],
@@ -387,6 +389,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "actions/promote-buildchain-ref/index.js",
         "actions/promote-buildchain-ref/action.yml",
         "scripts/ensure-github-release.mjs",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/release-governance.md",
       ],
@@ -415,6 +418,7 @@ export function createBuildchainPublicClaimDefinitions() {
       sourcePaths: [
         "scripts/npm-publish-transaction.mjs",
         "actions/promote-buildchain-ref/index.js",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/publish-transaction.md",
       ],

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

@@ -5,6 +5,7 @@ import { createPublicationAuthorityRegistry } from "./publication-authority.js";
 
 const DESCRIPTORS = Object.freeze([
   [".github/workflows/.build.yml", "non-publication-oidc"],
+  [".github/workflows/.release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/.publication-authority.yml", "evidence-publication"],
   [".github/workflows/.release-verify.yml", "governance-write"],
   [".github/workflows/.sam-release.yml", "retired-deny"],

package/packages/core/controller-evidence.js

@@ -72,7 +72,7 @@ const CONTROLLER_SPECS = [
   },
   {
     id: "release-candidate-promotion",
-    workflowId: "release-candidate-promote",
+    workflowId: ".release-candidate-promote",
     version: 1,
     capabilities: ["promotion-preflight", "artifact-admission", "publication-authority", "publish-transaction", "release-passport"],
     stages: ["preflight", "admit-release-candidate", "publication-authority", "publish", "passport", "aggregate"],

package/packages/core/index.js

@@ -37,6 +37,7 @@ export {
   detectPackageManager,
   getWorkspaceInfo,
   shellJoin,
+  validatePackageManagerContract,
 } from "./package-manager.js";
 
 export {
@@ -320,6 +321,14 @@ export {
   verifyReleasePassport,
 } from "./release-passport.js";
 
+export {
+  RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT,
+  RELEASE_PASSPORT_SCHEMA,
+  RELEASE_PASSPORT_SCHEMA_ID,
+  createReleasePassportCheckManifest,
+  validateReleasePassportSchema,
+} from "./release-passport-contract.js";
+
 export {
   BUILDCHAIN_CONSUMER_ISSUE_CONTRACT,
   BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT,

package/packages/core/package-manager.js

@@ -15,6 +15,37 @@ function parsePackageManager(value) {
   return match ? match[1] : null;
 }
 
+export function validatePackageManagerContract({ cwd = process.cwd(), expectedManager = "" } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const pkg = readJsonIfExists(path.join(resolvedCwd, "package.json"));
+  const declaredSpec = String(pkg?.packageManager || "").trim();
+  const declaredMatch = declaredSpec.match(/^([A-Za-z0-9._-]+)@([^\s]+)$/);
+
+  if (declaredSpec && !declaredMatch) {
+    throw new Error(
+      `Invalid packageManager declaration: ${declaredSpec}. Expected <manager>@<version>.`,
+    );
+  }
+
+  const declaredName = declaredMatch?.[1] || "";
+  const detected = declaredName && !KNOWN_MANAGERS.has(declaredName)
+    ? { name: "custom", reason: "packageManager" }
+    : detectPackageManager(resolvedCwd);
+  const expected = String(expectedManager || "").trim();
+  if (expected && expected !== "custom" && detected.name !== expected) {
+    throw new Error(
+      `Package manager mismatch: workflow requested ${expected}, but the consumer declares ${detected.name}.`,
+    );
+  }
+
+  return {
+    name: detected.name,
+    reason: detected.reason,
+    declaredSpec,
+    declaredVersion: declaredMatch?.[2] || "",
+  };
+}
+
 export function assertPackageManager(manager) {
   if (!KNOWN_MANAGERS.has(manager)) {
     throw new Error(`Unsupported package manager: ${manager}`);
@@ -288,4 +319,5 @@ export default {
   getWorkspaceInfo,
   getYarnLockInfo,
   shellJoin,
+  validatePackageManagerContract,
 };

package/packages/core/release-passport-contract.js

@@ -0,0 +1,249 @@
+import kfdStandards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
+import {
+  RELEASE_CHECK_REPORT_CONTRACT,
+  RELEASE_PASSPORT_CONTRACT,
+} from "./release-passport.js";
+
+export const RELEASE_PASSPORT_SCHEMA_ID =
+  "https://buildchain.libkungfu.dev/schemas/release-passport-v1.schema.json";
+export const RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT =
+  "kungfu-buildchain-release-passport-check-manifest";
+
+const OBJECT = { type: "object" };
+const STRING = { type: "string", minLength: 1 };
+const OPTIONAL_STRING = { type: "string" };
+
+export const RELEASE_PASSPORT_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: RELEASE_PASSPORT_SCHEMA_ID,
+  title: "Buildchain Release Passport v1",
+  description:
+    "Standalone structural schema for the Buildchain-owned release-passport envelope. KFD subsection semantics remain owned by their canonical KFD schemas.",
+  type: "object",
+  required: [
+    "schemaVersion",
+    "contract",
+    "product",
+    "release",
+    "artifacts",
+    "evidence",
+    "recovery",
+  ],
+  properties: {
+    schemaVersion: { const: 1 },
+    contract: { const: RELEASE_PASSPORT_CONTRACT },
+    generatedAt: { type: "string", format: "date-time" },
+    product: {
+      type: "object",
+      required: ["name", "repository", "mechanism"],
+      properties: {
+        name: STRING,
+        repository: STRING,
+        mechanism: STRING,
+      },
+      additionalProperties: true,
+    },
+    release: {
+      type: "object",
+      required: ["tag"],
+      properties: {
+        tag: STRING,
+        sourceSha: OPTIONAL_STRING,
+        releaseSha: OPTIONAL_STRING,
+        releaseMaterialSha: OPTIONAL_STRING,
+        targetRef: OPTIONAL_STRING,
+        channel: OPTIONAL_STRING,
+        line: OPTIONAL_STRING,
+        package: OBJECT,
+      },
+      additionalProperties: true,
+    },
+    artifacts: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["name"],
+        properties: { name: STRING },
+        additionalProperties: true,
+      },
+    },
+    evidence: {
+      type: "object",
+      required: ["artifactEvidence", "impact", "agentIndex"],
+      properties: {
+        artifactEvidence: STRING,
+        impact: STRING,
+        agentIndex: STRING,
+        publishEvidence: OPTIONAL_STRING,
+        transactionState: OPTIONAL_STRING,
+      },
+      additionalProperties: true,
+    },
+    recovery: OBJECT,
+    workflow: OBJECT,
+    runnerPolicy: OBJECT,
+    versionImpact: OBJECT,
+    surfaceImpacts: { type: "array", items: OBJECT },
+    packageSet: OBJECT,
+    anchorManifest: OBJECT,
+    trustedPublishing: OBJECT,
+    transaction: OBJECT,
+    surfaceTimestampPolicy: OBJECT,
+    buildFacts: { type: "array", items: OBJECT },
+    buildSummary: OBJECT,
+    platformArtifactManifests: { type: "array", items: OBJECT },
+    distTagPromotion: OBJECT,
+    controllerReceipts: { type: "array", items: OBJECT },
+    "kfd-1": OBJECT,
+    "kfd-2": OBJECT,
+    "kfd-3": OBJECT,
+  },
+  additionalProperties: true,
+};
+
+const BUILDCHAIN_AGGREGATION_FIELDS = [
+  "product",
+  "release",
+  "workflow",
+  "runnerPolicy",
+  "versionImpact",
+  "surfaceImpacts",
+  "packageSet",
+  "anchorManifest",
+  "trustedPublishing",
+  "transaction",
+  "surfaceTimestampPolicy",
+  "buildFacts",
+  "buildSummary",
+  "platformArtifactManifests",
+  "distTagPromotion",
+  "controllerReceipts",
+  "artifacts",
+  "evidence",
+  "recovery",
+];
+
+function kfdSectionAuthority(id, standards = kfdStandards) {
+  const standard = standards?.standards?.[id] || {};
+  return {
+    section: id,
+    owner: "KFD",
+    package: standards?.source?.package || "@kungfu-tech/kfd",
+    metadataSchema: standards?.metadataSchema || {},
+    schemaIds: standard.schemaIds || {},
+    schemaPaths: standard.schemaPaths || {},
+    compatibility: standard.compatibility || {},
+    rule: `Buildchain aggregates and checks ${id} evidence but does not redefine its schema semantics.`,
+  };
+}
+
+export function createReleasePassportCheckManifest({ standards = kfdStandards } = {}) {
+  return {
+    schemaVersion: 1,
+    contract: RELEASE_PASSPORT_CHECK_MANIFEST_CONTRACT,
+    passport: {
+      contract: RELEASE_PASSPORT_CONTRACT,
+      schemaVersion: 1,
+      schema: {
+        id: RELEASE_PASSPORT_SCHEMA_ID,
+        path: "schemas/release-passport-v1.schema.json",
+        npmExport: "@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json",
+      },
+      checker: {
+        contract: RELEASE_CHECK_REPORT_CONTRACT,
+        command: "buildchain verify release-passport <buildchain.release.json>",
+        nodeApi: "@kungfu-tech/buildchain/release-passport#verifyReleasePassport",
+        result: "check-report.json",
+      },
+    },
+    ownership: {
+      envelopeOwner: "Buildchain",
+      aggregationFields: BUILDCHAIN_AGGREGATION_FIELDS,
+      kfdSections: ["kfd-1", "kfd-2", "kfd-3"].map((id) =>
+        kfdSectionAuthority(id, standards),
+      ),
+    },
+    localClosure: {
+      entrypoint: "buildchain.release.json",
+      resolutionBase: "directory containing the passport",
+      requiredSiblings: [
+        "product.mechanism",
+        "evidence.artifactEvidence",
+        "evidence.impact",
+        "evidence.agentIndex",
+      ],
+      conditionalSiblings: [
+        {
+          when: "evidence.publishEvidence is present or packageSet is present",
+          pointer: "evidence.publishEvidence",
+        },
+        {
+          when: "evidence.transactionState is present",
+          pointer: "evidence.transactionState",
+        },
+      ],
+      rule:
+        "The normative checker resolves every declared sibling relative to the passport and fails closed on missing required evidence, digest drift, or semantic mismatch.",
+    },
+    compatibility: {
+      envelope:
+        "Compatible optional fields may be added while schemaVersion remains 1; removing or changing required-field semantics requires a new schema id or contract version.",
+      siblings:
+        "New optional siblings may be added in v1; making a sibling required requires a new schema id or contract version.",
+      kfdSections:
+        "Each KFD subsection follows the compatibility metadata published by @kungfu-tech/kfd; Buildchain must not silently reinterpret a KFD schema version.",
+      unknownFields: "Independent readers must preserve or ignore unknown additive fields.",
+    },
+  };
+}
+
+function matchesType(value, type) {
+  if (type === "object") return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  return typeof value === type;
+}
+
+function validateSchemaNode(schema, value, pointer, issues) {
+  if (schema.type && !matchesType(value, schema.type)) {
+    issues.push({ pointer, code: "type", message: `${pointer} must be ${schema.type}` });
+    return;
+  }
+  if (Object.hasOwn(schema, "const") && value !== schema.const) {
+    issues.push({ pointer, code: "const", message: `${pointer} must equal ${JSON.stringify(schema.const)}` });
+  }
+  if (schema.minLength && typeof value === "string" && value.length < schema.minLength) {
+    issues.push({ pointer, code: "minLength", message: `${pointer} must not be empty` });
+  }
+  if (schema.minItems && Array.isArray(value) && value.length < schema.minItems) {
+    issues.push({ pointer, code: "minItems", message: `${pointer} must contain at least ${schema.minItems} item(s)` });
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((entry, index) => validateSchemaNode(schema.items, entry, `${pointer}/${index}`, issues));
+  }
+  if (matchesType(value, "object")) {
+    for (const key of schema.required || []) {
+      if (!Object.hasOwn(value, key)) {
+        issues.push({ pointer: `${pointer}/${key}`, code: "required", message: `${pointer}/${key} is required` });
+      }
+    }
+    for (const [key, childSchema] of Object.entries(schema.properties || {})) {
+      if (Object.hasOwn(value, key)) {
+        validateSchemaNode(childSchema, value[key], `${pointer}/${key}`, issues);
+      }
+    }
+  }
+}
+
+export function validateReleasePassportSchema(passport) {
+  const issues = [];
+  validateSchemaNode(RELEASE_PASSPORT_SCHEMA, passport, "#", issues);
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-passport-schema-validation",
+    schemaId: RELEASE_PASSPORT_SCHEMA_ID,
+    ok: issues.length === 0,
+    issues,
+  };
+}

package/packages/core/release-passport.js

@@ -926,6 +926,43 @@ function normalizeTransaction(value = undefined) {
   };
 }
 
+function normalizePromotionRouting(value = undefined) {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("release.promotionRouting must be a JSON object");
+  }
+  if (value.contract !== "buildchain.promotion-routing/v1") {
+    throw new Error("release.promotionRouting contract must be buildchain.promotion-routing/v1");
+  }
+  for (const [label, field] of [
+    ["router.ref", value.router?.ref],
+    ["router.sha", value.router?.sha],
+    ["shell.ref", value.shell?.ref],
+    ["shell.sha", value.shell?.sha],
+    ["runtime.requestedRef", value.runtime?.requestedRef],
+    ["runtime.resolvedSha", value.runtime?.resolvedSha],
+    ["contractLock.path", value.contractLock?.path],
+    ["contractLock.digest", value.contractLock?.digest],
+    ["publication.channel", value.publication?.channel],
+    ["publication.targetRef", value.publication?.targetRef],
+  ]) {
+    if (!String(field || "").trim()) throw new Error(`release.promotionRouting.${label} is required`);
+  }
+  for (const [label, sha] of [
+    ["router.sha", value.router.sha],
+    ["shell.sha", value.shell.sha],
+    ["runtime.resolvedSha", value.runtime.resolvedSha],
+  ]) {
+    if (!/^[0-9a-f]{40}$/i.test(String(sha))) {
+      throw new Error(`release.promotionRouting.${label} must be a 40-character Git SHA`);
+    }
+  }
+  if (!/^sha256:[0-9a-f]{64}$/i.test(String(value.contractLock.digest))) {
+    throw new Error("release.promotionRouting.contractLock.digest must be a sha256 digest");
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
 export function createArtifactEvidence({ assets = [], repository = "", tag = "", sourceSha = "", workflow = {} } = {}) {
   const normalizedAssets = assets.map((asset, index) => normalizeAsset(asset, index));
   return {
@@ -1002,6 +1039,7 @@ export function createReleasePassport({
   const normalizedPackageSet = normalizePackageSet(packageSet, { packageName, packageVersion, publish });
   const normalizedTrustedPublishing = normalizeTrustedPublishing(trustedPublishing, { workflow, publish });
   const normalizedTransaction = normalizeTransaction(transaction);
+  const normalizedPromotionRouting = normalizePromotionRouting(release.promotionRouting);
   const normalizedBuildSummary = buildSummary ? normalizeEvidenceDocument(buildSummary, "buildSummary") : undefined;
   const normalizedBuildFacts = (buildFacts || [])
     .map((fact, index) => normalizeEvidenceDocument(fact, `buildFacts[${index}]`))
@@ -1150,6 +1188,7 @@ export function createReleasePassport({
     ...(anchorManifest ? { anchorManifest } : {}),
     ...(normalizedTrustedPublishing ? { trustedPublishing: normalizedTrustedPublishing } : {}),
     ...(normalizedTransaction ? { transaction: normalizedTransaction } : {}),
+    ...(normalizedPromotionRouting ? { promotionRouting: normalizedPromotionRouting } : {}),
     ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
     ...(normalizedBuildFacts.length > 0 ? { buildFacts: normalizedBuildFacts } : {}),
     ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),

package/scripts/check-inventory.mjs

@@ -6,6 +6,7 @@ import {
 } from "../packages/core/public-surface-audit.js";
 import { evaluateBuildchainContractLock } from "../packages/core/buildchain-contract.js";
 import { generateChannelBuildWorkflow } from "./generate-channel-build-workflow.mjs";
+import { generateChannelPromotionWorkflow } from "./generate-channel-promotion-workflow.mjs";
 
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
@@ -44,6 +45,8 @@ const requiredPaths = [
   "scripts/release-line-dry-run.mjs",
   "scripts/buildchain-channel-router.mjs",
   "scripts/generate-channel-build-workflow.mjs",
+  "scripts/promotion-channel-router.mjs",
+  "scripts/generate-channel-promotion-workflow.mjs",
   "scripts/build-standalone-binary.mjs",
   "scripts/create-release-bundle.mjs",
   "scripts/ensure-github-release.mjs",
@@ -81,6 +84,7 @@ const requiredPaths = [
   ".github/workflows/buildchain-patrol-monthly.yml",
   ".github/workflows/buildchain-alpha-self-dogfood.yml",
   ".github/workflows/release-candidate-promote.yml",
+  ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-propagation.yml",
   ".github/workflows/npm-publish.yml",
   ".github/workflows/paper-release.yml",
@@ -174,6 +178,30 @@ const channelBuildWorkflow = fs.readFileSync(
 if (channelBuildWorkflow !== generateChannelBuildWorkflow(reusableBuildWorkflow)) {
   throw new Error("generated channel build workflow is stale");
 }
+const advancedPromotionWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/.release-candidate-promote.yml"),
+  "utf8",
+);
+const channelPromotionWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/release-candidate-promote.yml"),
+  "utf8",
+);
+if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromotionWorkflow, {
+  major: Number(selfDogfoodMajor),
+})) {
+  throw new Error("generated channel promotion workflow is stale");
+}
+for (const requiredSnippet of [
+  "buildchain-channel:",
+  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}-alpha`,
+  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}`,
+  "promotion-contract-lock-digest:",
+  "promotion runtime override is only allowed for trusted workflow_dispatch runs",
+]) {
+  if (!channelPromotionWorkflow.includes(requiredSnippet)) {
+    throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "buildchain-channel:",
   "uses: ./.github/workflows/.build.yml",
@@ -270,6 +298,9 @@ if (rootPackage.exports?.["./kfd-gate"] !== "./packages/core/kfd-gate.js") {
 if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-passport.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-passport");
 }
+if (rootPackage.exports?.["./release-passport-contract"] !== "./packages/core/release-passport-contract.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/release-passport-contract");
+}
 if (rootPackage.exports?.["./release-propagation"] !== "./packages/core/release-propagation.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-propagation");
 }
@@ -627,6 +658,9 @@ for (const requiredSnippet of [
   "--kfd-3-artifact-verify-cmd",
   "currently named `kfd-3`",
   "KFD-3 collaboration-interface release gate",
+  "release-passport-v1.schema.json",
+  "release-passport-check-manifest.json",
+  "Buildchain owns envelope aggregation",
 ]) {
   if (!releasePassportDoc.includes(requiredSnippet)) {
     throw new Error(`release passport doc missing KFD-1 gate snippet: ${requiredSnippet}`);
@@ -808,7 +842,7 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: read",
-  "uses: ./.github/workflows/release-candidate-promote.yml",
+  "uses: ./.github/workflows/.release-candidate-promote.yml",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): release v')",
@@ -822,7 +856,7 @@ for (const requiredSnippet of [
     throw new Error(`buildchain ref promotion workflow missing npm transaction snippet: ${requiredSnippet}`);
   }
 }
-const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/release-candidate-promote.yml"), "utf8");
+const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/.release-candidate-promote.yml"), "utf8");
 for (const requiredSnippet of [
   "release-passport-kfd-1-witness-jsons:",
   "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",
@@ -1071,7 +1105,7 @@ if (!badgeEndpointRegistry.badges?.some((entry) => entry.id === "buildchain-rele
   throw new Error("badge endpoint registry must include Buildchain Release Passport badge");
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "publication-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "controller-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "publication-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "controller-registry.json", "public-surface-audit.json", "release-model.json", "release-passport-check-manifest.json", "schemas/release-passport-v1.schema.json", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }