@kungfu-tech/buildchain 2.8.2-alpha.0 → 2.8.2-alpha.2

package/packages/core/release-passport.js

@@ -21,6 +21,7 @@ export const AGENT_INDEX_CONTRACT = "kungfu-buildchain-agent-index";
 export const PRODUCT_MECHANISM_CONTRACT = "kungfu-buildchain-product-mechanism";
 export const RELEASE_CHECK_REPORT_CONTRACT = "kungfu-buildchain-release-check-report";
 export const KFD2_RELEASE_TRUST_PASSPORT_CONTRACT = "kungfu-buildchain-kfd-2-release-trust-passport-audit";
+export const KFD2_TRUST_PROOF_CONTRACT = "kungfu-buildchain-kfd-2-trust-proof";
 
 const CONTRACTS = new Set([
   RELEASE_PASSPORT_CONTRACT,
@@ -571,6 +572,9 @@ function normalizeKfd2Claim(raw = {}, index = 0) {
       : {};
   const responsibility = claim.responsibility && typeof claim.responsibility === "object" && !Array.isArray(claim.responsibility) ? claim.responsibility : {};
   const residualRisk = arrayOrEmpty(claim.residualRisk || claim.residual_risk);
+  const trustProof = claim.trustProof && typeof claim.trustProof === "object" && !Array.isArray(claim.trustProof)
+    ? claim.trustProof
+    : undefined;
   const missingBindings = [];
   if (sourceBindings.length === 0) missingBindings.push("declared-sources");
   if (machineEvidence.length === 0) missingBindings.push("machine-readable-evidence");
@@ -597,6 +601,7 @@ function normalizeKfd2Claim(raw = {}, index = 0) {
     auditBoundary,
     responsibility,
     residualRisk,
+    ...(trustProof ? { trustProof } : {}),
     proseOnly,
     missingBindings,
     status,
@@ -642,6 +647,17 @@ function kfd2ClaimFromKfd1World(world = {}, index = 0) {
 }
 
 function kfd2ClaimFromKfd3Interface(entry = {}, index = 0) {
+  const witnessHashes = {
+    prebuildWitnessSha256: entry.preBuildWitnessSha256,
+    artifactWitnessSha256: entry.artifactWitnessSha256,
+    prebuildCanonicalSha256: entry.witnessEvidence?.prebuild?.canonicalSha256 || "",
+    artifactCanonicalSha256: entry.witnessEvidence?.artifact?.canonicalSha256 || "",
+  };
+  const reverseAuditBoundary = entry.reverseAudit?.auditBoundary || entry.auditBoundary;
+  const residualRisk = arrayOrEmpty(entry.residualRisk);
+  const proofResult = entry.trustProof?.result === "pass"
+    ? (residualRisk.length > 0 ? "downgraded" : "passed")
+    : "failed";
   return normalizeKfd2Claim({
     id: `kfd-3:${entry.id || index + 1}`,
     public: true,
@@ -658,10 +674,7 @@ function kfd2ClaimFromKfd3Interface(entry = {}, index = 0) {
       { id: "reverse-audit", result: entry.reverseAudit?.status || "" },
     ],
     hashes: {
-      prebuildWitnessSha256: entry.preBuildWitnessSha256,
-      artifactWitnessSha256: entry.artifactWitnessSha256,
-      prebuildCanonicalSha256: entry.witnessEvidence?.prebuild?.canonicalSha256 || "",
-      artifactCanonicalSha256: entry.witnessEvidence?.artifact?.canonicalSha256 || "",
+      ...witnessHashes,
     },
     artifacts: entry.artifactWitness?.artifact?.name || entry.artifactWitness?.artifact?.path
       ? [entry.artifactWitness.artifact]
@@ -673,10 +686,25 @@ function kfd2ClaimFromKfd3Interface(entry = {}, index = 0) {
     },
     auditBoundary: entry.auditBoundary,
     responsibility: entry.responsibility,
-    residualRisk: entry.residualRisk,
-    status: entry.trustProof?.result === "pass"
-      ? (arrayOrEmpty(entry.residualRisk).length > 0 ? "downgraded" : "passed")
-      : "failed",
+    residualRisk,
+    trustProof: {
+      contract: KFD2_TRUST_PROOF_CONTRACT,
+      source: "kfd-3-collaboration-interface-release-gate",
+      result: proofResult,
+      statement: entry.trustProof?.statement || "",
+      kfd3TrustProof: {
+        contract: entry.trustProof?.contract || "",
+        result: entry.trustProof?.result || "",
+        releaseStatus: entry.trustProof?.releaseStatus || entry.releaseStatus || "",
+      },
+      witnessHashes,
+      declaredCapabilityVerification: entry.declaredCapabilityVerification,
+      reverseAudit: entry.reverseAudit,
+      reverseAuditBoundary,
+      residualRisk,
+      responsibility: entry.responsibility,
+    },
+    status: proofResult,
   }, index);
 }
 
@@ -1220,6 +1248,48 @@ function validateKfd2ReleaseTrustPassportAudit(section, issues) {
         proseOnly: Boolean(claim.proseOnly),
       }));
     }
+    if (String(claim.id || "").startsWith("kfd-3:")) {
+      const trustProof = claim.trustProof && typeof claim.trustProof === "object" && !Array.isArray(claim.trustProof)
+        ? claim.trustProof
+        : undefined;
+      if (!trustProof || trustProof.contract !== KFD2_TRUST_PROOF_CONTRACT) {
+        issues.push(issue("error", `kfd-2.claims[${index}].trustProof`, "KFD-3 generated public claims must include a KFD-2 trust proof", {
+          id: claim.id || "",
+          expectedContract: KFD2_TRUST_PROOF_CONTRACT,
+        }));
+      } else {
+        if (!trustProof.witnessHashes?.prebuildWitnessSha256 || !trustProof.witnessHashes?.artifactWitnessSha256) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.witnessHashes`, "KFD-2 trust proof must preserve KFD-3 witness hashes", {
+            id: claim.id || "",
+          }));
+        }
+        if (!trustProof.declaredCapabilityVerification?.result) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.declaredCapabilityVerification`, "KFD-2 trust proof must preserve declared capability verification", {
+            id: claim.id || "",
+          }));
+        }
+        if (!trustProof.reverseAudit?.status) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.reverseAudit`, "KFD-2 trust proof must preserve reverse audit result", {
+            id: claim.id || "",
+          }));
+        }
+        if (!trustProof.reverseAuditBoundary || typeof trustProof.reverseAuditBoundary !== "object" || Array.isArray(trustProof.reverseAuditBoundary)) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.reverseAuditBoundary`, "KFD-2 trust proof must preserve the reverse audit boundary", {
+            id: claim.id || "",
+          }));
+        }
+        if (!Array.isArray(trustProof.residualRisk)) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.residualRisk`, "KFD-2 trust proof must preserve residual risk as an array", {
+            id: claim.id || "",
+          }));
+        }
+        if (!trustProof.responsibility?.registryFactsOwner || !trustProof.responsibility?.artifactVerificationOwner || !trustProof.responsibility?.releasePassportProofOwner) {
+          issues.push(issue("error", `kfd-2.claims[${index}].trustProof.responsibility`, "KFD-2 trust proof must preserve KFD-3 responsibility state", {
+            id: claim.id || "",
+          }));
+        }
+      }
+    }
   }
   if (section.status === "failed") {
     issues.push(issue("error", "kfd-2.status", "kfd-2 release trust passport audit must not contain failed public claims"));

package/scripts/check-inventory.mjs

@@ -30,6 +30,7 @@ const requiredPaths = [
   "scripts/create-release-bundle.mjs",
   "scripts/ensure-github-release.mjs",
   "scripts/generate-site-bundle.mjs",
+  "scripts/generate-buildchain-kfd-witnesses.mjs",
   "scripts/generate-release-candidate-passport.mjs",
   "scripts/artifact-relay-s3.mjs",
   "scripts/npm-publish-dry-run.mjs",
@@ -105,6 +106,18 @@ if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-pas
 if (rootPackage.exports?.["./release-propagation"] !== "./packages/core/release-propagation.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-propagation");
 }
+if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildchain-kfd-claims.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/buildchain-kfd-claims");
+}
+if (rootPackage.exports?.["./site/manual-registry.json"] !== "./dist/site/manual-registry.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/manual-registry.json");
+}
+if (rootPackage.exports?.["./site/node-api-registry.json"] !== "./dist/site/node-api-registry.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/node-api-registry.json");
+}
+if (rootPackage.exports?.["./site/kfd-claims.json"] !== "./dist/site/kfd-claims.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/kfd-claims.json");
+}
 if (rootPackage.publishConfig?.access !== "public") {
   throw new Error("root package publishConfig.access must be public");
 }
@@ -128,6 +141,7 @@ const cliSource = fs.readFileSync(path.join(root, "bin/buildchain.mjs"), "utf8")
 const coreIndexSource = fs.readFileSync(path.join(root, "packages/core/index.js"), "utf8");
 const versioningDoc = fs.readFileSync(path.join(root, "docs/versioning.md"), "utf8");
 const cliDoc = fs.readFileSync(path.join(root, "docs/cli.md"), "utf8");
+const docsMap = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
 const installDoc = fs.readFileSync(path.join(root, "docs/install.md"), "utf8");
 if (!cliSource.startsWith("#!/usr/bin/env node")) {
   throw new Error("bin/buildchain.mjs must be executable with a node shebang");
@@ -150,6 +164,20 @@ if (!coreIndexSource.includes("createBuildchainContractWorld")) {
 if (!coreIndexSource.includes("KFD2_RELEASE_TRUST_PASSPORT_CONTRACT")) {
   throw new Error("packages/core/index.js must export KFD-2 release trust passport contract");
 }
+if (!coreIndexSource.includes("KFD2_TRUST_PROOF_CONTRACT")) {
+  throw new Error("packages/core/index.js must export KFD-2 trust proof contract");
+}
+for (const requiredSnippet of [
+  "createBuildchainKfdClaimRegistry",
+  "createBuildchainKfd1Witness",
+  "createBuildchainKfd2Claims",
+  "createBuildchainKfd3PrebuildWitness",
+  "BUILDCHAIN_AGENT_MANUALS",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export Buildchain self KFD claim API: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "createKfd1ReleaseGateEvidence",
   "resolveKfd1Metadata",
@@ -204,6 +232,20 @@ for (const requiredSnippet of [
     throw new Error(`release passport doc missing KFD-1 gate snippet: ${requiredSnippet}`);
   }
 }
+for (const requiredSnippet of [
+  "Capability Coverage",
+  "KFD-1 / KFD-2 / KFD-3",
+  "floating `@v2`",
+  "npm publish transactions",
+  "GitHub Release",
+  "release propagation",
+  "manual-registry.json",
+  "node-api-registry.json",
+]) {
+  if (!docsMap.includes(requiredSnippet)) {
+    throw new Error(`documentation map missing capability coverage snippet: ${requiredSnippet}`);
+  }
+}
 const reusableBuildSurfaceDoc = fs.readFileSync(path.join(root, "docs/reusable-build-surface.md"), "utf8");
 for (const requiredSnippet of [
   "Floating Ref Contract Lock",
@@ -291,6 +333,7 @@ for (const requiredSnippet of [
   "github.event.workflow_run.event == 'push'",
   "target-sha: ${{ github.event.workflow_run.head_sha || inputs.sha || github.sha }}",
   "github-release: true",
+  "release-passport-buildchain-self-kfd: true",
   "publish-required-artifacts-json: \"[]\"",
   "release-passport-impact-json: >-",
   "Buildchain v2.8 promotes KFD self-verification",
@@ -308,17 +351,21 @@ for (const requiredSnippet of [
 const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/release-candidate-promote.yml"), "utf8");
 for (const requiredSnippet of [
   "release-passport-kfd-1-witness-jsons:",
-  "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",
+  "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons || steps.buildchain-self-kfd.outputs.kfd-1-witness-jsons }}",
   "release-passport-kfd-2-claim-jsons:",
-  "release-passport-kfd-2-claim-jsons: ${{ inputs.release-passport-kfd-2-claim-jsons }}",
+  "release-passport-kfd-2-claim-jsons: ${{ inputs.release-passport-kfd-2-claim-jsons || steps.buildchain-self-kfd.outputs.kfd-2-claim-jsons }}",
   "release-passport-kfd-3-prebuild-witness-jsons:",
-  "release-passport-kfd-3-prebuild-witness-jsons: ${{ inputs.release-passport-kfd-3-prebuild-witness-jsons }}",
+  "release-passport-kfd-3-prebuild-witness-jsons: ${{ inputs.release-passport-kfd-3-prebuild-witness-jsons || steps.buildchain-self-kfd.outputs.kfd-3-prebuild-witness-jsons }}",
   "release-passport-kfd-3-artifact-witness-jsons:",
+  "release-passport-kfd-3-artifact-witness-jsons: ${{ inputs.release-passport-kfd-3-artifact-witness-jsons || steps.buildchain-self-kfd.outputs.kfd-3-artifact-witness-jsons }}",
   "release-passport-kfd-3-artifact-verify-command:",
+  "release-passport-buildchain-self-kfd:",
+  "Generate Buildchain self KFD release claims",
+  "generate-buildchain-kfd-witnesses.mjs",
   "github-release:",
-  "Publish GitHub Release evidence",
-  "scripts/ensure-github-release.mjs",
-  "gh release upload \"${RELEASE_TAG}\" \"${upload_args[@]}\" --clobber",
+  "github-release: ${{ inputs.github-release }}",
+  "github-release-title: ${{ inputs.github-release-title }}",
+  "github-release-notes: ${{ inputs.github-release-notes }}",
   "require-publish-source-lock: \"true\"",
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
@@ -374,6 +421,31 @@ for (const retiredWorkflow of [
     }
   }
 }
+const promoteBuildchainRefAction = fs.readFileSync(path.join(root, "actions/promote-buildchain-ref/action.yml"), "utf8");
+const promoteBuildchainRefIndex = fs.readFileSync(path.join(root, "actions/promote-buildchain-ref/index.js"), "utf8");
+for (const requiredSnippet of [
+  "github-release:",
+  "github-release-title:",
+  "github-release-notes:",
+  "github-release-url:",
+  "github-release-action:",
+]) {
+  if (!promoteBuildchainRefAction.includes(requiredSnippet)) {
+    throw new Error(`promote-buildchain-ref action missing GitHub Release surface: ${requiredSnippet}`);
+  }
+}
+for (const requiredSnippet of [
+  "ensureGitHubRelease",
+  "publishGitHubReleaseEvidence",
+  "collectGitHubReleaseEvidenceAssets",
+  "uploadReleaseAsset",
+  "result.publishTransaction?.state === \"complete\"",
+  "result.publishTransaction?.finalizationNeeded !== true",
+]) {
+  if (!promoteBuildchainRefIndex.includes(requiredSnippet)) {
+    throw new Error(`promote-buildchain-ref index missing semver GitHub Release implementation: ${requiredSnippet}`);
+  }
+}
 for (const forbiddenSnippet of [
   "run: node scripts/release-candidate-resolver.mjs",
   "uses: ./actions/promote-buildchain-ref",
@@ -490,7 +562,7 @@ for (const artifact of [
   }
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "cli-registry.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "cli-registry.json", "manual-registry.json", "node-api-registry.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/ensure-github-release.mjs

@@ -168,7 +168,15 @@ async function main() {
   console.log(`github-release-make-latest=${result.metadata.makeLatest}`);
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+function isCliEntrypoint() {
+  const entry = process.argv[1] || "";
+  return (
+    entry.replace(/\\/g, "/").endsWith("/ensure-github-release.mjs") &&
+    import.meta.url === pathToFileURL(entry).href
+  );
+}
+
+if (isCliEntrypoint()) {
   main().catch((error) => {
     console.error(error.message);
     process.exit(1);

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import {
+  createBuildchainKfd1Witness,
+  createBuildchainKfd2Claims,
+  createBuildchainKfd3ArtifactWitness,
+  createBuildchainKfd3PrebuildWitness,
+} from "../packages/core/buildchain-kfd-claims.js";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function parseArgs(argv = process.argv.slice(2)) {
+  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}`);
+    }
+  }
+  return args;
+}
+
+function gitSha(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+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 paths = {
+    kfd1Witness: path.join(outDir, "buildchain-kfd-1-witness.json"),
+    kfd3PrebuildWitness: path.join(outDir, "buildchain-kfd-3-prebuild-witness.json"),
+    kfd3ArtifactWitness: path.join(outDir, "buildchain-kfd-3-artifact-witness.json"),
+    kfd2ClaimsDir: path.join(outDir, "kfd-2-claims"),
+  };
+  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";
+    const claimPath = path.join(paths.kfd2ClaimsDir, `${slug}.json`);
+    writeJson(claimPath, claim);
+    return claimPath;
+  });
+  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);
+  }
+  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");
+      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-site-bundle.mjs

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { pathToFileURL } from "node:url";
 import { createBuildchainContractWorld } from "../packages/core/buildchain-contract.js";
