@kungfu-tech/buildchain 2.8.17 → 2.9.0

package/dist/site/release-provenance.json

@@ -9,6 +9,8 @@
     },
     "exports": {
       ".": "./packages/core/index.js",
+      "./badges": "./packages/core/badges.js",
+      "./build-facts": "./packages/core/build-facts.js",
       "./core": "./packages/core/index.js",
       "./artifact-passport": "./packages/core/artifact-passport.js",
       "./buildchain-contract": "./packages/core/buildchain-contract.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-08T00:24:24.491Z",
-  "publishedAt": "2026-07-08T00:24:24.491Z",
+  "generatedAt": "2026-07-08T02:47:46.506Z",
+  "publishedAt": "2026-07-08T02:47:46.506Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "186482073690d8f922f5f4ecbea20849dda724a4",
+  "sourceRevision": "2142b74c1ce1b6be6e2227ffe53ba87750afde07",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.8.17",
+    "version": "2.9.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:03f52660d03223fff7daf500f995645d78a46fffd8cddec9d8c01bbee0863145"
+      "digest": "sha256:2d95d0dd56088efb1a9a16d026810cf2e74659963612451f903e37825c260122"
     },
     {
       "id": "install",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094"
+      "digest": "sha256:495e1c46ce45268a9ed6502fe115af45a8cd1d8e644cb4332da9b551f919f578"
     },
     {
       "id": "release-propagation",
@@ -85,7 +85,7 @@
       "path": "docs/readme-badges.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:c886d5d469d143571ae68497643be754b1616b562fddc780a5708f49b4c46242"
+      "digest": "sha256:06eaef737dcc73a6526d856d79275ee87af9670f0e2be39a5596758bfc3527c9"
     },
     {
       "id": "homebrew",
@@ -165,7 +165,15 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:cfb0bf32f2b8b44bf352e79c27e34b7980e0f66e5fa10e4f202975fbb4780ad1"
+      "digest": "sha256:60686b5b4d5fe7f3944cb53ab709231fd00bb02b6d51770f1fe8b018122afd8f"
+    },
+    {
+      "id": "build-facts",
+      "title": "Build Facts",
+      "path": "docs/build-facts.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:75dcf7a6628dac9e982a455de9966044ae771611d4efc04e7264a2d4adb0bd3e"
     },
     {
       "id": "lifecycle-protocol",
@@ -221,7 +229,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:77b92fc979cc100beab3f8a13cd791dea992737b986ace505104edff4810a296"
+      "digest": "sha256:2c79f7d1a072a40c75d889beac38ae843b2170587fc570ce40722d3968b6506e"
     },
     {
       "id": "web-surface-deployments",
@@ -229,7 +237,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:5063ebb76db3cd36797561782e6c741e30d60bfa0dac8f798dbbd34c4ab2b3c0"
+      "digest": "sha256:70995864ece77573756e1c197a936d86011f84b356d75683881b59b5aa537d8c"
     }
   ],
   "facts": [

package/docs/MAP.md

@@ -23,9 +23,10 @@ manuals explain those facts and give operator examples.
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
 | Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
+| Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |
 | GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |
 | release propagation for package/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |
-| Generated README badge blocks and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |
+| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |
 | Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |
 | Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |
 | Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |
@@ -55,13 +56,14 @@ replace them.
 | What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
+| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
 | How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |
 | How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
-| How do I generate README status badges without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |
+| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |
 | How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
@@ -120,9 +122,11 @@ replace them.
   and [`release-passport.md`](release-passport.md).
 - **Trusted Publishing / npm / publish evidence / recovery** ->
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
+- **Git source digest / module build facts / product build facts / legacy
+  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).
 - **release chains / upstream package as source of truth / site synchronization** ->
   [`release-propagation.md`](release-propagation.md).
-- **README status badges / KFD badge blocks / badge facts JSON** ->
+- **README status badges / KFD badge bundles / badge facts JSON** ->
   [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).
 - **Homebrew taps / distribution indexes / Formula drift checks** ->
   [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).

package/docs/build-facts.md

