@kungfu-tech/buildchain 2.12.4 → 2.12.5-alpha.2

package/packages/core/release-passport.js

@@ -16,6 +16,7 @@ import {
 } from "./kfd-gate.js";
 import { createSurfaceTimestampPolicy } from "./surface-manifest.js";
 import { validatePublishEvidence as validateTransactionPublishEvidence } from "./publish-transaction.js";
+import { normalizeControllerReceiptReferences } from "./controller-evidence.js";
 
 export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
 export const ARTIFACT_EVIDENCE_CONTRACT = "kungfu-buildchain-artifact-evidence";
@@ -989,6 +990,8 @@ export function createReleasePassport({
   kfd1 = undefined,
   kfd2Claims = [],
   kfd3 = undefined,
+  controllerReceipts = [],
+  controllerReceiptReferences = [],
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: normalizedTag, sourceSha, workflow });
@@ -1016,6 +1019,18 @@ export function createReleasePassport({
     kfd1Section: normalizedKfd1?.passportSection,
     kfd3Section: normalizedKfd3?.passportSection,
   });
+  const builtSourceSha = optionalString(release.builtSourceSha || release.built_source_sha);
+  const promotionChannelSha = optionalString(release.promotionChannelSha || release.promotion_channel_sha);
+  const treeEquivalent = release.treeEquivalent === true;
+  const normalizedControllerReceipts = normalizeControllerReceiptReferences({
+    receipts: controllerReceipts,
+    references: controllerReceiptReferences,
+    expectedSourceSha: sourceSha,
+    acceptedSourceShas: treeEquivalent && promotionChannelSha === sourceSha && builtSourceSha
+      ? [builtSourceSha]
+      : [],
+    requirePassed: true,
+  });
   const publishArtifacts = normalizedPublishEvidence?.artifacts || [];
   const normalizedPublishSummary = normalizePublishSummary({
     packageSet: normalizedPackageSet,
@@ -1069,6 +1084,7 @@ export function createReleasePassport({
         "artifact-evidence.json",
         "publish evidence",
         "release-state transaction",
+        "controller receipt references",
       ],
       timestampFields: ["generatedAt", "publishedAt", "surfaceTimestampPolicy.generatedAt", "surfaceTimestampPolicy.publishedAt"],
       timestampFieldsParticipateInArtifactDigest: true,
@@ -1138,6 +1154,7 @@ export function createReleasePassport({
     ...(normalizedKfd1 ? { [normalizedKfd1.key || kfd1Metadata.key]: normalizedKfd1.passportSection } : {}),
     ...(normalizedKfd2 ? { "kfd-2": normalizedKfd2 } : {}),
     ...(normalizedKfd3 ? { [normalizedKfd3.key || "kfd-3"]: normalizedKfd3.passportSection } : {}),
+    ...(normalizedControllerReceipts.length > 0 ? { controllerReceipts: normalizedControllerReceipts } : {}),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [
@@ -1218,6 +1235,7 @@ export function collectGitHubReleasePassport({
   kfd3PrebuildWitnessJsons = [],
   kfd3ArtifactWitnessJsons = [],
   kfd3ArtifactVerifyCommand = "",
+  controllerReceiptReferences = [],
   basePassportJson = "",
   requireBaseKfd = false,
   releaseJsonExtra = "",
@@ -1340,6 +1358,7 @@ export function collectGitHubReleasePassport({
     kfd1,
     kfd2Claims: kfd2ClaimMetas.map((meta) => meta.value),
     kfd3,
+    controllerReceiptReferences,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,

package/scripts/check-inventory.mjs

@@ -234,6 +234,9 @@ if (rootPackage.exports?.["./homebrew"] !== "./packages/core/homebrew.js") {
 if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildchain-contract.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/buildchain-contract");
 }
+if (rootPackage.exports?.["./controller-evidence"] !== "./packages/core/controller-evidence.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/controller-evidence");
+}
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
@@ -1040,7 +1043,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", "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", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }

package/scripts/controller-evidence.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createControllerPlan,
+  createControllerReceipt,
+  validateControllerPlan,
+  validateControllerReceipt,
+} from "../packages/core/controller-evidence.js";
+
+function argument(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : process.argv[index + 1] || "";
+}
+
+function env(name, fallback = "") {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function readJson(filePath, label = filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`could not read ${label}: ${error.message}`);
+  }
+}
+
+function parseJson(value, label, fallback = undefined) {
+  if (!String(value || "").trim() && fallback !== undefined) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${label} must be valid JSON: ${error.message}`);
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeOutputs(outputs) {
+  const outputPath = env("GITHUB_OUTPUT");
+  if (!outputPath) return;
+  fs.appendFileSync(outputPath, Object.entries(outputs).map(([name, value]) => `${name}=${String(value ?? "")}\n`).join(""));
+}
+
+function sha256File(filePath) {
+  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+}
+
+function descriptorFromRegistry(registry, controllerId) {
+  const descriptor = registry.controllers?.find((entry) => entry.id === controllerId);
+  if (!descriptor) throw new Error(`controller registry does not declare ${controllerId}`);
+  return descriptor;
+}
+
+function normalizeStageStatus(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return {
+    success: "passed",
+    failure: "failed",
+    cancelled: "cancelled",
+    skipped: "skipped",
+  }[normalized] || normalized;
+}
+
+function collectEvidence() {
+  const inline = parseJson(env("BUILDCHAIN_CONTROLLER_EVIDENCE_JSON", "[]"), "controller evidence JSON", []);
+  const files = parseJson(env("BUILDCHAIN_CONTROLLER_EVIDENCE_FILES_JSON", "[]"), "controller evidence files JSON", []);
+  if (!Array.isArray(inline) || !Array.isArray(files)) throw new Error("controller evidence inputs must be arrays");
+  return [
+    ...inline,
+    ...files.map((entry, index) => {
+      const filePath = path.resolve(String(entry.path || ""));
+      if (!entry.kind || !entry.path) throw new Error(`controller evidence file ${index} requires kind and path`);
+      if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) throw new Error(`controller evidence file is missing: ${entry.path}`);
+      return {
+        kind: String(entry.kind),
+        digest: sha256File(filePath),
+        ...(entry.artifact ? { artifact: String(entry.artifact) } : {}),
+      };
+    }),
+  ];
+}
+
+function planMode() {
+  const registryPath = path.resolve(env("BUILDCHAIN_CONTROLLER_REGISTRY", ".buildchain/runtime/dist/site/controller-registry.json"));
+  const registry = readJson(registryPath, "controller registry");
+  const descriptor = descriptorFromRegistry(registry, env("BUILDCHAIN_CONTROLLER_ID"));
+  const plan = createControllerPlan({
+    descriptor,
+    source: {
+      repository: env("BUILDCHAIN_CONTROLLER_SOURCE_REPOSITORY"),
+      sha: env("BUILDCHAIN_CONTROLLER_SOURCE_SHA"),
+    },
+    runtime: {
+      ref: env("BUILDCHAIN_CONTROLLER_RUNTIME_REF"),
+      sha: env("BUILDCHAIN_CONTROLLER_RUNTIME_SHA"),
+      contractDigest: env("BUILDCHAIN_CONTROLLER_CONTRACT_DIGEST"),
+    },
+    inputs: parseJson(env("BUILDCHAIN_CONTROLLER_INPUTS_JSON", "{}"), "controller inputs JSON", {}),
+  });
+  const outputPath = path.resolve(env("BUILDCHAIN_CONTROLLER_PLAN_PATH", ".buildchain/controller/plan.json"));
+  writeJson(outputPath, plan);
+  writeOutputs({
+    "controller-plan-path": outputPath,
+    "controller-plan-json": JSON.stringify(plan),
+    "controller-plan-digest": plan.digest,
+  });
+  return plan;
+}
+
+function receiptMode() {
+  const planPath = path.resolve(env("BUILDCHAIN_CONTROLLER_PLAN_PATH", ".buildchain/controller/plan.json"));
+  const stages = parseJson(env("BUILDCHAIN_CONTROLLER_STAGES_JSON", "[]"), "controller stages JSON", []);
+  if (!Array.isArray(stages)) throw new Error("controller stages JSON must be an array");
+  const receipt = createControllerReceipt({
+    plan: readJson(planPath, "controller plan"),
+    stages: stages.map((stage) => ({ ...stage, status: normalizeStageStatus(stage.status) })),
+    evidence: collectEvidence(),
+    reason: env("BUILDCHAIN_CONTROLLER_REASON_CODE")
+      ? {
+          code: env("BUILDCHAIN_CONTROLLER_REASON_CODE"),
+          summary: env("BUILDCHAIN_CONTROLLER_REASON_SUMMARY", "controller did not pass"),
+        }
+      : undefined,
+    artifact: env("BUILDCHAIN_CONTROLLER_RECEIPT_ARTIFACT"),
+  });
+  const outputPath = path.resolve(env("BUILDCHAIN_CONTROLLER_RECEIPT_PATH", ".buildchain/controller/receipt.json"));
+  writeJson(outputPath, receipt);
+  writeOutputs({
+    "controller-receipt-path": outputPath,
+    "controller-receipt-json": JSON.stringify(receipt),
+    "controller-receipt-digest": receipt.digest,
+    "controller-receipt-status": receipt.status,
+    "controller-receipt-qualifying": String(receipt.qualifying),
+  });
+  return receipt;
+}
+
+function validateMode() {
+  const kind = env("BUILDCHAIN_CONTROLLER_EVIDENCE_KIND", argument("kind", "receipt"));
+  const filePath = path.resolve(env("BUILDCHAIN_CONTROLLER_EVIDENCE_PATH", argument("file")));
+  const value = readJson(filePath, `controller ${kind}`);
+  const validation = kind === "plan" ? validateControllerPlan(value) : validateControllerReceipt(value);
+  if (!validation.ok || (process.argv.includes("--require-qualifying") && !validation.qualifying)) {
+    throw new Error(`controller ${kind} validation failed: ${validation.issues.join("; ") || "not qualifying"}`);
+  }
+  return validation;
+}
+
+export function controllerEvidenceCli() {
+  const mode = argument("mode", env("BUILDCHAIN_CONTROLLER_MODE", "plan"));
+  if (mode === "plan") return planMode();
+  if (mode === "receipt") return receiptMode();
+  if (mode === "validate") return validateMode();
+  throw new Error(`unsupported controller evidence mode: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    controllerEvidenceCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

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

@@ -45,7 +45,16 @@ function routerInputs(inputBlock) {
 }
 
 function routerOutputs(outputBlock) {
-  const forwarded = outputBlock.replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.build.outputs.$1 }}");
+  const forwarded = outputBlock
+    .replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.build.outputs.$1 }}")
+    .replaceAll("build-lifecycle", "build-channel-router")
+    .replace("value: ${{ jobs.build.outputs.controller-plan-artifact }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-artifact }}")
+    .replace("value: ${{ jobs.build.outputs.controller-plan-json }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-json }}")
+    .replace("value: ${{ jobs.build.outputs.controller-plan-digest }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-digest }}")
+    .replace("value: ${{ jobs.build.outputs.controller-receipt-artifact }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-artifact }}")
+    .replace("value: ${{ jobs.build.outputs.controller-receipt-json }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-json }}")
+    .replace("value: ${{ jobs.build.outputs.controller-receipt-digest }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-digest }}")
+    .replace("value: ${{ jobs.build.outputs.controller-receipt-status }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-status }}");
   return [
     "      buildchain-channel:",
     '        description: "Resolved Buildchain channel: alpha, stable, or override"',
@@ -72,7 +81,127 @@ function forwardedInputs(names) {
     .join("\n");
 }
 
-export function generateChannelBuildWorkflow(source) {
+function routerControllerPlanJob() {
+  return `  controller-plan:
+    name: Plan channel router controller evidence
+    needs: resolve-channel
+    runs-on: ubuntu-24.04
+    outputs:
+      controller-plan-artifact: \${{ steps.names.outputs.controller-plan-artifact }}
+      controller-plan-json: \${{ steps.plan.outputs.controller-plan-json }}
+      controller-plan-digest: \${{ steps.plan.outputs.controller-plan-digest }}
+      runtime-sha: \${{ steps.identities.outputs.runtime-sha }}
+    steps:
+      - name: Checkout selected Buildchain runtime
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ inputs.buildchain-repository }}
+          ref: \${{ needs.resolve-channel.outputs.buildchain-ref }}
+          path: .buildchain/runtime
+          persist-credentials: false
+
+      - name: Resolve selected runtime identity
+        id: identities
+        shell: bash
+        run: |
+          runtime_sha="$(git -C .buildchain/runtime rev-parse HEAD)"
+          contract_digest="$(node -e 'const fs=require("fs"); const value=JSON.parse(fs.readFileSync(".buildchain/runtime/dist/site/buildchain-contract.json","utf8")); process.stdout.write(value.contractDigest)')"
+          {
+            echo "runtime-sha=\${runtime_sha}"
+            echo "contract-digest=\${contract_digest}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create channel router controller plan
+        id: plan
+        run: node .buildchain/runtime/scripts/controller-evidence.mjs --mode plan
+        env:
+          BUILDCHAIN_CONTROLLER_ID: build-channel-router
+          BUILDCHAIN_CONTROLLER_SOURCE_REPOSITORY: \${{ github.repository }}
+          BUILDCHAIN_CONTROLLER_SOURCE_SHA: \${{ github.sha }}
+          BUILDCHAIN_CONTROLLER_RUNTIME_REF: \${{ needs.resolve-channel.outputs.buildchain-ref }}
+          BUILDCHAIN_CONTROLLER_RUNTIME_SHA: \${{ steps.identities.outputs.runtime-sha }}
+          BUILDCHAIN_CONTROLLER_CONTRACT_DIGEST: \${{ steps.identities.outputs.contract-digest }}
+          BUILDCHAIN_CONTROLLER_INPUTS_JSON: \${{ toJSON(inputs) }}
+          BUILDCHAIN_CONTROLLER_PLAN_PATH: .buildchain/controller/plan.json
+
+      - name: Resolve channel router controller plan artifact
+        id: names
+        run: echo "controller-plan-artifact=buildchain-channel-controller-plan-\${SOURCE_SHA}" >> "$GITHUB_OUTPUT"
+        env:
+          SOURCE_SHA: \${{ github.sha }}
+
+      - name: Upload channel router controller plan
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: \${{ steps.names.outputs.controller-plan-artifact }}
+          path: .buildchain/controller/plan.json
+          if-no-files-found: error`;
+}
+
+function routerControllerReceiptJob() {
+  return `  controller-receipt:
+    name: Finalize channel router controller evidence
+    needs:
+      - resolve-channel
+      - controller-plan
+      - build
+    if: \${{ always() && needs.controller-plan.result == 'success' }}
+    runs-on: ubuntu-24.04
+    outputs:
+      controller-receipt-artifact: \${{ steps.names.outputs.controller-receipt-artifact }}
+      controller-receipt-json: \${{ steps.receipt.outputs.controller-receipt-json }}
+      controller-receipt-digest: \${{ steps.receipt.outputs.controller-receipt-digest }}
+      controller-receipt-status: \${{ steps.receipt.outputs.controller-receipt-status }}
+    steps:
+      - name: Checkout selected Buildchain runtime
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ inputs.buildchain-repository }}
+          ref: \${{ needs.controller-plan.outputs.runtime-sha }}
+          path: .buildchain/runtime
+          persist-credentials: false
+
+      - name: Download channel router controller plan
+        uses: actions/download-artifact@v7.0.0
+        with:
+          name: \${{ needs.controller-plan.outputs.controller-plan-artifact }}
+          path: .buildchain/controller
+
+      - name: Create channel router controller receipt
+        id: receipt
+        run: node .buildchain/runtime/scripts/controller-evidence.mjs --mode receipt
+        env:
+          BUILDCHAIN_CONTROLLER_PLAN_PATH: .buildchain/controller/plan.json
+          BUILDCHAIN_CONTROLLER_STAGES_JSON: >-
+            [{"id":"resolve-channel","status":"\${{ needs.resolve-channel.result }}"},{"id":"build","status":"\${{ needs.build.result }}"},{"id":"aggregate","status":"\${{ needs.build.result }}"}]
+          BUILDCHAIN_CONTROLLER_EVIDENCE_JSON: \${{ needs.build.outputs.controller-receipt-digest != '' && format('[{{"kind":"nested-controller-receipt","digest":"{0}"}}]', needs.build.outputs.controller-receipt-digest) || '[]' }}
+          BUILDCHAIN_CONTROLLER_REASON_CODE: \${{ needs.build.result == 'success' && '' || 'nested-build-incomplete' }}
+          BUILDCHAIN_CONTROLLER_REASON_SUMMARY: Nested build controller did not complete successfully
+          BUILDCHAIN_CONTROLLER_RECEIPT_ARTIFACT: buildchain-channel-controller-receipt-\${{ github.sha }}
+          BUILDCHAIN_CONTROLLER_RECEIPT_PATH: .buildchain/controller/receipt.json
+
+      - name: Resolve channel router controller receipt artifact
+        id: names
+        run: echo "controller-receipt-artifact=buildchain-channel-controller-receipt-\${SOURCE_SHA}" >> "$GITHUB_OUTPUT"
+        env:
+          SOURCE_SHA: \${{ github.sha }}
+
+      - name: Upload channel router controller receipt
+        if: \${{ always() && steps.receipt.outcome == 'success' }}
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: \${{ steps.names.outputs.controller-receipt-artifact }}
+          path: .buildchain/controller/receipt.json
+          if-no-files-found: error
+
+      - name: Enforce qualifying channel router controller receipt
+        if: \${{ steps.receipt.outputs.controller-receipt-qualifying != 'true' }}
+        run: |
+          echo "::error::channel router controller receipt is not qualifying: \${{ steps.receipt.outputs.controller-receipt-status }}"
+          exit 1`;
+}
+
+function generateChannelBuildWorkflowBase(source) {
   const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
   const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
   const outputs = blockBetween(source, "    outputs:\n", "\npermissions:\n");
@@ -83,6 +212,16 @@ export function generateChannelBuildWorkflow(source) {
   return `# Generated by scripts/generate-channel-build-workflow.mjs. Do not edit directly.\nname: Buildchain Channel Build\n\non:\n  workflow_call:\n    inputs:\n${routerInputs(inputs)}\n    secrets:\n${secrets.trimEnd()}\n    outputs:\n${routerOutputs(outputs)}\n\npermissions:\n  contents: read\n  issues: write\n  id-token: write\n\njobs:\n  resolve-channel:\n    name: Resolve Buildchain channel\n    runs-on: ubuntu-24.04\n    outputs:\n      channel: \${{ steps.channel.outputs.channel }}\n      buildchain-ref: \${{ steps.channel.outputs.buildchain-ref }}\n      contract-lock-path: \${{ steps.lock.outputs.path }}\n      selection-source: \${{ steps.channel.outputs.selection-source }}\n      reason: \${{ steps.channel.outputs.reason }}\n    steps:\n      - name: Resolve router source\n        id: router\n        shell: bash\n        env:\n          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}\n        run: |\n          set -euo pipefail\n          workflow_ref=\"\${BUILDCHAIN_ROUTER_WORKFLOW_REF}\"\n          repository=\"\${workflow_ref%%/.github/workflows/*}\"\n          ref=\"\${workflow_ref##*@}\"\n          ref=\"\${ref#refs/heads/}\"\n          ref=\"\${ref#refs/tags/}\"\n          if [[ -z \"\${repository}\" || \"\${repository}\" = \"\${workflow_ref}\" || -z \"\${ref}\" ]]; then\n            echo \"Unable to resolve Buildchain router source from job.workflow_ref=\${workflow_ref}\" >&2\n            exit 1\n          fi\n          {\n            echo \"repository=\${repository}\"\n            echo \"ref=\${ref}\"\n          } >> \"\${GITHUB_OUTPUT}\"\n\n      - name: Checkout Buildchain router\n        uses: actions/checkout@v7.0.0\n        with:\n          repository: \${{ steps.router.outputs.repository }}\n          ref: \${{ steps.router.outputs.ref }}\n          path: .buildchain/router\n          persist-credentials: false\n\n      - name: Resolve channel\n        id: channel\n        shell: bash\n        env:\n          BUILDCHAIN_CHANNEL: \${{ inputs.buildchain-channel }}\n          BUILDCHAIN_REQUESTED_REF: \${{ inputs.buildchain-ref }}\n          BUILDCHAIN_PUBLISH_CHANNEL: \${{ inputs.publish-channel }}\n          BUILDCHAIN_EVENT_NAME: \${{ github.event_name }}\n          BUILDCHAIN_GIT_REF: \${{ github.ref }}\n          BUILDCHAIN_RELEASE_PRERELEASE: \${{ github.event.release.prerelease }}\n          BUILDCHAIN_ROUTER_REF: \${{ steps.router.outputs.ref }}\n        run: |\n          node .buildchain/router/scripts/buildchain-channel-router.mjs \\\n            --cwd .buildchain/router \\\n            --channel \"\${BUILDCHAIN_CHANNEL}\" \\\n            --buildchain-ref \"\${BUILDCHAIN_REQUESTED_REF}\" \\\n            --publish-channel \"\${BUILDCHAIN_PUBLISH_CHANNEL}\" \\\n            --event-name \"\${BUILDCHAIN_EVENT_NAME}\" \\\n            --ref \"\${BUILDCHAIN_GIT_REF}\" \\\n            --release-prerelease \"\${BUILDCHAIN_RELEASE_PRERELEASE}\" \\\n            --router-ref \"\${BUILDCHAIN_ROUTER_REF}\"\n\n      - name: Select consumer contract lock\n        id: lock\n        shell: bash\n        env:\n          EXPLICIT_PATH: \${{ inputs.buildchain-contract-lock-path }}\n          ALPHA_PATH: \${{ inputs.buildchain-alpha-contract-lock-path }}\n          STABLE_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}\n          CHANNEL: \${{ steps.channel.outputs.channel }}\n        run: |\n          set -euo pipefail\n          path=\"\${EXPLICIT_PATH}\"\n          if [[ -z \"\${path}\" ]]; then\n            if [[ \"\${CHANNEL}\" = \"alpha\" ]]; then\n              path=\"\${ALPHA_PATH}\"\n            else\n              path=\"\${STABLE_PATH}\"\n            fi\n          fi\n          echo \"path=\${path}\" >> \"\${GITHUB_OUTPUT}\"\n\n  build:\n    name: Build with resolved channel\n    needs: resolve-channel\n    uses: ./.github/workflows/.build.yml\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n${forwardedInputs(names)}\n    secrets: inherit\n`;
 }
 
+export function generateChannelBuildWorkflow(source) {
+  const generated = generateChannelBuildWorkflowBase(source)
+    .replace("\n  build:\n", `\n${routerControllerPlanJob()}\n\n  build:\n`)
+    .replace(
+      "    needs: resolve-channel\n    uses: ./.github/workflows/.build.yml",
+      "    needs:\n      - resolve-channel\n      - controller-plan\n    uses: ./.github/workflows/.build.yml",
+    );
+  return `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n`;
+}
+
 function main() {
   const source = fs.readFileSync(sourcePath, "utf8");
   const generated = generateChannelBuildWorkflow(source);

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

@@ -27,6 +27,8 @@ export function generateReleaseCandidatePassportCli() {
   );
   const gateAggregateJson = env("BUILDCHAIN_GATE_PROFILE_AGGREGATE_JSON");
   const gateAggregate = gateAggregateJson ? JSON.parse(gateAggregateJson) : undefined;
+  const controllerReceiptJson = env("BUILDCHAIN_CONTROLLER_RECEIPT_JSON");
+  const controllerReceipts = controllerReceiptJson ? [JSON.parse(controllerReceiptJson)] : [];
   const passport = createReleaseCandidatePassport({
     repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
     pullRequest: {
@@ -49,6 +51,7 @@ export function generateReleaseCandidatePassportCli() {
       workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""),
     },
     gateAggregate,
+    controllerReceipts,
     workflow: {
       name: env("GITHUB_WORKFLOW"),
       runId: env("GITHUB_RUN_ID", buildSummary.git?.runId || ""),
@@ -77,6 +80,7 @@ export function generateReleaseCandidatePassportCli() {
       candidateHash: passport.candidateHash,
       platformCount: passport.platformMatrix.length,
       gateProfileEvidence: passport.gateProfileEvidence,
+      controllerReceipts: passport.controllerReceipts || [],
     }),
   });
   return passport;

package/scripts/generate-site-bundle.mjs

@@ -5,6 +5,7 @@ import crypto from "node:crypto";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { createBuildchainContractWorld } from "../packages/core/buildchain-contract.js";
+import { createControllerRegistry } from "../packages/core/controller-evidence.js";
 import {
   BUILDCHAIN_AGENT_MANUALS,
   createBuildchainKfdClaimRegistry,
@@ -316,6 +317,7 @@ const manualMetaById = new Map(Object.entries({
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
+  "controller-evidence": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator", "agent"], maturity: "draft", order: 205 },
   "binary-distribution": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 110 },
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
@@ -478,6 +480,7 @@ function nodeApiMeta(exportName) {
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
+    "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
     "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain path resolution and migration APIs." },
@@ -753,6 +756,7 @@ function buildSiteBundle() {
       "docs/stable-candidate-patrol.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
+      "docs/controller-evidence.md",
       "docs/publish-transaction.md",
       "docs/homebrew.md",
       "docs/site-bundle-contract.md",
@@ -862,6 +866,7 @@ function buildSiteBundle() {
       status: "active",
     })),
   };
+  const controllerRegistry = createControllerRegistry({ workflows: workflowRegistry.workflows });
   const publicSurfaceAudit = collectPublicSurfaceReverseAudit({
     root,
     cliRegistry,
@@ -949,6 +954,7 @@ function buildSiteBundle() {
       "manual-registry.json",
       "node-api-registry.json",
       "workflow-registry.json",
+      "controller-registry.json",
       "public-surface-audit.json",
       "release-model.json",
       "artifact-schemas.json",
@@ -1029,6 +1035,7 @@ function buildSiteBundle() {
       "manual-registry.json",
       "node-api-registry.json",
       "workflow-registry.json",
+      "controller-registry.json",
       "public-surface-audit.json",
       "release-model.json",
       "artifact-schemas.json",
@@ -1055,6 +1062,7 @@ function buildSiteBundle() {
       "manual-registry.json",
       "node-api-registry.json",
       "workflow-registry.json",
+      "controller-registry.json",
       "public-surface-audit.json",
       "artifact-schemas.json",
       "buildchain-contract.json",
@@ -1191,6 +1199,7 @@ function buildSiteBundle() {
         "capability-grouped navigation registry for docs, CLI, Node API, workflows, actions, and KFD claims",
         "release model facts",
         "workflow and action registries",
+        "controller evidence descriptors and input classification",
         "CLI command registry",
         "public surface reverse audit",
         "manual and Node API registries",
@@ -1221,12 +1230,13 @@ function buildSiteBundle() {
     "manual-registry.json": manualRegistry,
     "node-api-registry.json": nodeApiRegistry,
     "workflow-registry.json": workflowRegistry,
+    "controller-registry.json": controllerRegistry,
     "public-surface-audit.json": publicSurfaceAudit,
     "release-model.json": releaseModel,
     "artifact-schemas.json": artifactSchemas,
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
-    "buildchain-contract.json": createBuildchainContractWorld({ root }),
+    "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),
     "kfd-upstream-aggregate.json": collectKfdUpstreamFacts({ cwd: root, includeOwn: false }),
     "kfd-claims.json": createBuildchainKfdClaimRegistry({ root }),
     "product-mechanism.json": productMechanism,