@kungfu-tech/buildchain 2.8.17 → 2.9.0

package/packages/core/buildchain-config.js

@@ -42,6 +42,8 @@ const SUPPORTED_INFRA_ADOPTION_MODES = new Set([
   "managed-apply",
 ]);
 const SUPPORTED_INFRA_APPLY_MODES = new Set(["disabled", "manual-approval", "environment-approval"]);
+const SUPPORTED_FACT_VERSION_SOURCE_TYPES = new Set(["static", "json", "toml", "regex", "command"]);
+const SUPPORTED_FACT_LEGACY_PROJECTIONS = new Set(["kungfu-buildinfo"]);
 
 function posixPath(value) {
   return String(value || "").split(path.sep).join("/");
@@ -154,11 +156,123 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.diagnostics !== undefined) {
     normalized.diagnostics = normalizeDiagnosticsSection(normalized.diagnostics);
   }
+  if (normalized.facts !== undefined) {
+    normalized.facts = normalizeFactsSection(normalized.facts);
+  }
   validateWebSurfaceConfig(normalized);
   validateInfraContractConfig(normalized);
   return normalized;
 }
 
+function normalizeFactsSection(facts) {
+  assertPlainObject(facts, "facts");
+  return {
+    outputDir: facts.output_dir === undefined ? ".buildchain/facts" : posixPath(assertString(facts.output_dir, "facts.output_dir")),
+    versionSources: normalizeFactVersionSources(facts.version_sources),
+    modules: normalizeFactModules(facts.modules),
+    products: normalizeFactProducts(facts.products),
+    legacyProjections: normalizeFactLegacyProjections(facts.legacy_projections),
+  };
+}
+
+function normalizeFactVersionSources(sources = []) {
+  if (sources === undefined) {
+    return [];
+  }
+  if (!Array.isArray(sources)) {
+    throw new Error("facts.version_sources must be an array of tables");
+  }
+  return sources.map((source, index) => {
+    assertPlainObject(source, `facts.version_sources[${index}]`);
+    const id = assertString(source.id, `facts.version_sources[${index}].id`);
+    const type = source.type === undefined ? "static" : assertString(source.type, `facts.version_sources[${index}].type`);
+    if (!SUPPORTED_FACT_VERSION_SOURCE_TYPES.has(type)) {
+      throw new Error("facts.version_sources[].type must be one of static, json, toml, regex, or command");
+    }
+    if (["json", "toml", "regex"].includes(type) && source.path === undefined) {
+      throw new Error(`facts.version_sources[${index}].path is required for ${type}`);
+    }
+    if (["json", "toml"].includes(type) && source.key === undefined) {
+      throw new Error(`facts.version_sources[${index}].key is required for ${type}`);
+    }
+    if (type === "regex" && source.pattern === undefined) {
+      throw new Error(`facts.version_sources[${index}].pattern is required for regex`);
+    }
+    if (type === "command" && source.command === undefined) {
+      throw new Error(`facts.version_sources[${index}].command is required for command`);
+    }
+    return {
+      id,
+      type,
+      value: source.value === undefined ? undefined : String(source.value),
+      path: source.path === undefined ? "" : posixPath(assertString(source.path, `facts.version_sources[${index}].path`)),
+      key: source.key === undefined ? "" : assertString(source.key, `facts.version_sources[${index}].key`),
+      pattern: source.pattern === undefined ? "" : assertString(source.pattern, `facts.version_sources[${index}].pattern`),
+      command: source.command === undefined ? "" : assertString(source.command, `facts.version_sources[${index}].command`),
+      trust: source.trust === undefined ? "" : assertString(source.trust, `facts.version_sources[${index}].trust`),
+      reproducible: optionalBoolean(source.reproducible, type !== "command"),
+    };
+  });
+}
+
+function normalizeFactModules(modules = []) {
+  if (modules === undefined) {
+    return [];
+  }
+  if (!Array.isArray(modules)) {
+    throw new Error("facts.modules must be an array of tables");
+  }
+  return modules.map((module, index) => {
+    assertPlainObject(module, `facts.modules[${index}]`);
+    return {
+      id: assertString(module.id, `facts.modules[${index}].id`),
+      root: module.root === undefined ? "." : posixPath(assertString(module.root, `facts.modules[${index}].root`)),
+      scope: module.scope === undefined ? "" : assertString(module.scope, `facts.modules[${index}].scope`),
+      versionSource: module.version_source === undefined ? "" : assertString(module.version_source, `facts.modules[${index}].version_source`),
+      lifecycle: module.lifecycle === undefined ? "" : assertString(module.lifecycle, `facts.modules[${index}].lifecycle`),
+      outputs: normalizeStringArray(module.outputs, `facts.modules[${index}].outputs`).map(posixPath),
+    };
+  });
+}
+
+function normalizeFactProducts(products = []) {
+  if (products === undefined) {
+    return [];
+  }
+  if (!Array.isArray(products)) {
+    throw new Error("facts.products must be an array of tables");
+  }
+  return products.map((product, index) => {
+    assertPlainObject(product, `facts.products[${index}]`);
+    return {
+      id: assertString(product.id, `facts.products[${index}].id`),
+      moduleFacts: normalizeStringArray(product.module_facts, `facts.products[${index}].module_facts`).map(posixPath),
+      artifacts: normalizeStringArray(product.artifacts, `facts.products[${index}].artifacts`).map(posixPath),
+    };
+  });
+}
+
+function normalizeFactLegacyProjections(projections = []) {
+  if (projections === undefined) {
+    return [];
+  }
+  if (!Array.isArray(projections)) {
+    throw new Error("facts.legacy_projections must be an array of tables");
+  }
+  return projections.map((projection, index) => {
+    assertPlainObject(projection, `facts.legacy_projections[${index}]`);
+    const type = assertString(projection.type, `facts.legacy_projections[${index}].type`);
+    if (!SUPPORTED_FACT_LEGACY_PROJECTIONS.has(type)) {
+      throw new Error("facts.legacy_projections[].type must be kungfu-buildinfo");
+    }
+    return {
+      type,
+      module: projection.module === undefined ? "" : assertString(projection.module, `facts.legacy_projections[${index}].module`),
+      path: posixPath(assertString(projection.path, `facts.legacy_projections[${index}].path`)),
+    };
+  });
+}
+
 function normalizeDiagnosticsSection(diagnostics) {
   assertPlainObject(diagnostics, "diagnostics");
   const normalized = { ...diagnostics };
@@ -1062,6 +1176,7 @@ export function validateBuildchainConfig(
     })),
     lifecycleStages,
     publish: loadedConfig.config.publish,