@@ -0,0 +1,164 @@
+# Build Facts
+
+Build Facts are Buildchain's machine-readable record of what a repository
+built. They sit between lifecycle logs and release passports:
+
+- lifecycle logs explain what ran and how long it took;
+- module build facts bind one module to its Git source digest, version source,
+  platform, lifecycle invocation, and output digests;
+- product build facts aggregate module facts and product artifacts;
+- release passports can carry build facts as first-class evidence.
+
+The goal is to remove handwritten build metadata from consumer repositories.
+Consumers declare where their version and outputs live; Buildchain collects and
+verifies the facts.
+
+## Config
+
+Declare build facts in `buildchain.toml`:
+
+```toml
+schema = 1
+
+[[facts.version_sources]]
+id = "package"
+type = "json"
+path = "package.json"
+key = "version"
+
+[[facts.modules]]
+id = "native-core"
+root = "src/core"
+scope = "core"
+version_source = "package"
+lifecycle = "build"
+outputs = ["dist/core.node"]
+
+[[facts.products]]
+id = "kungfu"
+module_facts = [".buildchain/facts/native-core.json"]
+artifacts = ["dist/kungfu.zip"]
+
+[[facts.legacy_projections]]
+type = "kungfu-buildinfo"
+module = "native-core"
+path = "framework/core/src/kungfu/yijinjing/kungfubuildinfo.json"
+```
+
+Supported version sources:
+
+- `static`: an explicit `value`;
+- `json`: a JSON file plus dotted `key`;
+- `toml`: a TOML file plus dotted `key`;
+- `regex`: a text file plus regex `pattern`, using a named `version` group or
+  the first capture group;
+- `command`: an explicit command whose output is the version.
+
+Prefer file-based sources. Command sources are allowed for legacy projects but
+are marked as less reproducible because the command output is not a static
+source file.
+
+## CLI
+
+Collect a module fact:
+
+```bash
+buildchain facts module \
+  --module native-core \
+  --output .buildchain/facts/native-core.json
+```
+
+Override declarative config from a workflow step when needed:
+
+```bash
+buildchain facts module \
+  --cwd "$GITHUB_WORKSPACE" \
+  --module native-core \
+  --module-root src/core \
+  --version-source package \
+  --output-path dist/core.node \
+  --output .buildchain/facts/native-core.json \
+  --json
+```
+
+Write the Kungfu legacy `kungfubuildinfo.json` projection from the same module
+fact:
+
+```bash
+buildchain facts module \
+  --module native-core \
+  --output .buildchain/facts/native-core.json \
+  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json
+```
+
+Aggregate product facts:
+
+```bash
+buildchain facts aggregate \
+  --product kungfu \
+  --module-fact .buildchain/facts/native-core.json \
+  --artifact dist/kungfu.zip \
+  --output .buildchain/facts/kungfu.json
+```
+
+Verify a fact before publishing:
+
+```bash
+buildchain facts verify --fact .buildchain/facts/kungfu.json
+```
+
+Verification fails closed when a declared output is missing, an output digest is
+stale, a module fact was collected from a different Git `HEAD`, or a source
+digest no longer matches the tracked source files.
+
+## Node API
+
+```js
+import {
+  aggregateBuildFacts,
+  collectModuleBuildFacts,
+  verifyBuildFacts,
+  writeBuildFacts,
+  writeKungfuBuildInfoProjection,
+} from "@kungfu-tech/buildchain/build-facts";
+
+const moduleFact = collectModuleBuildFacts({ moduleId: "native-core" });
+writeBuildFacts({ fact: moduleFact, output: ".buildchain/facts/native-core.json" });
+
+const productFact = aggregateBuildFacts({ productId: "kungfu" });
+const verification = verifyBuildFacts({ fact: productFact });
+```
+
+The root package export also re-exports these APIs from
+`@kungfu-tech/buildchain`.
+
+## Release Passport Integration
+
+Pass build facts into a release passport:
+
+```bash
+buildchain collect github-release \
+  --tag "$TAG" \
+  --assets-dir dist \
+  --build-facts-json .buildchain/facts/native-core.json \
+  --build-facts-json .buildchain/facts/kungfu.json \
+  --output-dir .buildchain/release-passport
+```
+
+The passport records the full build facts in `buildFacts[]` and a compact
+evidence index in `evidence.buildFacts[]`. Agents can start from
+`buildchain.release.json`, discover the module/product facts, and verify that
+the released artifacts still match the declared source, version, and output
+facts.
+
+## Kungfu Legacy Projection
+
+Kungfu historically consumes `kungfubuildinfo.json`. Buildchain now treats that
+file as a projection of module build facts, not as an independent source of
+truth. The projection preserves legacy fields such as `version`,
+`python_version`, `git_branch`, `git_revision`, and `git_pristine`, while adding
+a `buildchain` section that points back to the module fact digest, version
+source digest, and source digest.
+
+Repositories that no longer need the legacy file should consume the module and
+product facts directly.