+import {
+  BUILDCHAIN_AGENT_MANUALS,
+  createBuildchainKfdClaimRegistry,
+} from "../packages/core/buildchain-kfd-claims.js";
 
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
 const root = path.resolve(import.meta.dirname, "..");
@@ -21,6 +26,13 @@ function stableJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function sha256File(rel) {
+  const filePath = path.join(root, rel);
+  return fs.existsSync(filePath) && fs.statSync(filePath).isFile()
+    ? `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`
+    : "";
+}
+
 function existingJson(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
 }
@@ -32,30 +44,14 @@ function docEntry(id, title, pathName, plane) {
     path: pathName,
     plane,
     exists: fs.existsSync(path.join(root, pathName)),
+    digest: sha256File(pathName),
   };
 }
 
 function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
-  const docs = [
-    docEntry("install", "Install and verify Buildchain", "docs/install.md", "use"),
-    docEntry("release-passport", "Release Passport protocol", "docs/release-passport.md", "verify"),
-    docEntry("release-propagation", "Release propagation", "docs/release-propagation.md", "use"),
-    docEntry("binary-distribution", "Binary distribution contract", "docs/binary-distribution.md", "verify"),
-    docEntry("toolkit-observability", "Toolkit observability", "docs/toolkit-observability.md", "use"),
-    docEntry("site-bundle-contract", "Site bundle contract", "docs/site-bundle-contract.md", "use"),
-    docEntry("product-mechanism", "Product mechanism", "docs/product-mechanism.md", "why"),
-    docEntry("cli", "CLI and npm package", "docs/cli.md", "use"),
-    docEntry("lifecycle-protocol", "Lifecycle protocol", "docs/lifecycle-protocol.md", "use"),
-    docEntry("reusable-build-surface", "Reusable build surface", "docs/reusable-build-surface.md", "use"),
-    docEntry("publish-transaction", "Publish transaction", "docs/publish-transaction.md", "verify"),
-    docEntry("release-governance", "Release governance", "docs/release-governance.md", "why"),
-    docEntry("release-flow", "Release flow", "docs/release-flow.md", "verify"),
-    docEntry("versioning", "Versioning", "docs/versioning.md", "why"),
-    docEntry("web-surface-deployments", "Web surface deployments", "docs/web-surface-deployments.md", "use"),
-    docEntry("infra-contract", "Infra Contract", "docs/infra-contract.md", "use"),
-  ];
+  const docs = BUILDCHAIN_AGENT_MANUALS.map((manual) => docEntry(manual.id, manual.title, manual.path, manual.plane));
 
   const cliRegistry = {
     schemaVersion: 1,
@@ -80,6 +76,52 @@ function buildSiteBundle() {
     ],
   };
 
+  const manualRegistry = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-agent-manual-registry",
+    package: packageJson.name,
+    source: "npm package docs/",
+    manuals: docs.map((entry) => ({
+      id: entry.id,
+      title: entry.title,
+      path: entry.path,
+      plane: entry.plane,
+      digest: entry.digest,
+    })),
+    requiredAgentManuals: [
+      "docs/MAP.md",
+      "docs/install.md",
+      "docs/cli.md",
+      "docs/reusable-build-surface.md",
+      "docs/release-candidate.md",
+      "docs/release-governance.md",
+      "docs/release-passport.md",
+      "docs/publish-transaction.md",
+      "docs/site-bundle-contract.md",
+    ],
+    guidance: "Agent consumers should use this registry to find packaged Buildchain manuals before inferring behavior from workflow snippets or release notes.",
+  };
+
+  const nodeApiRegistry = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-node-api-registry",
+    package: packageJson.name,
+    moduleSystem: packageJson.type || "module",
+    exports: Object.entries(packageJson.exports || {})
+      .filter(([specifier]) => !specifier.startsWith("./site/") && specifier !== "./package.json")
+      .map(([specifier, target]) => ({
+        specifier: specifier === "." ? packageJson.name : `${packageJson.name}/${specifier.replace(/^\.\//, "")}`,
+        export: specifier,
+        target,
+        digest: typeof target === "string" ? sha256File(target.replace(/^\.\//, "")) : "",
+      })),
+    docs: [
+      { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
+      { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },
+    ],
+    guidance: "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths.",
+  };
+
   const workflowRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-workflow-registry",
@@ -124,6 +166,17 @@ function buildSiteBundle() {
       alphaDistTag: "alpha",
       stableDistTag: "latest",
     },
+    githubRelease: {
+      exactTagRelease: true,
+      prereleaseTags: "semver prerelease tags set prerelease=true and make_latest=false",
+      stableTags: "stable semver tags set make_latest=true",
+      evidenceAssets: [
+        "publish evidence JSON",
+        "buildchain.release.json",
+        "release passport assets",
+      ],
+      owner: "promote-buildchain-ref",
+    },
   };
 
   const artifactSchemas = {
@@ -144,10 +197,13 @@ function buildSiteBundle() {
       "buildchain-site.json",
       "site-manifest.json",
       "cli-registry.json",
+      "manual-registry.json",
+      "node-api-registry.json",
       "workflow-registry.json",
       "release-model.json",
       "artifact-schemas.json",
       "buildchain-contract.json",
+      "kfd-claims.json",
       "product-mechanism.json",
       "release-provenance.json",
       "agent-index.json",
@@ -211,11 +267,14 @@ function buildSiteBundle() {
     docs,
     facts: [
       "cli-registry.json",
+      "manual-registry.json",
+      "node-api-registry.json",
       "workflow-registry.json",
       "release-model.json",
       "artifact-schemas.json",
       "product-mechanism.json",
       "release-provenance.json",
+      "kfd-claims.json",
       "agent-index.json",
     ],
   };
@@ -228,9 +287,12 @@ function buildSiteBundle() {
       "product-mechanism.json",
       "release-model.json",
       "cli-registry.json",
+      "manual-registry.json",
+      "node-api-registry.json",
       "workflow-registry.json",
       "artifact-schemas.json",
       "buildchain-contract.json",
+      "kfd-claims.json",
     ],
     instruction: "Use this bundle as the package-owned fact source for Buildchain pages. Do not infer current release mechanics from prose alone.",
   };
@@ -252,10 +314,13 @@ function buildSiteBundle() {
     "buildchain-site.json": siteBundle,
     "site-manifest.json": siteManifest,
     "cli-registry.json": cliRegistry,
+    "manual-registry.json": manualRegistry,
+    "node-api-registry.json": nodeApiRegistry,
     "workflow-registry.json": workflowRegistry,
     "release-model.json": releaseModel,
     "artifact-schemas.json": artifactSchemas,
     "buildchain-contract.json": createBuildchainContractWorld({ root }),
+    "kfd-claims.json": createBuildchainKfdClaimRegistry({ root }),
     "product-mechanism.json": productMechanism,
     "release-provenance.json": releaseProvenance,
     "agent-index.json": agentIndex,
@@ -263,7 +328,7 @@ function buildSiteBundle() {
 }
 
 export function writeSiteBundle({ check = false } = {}) {
-  const files = buildSiteBundle();
+  let files = buildSiteBundle();
   const mismatches = [];
   for (const [name, value] of Object.entries(files)) {
     const filePath = path.join(outputDir, name);
@@ -272,13 +337,32 @@ export function writeSiteBundle({ check = false } = {}) {
       if (existingJson(filePath) !== next) {
         mismatches.push(path.relative(root, filePath));
       }
-    } else {
-      writeJson(filePath, value);
     }
   }
   if (mismatches.length > 0) {
     throw new Error(`site bundle is stale: ${mismatches.join(", ")}`);
   }
+  if (!check) {
+    for (let iteration = 0; iteration < 5; iteration += 1) {
+      for (const [name, value] of Object.entries(files)) {
+        writeJson(path.join(outputDir, name), value);
+      }
+      const nextFiles = buildSiteBundle();
+      const stable = Object.entries(nextFiles).every(([name, value]) => (
+        existingJson(path.join(outputDir, name)) === stableJson(value)
+      ));
+      files = nextFiles;
+      if (stable) {
+        break;
+      }
+      if (iteration === 4) {
+        throw new Error("site bundle did not converge after 5 generations");
+      }
+    }
+    for (const [name, value] of Object.entries(files)) {
+      writeJson(path.join(outputDir, name), value);
+    }
+  }
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-site-bundle-generation",