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

package/scripts/dev-pr-delivery-warrant.mjs

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { defaultDevDeliveryStateRef, GitHubDevDeliveryStore } from "./dev-delivery-warrant.mjs";
 
 const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
 const SHA_PATTERN = /^[0-9a-f]{40}$/;
@@ -34,6 +35,11 @@ function exactActiveReadback(result) {
   const warrant = result.observation.activeWarrant;
   const candidate = result.observation.activeCandidate;
   requireMatch(warrant?.schema === "kungfu.buildchain.dev-delivery-warrant/v1", "delivery-warrant-missing");
+  requireMatch((warrant.phase || "qualified") === "qualified", "delivery-warrant-not-qualified");
+  if (warrant.phase === "qualified") {
+    requireMatch(ROOT_PATTERN.test(String(warrant.nativeProofRoot || "")), "delivery-warrant-native-proof-missing");
+    requireMatch(ROOT_PATTERN.test(String(warrant.nativeProofReuseRoot || "")), "delivery-warrant-native-reuse-missing");
+  }
   requireMatch(candidate?.candidateId === warrant.candidateId, "delivery-warrant-candidate-readback-missing");
   requireMatch(!result.warrant || JSON.stringify(result.warrant) === JSON.stringify(warrant), "delivery-warrant-readback-mismatch");
   return { warrant, candidate };
@@ -117,19 +123,18 @@ export function readDeliveryWarrantResult(options, pullRequest) {
 }
 
 export async function readCurrentDeliveryQueueState(client, repository, targetBranch) {
-  if (typeof client.getDevDeliveryQueueState === "function") {
-    return client.getDevDeliveryQueueState(targetBranch);
-  }
-  const stateRef = `buildchain/dev-delivery-warrant/${targetBranch.replaceAll("/", "-")}`;
-  const query = new URLSearchParams({ ref: stateRef });
-  const { data } = await client.request(
-    "GET",
-    `/repos/${repository.owner}/${repository.repo}/contents/queue.json?${query}`,
-  );
-  if (data?.type !== "file" || data?.encoding !== "base64" || !data?.content) {
-    mismatch("delivery-warrant-current-readback-invalid");
-  }
-  return JSON.parse(Buffer.from(String(data.content).replace(/\s+/g, ""), "base64").toString("utf8"));
+  if (typeof client.getDevDeliveryQueueState === "function") return client.getDevDeliveryQueueState(targetBranch);
+  const store = new GitHubDevDeliveryStore({
+    repository: `${repository.owner}/${repository.repo}`,
+    token: client.token,
+    apiUrl: client.apiUrl,
+    fetchImpl: client.fetch,
+  });
+  const { queue } = await store.read({
+    stateRef: defaultDevDeliveryStateRef(targetBranch),
+    protectedBase: targetBranch,
+  });
+  return queue;
 }
 
 export async function verifyCurrentDeliveryWarrant(client, options, pullRequest, warrant) {
@@ -147,7 +152,7 @@ export async function verifyCurrentDeliveryWarrant(client, options, pullRequest,
   requireMatch(Number(active?.generation) === Number(warrant.generation), "delivery-warrant-current-generation-mismatch");
   requireMatch(Number(active?.pullRequestNumber) === Number(pullRequest.number), "delivery-warrant-current-pr-mismatch");
   requireMatch(String(active?.sourceHead || "").toLowerCase() === options.expectedHeadSha, "delivery-warrant-current-head-mismatch");
-  requireMatch(["selected", "proving", "waiting", "blocked"].includes(candidate?.status), "delivery-warrant-current-candidate-not-selected");
+  requireMatch(["selected", "proving", "waiting", "blocked", "qualified"].includes(candidate?.status), "delivery-warrant-current-candidate-not-selected");
   requireMatch(candidate?.sourceHead === active.sourceHead, "delivery-warrant-current-candidate-head-mismatch");
 }
 

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

@@ -1,121 +1,115 @@
 #!/usr/bin/env node
+import crypto from "node:crypto";
 import fs from "node:fs";
-import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
 import { pathToFileURL } from "node:url";
-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 { 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 { 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 writeJson(filePath, value) {
+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);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  return { path: relativePath, sha256: fileDigest(filePath), filePath };
 }
-
-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);
+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);
   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(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 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 kfd2ClaimPaths = createBuildchainKfd2Claims({ root, witnessFiles }).map((claim) => {
-    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 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 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 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."];
   }
-  return {
-    schemaVersion: 1,
-    contract: "kungfu-buildchain-self-kfd-witness-generation",
-    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 };
 }
-
 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");
-      process.exit(0);
-    }
-    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");
+    else 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,30 @@ function routerInputs(inputBlock) {
 
 function routerOutputs(outputBlock) {
   const forwarded = outputBlock
-    .replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.build.outputs.$1 }}")
+    .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 }}")
     .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 }}")