package/docs/cli.md

@@ -64,8 +64,10 @@ Current public import families include:
 ```js
 import * as buildchain from "@kungfu-tech/buildchain";
 import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+import { collectModuleBuildFacts } from "@kungfu-tech/buildchain/build-facts";
 import { checkHomebrewTap } from "@kungfu-tech/buildchain/homebrew";
 import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
+import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain/badges";
 import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
@@ -199,6 +201,30 @@ install/build/verify/publish, artifact scan/upload, total, warning, and error
 columns for each platform, plus `jobs` and `active` columns for requested and
 observed process concurrency when sampler data is present.
 
+`buildchain facts` collects and verifies source/version/output facts for
+modules and products:
+
+```bash
+buildchain facts module \
+  --module native-core \
+  --output .buildchain/facts/native-core.json \
+  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json
+
+buildchain facts aggregate \
+  --product kungfu \
+  --module-fact .buildchain/facts/native-core.json \
+  --artifact dist/kungfu.zip \
+  --output .buildchain/facts/kungfu.json
+
+buildchain facts verify --fact .buildchain/facts/kungfu.json
+```
+
+The same implementation is available from
+`@kungfu-tech/buildchain/build-facts`. Release passports can include these
+facts with repeated `--build-facts-json` arguments to
+`buildchain collect github-release`. See
+[`build-facts.md`](build-facts.md) for the config schema and Node API.
+
 `buildchain sample process-tree` wraps a long-running command and periodically
 writes process-tree snapshots:
 
@@ -259,6 +285,10 @@ Generate, check, or update the managed README badge block:
 buildchain badges readme --json
 buildchain badges readme --check
 buildchain badges readme --write
+buildchain badges bundle --json
+buildchain badges bundle --check
+buildchain badges bundle --write
+buildchain badges bundle --claims kfd-1,release-passport --write
 ```
 
 The `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.
@@ -266,8 +296,10 @@ The `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.
 `--write` inserts or replaces only the marked block. KFD passed badges come
 from the repository's own verified release passport; unreleased repositories
 downgrade to explicit local declarations such as `declared`, `aligned`, or
-`planned`. See [`readme-badges.md`](readme-badges.md) for the marker contract
-and `[badges]` configuration.
+`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it
+emits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,
+KFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the
+marker contract and `[badges]` / `[badges.bundle]` configuration.
 
 Generate or check Homebrew tap projections from upstream release passports:
 

package/docs/readme-badges.md

@@ -22,13 +22,20 @@ Use the public package export:
 
 ```js
 import {
+  collectBadgeBundleFacts,
   collectReadmeBadgeFacts,
+  renderBadgeBundleBlock,
   renderReadmeBadgeBlock,
+  checkBadgeBundleBlock,
   checkReadmeBadgeBlock,
+  updateBadgeBundleBlock,
   updateReadmeBadgeBlock,
-} from "@kungfu-tech/buildchain/readme-badges";
+} from "@kungfu-tech/buildchain/badges";
 ```
 
+`@kungfu-tech/buildchain/readme-badges` remains available for compatibility,
+but new integrations should use `@kungfu-tech/buildchain/badges`.
+
 `collectReadmeBadgeFacts({ cwd })` returns a machine-readable object with
 contract `kungfu-buildchain-readme-badge-facts`. It collects repository
 identity, package name/version/license, configured platforms, configured
@@ -50,6 +57,13 @@ managed block.
 
 The Node API is the implementation source. The CLI delegates to it.
 
+`collectBadgeBundleFacts({ cwd, claims })` is the trust-badge bundle API. It
+uses the same repository facts, but returns contract
+`kungfu-buildchain-badge-bundle-facts` and only renders the Buildchain trust
+claims: `kfd-1`, `kfd-2`, `kfd-3`, and `release-passport`. Those four claims are
+enabled by default. Callers can pass `claims: "kfd-1,release-passport"` or an
+array to narrow the bundle without hand-writing badge Markdown.
+
 ## CLI
 
 Generate facts as JSON:
@@ -70,9 +84,23 @@ Insert or replace the block:
 buildchain badges readme --write
 ```
 
+Generate only the Buildchain trust badge bundle:
+
+```bash
+buildchain badges bundle --json
+buildchain badges bundle --check
+buildchain badges bundle --write
+```
+
+Narrow the bundle to specific claims:
+
+```bash
+buildchain badges bundle --claims kfd-1,release-passport --write
+```
+
 All commands accept `--cwd <dir>` and `--readme <path>`. Repositories can add
-`buildchain badges readme --check` to CI so badge drift is detected like any
-other generated release-facing surface.
+`buildchain badges bundle --check` or `buildchain badges readme --check` to CI
+so badge drift is detected like any other generated release-facing surface.
 
 ## Configuration
 
@@ -88,6 +116,9 @@ kfd_2 = "planned"
 kfd_3 = "aligned"
 platforms = ["macOS", "Linux", "Windows"]
 workflows = ["verify.yml", "build.yml"]
+
+[badges.bundle]
+claims = ["kfd-1", "kfd-2", "kfd-3", "release-passport"]
 ```
 
 `release_passport` may be a local path or URL. If omitted, Buildchain tries
@@ -154,6 +185,12 @@ Recommended CI gate:
 buildchain badges readme --check
 ```
 
+or, when the repository only wants the Buildchain trust bundle:
+
+```bash
+buildchain badges bundle --check
+```
+
 The check fails when:
 
 - the marker block is missing;

package/docs/release-passport.md

@@ -51,6 +51,9 @@ Additive passport sections:
   policy. It records real CI/release generation and publication times,
   reproducibility inputs, source revision or source-date-epoch, and whether
   timestamp fields participate in the release artifact digest.
+- `buildFacts`: module/product build facts that bind Git source digests,
+  version sources, lifecycle invocations, platforms, outputs, product
+  artifacts, and verification results to the release.
 - `artifacts`: release assets and registry artifacts in one list, each pointing
   back to the evidence file that proves its digest.
 
@@ -97,6 +100,8 @@ buildchain collect github-release \
   --package-set-json package-set.json \
   --anchor-manifest-json libnode.release.json \
   --build-summary-json .buildchain/artifacts/build-summary.json \
+  --build-facts-json .buildchain/facts/native-core.json \
+  --build-facts-json .buildchain/facts/product.json \
   --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
@@ -111,7 +116,12 @@ buildchain collect github-release \
 dist-tag, registry, role, platform, and digest, so agents do not need to stitch
 npm facts back together from the lower-level evidence files.
 `buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the
-build and npm dist-tag evidence chain in the same passport.
+build and npm dist-tag evidence chain in the same passport. `buildFacts[]`
+records first-class module/product build facts, while
+`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,
+ids, and digests for quick audit traversal. See
+[`build-facts.md`](build-facts.md) for the fact collection and verification
+contract.
 
 ### KFD-1 contract-world release gate
 

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
 | 2026-07-06 | open-minor | `v2.8` | 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 | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |
 | 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |
 | 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |

package/docs/web-surface-deployments.md

@@ -376,6 +376,14 @@ records this as `routing.contract =
 `viewerPathPrefix = "/"`, `artifactPathPrefix = "buildchain"`, and
 `directoryIndexResolution = true`.
 
+When a surface uses an S3 object prefix, Buildchain also writes directory-index
+alias objects during apply. The root `dist/buildchain/index.html` is copied to
+the prefix keys `pr-29/buildchain` and `pr-29/buildchain/`, while nested indexes
+such as `dist/buildchain/docs/index.html` are copied to `pr-29/buildchain/docs`
+and `pr-29/buildchain/docs/`. This makes surface-host requests for `/` and
+`/docs/` resolve to the surface's `index.html` files even when the CloudFront
+origin is an S3 REST origin rather than an S3 website endpoint.
+
 It can also execute a previously saved deploy plan. In that mode Buildchain
 recomputes the local artifact hash before running AWS commands and fails closed
 if the artifact no longer matches the saved plan:
@@ -464,13 +472,17 @@ such as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain
 preview host. If a surface has no nested HTML route, Buildchain records only
 the root smoke URL; absence of nested HTML is not a deployment failure. When a
 nested route is present, the check fails closed if a deploy reports success but
-that child page returns 403 or another unexpected status. Production additionally fails if a
-response is unreachable, returns an unexpected status, or still sends
-`x-robots-tag: noindex`. The health check also verifies that each surface
-binding recorded a deployment manifest pointer. The production release passport
-embeds the deploy plan, apply result, production preflight, and health check so
-a reviewer or agent can audit why the production site changed and whether every
-declared host and every existing nested route was actually covered.
+that child page returns 403 or another unexpected status. Surface root checks
+expect the apply result to have written directory-index alias objects, so a
+multi-host preview root such as `https://buildchain-pr-29.preview.libkungfu.dev/`
+must resolve to the surface `index.html`, not the bare prefix directory.
+Production additionally fails if a response is unreachable, returns an
+unexpected status, or still sends `x-robots-tag: noindex`. The health check also
+verifies that each surface binding recorded a deployment manifest pointer. The
+production release passport embeds the deploy plan, apply result, production
+preflight, and health check so a reviewer or agent can audit why the production
+site changed and whether every declared host and every existing nested route was
+actually covered.
 
 ## Cleanup Plans
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.17",
+  "version": "2.9.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -12,6 +12,8 @@
   },
   "exports": {
     ".": "./packages/core/index.js",
+    "./badges": "./packages/core/badges.js",
+    "./build-facts": "./packages/core/build-facts.js",
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",

package/packages/core/README.md

@@ -12,10 +12,12 @@ Current shared surfaces:
 - toolkit observability logging through `@kungfu-tech/buildchain/logging`;
 - toolkit diagnostics and native profile collection through
   `@kungfu-tech/buildchain/diagnostics`;
+- source/version/module/product build facts through
+  `@kungfu-tech/buildchain/build-facts`;
 - release passport creation and verification through
   `@kungfu-tech/buildchain/release-passport`.
-- managed README badge facts and marker blocks through
-  `@kungfu-tech/buildchain/readme-badges`.
+- managed KFD / Release Passport badge bundle facts and README marker blocks
+  through `@kungfu-tech/buildchain/badges`.
 
 ## Toolkit Imports
 
@@ -52,16 +54,30 @@ const { createBuildchainLogger } = await import("@kungfu-tech/buildchain/logging
 const { collectRunnerDiagnostics } = await import("@kungfu-tech/buildchain/diagnostics");
 ```
 
+Build facts consumers can collect source-bound module/product facts before
+publishing and pass those facts into the release passport:
+
+```js
+import { collectModuleBuildFacts, writeBuildFacts } from "@kungfu-tech/buildchain/build-facts";
+
+const fact = collectModuleBuildFacts({ moduleId: "native-core" });
+writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
+```
+
 Web-surface validation stays in core because both local scripts and GitHub
 Actions need the same fail-closed interpretation of project, channel, deploy,
 retention, and staging security declarations.
 
-README badge consumers should import the public subpath and treat Markdown as a
-projection of the returned facts:
+README badge consumers should import the public badge subpath and treat
+Markdown as a projection of the returned facts:
 
 ```js
-import { collectReadmeBadgeFacts, renderReadmeBadgeBlock } from "@kungfu-tech/buildchain/readme-badges";
+import { collectBadgeBundleFacts, renderBadgeBundleBlock } from "@kungfu-tech/buildchain/badges";
 
-const facts = await collectReadmeBadgeFacts({ cwd: process.cwd() });
-const markdown = renderReadmeBadgeBlock(facts);
+const facts = await collectBadgeBundleFacts({ cwd: process.cwd() });
+const markdown = renderBadgeBundleBlock(facts);
 ```
+
+The older `@kungfu-tech/buildchain/readme-badges` subpath remains available for
+callers that need the full README badge surface instead of the default
+KFD-1 / KFD-2 / KFD-3 / Release Passport bundle.

package/packages/core/badges.js

@@ -0,0 +1,18 @@
+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";