@kungfu-tech/buildchain 3.0.9-alpha.9 → 4.0.0-alpha.0

package/scripts/generate-buildchain-kfd-witnesses.mjs

@@ -1,115 +1,121 @@
 #!/usr/bin/env node
-import crypto from "node:crypto";
 import fs from "node:fs";
-import { execFileSync } from "node:child_process";
-import { createRequire } from "node:module";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
-import { addAdopterWitness, initAdopterManifest } from "@kungfu-tech/kfd/adopter-conformance/toolchain";
-import kfdStandards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
-import { installedKfdPackageArtifactRoot } from "../packages/core/artifact-verification-envelope.js";
-import { createKfdAdopterManifestGate, createKfdLegacySupportMatrixProjection, validateKfdAdopterManifestGate, validateKfdLegacySupportMatrixProjection } from "../packages/core/kfd-adopter-manifest.js";
-import { KFD_PRODUCT_GATE_INPUT_CONTRACT, evaluateKfdProductGate, kfdProductGateDigest, validateKfdProductGateResult } from "../packages/core/kfd-product-gates.js";
-import { createBuildchainKfd1Witness, createBuildchainKfd2Claims, createBuildchainKfd3ArtifactWitness, createBuildchainKfd3PrebuildWitness } from "../packages/core/buildchain-kfd-claims.js";
-import { BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH, BUILDCHAIN_KFD2_CLAIMS_DIR, BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH, BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH } from "../packages/core/buildchain-layout.js";
+import {
+  createBuildchainKfd1Witness,
+  createBuildchainKfd2Claims,
+  createBuildchainKfd3ArtifactWitness,
+  createBuildchainKfd3PrebuildWitness,
+} from "../packages/core/buildchain-kfd-claims.js";
+import {
+  BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH,
+  BUILDCHAIN_KFD2_CLAIMS_DIR,
+  BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH,
+  BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH,
+} from "../packages/core/buildchain-layout.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
-const REPOSITORY = "kungfu-systems/buildchain", require = createRequire(import.meta.url), kfdRoot = path.dirname(require.resolve("@kungfu-tech/kfd/package.json"));
-const evidenceSources = { "KFD-1": "dist/site/release-passport-check-manifest.json", "KFD-2": "dist/site/kfd-claims.json", "KFD-3": "dist/site/public-surface-audit.json", "KFD-4": "packages/core/kfd-product-gates.js", "KFD-5": "packages/core/kfd-product-gates.js", "KFD-7": "packages/core/kfd-product-gates.js", "KFD-10": "packages/core/dev-delivery-warrant.js" };
+
 function parseArgs(argv = process.argv.slice(2)) {
-  const args = { cwd: process.cwd(), outputDir: ".buildchain/kfd", sourceSha: process.env.BUILDCHAIN_SOURCE_SHA || "" };
+  const args = {
+    cwd: process.cwd(),
+    outputDir: ".buildchain/kfd",
+    sourceSha: process.env.BUILDCHAIN_SOURCE_SHA || "",
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === "--cwd") args.cwd = argv[++index] || args.cwd;
-    else if (arg === "--output-dir") args.outputDir = argv[++index] || args.outputDir;
-    else if (arg === "--source-sha") args.sourceSha = argv[++index] || args.sourceSha;
-    else if (arg === "--help") args.help = true;
-    else throw new Error(`unknown argument: ${arg}`);
+    if (arg === "--cwd") {
+      args.cwd = argv[++index] || args.cwd;
+    } else if (arg === "--output-dir") {
+      args.outputDir = argv[++index] || args.outputDir;
+    } else if (arg === "--source-sha") {
+      args.sourceSha = argv[++index] || args.sourceSha;
+    } else if (arg === "--help") {
+      args.help = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
   }
   return args;
 }
+
 function gitSha(cwd) {
-  try { return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim(); } catch { return ""; }
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
 }
-function digest(bytes) { return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`; }
-function fileDigest(filePath) { return digest(fs.readFileSync(filePath)); }
-function relative(root, filePath) { return path.relative(root, filePath).replace(/\\/g, "/"); }
-function writeJson(root, relativePath, value) {
-  const filePath = path.join(root, relativePath);
+
+function writeJson(filePath, value) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
-  return { path: relativePath, sha256: fileDigest(filePath), filePath };
 }
-function readJson(filePath, sourceSha = "") { return JSON.parse(fs.readFileSync(filePath, "utf8").replaceAll("{{SOURCE_SHA}}", sourceSha)); }
-export function generateBuildchainKfdWitnesses({ cwd = process.cwd(), outputDir = ".buildchain/kfd", sourceSha = "", emitOutputs = true } = {}) {
-  const root = path.resolve(cwd), outDir = path.resolve(root, outputDir), resolvedSourceSha = sourceSha || gitSha(root);
+
+function toRepoRelative(cwd, filePath) {
+  return path.relative(cwd, filePath).replace(/\\/g, "/");
+}
+
+export function generateBuildchainKfdWitnesses({
+  cwd = process.cwd(),
+  outputDir = ".buildchain/kfd",
+  sourceSha = "",
+  emitOutputs = true,
+} = {}) {
+  const root = path.resolve(cwd);
+  const outDir = path.resolve(root, outputDir);
+  const resolvedSourceSha = sourceSha || gitSha(root);
   const outputPath = (canonicalPath) => path.join(outDir, path.relative(".buildchain/kfd", canonicalPath));
-  const paths = { kfd1Witness: outputPath(BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH), kfd3PrebuildWitness: outputPath(BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH), kfd3ArtifactWitness: outputPath(BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH), kfd2ClaimsDir: outputPath(BUILDCHAIN_KFD2_CLAIMS_DIR) };
-  writeJson(path.dirname(paths.kfd1Witness), path.basename(paths.kfd1Witness), createBuildchainKfd1Witness({ root, sourceSha: resolvedSourceSha }));
-  writeJson(path.dirname(paths.kfd3PrebuildWitness), path.basename(paths.kfd3PrebuildWitness), createBuildchainKfd3PrebuildWitness({ root, sourceSha: resolvedSourceSha }));
-  writeJson(path.dirname(paths.kfd3ArtifactWitness), path.basename(paths.kfd3ArtifactWitness), createBuildchainKfd3ArtifactWitness({ root, sourceSha: resolvedSourceSha }));
-  const witnessFiles = { "kfd-1-witness": relative(root, paths.kfd1Witness), "kfd-3-prebuild-witness": relative(root, paths.kfd3PrebuildWitness), "kfd-3-artifact-witness": relative(root, paths.kfd3ArtifactWitness) };
+  const paths = {
+    kfd1Witness: outputPath(BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH),
+    kfd3PrebuildWitness: outputPath(BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH),
+    kfd3ArtifactWitness: outputPath(BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH),
+    kfd2ClaimsDir: outputPath(BUILDCHAIN_KFD2_CLAIMS_DIR),
+  };
+  writeJson(paths.kfd1Witness, createBuildchainKfd1Witness({ root, sourceSha: resolvedSourceSha }));
+  writeJson(paths.kfd3PrebuildWitness, createBuildchainKfd3PrebuildWitness({ root, sourceSha: resolvedSourceSha }));
+  writeJson(paths.kfd3ArtifactWitness, createBuildchainKfd3ArtifactWitness({ root, sourceSha: resolvedSourceSha }));
+  const witnessFiles = {
+    "kfd-1-witness": toRepoRelative(root, paths.kfd1Witness),
+    "kfd-3-prebuild-witness": toRepoRelative(root, paths.kfd3PrebuildWitness),
+    "kfd-3-artifact-witness": toRepoRelative(root, paths.kfd3ArtifactWitness),
+  };
   const kfd2ClaimPaths = createBuildchainKfd2Claims({ root, witnessFiles }).map((claim) => {
-    const slug = String(claim.id || "claim").replace(/^claim:/, "").replace(/[^0-9A-Za-z._-]+/g, "-").replace(/^-+|-+$/g, "") || "claim";
-    return writeJson(paths.kfd2ClaimsDir, `${slug}.json`, claim).filePath;
+    const slug = String(claim.id || "claim")
+      .replace(/^claim:/, "")
+      .replace(/[^0-9A-Za-z._-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "claim";
+    const claimPath = path.join(paths.kfd2ClaimsDir, `${slug}.json`);
+    writeJson(claimPath, claim);
+    return claimPath;
   });
-  const outputs = { "kfd-1-witness-jsons": relative(root, paths.kfd1Witness), "kfd-2-claim-jsons": kfd2ClaimPaths.map((filePath) => relative(root, filePath)).join(","), "kfd-3-prebuild-witness-jsons": relative(root, paths.kfd3PrebuildWitness), "kfd-3-artifact-witness-jsons": relative(root, paths.kfd3ArtifactWitness), "source-sha": resolvedSourceSha, "output-dir": relative(root, outDir) };
-  if (emitOutputs) writeGitHubOutputs(outputs);
-  return { schemaVersion: 1, contract: "kungfu-buildchain-self-kfd-witness-generation", outputs };
-}
-function productRecords(root, standard, sourceSha) {
-  if (standard === "kfd-4") return [
-    ["observer-perspective", readJson(path.join(root, "contracts/fixtures/kfd-adopter-release-v1/kfd-4-perspective.json"), sourceSha)],
-    ["perspective-replay", readJson(path.join(root, "contracts/fixtures/kfd-adopter-release-v1/kfd-4-replay.json"), sourceSha)],
-  ];
-  if (standard === "kfd-5") return [["primitive-discovery", readJson(path.join(kfdRoot, "cases/live/software-work-perspective-settlement/cuts/0001-assignment.json"))]];
-  const profile = readJson(path.join(kfdRoot, "verifier/fixtures/kfd-7/valid-domain-profile.json"));
-  profile.evidenceObligations = profile.evidenceObligations.map((entry) => ({ ...entry, status: "passed", artifactRefs: ["qualification-proof"], residualRisk: "Bound to the retained Buildchain product gate cut; independent certification remains external." }));
-  profile.activation = { decision: "activate", evidenceCut: `git://${REPOSITORY}@${sourceSha}`, independentReview: "review://protected-release-review", productWitnesses: ["qualification-proof"], residualRisk: "The product gate is non-qualifying and non-self-certifying." };
-  profile.domainProfile = { ...profile.domainProfile, product: "Buildchain", implementation: `git+https://github.com/${REPOSITORY}@${sourceSha}`, qualificationStatus: "qualified" };
-  return [["domain-profile", profile]];
-}
-async function generateProductGate(root, outDir, standard, sourceSha, checkedAt) {
-  const records = productRecords(root, standard, sourceSha).map(([role, value], index) => ({ role, ...writeJson(outDir, `records/${standard}-${index}.json`, value) }));
-  const kinds = standard === "kfd-4" ? [["projection-fsck", "projection-fsck"], ["negative", "negative-fixture"]] : standard === "kfd-5" ? [["negative", "negative-fixture"]] : [["qualification-proof", "qualification-proof"], ["independent-review", "independent-review"], ["negative", "negative-fixture"]];
-  const evidence = kinds.map(([id, kind]) => ({ id, kind, ...writeJson(outDir, `evidence/${standard}-${id}.json`, { schemaVersion: 1, contract: "kungfu-buildchain-kfd-adopter-evidence-reference", id, kind, source: { repository: REPOSITORY, sha: sourceSha }, observedAt: checkedAt, status: "retained", nonClaim: "This product-owned reference does not independently qualify or certify KFD adoption." }) }));
-  const input = { schemaVersion: 1, contract: KFD_PRODUCT_GATE_INPUT_CONTRACT, standard, standardRevision: kfdStandards.standards[standard].revision, source: { repository: REPOSITORY, sha: sourceSha }, evidenceCut: { generatedAt: checkedAt, expiresAt: new Date(Date.parse(checkedAt) + 86400000).toISOString() }, records: records.map(({ role, path, sha256 }) => ({ role, path, sha256 })), evidence: evidence.map(({ id, kind, path, sha256 }) => ({ id, kind, path, sha256 })), responsibility: { owner: REPOSITORY, evidenceOwner: "Buildchain maintainers", proofOwner: "Buildchain release gate" }, nonClaims: ["A passed product gate does not qualify, certify, activate, or independently approve KFD adoption."] };
-  const gate = await evaluateKfdProductGate({ cwd: outDir, input, expectedSourceSha: sourceSha, checkedAt });
-  if (gate.status !== "passed" || !validateKfdProductGateResult(gate, { expectedSourceSha: sourceSha, checkedAt }).valid) throw new Error(`${standard} product gate failed: ${JSON.stringify(gate.issues)}`);
-  writeJson(outDir, `${standard}/product-gate.json`, gate);
-  return gate;
-}
-export async function generateBuildchainKfdAdopterRelease({ cwd = process.cwd(), outputDir = ".buildchain/kfd/adopter-release", sourceSha = "", checkedAt = new Date().toISOString(), emitOutputs = true } = {}) {
-  const root = path.resolve(cwd), outDir = path.resolve(root, outputDir);
-  if (!/^[0-9a-f]{40}$/.test(sourceSha) || !Number.isFinite(Date.parse(checkedAt))) throw new Error("source SHA and checked-at must be exact");
-  for (const sourcePath of Object.values(evidenceSources)) if (!fs.statSync(path.join(root, sourcePath)).isFile()) throw new Error(`required Buildchain evidence source is missing: ${sourcePath}`);
-  const packageArtifactRoot = installedKfdPackageArtifactRoot(), gates = [];
-  for (const standard of ["kfd-4", "kfd-5", "kfd-7"]) gates.push(await generateProductGate(root, outDir, standard, sourceSha, checkedAt));
-  const sourceRoot = kfdProductGateDigest({ repository: REPOSITORY, sourceSha, files: [...new Set(Object.values(evidenceSources))].sort().map((sourcePath) => ({ path: sourcePath, sha256: fileDigest(path.join(root, sourcePath)) })) });
-  let manifest = initAdopterManifest({ manifestId: "buildchain-v3-full-cut", adopterId: REPOSITORY, artifactKind: "git-commit", artifactCoordinate: `${REPOSITORY}@${sourceSha}`, artifactRoot: sourceRoot, scope: "Buildchain v3 release and protected delivery authority", packageArtifactRoot, verifiedAt: checkedAt, maxAgeSeconds: 86400, packageRoot: kfdRoot });
-  const gateById = new Map(gates.map((gate) => [gate.standard.toUpperCase(), gate]));
-  for (const id of ["KFD-1", "KFD-2", "KFD-3", "KFD-4", "KFD-5", "KFD-7"]) {
-    const row = manifest.decisions.find((entry) => entry.id === id);
-    const sourcePath = evidenceSources[id];
-    const sourceEvidence = (kind, rootValue = fileDigest(path.join(root, sourcePath))) => ({ kind, coordinate: `git+https://github.com/${REPOSITORY}@${sourceSha}#${sourcePath}`, root: rootValue, observedAt: checkedAt, kfdPackageRoot: packageArtifactRoot });
-    row.state = "candidate"; row.usage = "used"; row.implementationEvidence = [sourceEvidence("implementation")]; row.verificationEvidence = [sourceEvidence("verification", gateById.get(id)?.gateRoot)]; row.gaps = ["Independent decision-specific assessment and certification remain external."];
+  const outputs = {
+    "kfd-1-witness-jsons": toRepoRelative(root, paths.kfd1Witness),
+    "kfd-2-claim-jsons": kfd2ClaimPaths.map((claimPath) => toRepoRelative(root, claimPath)).join(","),
+    "kfd-3-prebuild-witness-jsons": toRepoRelative(root, paths.kfd3PrebuildWitness),
+    "kfd-3-artifact-witness-jsons": toRepoRelative(root, paths.kfd3ArtifactWitness),
+    "source-sha": resolvedSourceSha,
+    "output-dir": toRepoRelative(root, outDir),
+  };
+  if (emitOutputs) {
+    writeGitHubOutputs(outputs);
   }
-  const kfd6 = manifest.decisions.find((entry) => entry.id === "KFD-6");
-  kfd6.state = "unsupported"; kfd6.usage = "unused"; kfd6.gaps = ["Buildchain does not claim KFD-6 support in this cut."];
-  manifest = addAdopterWitness(manifest, { decisionId: "KFD-10", profileId: "kfd-warrant-evidence", witnessCoordinate: `git+https://github.com/${REPOSITORY}@${sourceSha}#${evidenceSources["KFD-10"]}`, witnessRoot: fileDigest(path.join(root, evidenceSources["KFD-10"])), packageArtifactRoot, verifiedAt: checkedAt, maxAgeSeconds: 86400, packageRoot: kfdRoot });
-  const manifestPath = writeJson(outDir, "kfd-adopter-manifest.json", manifest).filePath, manifestGate = createKfdAdopterManifestGate({ manifest, packageArtifactRoot, gateResults: gates, authorityPath: "kfd-adopter-manifest.json", expectedSourceSha: sourceSha, checkedAt });
-  if (!validateKfdAdopterManifestGate(manifestGate, { expectedSourceSha: sourceSha, checkedAt }).valid) throw new Error(`generated adopter manifest gate failed: ${JSON.stringify(manifestGate.issues)}`);
-  const gatePath = writeJson(outDir, "kfd-adopter-manifest-gate.json", manifestGate).filePath, support = createKfdLegacySupportMatrixProjection({ manifest, manifestGate });
-  if (!validateKfdLegacySupportMatrixProjection(support, { manifest, manifestGate }).valid) throw new Error("generated KFD support projection failed");
-  const supportPath = writeJson(outDir, "kfd-support.json", support).filePath;
-  const outputs = { "kfd-adopter-manifest-json": relative(root, manifestPath), "kfd-adopter-manifest-gate-json": relative(root, gatePath), "kfd-support-matrix-json": relative(root, supportPath), "kfd-product-gate-jsons": gates.map((gate) => relative(root, path.join(outDir, gate.standard, "product-gate.json"))).join(","), "kfd-adopter-manifest-root": manifestGate.authority.manifestRoot, "kfd-adopter-gate-root": manifestGate.gateRoot, "kfd-package-artifact-root": packageArtifactRoot, "source-sha": sourceSha };
-  if (emitOutputs) writeGitHubOutputs(outputs);
-  return { schemaVersion: 1, contract: "kungfu-buildchain-kfd-adopter-release-generation", status: "passed", qualifying: false, selfCertified: false, outputs };
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-self-kfd-witness-generation",
+    outputs,
+  };
 }
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const args = parseArgs();
-    if (args.help) process.stdout.write("Usage: generate-buildchain-kfd-witnesses [--cwd <repo>] [--output-dir <dir>] [--source-sha <sha>]\n");
-    else process.stdout.write(`${JSON.stringify(generateBuildchainKfdWitnesses(args), null, 2)}\n`);
+    if (args.help) {
+      process.stdout.write("Usage: generate-buildchain-kfd-witnesses [--cwd <repo>] [--output-dir <dir>] [--source-sha <sha>]\n");
+      process.exit(0);
+    }
+    process.stdout.write(`${JSON.stringify(generateBuildchainKfdWitnesses(args), null, 2)}\n`);
   } catch (error) {
     console.error(`buildchain self KFD witnesses: ${error.message}`);
     process.exitCode = 1;

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

@@ -46,26 +46,22 @@ function routerInputs(inputBlock) {
 
 function routerOutputs(outputBlock) {
   const forwarded = outputBlock
-    .replace(
-      /^        value: \$\{\{ jobs\.[^.]+\.outputs\.([a-z0-9-]+) \|\| jobs\.[^.]+\.outputs\.\1 \}\}$/gm,
-      "        value: ${{ jobs.alpha.outputs.$1 || jobs.stable.outputs.$1 }}",
-    )
-    .replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.alpha.outputs.$1 || jobs.stable.outputs.$1 }}")
+    .replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.override.outputs.$1 || jobs.alpha.outputs.$1 || jobs.stable.outputs.$1 }}")
     .replaceAll("build-lifecycle", "build-channel-router")
-    .replace("value: ${{ jobs.alpha.outputs.controller-plan-artifact || jobs.stable.outputs.controller-plan-artifact }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-artifact }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-plan-json || jobs.stable.outputs.controller-plan-json }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-json }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-plan-digest || jobs.stable.outputs.controller-plan-digest }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-digest }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-receipt-artifact || jobs.stable.outputs.controller-receipt-artifact }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-artifact }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-receipt-json || jobs.stable.outputs.controller-receipt-json }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-json }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-receipt-digest || jobs.stable.outputs.controller-receipt-digest }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-digest }}")
-    .replace("value: ${{ jobs.alpha.outputs.controller-receipt-status || jobs.stable.outputs.controller-receipt-status }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-status }}")
+    .replace("value: ${{ jobs.override.outputs.controller-plan-artifact || jobs.alpha.outputs.controller-plan-artifact || jobs.stable.outputs.controller-plan-artifact }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-artifact }}")
+    .replace("value: ${{ jobs.override.outputs.controller-plan-json || jobs.alpha.outputs.controller-plan-json || jobs.stable.outputs.controller-plan-json }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-json }}")
+    .replace("value: ${{ jobs.override.outputs.controller-plan-digest || jobs.alpha.outputs.controller-plan-digest || jobs.stable.outputs.controller-plan-digest }}", "value: ${{ jobs.controller-plan.outputs.controller-plan-digest }}")
+    .replace("value: ${{ jobs.override.outputs.controller-receipt-artifact || jobs.alpha.outputs.controller-receipt-artifact || jobs.stable.outputs.controller-receipt-artifact }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-artifact }}")
+    .replace("value: ${{ jobs.override.outputs.controller-receipt-json || jobs.alpha.outputs.controller-receipt-json || jobs.stable.outputs.controller-receipt-json }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-json }}")
+    .replace("value: ${{ jobs.override.outputs.controller-receipt-digest || jobs.alpha.outputs.controller-receipt-digest || jobs.stable.outputs.controller-receipt-digest }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-digest }}")
+    .replace("value: ${{ jobs.override.outputs.controller-receipt-status || jobs.alpha.outputs.controller-receipt-status || jobs.stable.outputs.controller-receipt-status }}", "value: ${{ jobs.controller-receipt.outputs.controller-receipt-status }}")
     .replace(
-      /(      credential-island-macos-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.alpha\.outputs\.artifact-name \|\| jobs\.stable\.outputs\.artifact-name \}\}/,
-      "$1 ${{ jobs.alpha.outputs.credential-island-macos-artifact || jobs.stable.outputs.credential-island-macos-artifact }}",
+      /(      credential-island-macos-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.override\.outputs\.artifact-name \|\| jobs\.alpha\.outputs\.artifact-name \|\| jobs\.stable\.outputs\.artifact-name \}\}/,
+      "$1 ${{ jobs.override.outputs.credential-island-macos-artifact || jobs.alpha.outputs.credential-island-macos-artifact || jobs.stable.outputs.credential-island-macos-artifact }}",
     )
     .replace(
-      /(      credential-island-macos-manifest-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.alpha\.outputs\.manifest-artifact-name \|\| jobs\.stable\.outputs\.manifest-artifact-name \}\}/,
-      "$1 ${{ jobs.alpha.outputs.credential-island-macos-manifest-artifact || jobs.stable.outputs.credential-island-macos-manifest-artifact }}",
+      /(      credential-island-macos-manifest-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.override\.outputs\.manifest-artifact-name \|\| jobs\.alpha\.outputs\.manifest-artifact-name \|\| jobs\.stable\.outputs\.manifest-artifact-name \}\}/,
+      "$1 ${{ jobs.override.outputs.credential-island-macos-manifest-artifact || jobs.alpha.outputs.credential-island-macos-manifest-artifact || jobs.stable.outputs.credential-island-macos-manifest-artifact }}",
     );
   return [
     "      buildchain-channel:",
@@ -85,6 +81,12 @@ function forwardedInputs(names) {
   return names
     .map((name) => {
       if (name === "buildchain-ref") return `      buildchain-ref: \${{ needs.resolve-channel.outputs.buildchain-ref }}`;
+      if (name === "buildchain-expected-channel") {
+        return "      buildchain-expected-channel: ${{ needs.resolve-channel.outputs.channel }}";
+      }
+      if (name === "buildchain-expected-major") {
+        return "      buildchain-expected-major: ${{ needs.resolve-channel.outputs.major }}";
+      }
       if (name === "buildchain-contract-lock-path") {
         return "      buildchain-contract-lock-path: ${{ needs.resolve-channel.outputs.contract-lock-path }}";
       }
@@ -158,6 +160,7 @@ function routerControllerReceiptJob() {
     needs:
       - resolve-channel
       - controller-plan
+      - override
       - alpha
       - stable
     if: \${{ always() && needs.controller-plan.result == 'success' }}
@@ -188,9 +191,9 @@ function routerControllerReceiptJob() {
         env:
           BUILDCHAIN_CONTROLLER_PLAN_PATH: .buildchain/controller/plan.json
           BUILDCHAIN_CONTROLLER_STAGES_JSON: >-
-            [{"id":"resolve-channel","status":"\${{ needs.resolve-channel.result }}"},{"id":"alpha","status":"\${{ needs.alpha.result }}"},{"id":"stable","status":"\${{ needs.stable.result }}"},{"id":"aggregate","status":"\${{ needs.resolve-channel.outputs.channel == 'alpha' && needs.alpha.result || needs.stable.result }}"}]
-          BUILDCHAIN_CONTROLLER_EVIDENCE_JSON: \${{ (needs.alpha.outputs.controller-receipt-digest != '' || needs.stable.outputs.controller-receipt-digest != '') && format('[{{"kind":"nested-controller-receipt","digest":"{0}"}}]', needs.alpha.outputs.controller-receipt-digest || needs.stable.outputs.controller-receipt-digest) || '[]' }}
-          BUILDCHAIN_CONTROLLER_REASON_CODE: \${{ ((needs.resolve-channel.outputs.channel == 'alpha' && needs.alpha.result == 'success') || (needs.resolve-channel.outputs.channel == 'stable' && needs.stable.result == 'success')) && '' || 'nested-build-incomplete' }}
+            [{"id":"resolve-channel","status":"\${{ needs.resolve-channel.result }}"},{"id":"override","status":"\${{ needs.override.result }}"},{"id":"alpha","status":"\${{ needs.alpha.result }}"},{"id":"stable","status":"\${{ needs.stable.result }}"},{"id":"aggregate","status":"\${{ needs.resolve-channel.outputs.runtime-override == 'true' && needs.override.result || needs.resolve-channel.outputs.channel == 'alpha' && needs.alpha.result || needs.stable.result }}"}]
+          BUILDCHAIN_CONTROLLER_EVIDENCE_JSON: \${{ (needs.override.outputs.controller-receipt-digest != '' || needs.alpha.outputs.controller-receipt-digest != '' || needs.stable.outputs.controller-receipt-digest != '') && format('[{{"kind":"nested-controller-receipt","digest":"{0}"}}]', needs.override.outputs.controller-receipt-digest || needs.alpha.outputs.controller-receipt-digest || needs.stable.outputs.controller-receipt-digest) || '[]' }}
+          BUILDCHAIN_CONTROLLER_REASON_CODE: \${{ ((needs.resolve-channel.outputs.runtime-override == 'true' && needs.override.result == 'success') || (needs.resolve-channel.outputs.runtime-override != 'true' && needs.resolve-channel.outputs.channel == 'alpha' && needs.alpha.result == 'success') || (needs.resolve-channel.outputs.runtime-override != 'true' && needs.resolve-channel.outputs.channel == 'stable' && needs.stable.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
@@ -221,6 +224,7 @@ function routerAggregateJob() {
     name: Summarize build contract
     needs:
       - resolve-channel
+      - override
       - alpha
       - stable
       - controller-receipt
@@ -231,13 +235,19 @@ function routerAggregateJob() {
         shell: bash
         env:
           CHANNEL: \${{ needs.resolve-channel.outputs.channel }}
+          RUNTIME_OVERRIDE: \${{ needs.resolve-channel.outputs.runtime-override }}
+          OVERRIDE_RESULT: \${{ needs.override.result }}
           ALPHA_RESULT: \${{ needs.alpha.result }}
           STABLE_RESULT: \${{ needs.stable.result }}
           CONTROLLER_RECEIPT_RESULT: \${{ needs.controller-receipt.result }}
         run: |
           set -euo pipefail
           selected_result="\${STABLE_RESULT}"
-          if [[ "\${CHANNEL}" = "alpha" ]]; then selected_result="\${ALPHA_RESULT}"; fi
+          if [[ "\${RUNTIME_OVERRIDE}" = "true" ]]; then
+            selected_result="\${OVERRIDE_RESULT}"
+          elif [[ "\${CHANNEL}" = "alpha" ]]; then
+            selected_result="\${ALPHA_RESULT}"
+          fi
           if [[ "\${selected_result}" != "success" || "\${CONTROLLER_RECEIPT_RESULT}" != "success" ]]; then
             echo "::error::Buildchain channel router did not qualify: channel=\${CHANNEL} selected=\${selected_result} controller-receipt=\${CONTROLLER_RECEIPT_RESULT}"
             exit 1
@@ -262,13 +272,29 @@ function splitBuildJobsByChannel(workflow, names, major) {
   if (index < 0) throw new Error("generated workflow is missing the build job");
   const inputs = forwardedInputs(names);
   const jobs = `
+  override:
+    name: Build trusted runtime override
+    needs:
+      - resolve-channel
+      - controller-plan
+    if: \${{ needs.resolve-channel.outputs.runtime-override == 'true' }}
+    uses: ./.github/workflows/.build.yml
+    permissions:
+      actions: read
+      contents: read
+      issues: write
+      id-token: write
+    with:
+${inputs}
+    secrets: inherit
+
   alpha:
     name: Build alpha channel
     needs:
       - resolve-channel
       - controller-plan
-    if: \${{ needs.resolve-channel.outputs.channel == 'alpha' }}
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v${major}-alpha
+    if: \${{ needs.resolve-channel.outputs.runtime-override != 'true' && needs.resolve-channel.outputs.channel == 'alpha' }}
+    uses: ./.github/workflows/.build.yml
     permissions:
       actions: read
       contents: read
@@ -283,8 +309,8 @@ ${inputs}
     needs:
       - resolve-channel
       - controller-plan
-    if: \${{ needs.resolve-channel.outputs.channel == 'stable' }}
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v${major}
+    if: \${{ needs.resolve-channel.outputs.runtime-override != 'true' && needs.resolve-channel.outputs.channel == 'stable' }}
+    uses: ./.github/workflows/.build.yml
     permissions:
       actions: read
       contents: read
@@ -355,6 +381,10 @@ export function generateChannelBuildWorkflow(source) {
     splitBuildJobsByChannel(generateChannelBuildWorkflowBase(source), names, major),
   )
     .replaceAll("runs-on: ubuntu-24.04", "runs-on: ${{ fromJSON(inputs.control-runner-json) }}")
+    .replace(
+      "      buildchain-ref: ${{ steps.channel.outputs.buildchain-ref }}\n",
+      "      buildchain-ref: ${{ steps.channel.outputs.buildchain-ref }}\n      major: ${{ steps.channel.outputs.major }}\n      runtime-override: ${{ steps.channel.outputs.runtime-override }}\n",
+    )
     .replace(
       "\npermissions:\n  contents: read\n",
       "\npermissions:\n  actions: read\n  contents: read\n",

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

@@ -21,6 +21,8 @@ const internalInputs = new Set([
   "promotion-target-ref",
   "promotion-override-used",
   "publication-authority-workflow-path",
+  "buildchain-expected-channel",
+  "buildchain-expected-major",
 ]);
 
 function blockBetween(source, start, end) {
@@ -91,7 +93,7 @@ function publicOutputs(outputBlock) {
   return [...routed, ...forwarded].join("\n");
 }
 
-function forwardedInputs(inputNames, { includeInternal = true, unsupportedInputs = [] } = {}) {
+function forwardedInputs(inputNames, { includeInternal = true, major = 2, unsupportedInputs = [], workflowPath = ".github/workflows/.release-candidate-promote.yml" } = {}) {
   const unsupported = new Set(unsupportedInputs);
   return inputNames
     .filter((name) => includeInternal || !internalInputs.has(name))
@@ -100,6 +102,7 @@ function forwardedInputs(inputNames, { includeInternal = true, unsupportedInputs
       const routed = {
         "buildchain-ref": "runtime-sha",
         "buildchain-contract-lock-path": "contract-lock-path",
+        "buildchain-expected-channel": "channel",
         channel: "publication-channel",
         "target-ref": "target-ref",
         "promotion-router-ref": "router-ref",
@@ -117,8 +120,11 @@ function forwardedInputs(inputNames, { includeInternal = true, unsupportedInputs
       if (name === "promotion-override-used") {
         return `      ${name}: \${{ needs.resolve-promotion.outputs.override-used == 'true' }}`;
       }
+      if (name === "buildchain-expected-major") {
+        return `      buildchain-expected-major: "${major}"`;
+      }
       if (name === "publication-authority-workflow-path") {
-        return "      publication-authority-workflow-path: .github/workflows/.release-candidate-promote.yml";
+        return `      publication-authority-workflow-path: ${workflowPath}`;
       }
       return routed
         ? `      ${name}: \${{ needs.resolve-promotion.outputs.${routed} }}`
@@ -189,11 +195,13 @@ export function generateChannelPromotionWorkflow(source, { major = 2, shellRouti
   }
   const alphaForwarded = forwardedInputs(inputNames, {
     includeInternal: alphaRoute.forwardInternalInputs,
-    unsupportedInputs: alphaRoute.unsupportedInputs,
+    major,
+    unsupportedInputs: alphaRoute.unsupportedInputs, workflowPath: alphaRoute.workflowPath,
   });
   const stableForwarded = forwardedInputs(inputNames, {
     includeInternal: stableRoute.forwardInternalInputs,
-    unsupportedInputs: stableRoute.unsupportedInputs,
+    major,
+    unsupportedInputs: stableRoute.unsupportedInputs, workflowPath: stableRoute.workflowPath,
   });
   return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
 name: Release Candidate Promote
@@ -259,8 +267,9 @@ jobs:
             exit 1
           fi
 
-          if [[ "\${ref}" =~ ^[0-9A-Fa-f]{40}$ ]]; then sha="\${ref,,}"; else
-            remote_url="https://github.com/\${repository}.git"; refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
+          if [[ "\${ref}" =~ ^[0-9a-fA-F]{40}$ ]]; then sha="\${ref,,}"; else
+            remote_url="https://github.com/\${repository}.git"
+            refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
             head_sha="$(printf '%s\\n' "\${refs}" | awk -v name="refs/heads/\${ref}" '$2 == name { print tolower($1) }')"
             tag_sha="$(printf '%s\\n' "\${refs}" | awk -v peeled="refs/tags/\${ref}^{}" -v name="refs/tags/\${ref}" '$2 == peeled { print tolower($1); found=1 } $2 == name && !found { fallback=tolower($1) } END { if (!found && fallback != "") print fallback }')"
             if [[ -n "\${head_sha}" && -n "\${tag_sha}" && "\${head_sha}" != "\${tag_sha}" ]]; then echo "::error::Promotion router ref is ambiguous between branch and tag"; exit 1; fi

package/scripts/generate-site-bundle.mjs

@@ -364,14 +364,13 @@ const manualMetaById = new Map(Object.entries({
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
   "release-tail-contract": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "draft", order: 122 },
   "release-tail-provider-plane": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "preview", order: 123 },
-  "publication-rehearsal": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "preview", order: 124 },
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "release-train": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 132 },
-  "next-development-transition": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 133 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
+  "v4-canonical-contracts": { capabilityGroup: "governance-versioning", audience: ["developer", "maintainer", "agent"], maturity: "preview", order: 138 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
@@ -412,6 +411,10 @@ function pageCapabilityMeta(relPath, category) {
   if (manual) {
     return manualMeta(manual.id);
   }
+  const docMeta = category === "manual" ? manualMetaById.get(path.basename(relPath, ".md")) : null;
+  if (docMeta) {
+    return docMeta;
+  }
   if (category === "action") {
     return { capabilityGroup: capabilityGroup("api-cli-reference"), audience: ["developer", "agent"], maturity: "stable" };
   }
@@ -734,7 +737,6 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-train.md",
-      "docs/next-development-transition.md",
       "docs/stable-candidate-patrol.md",
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
@@ -927,11 +929,8 @@ function buildSiteBundle() {
       "buildchain.release.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
-      "schemas/publication-rehearsal-capsule-v1.schema.json",
-      "schemas/release-tail-capabilities-v1.schema.json",
-      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
-      "schemas/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
       "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
@@ -964,11 +963,8 @@ function buildSiteBundle() {
       "artifact-schemas.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
-      "schemas/publication-rehearsal-capsule-v1.schema.json",
-      "schemas/release-tail-capabilities-v1.schema.json",
-      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
-      "schemas/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1097,11 +1093,8 @@ function buildSiteBundle() {
       "artifact-schemas.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
-      "schemas/publication-rehearsal-capsule-v1.schema.json",
-      "schemas/release-tail-capabilities-v1.schema.json",
-      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
-      "schemas/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/kfd-product-gate-input-v1.schema.json",
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1274,20 +1267,8 @@ function buildSiteBundle() {
     "artifact-schemas.json": artifactSchemas,
     "release-passport-check-manifest.json": createReleasePassportCheckManifest(),
     "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
-    "schemas/publication-rehearsal-capsule-v1.schema.json": readJson(
-      "contracts/publication-rehearsal-capsule-v1.schema.json",
-    ),
-    "schemas/release-tail-capabilities-v1.schema.json": readJson(
-      "contracts/release-tail-capabilities-v1.schema.json",
-    ),
-    "schemas/release-tail-provider-bindings-v1.schema.json": readJson(
-      "contracts/release-tail-provider-bindings-v1.schema.json",
-    ),
     "schemas/kfd-agent-hub-adoption.schema.json": KFD_AGENT_HUB_ADOPTION_SCHEMA,
     "schemas/kfd-product-gate-input-v1.schema.json": KFD_PRODUCT_GATE_INPUT_SCHEMA,
-    "schemas/dev-delivery-authority-v2.schema.json": readJson(
-      "contracts/dev-delivery-authority-v2.schema.json",
-    ),
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),

package/scripts/git-fetch-process-tree.mjs

@@ -1,12 +1,43 @@
 #!/usr/bin/env node
 import { execFileSync, spawn } from "node:child_process";
 import fs from "node:fs";
+import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const INTERNAL_COMMAND = "--buildchain-internal-git-fetch";
+const CMD_META_CHARACTERS = /([()\][%!^`"<>&|;, *?])/g;
 const TIMEOUT_EXIT_CODE = 124;
 const scriptPath = fileURLToPath(import.meta.url);
 
+function cmdEscapeCommand(value) {
+  return String(value).replace(CMD_META_CHARACTERS, "^$1");
+}
+
+function cmdEscapeArgument(value) {
+  let text = String(value);
+  text = text.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"');
+  text = text.replace(/(?=(\\+?)?)\1$/g, "$1$1");
+  return `"${text}"`.replace(CMD_META_CHARACTERS, "^$1");
+}
+
+function resolveGitInvocation(args, env = process.env) {
+  if (process.platform !== "win32") return { command: "git", args };
+  const gitShim = String(env.PATH || "")
+    .split(path.delimiter)
+    .map((directory) => path.join(directory, "git.cmd"))
+    .find((candidate) => fs.existsSync(candidate));
+  if (!gitShim) return { command: "git", args };
+  const shellCommand = [
+    cmdEscapeCommand(gitShim),
+    ...args.map(cmdEscapeArgument),
+  ].join(" ");
+  return {
+    command: env.ComSpec || env.comspec || process.env.ComSpec || process.env.comspec || "cmd.exe",
+    args: ["/d", "/s", "/c", `"${shellCommand}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
 async function terminateProcessTree(child, graceMs) {
   if (!child?.pid) return;
   if (process.platform === "win32") {
@@ -63,12 +94,14 @@ async function runInternalGitFetch() {
     50,
     Number(process.env.BUILDCHAIN_GIT_TIMEOUT_GRACE_MS || 2000),
   );
-  const child = spawn("git", payload.args, {
+  const invocation = resolveGitInvocation(payload.args);
+  const child = spawn(invocation.command, invocation.args, {
     cwd: payload.cwd,
     env: process.env,
     detached: process.platform !== "win32",
     stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true,
+    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
   });
   const stdout = [];
   const stderr = [];