+    .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(
-      /(      credential-island-macos-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.build\.outputs\.artifact-name \}\}/,
-      "$1 ${{ jobs.build.outputs.credential-island-macos-artifact }}",
+      /(      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 }}",
     )
     .replace(
-      /(      credential-island-macos-manifest-artifact:\n(?:        .*\n)*?        value:) \$\{\{ jobs\.build\.outputs\.manifest-artifact-name \}\}/,
-      "$1 ${{ jobs.build.outputs.credential-island-macos-manifest-artifact }}",
+      /(      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 }}",
     );
   return [
     "      buildchain-channel:",
-    '        description: "Resolved Buildchain channel: alpha, stable, or override"',
+    '        description: "Resolved Buildchain channel: alpha or stable"',
     "        value: ${{ jobs.resolve-channel.outputs.channel }}",
     "      buildchain-channel-selection-source:",
     '        description: "Evidence source used to select the Buildchain channel"',
@@ -154,7 +158,8 @@ function routerControllerReceiptJob() {
     needs:
       - resolve-channel
       - controller-plan
-      - build
+      - alpha
+      - stable
     if: \${{ always() && needs.controller-plan.result == 'success' }}
     runs-on: \${{ fromJSON(inputs.control-runner-json) }}
     outputs:
@@ -183,9 +188,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":"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' }}
+            [{"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' }}
           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
@@ -215,7 +220,9 @@ function routerAggregateJob() {
   return `  summarize:
     name: Summarize build contract
     needs:
-      - build
+      - resolve-channel
+      - alpha
+      - stable
       - controller-receipt
     if: \${{ always() }}
     runs-on: \${{ fromJSON(inputs.control-runner-json) }}
@@ -223,12 +230,16 @@ function routerAggregateJob() {
       - name: Enforce public channel router aggregate
         shell: bash
         env:
-          BUILD_RESULT: \${{ needs.build.result }}
+          CHANNEL: \${{ needs.resolve-channel.outputs.channel }}
+          ALPHA_RESULT: \${{ needs.alpha.result }}
+          STABLE_RESULT: \${{ needs.stable.result }}
           CONTROLLER_RECEIPT_RESULT: \${{ needs.controller-receipt.result }}
         run: |
           set -euo pipefail
-          if [[ "\${BUILD_RESULT}" != "success" || "\${CONTROLLER_RECEIPT_RESULT}" != "success" ]]; then
-            echo "::error::Buildchain channel router did not qualify: build=\${BUILD_RESULT} controller-receipt=\${CONTROLLER_RECEIPT_RESULT}"
+          selected_result="\${STABLE_RESULT}"
+          if [[ "\${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
           fi
           echo "Buildchain channel router aggregate passed."`;
@@ -245,6 +256,47 @@ function generateChannelBuildWorkflowBase(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`;
 }
 
+function splitBuildJobsByChannel(workflow, names, major) {
+  const marker = "\n  build:\n";
+  const index = workflow.indexOf(marker);
+  if (index < 0) throw new Error("generated workflow is missing the build job");
+  const inputs = forwardedInputs(names);
+  const jobs = `
+  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
+    permissions:
+      actions: read
+      contents: read
+      issues: write
+      id-token: write
+    with:
+${inputs}
+    secrets: inherit
+
+  stable:
+    name: Build stable channel
+    needs:
+      - resolve-channel
+      - controller-plan
+    if: \${{ needs.resolve-channel.outputs.channel == 'stable' }}
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v${major}
+    permissions:
+      actions: read
+      contents: read
+      issues: write
+      id-token: write
+    with:
+${inputs}
+    secrets: inherit
+`;
+  return `${workflow.slice(0, index)}${jobs}`;
+}
+
 function bindRouterCheckoutToWorkflowSha(workflow) {
   return workflow
     .replace(
@@ -294,7 +346,14 @@ function bindRouterCheckoutToWorkflowSha(workflow) {
 }
 
 export function generateChannelBuildWorkflow(source) {
-  const generated = bindRouterCheckoutToWorkflowSha(generateChannelBuildWorkflowBase(source))
+  const inputBlock = blockBetween(source, "    inputs:\n", "    secrets:\n");
+  const names = inputNames(inputBlock);
+  const packageVersion = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version || "";
+  const major = Number(String(packageVersion).split(".")[0]);
+  if (!Number.isInteger(major) || major < 1) throw new Error("package.json version must declare a positive major");
+  const generated = bindRouterCheckoutToWorkflowSha(
+    splitBuildJobsByChannel(generateChannelBuildWorkflowBase(source), names, major),
+  )
     .replaceAll("runs-on: ubuntu-24.04", "runs-on: ${{ fromJSON(inputs.control-runner-json) }}")
     .replace(
       "\npermissions:\n  contents: read\n",
@@ -310,15 +369,7 @@ export function generateChannelBuildWorkflow(source) {
         "",
       ].join("\n"),
     )
-    .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",
-    )
-    .replace(
-      "    uses: ./.github/workflows/.build.yml\n    permissions:\n      contents: read\n",
-      "    uses: ./.github/workflows/.build.yml\n    permissions:\n      actions: read\n      contents: read\n",
-    );
+    .replace("\n  alpha:\n", `\n${routerControllerPlanJob()}\n\n  alpha:\n`);
   return `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n\n${routerAggregateJob()}\n`;
 }
 

package/scripts/generate-next-development-guidance.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { nextDevelopmentManual } from "../packages/core/next-development-projection.js";
+
+export const NEXT_DEVELOPMENT_MANUAL_PATH =
+  "docs/next-development-transition.md";
+
+export function generateNextDevelopmentGuidance({
+  cwd = process.cwd(),
+  check = false,
+} = {}) {
+  const target = path.resolve(cwd, NEXT_DEVELOPMENT_MANUAL_PATH);
+  const expected = nextDevelopmentManual();
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (check) {
+    if (current !== expected) {
+      throw new Error(
+        `${NEXT_DEVELOPMENT_MANUAL_PATH} drifted from its contract source`,
+      );
+    }
+    return { ok: true, changed: false, path: NEXT_DEVELOPMENT_MANUAL_PATH };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (current !== expected) fs.writeFileSync(target, expected);
+  return {
+    ok: true,
+    changed: current !== expected,
+    path: NEXT_DEVELOPMENT_MANUAL_PATH,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = generateNextDevelopmentGuidance({
+      check: process.argv.includes("--check"),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`next-development guidance: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-site-bundle.mjs

@@ -368,6 +368,7 @@ const manualMetaById = new Map(Object.entries({
   "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 },
@@ -733,6 +734,7 @@ 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",
@@ -929,7 +931,7 @@ function buildSiteBundle() {
       "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/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
       "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
@@ -966,7 +968,7 @@ function buildSiteBundle() {
       "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/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1099,7 +1101,7 @@ function buildSiteBundle() {
       "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/kfd-product-gate-input-v1.schema.json", "schemas/dev-delivery-authority-v2.schema.json",
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1283,6 +1285,9 @@ function buildSiteBundle() {
     ),
     "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 }),