+    facts: loadedConfig.config.facts,
   };
 }
 

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

@@ -22,6 +22,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "ownership", title: "Ownership", path: "docs/ownership.md", plane: "why" },
   { id: "product-mechanism", title: "Product mechanism", path: "docs/product-mechanism.md", plane: "why" },
   { id: "cli", title: "CLI and npm package", path: "docs/cli.md", plane: "use" },
+  { id: "build-facts", title: "Build Facts", path: "docs/build-facts.md", plane: "use" },
   { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
   { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
   { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
@@ -72,6 +73,7 @@ const EXTRA_KFD1_FILES = Object.freeze([
   "bin/buildchain.mjs",
   "packages/core/index.js",
   "packages/core/homebrew.js",
+  "packages/core/build-facts.js",
   "packages/core/release-propagation.js",
   "scripts/generate-site-bundle.mjs",
   "scripts/ensure-github-release.mjs",

package/packages/core/index.js

@@ -86,6 +86,24 @@ export {
   writeDiagnosticsArtifact,
 } from "./diagnostics.js";
 
+export {
+  BUILD_FACTS_GIT_CONTRACT,
+  BUILD_FACTS_LEGACY_KUNGFU_BUILDINFO_CONTRACT,
+  BUILD_FACTS_MODULE_CONTRACT,
+  BUILD_FACTS_PRODUCT_CONTRACT,
+  BUILD_FACTS_VERIFY_CONTRACT,
+  BUILD_FACTS_VERSION_CONTRACT,
+  aggregateBuildFacts,
+  buildFactsDigest,
+  collectGitSourceFacts,
+  collectModuleBuildFacts,
+  collectVersionSourceFact,
+  createKungfuBuildInfoProjection,
+  verifyBuildFacts,
+  writeBuildFacts,
+  writeKungfuBuildInfoProjection,
+} from "./build-facts.js";
+
 export {
   RELEASE_CANDIDATE_PASSPORT_CONTRACT,
   createReleaseCandidatePassport,
@@ -194,15 +212,21 @@ export {
 } from "./issue-reporting.js";
 
 export {
+  BADGE_BUNDLE_DEFAULT_CLAIMS,
+  BADGE_BUNDLE_FACTS_CONTRACT,
   README_BADGE_BLOCK_END,
   README_BADGE_BLOCK_START,
   README_BADGE_FACTS_CONTRACT,
   README_BADGE_HOSTED_BASE_URL,
+  checkBadgeBundleBlock,
   checkReadmeBadgeBlock,
+  collectBadgeBundleFacts,
   collectReadmeBadgeFacts,
   createReadmeBadgeEndpointRegistry,
   readReadme,
+  renderBadgeBundleBlock,
   renderReadmeBadgeBlock,
+  updateBadgeBundleBlock,
   updateReadmeBadgeBlock,
 } from "./readme-badges.js";
 

package/packages/core/readme-badges.js

@@ -10,9 +10,16 @@ import {
 } from "./release-passport.js";
 
 export const README_BADGE_FACTS_CONTRACT = "kungfu-buildchain-readme-badge-facts";
+export const BADGE_BUNDLE_FACTS_CONTRACT = "kungfu-buildchain-badge-bundle-facts";
 export const README_BADGE_BLOCK_START = "<!-- buildchain:badges:start -->";
 export const README_BADGE_BLOCK_END = "<!-- buildchain:badges:end -->";
 export const README_BADGE_HOSTED_BASE_URL = "https://buildchain.libkungfu.dev/badges/v1";
+export const BADGE_BUNDLE_DEFAULT_CLAIMS = [
+  "kfd-1",
+  "kfd-2",
+  "kfd-3",
+  "release-passport",
+];
 
 const KFD_KEYS = [
   { key: "kfd-1", id: "kfd1", label: "KFD-1", text: "contract world" },
@@ -47,6 +54,22 @@ const BUILDCHAIN_BADGE_IDS = [
   "buildchain-release-passport",
 ];
 
+const BADGE_BUNDLE_CLAIM_ALIASES = {
+  kfd1: "kfd-1",
+  "kfd_1": "kfd-1",
+  "kfd-1": "kfd-1",
+  kfd2: "kfd-2",
+  "kfd_2": "kfd-2",
+  "kfd-2": "kfd-2",
+  kfd3: "kfd-3",
+  "kfd_3": "kfd-3",
+  "kfd-3": "kfd-3",
+  passport: "release-passport",
+  "release_passport": "release-passport",
+  "release-passport": "release-passport",
+  "buildchain-release-passport": "release-passport",
+};
+
 const BUILDCHAIN_BADGE_LOGO_PLACEHOLDER = {
   contract: "kungfu-buildchain-badge-logo-policy",
   mode: "hosted-placeholder",
@@ -83,6 +106,10 @@ function sha256File(filePath) {
   return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
 }
 
+function hashText(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
 function posixPath(value) {
   return String(value || "").split(path.sep).join("/");
 }
@@ -174,6 +201,51 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function splitClaimList(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return value.split(",");
+  }
+  return [];
+}
+
+function normalizeBadgeBundleClaims(value, fallback = BADGE_BUNDLE_DEFAULT_CLAIMS) {
+  const selected = [];
+  const unknown = [];
+  for (const claim of splitClaimList(value)) {
+    const key = String(claim || "").trim().toLowerCase();
+    if (!key) {
+      continue;
+    }
+    const normalized = BADGE_BUNDLE_CLAIM_ALIASES[key];
+    if (!normalized) {
+      unknown.push(key);
+      continue;
+    }
+    if (!selected.includes(normalized)) {
+      selected.push(normalized);
+    }
+  }
+  if (unknown.length > 0) {
+    throw new Error(`unsupported badge bundle claim(s): ${unknown.join(", ")}`);
+  }
+  return selected.length > 0 ? selected : [...fallback];
+}
+
+function badgeBundleConfig(badgeConfig = {}) {
+  const configured = badgeConfig.bundle && typeof badgeConfig.bundle === "object"
+    ? badgeConfig.bundle
+    : {};
+  return {
+    enabled: configured.enabled === undefined ? true : Boolean(configured.enabled),
+    claims: normalizeBadgeBundleClaims(configured.claims || badgeConfig.bundle_claims || badgeConfig.bundleClaims),
+    mode: String(configured.mode || "readme"),
+    hosted: configured.hosted === undefined ? true : Boolean(configured.hosted),
+  };
+}
+
 function resolveLocalFactPath({ cwd, location }) {
   const value = String(location || "").trim();
   if (!value || /^https?:\/\//.test(value)) {
@@ -531,6 +603,46 @@ function buildBadgeEntries(facts, { badgeConfig = {} } = {}) {
   return entries;
 }
 
+function buildBadgeBundleEntries(readmeFacts, bundle) {
+  const selected = new Set(bundle.claims);
+  const entries = [];
+  for (const kfd of readmeFacts.kfd) {
+    if (!selected.has(kfd.key)) {
+      continue;
+    }
+    entries.push({
+      id: kfd.key,
+      claim: kfd.key,
+      alt: `${kfd.label}: ${kfd.state}`,
+      image: readmeFacts.badges.find((badge) => badge.id === kfd.key)?.image || "",
+      link: kfd.url,
+      state: kfd.state,
+      source: kfd.source,
+      standard: {
+        title: kfd.title,
+        documentUrl: kfd.standardDocumentUrl,
+        documentSha256: kfd.standardDocumentSha256,
+        interfaceContract: kfd.interfaceContract,
+        schemaId: kfd.schemaId,
+      },
+    });
+  }
+  if (selected.has("release-passport")) {
+    const badge = readmeFacts.badges.find((entry) => entry.id === "buildchain-release-passport");
+    entries.push({
+      id: "buildchain-release-passport",
+      claim: "release-passport",
+      alt: `Buildchain Release Passport: ${readmeFacts.releasePassport.state}`,
+      image: badge?.image || "",
+      link: readmeFacts.releasePassport.url,
+      state: readmeFacts.releasePassport.state,
+      source: readmeFacts.releasePassport.verified ? "release-passport" : "declaration",
+      releasePassport: readmeFacts.releasePassport,
+    });
+  }
+  return entries;
+}
+
 export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const loadedConfig = loadBuildchainConfig(resolvedCwd);
@@ -610,13 +722,46 @@ export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
       hostedBadgeIds: BUILDCHAIN_BADGE_IDS,
       logoPolicy: BUILDCHAIN_BADGE_LOGO_PLACEHOLDER,
     },
+    badgeBundle: badgeBundleConfig(badgeConfig),
     badges: [],
   };
   facts.badges = buildBadgeEntries(facts, { badgeConfig });
   return facts;
 }
 
-export function renderReadmeBadgeBlock(facts) {
+export async function collectBadgeBundleFacts({ cwd = process.cwd(), claims = undefined } = {}) {
+  const readmeFacts = await collectReadmeBadgeFacts({ cwd });
+  const config = {
+    ...readmeFacts.badgeBundle,
+    claims: normalizeBadgeBundleClaims(claims, readmeFacts.badgeBundle.claims),
+  };
+  const badges = buildBadgeBundleEntries(readmeFacts, config);
+  return {
+    schemaVersion: 1,
+    contract: BADGE_BUNDLE_FACTS_CONTRACT,
+    cwd: readmeFacts.cwd,
+    repository: readmeFacts.repository,
+    package: readmeFacts.package,
+    sourceFactsContract: readmeFacts.contract,
+    sourceFactsSha256: hashText(JSON.stringify(readmeFacts)),
+    policy: {
+      defaultClaims: [...BADGE_BUNDLE_DEFAULT_CLAIMS],
+      claims: config.claims,
+      hosted: config.hosted,
+      mode: config.mode,
+      passedRequiresRepositoryPassport: true,
+      consumerActionForLogoChange: "none",
+    },
+    releasePassport: readmeFacts.releasePassport,
+    kfdStandards: readmeFacts.kfdStandards,
+    kfdClaimRegistry: readmeFacts.kfdClaimRegistry,
+    productMechanism: readmeFacts.productMechanism,
+    badgeRuntime: readmeFacts.badgeRuntime,
+    badges,
+  };
+}
+
+function renderBadgeMarkdownBlock(facts) {
   const lines = [
     README_BADGE_BLOCK_START,
     ...facts.badges.map((badge) => (
@@ -629,12 +774,20 @@ export function renderReadmeBadgeBlock(facts) {
   return `${lines.join("\n")}\n`;
 }
 
+export function renderReadmeBadgeBlock(facts) {
+  return renderBadgeMarkdownBlock(facts);
+}
+
+export function renderBadgeBundleBlock(facts) {
+  return renderBadgeMarkdownBlock(facts);
+}
+
 function badgeBlockRegex() {
   return new RegExp(`${README_BADGE_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${README_BADGE_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`);
 }
 
 export function checkReadmeBadgeBlock({ readmeText, facts } = {}) {
-  const expected = renderReadmeBadgeBlock(facts);
+  const expected = renderBadgeMarkdownBlock(facts);
   const match = String(readmeText || "").match(badgeBlockRegex());
   const actual = match ? match[0] : "";
   const normalizedActual = actual.endsWith("\n") ? actual : `${actual}\n`;
@@ -652,6 +805,13 @@ export function checkReadmeBadgeBlock({ readmeText, facts } = {}) {
   };
 }
 
+export function checkBadgeBundleBlock({ readmeText, facts } = {}) {
+  return {
+    ...checkReadmeBadgeBlock({ readmeText, facts }),
+    contract: "kungfu-buildchain-badge-bundle-check",
+  };
+}
+
 export function updateReadmeBadgeBlock({ readmeText, facts } = {}) {
   const source = String(readmeText || "");
   const block = renderReadmeBadgeBlock(facts);
@@ -665,6 +825,10 @@ export function updateReadmeBadgeBlock({ readmeText, facts } = {}) {
   return `${block}\n${source}`;
 }
 
+export function updateBadgeBundleBlock({ readmeText, facts } = {}) {
+  return updateReadmeBadgeBlock({ readmeText, facts });
+}
+
 export function readReadme({ cwd = process.cwd(), readmePath = "README.md" } = {}) {
   return readTextIfExists(path.resolve(cwd, readmePath));
 }

package/packages/core/release-passport.js

@@ -930,6 +930,7 @@ export function createReleasePassport({
   trustedPublishing = undefined,
   transaction = undefined,
   buildSummary = undefined,
+  buildFacts = [],
   platformArtifactManifests = [],
   distTagPromotionEvidence = undefined,
   release = {},
@@ -947,6 +948,9 @@ export function createReleasePassport({
   const normalizedTrustedPublishing = normalizeTrustedPublishing(trustedPublishing, { workflow, publish });
   const normalizedTransaction = normalizeTransaction(transaction);
   const normalizedBuildSummary = buildSummary ? normalizeEvidenceDocument(buildSummary, "buildSummary") : undefined;
+  const normalizedBuildFacts = (buildFacts || [])
+    .map((fact, index) => normalizeEvidenceDocument(fact, `buildFacts[${index}]`))
+    .filter(Boolean);
   const normalizedPlatformArtifactManifests = (platformArtifactManifests || [])
     .map((manifest, index) => normalizePlatformArtifactManifest(manifest, index))
     .filter(Boolean);
@@ -1078,6 +1082,7 @@ export function createReleasePassport({
     ...(normalizedTrustedPublishing ? { trustedPublishing: normalizedTrustedPublishing } : {}),
     ...(normalizedTransaction ? { transaction: normalizedTransaction } : {}),
     ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
+    ...(normalizedBuildFacts.length > 0 ? { buildFacts: normalizedBuildFacts } : {}),
     ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),
     ...(normalizedDistTagPromotionEvidence ? { distTagPromotion: normalizedDistTagPromotionEvidence } : {}),
     ...(normalizedKfd1 ? { [normalizedKfd1.key || kfd1Metadata.key]: normalizedKfd1.passportSection } : {}),
@@ -1111,6 +1116,13 @@ export function createReleasePassport({
       publishEvidence: publishEvidencePath,
       transactionState: transactionStatePath,
       buildSummary: normalizedBuildSummary?.path || "",
+      buildFacts: normalizedBuildFacts.map((fact) => ({
+        path: fact.path || "",
+        sha256: fact.sha256 || "",
+        contract: fact.fields?.contract || "",
+        id: fact.fields?.id || "",
+        digest: fact.fields?.digest || "",
+      })),
       platformArtifactManifests: normalizedPlatformArtifactManifests.map((manifest) => ({
         path: manifest.path,
         sha256: manifest.sha256,
@@ -1152,6 +1164,7 @@ export function collectGitHubReleasePassport({
   anchorManifestJson = "",
   impactJson = "",
   buildSummaryJson = "",
+  buildFactsJsons = [],
   platformManifestJsons = [],
   distTagEvidenceJson = "",
   kfd1WitnessJsons = [],
@@ -1175,6 +1188,10 @@ export function collectGitHubReleasePassport({
   const anchorManifest = normalizeAnchorManifest(parseJsonInputWithMeta(anchorManifestJson, undefined));
   const impactMeta = parseJsonInputWithMeta(impactJson, undefined);
   const buildSummaryMeta = parseJsonInputWithMeta(buildSummaryJson, undefined);
+  const buildFactMetas = (buildFactsJsons || [])
+    .filter(Boolean)
+    .map((buildFactsJson) => parseJsonInputWithMeta(buildFactsJson, undefined))
+    .filter((meta) => meta.value);
   const platformManifestMetas = (platformManifestJsons || [])
     .filter(Boolean)
     .map((manifestJson) => parseJsonInputWithMeta(manifestJson, undefined));
@@ -1255,6 +1272,10 @@ export function collectGitHubReleasePassport({
           path: buildSummaryMeta.path ? path.relative(resolvedOutputDir, buildSummaryMeta.path).split(path.sep).join("/") : "",
         }
       : undefined,
+    buildFacts: buildFactMetas.map((meta) => ({
+      ...meta,
+      path: meta.path ? path.relative(resolvedOutputDir, meta.path).split(path.sep).join("/") : "",
+    })),
     platformArtifactManifests: platformManifestMetas
       .filter((meta) => meta.value)
       .map((meta) => ({

package/scripts/check-inventory.mjs

@@ -15,7 +15,9 @@ const requiredPaths = [
   ".github/pull_request_template.md",
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
+  "packages/core/build-facts.js",
   "docs/MAP.md",
+  "docs/build-facts.md",
   "docs/binary-distribution.md",
   "docs/cli.md",
   "docs/consumer-issue-reporting.md",
@@ -120,6 +122,12 @@ if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-report
 if (rootPackage.exports?.["./readme-badges"] !== "./packages/core/readme-badges.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/readme-badges");
 }
+if (rootPackage.exports?.["./badges"] !== "./packages/core/badges.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/badges");
+}
+if (rootPackage.exports?.["./build-facts"] !== "./packages/core/build-facts.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/build-facts");
+}
 if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/logging");
 }
@@ -210,6 +218,20 @@ if (!coreIndexSource.includes("createSurfaceTimestampPolicy")) {
   throw new Error("packages/core/index.js must export surface manifest timestamp policy APIs");
 }
 for (const requiredSnippet of [
+  "collectModuleBuildFacts",
+  "aggregateBuildFacts",
+  "verifyBuildFacts",
+  "writeKungfuBuildInfoProjection",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export Build Facts API: ${requiredSnippet}`);
+  }
+}
+for (const requiredSnippet of [
+  "collectBadgeBundleFacts",
+  "renderBadgeBundleBlock",
+  "checkBadgeBundleBlock",
+  "updateBadgeBundleBlock",
   "collectReadmeBadgeFacts",
   "renderReadmeBadgeBlock",
   "checkReadmeBadgeBlock",
@@ -387,6 +409,8 @@ for (const requiredSnippet of [
   "Verification fails closed",
   "KFD-2 release trust passport audit",
   "Unbound public claims fail",
+  "buildFacts[]",
+  "--build-facts-json",
   "Floating Buildchain contract lock",
   "buildchain.contract-lock.json",
   "--kfd-3-prebuild-witness-json",
@@ -403,6 +427,7 @@ for (const requiredSnippet of [
   "KFD-1 / KFD-2 / KFD-3",
   "floating `@v2`",
   "npm publish transactions",
+  "Git/source/version/module/product build facts",
   "GitHub Release",
   "release propagation",
   "Homebrew tap distribution indexes",
@@ -416,6 +441,11 @@ for (const requiredSnippet of [
 }
 const readmeBadgesDoc = fs.readFileSync(path.join(root, "docs/readme-badges.md"), "utf8");
 for (const requiredSnippet of [
+  "buildchain badges bundle --check",
+  "collectBadgeBundleFacts",
+  "kungfu-buildchain-badge-bundle-facts",
+  "@kungfu-tech/buildchain/badges",
+  "[badges.bundle]",
   "buildchain badges readme --check",
   "collectReadmeBadgeFacts",
   "kungfu-buildchain-readme-badge-facts",
@@ -472,8 +502,11 @@ for (const [docName, docSource] of Object.entries({ "docs/cli.md": cliDoc, "docs
   }
 }
 for (const requiredSnippet of [
+  "buildchain badges bundle --check",
+  "buildchain badges bundle --write",
   "buildchain badges readme --check",
   "buildchain badges readme --write",
+  "@kungfu-tech/buildchain/badges",
   "@kungfu-tech/buildchain/readme-badges",
   "buildchain homebrew update-formula",
   "buildchain homebrew check",
@@ -553,12 +586,10 @@ for (const requiredSnippet of [
   "release-passport-buildchain-self-kfd: true",
   "publish-required-artifacts-json: \"[]\"",
   "release-passport-impact-json: >-",
-  "Buildchain v2.8 promotes KFD self-verification",
-  "kfd-1-contract-world-release-gate",
-  "kfd-2-release-trust-passport-audit",
-  "kfd-3-collaboration-interface-trust-proof",
-  "publish-source-lock-enforcement",
-  "required-check-protection",
+  "Buildchain v2.9 adds Build Facts as a public contract",
+  "build-facts-contract",
+  "trust-badge-bundle",
+  "web-surface-directory-index-aliases",
   "\"surfaceImpacts\":[",
 ]) {
   if (!buildchainRefPromotionWorkflow.includes(requiredSnippet)) {

package/scripts/generate-site-bundle.mjs

@@ -294,6 +294,7 @@ function buildSiteBundle() {
       { id: "verify-infra-contract-evidence-bundle", usage: "buildchain verify infra-contract-evidence-bundle <file>", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
       { id: "logging", usage: "buildchain log|mark|span|verify observability-log", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
       { id: "diagnostics-summary", usage: "buildchain diagnostics summary <diagnostics.json>...", purpose: "Summarize small diagnostics artifacts into JSON and a cross-platform lifecycle timing table." },
+      { id: "build-facts", usage: "buildchain facts module|aggregate|verify", purpose: "Collect and verify Git source, version, module output, product artifact, and legacy Kungfu buildinfo facts." },
       { id: "npm-dry-run", usage: "buildchain npm dry-run --json", purpose: "Verify npm publish shape before a release transaction." },
       { id: "infra-contract", usage: "buildchain infra-contract --mode validate|ci|plan|contract|propagation-plan|propagation-apply|apply|evidence-bundle", purpose: "Validate and publish provider-neutral infrastructure contract evidence with a mutation-free CI evidence chain, provider command plans, configured provider command execution, saved-plan apply gates, dry-run-first propagation, and lifecycle evidence bundles." },
       { id: "homebrew", usage: "buildchain homebrew update-formula|check", purpose: "Generate and verify Homebrew tap Formula metadata as a distribution-index projection of upstream release passport evidence." },
@@ -316,6 +317,7 @@ function buildSiteBundle() {
       "docs/MAP.md",
       "docs/install.md",
       "docs/cli.md",
+      "docs/build-facts.md",
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-governance.md",
@@ -361,6 +363,7 @@ function buildSiteBundle() {
       })),
     docs: [
       { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
+      { id: "build-facts", path: "docs/build-facts.md", digest: sha256File("docs/build-facts.md") },
       { id: "readme-badges", path: "docs/readme-badges.md", digest: sha256File("docs/readme-badges.md") },
       { id: "homebrew", path: "docs/homebrew.md", digest: sha256File("docs/homebrew.md") },
       { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },