@kungfu-tech/buildchain 2.8.16-alpha.1 → 2.8.16

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-07T14:53:34.643Z",
-  "publishedAt": "2026-07-07T14:53:34.643Z",
+  "generatedAt": "2026-07-07T15:39:12.336Z",
+  "publishedAt": "2026-07-07T15:39:12.336Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "3f3734348d6c4217a0aaea924b3537c519ab141a",
+  "sourceRevision": "19d02b246e1242f10bdb93a2a85d2f38b25c79b0",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.8.16-alpha.1",
+    "version": "2.8.16",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:46fa21a0fd496ba1b2afc4209e4e923aba3656e4fe83f757108f24ceef977741"
+      "digest": "sha256:f4300eed89765cee0df38eb92de4d9d3adce4fbf954c735aead3bea74f05d975"
     },
     {
       "id": "install",
@@ -87,6 +87,14 @@
       "exists": true,
       "digest": "sha256:3f4a44ea7f3b70cadc78a343fe53ade74b78fa369c19630cc9b926c1e460f66f"
     },
+    {
+      "id": "homebrew",
+      "title": "Homebrew distribution indexes",
+      "path": "docs/homebrew.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:2fc4e8411f35ca86d19d61c7843b9a1fa440f7afea25df13d3aa03342f09f90c"
+    },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",
@@ -157,7 +165,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:c7928797300772ed5240ef69529af99298c32dbb74c3be7fbcad5ae0786576ce"
+      "digest": "sha256:cfb0bf32f2b8b44bf352e79c27e34b7980e0f66e5fa10e4f202975fbb4780ad1"
     },
     {
       "id": "lifecycle-protocol",
@@ -221,7 +229,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367"
+      "digest": "sha256:4c7334fe2284fec3c1249124b0ff85f1242eb7a76d4b2c537c8b2cb6e0e598c1"
     }
   ],
   "facts": [

package/docs/MAP.md

@@ -26,6 +26,7 @@ manuals explain those facts and give operator examples.
 | 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) |
+| 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) |
 
@@ -61,6 +62,7 @@ replace them.
 | 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 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 |
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
@@ -119,6 +121,8 @@ replace them.
   [`release-propagation.md`](release-propagation.md).
 - **README status badges / KFD badge blocks / 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).
 - **KFD-1 contract worlds / byte-for-byte release gates** ->
   [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).
 - **KFD-2 public release trust claim audit** ->

package/docs/cli.md

@@ -64,6 +64,7 @@ Current public import families include:
 ```js
 import * as buildchain from "@kungfu-tech/buildchain";
 import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+import { checkHomebrewTap } from "@kungfu-tech/buildchain/homebrew";
 import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
 import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
@@ -91,6 +92,8 @@ Supported presets:
   validation, observation, contract publication, and downstream propagation
   planning without default mutation. Provider adapters expose built-in command
   plans by default, and only configured `[infra.commands]` hooks can execute.
+- `--type distribution-index` for Homebrew taps and other index repositories
+  whose files are projections of upstream release passport evidence.
 - `--type anchored-package` for packages whose version is anchored to an
   explicit upstream release manifest.
 
@@ -245,10 +248,10 @@ version against configured version files and the anchor manifest. The JSON
 result is shaped for future `buildchain.libkungfu.dev` fact ingestion.
 
 `buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,
-`buildchain publish-source`, `buildchain badges`, and `buildchain build-contract`
-route to the same implementation used by Buildchain's package APIs or GitHub
-Actions workflows. This keeps local inspection and CI behavior on the same
-implementation path.
+`buildchain publish-source`, `buildchain badges`, `buildchain homebrew`, and
+`buildchain build-contract` route to the same implementation used by
+Buildchain's package APIs or GitHub Actions workflows. This keeps local
+inspection and CI behavior on the same implementation path.
 
 Generate, check, or update the managed README badge block:
 
@@ -266,6 +269,22 @@ 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.
 
+Generate or check Homebrew tap projections from upstream release passports:
+
+```bash
+buildchain homebrew update-formula \
+  --package buildchain \
+  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \
+  --write
+
+buildchain homebrew check --json
+```
+
+`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from
+upstream release passport evidence. `check` fails closed when the Formula,
+manifest, artifact digests, or KFD status drift from the upstream passport. See
+[`homebrew.md`](homebrew.md) for the distribution-index project contract.
+
 `buildchain collect github-release` creates a release passport bundle from
 GitHub Release assets or a local asset directory:
 

package/docs/homebrew.md

@@ -0,0 +1,116 @@
+# Homebrew Distribution Indexes
+
+Buildchain treats a Homebrew tap as a distribution-index project: the tap
+contains Formula or Cask files, but those files are projections of upstream
+release passports. Version, download URLs, SHA-256 digests, KFD status, and
+evidence links come from the upstream product release, not from hand-maintained
+tap prose.
+
+## Configuration
+
+Use `project.type = "distribution-index"` for tap repositories:
+
+```toml
+schema = 1
+
+[project]
+type = "distribution-index"
+name = "homebrew-tap"
+
+[lifecycle.verify]
+command = "buildchain homebrew check"
+```
+
+The tap manifest is the repository-owned declaration of which upstream releases
+are indexed. Buildchain writes `tap-manifest.json` as a machine-readable
+projection:
+
+```json
+{
+  "schema": 1,
+  "contract": "kungfu-buildchain-homebrew-tap-manifest",
+  "kind": "homebrew-tap",
+  "entries": [
+    {
+      "type": "formula",
+      "name": "buildchain",
+      "path": "Formula/buildchain.rb",
+      "upstream": {
+        "repository": "kungfu-systems/buildchain",
+        "tag": "v2.8.15",
+        "releasePassportUrl": "https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json"
+      },
+      "version": "2.8.15",
+      "kfd": {
+        "kfd-1": "passed",
+        "kfd-2": "passed",
+        "kfd-3": "passed"
+      },
+      "artifacts": [
+        {
+          "platform": "darwin-arm64",
+          "url": "https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain-aarch64-apple-darwin.tar.gz",
+          "sha256": "..."
+        }
+      ]
+    }
+  ]
+}
+```
+
+## CLI
+
+Update a formula and manifest from an upstream passport:
+
+```bash
+buildchain homebrew update-formula \
+  --package buildchain \
+  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \
+  --write
+```
+
+Check that the tap still matches upstream evidence:
+
+```bash
+buildchain homebrew check --json
+```
+
+`check` fails closed when:
+
+- the upstream release passport or its sibling evidence does not verify;
+- `Formula/buildchain.rb` drifts from the projected version, URLs, or SHA-256
+  digests;
+- `tap-manifest.json` drifts from the projected upstream evidence;
+- the tap claims KFD-1, KFD-2, or KFD-3 passed without a verified upstream
+  passport section.
+
+## Node API
+
+Use the public `@kungfu-tech/buildchain/homebrew` export:
+
+```js
+import {
+  collectHomebrewTapFacts,
+  renderHomebrewFormula,
+  checkHomebrewTap,
+  updateHomebrewTap,
+} from "@kungfu-tech/buildchain/homebrew";
+```
+
+The API is the single implementation source. The CLI is a thin wrapper over
+these functions, so CI and local update commands evaluate the same facts.
+
+## Trust Model
+
+Formula metadata is not source of truth. A tap entry may claim `kfd-1`,
+`kfd-2`, or `kfd-3` passed only when the upstream release passport verifies and
+the corresponding passport section is `status = "passed"`. If verification
+fails, Buildchain downgrades the projected KFD status to `unverified` and
+`buildchain homebrew check` fails.
+
+In short: KFD passed in a tap means the upstream release passport passed, not
+that the tap author typed a passing status.
+
+This makes Homebrew taps suitable for automated distribution-index CI: the tap
+can move quickly while still proving that every download URL and digest is
+bound to release passport evidence.

package/docs/web-surface-deployments.md

@@ -264,12 +264,32 @@ rollback:
       "alias": "sha-abcdef123456",
       "url": "https://sha-abcdef123456.preview.libkungfu.dev",
       "sourcePath": "/",
+      "artifactPathPrefix": "",
+      "viewerPathPrefix": "/",
+      "directoryIndex": "index.html",
+      "directoryIndexResolution": true,
       "canonicalUrl": "https://libkungfu.dev",
       "bucket": "libkungfu-dev-preview",
       "distributionId": "E-PREVIEW",
       "originPath": "",
       "objectPrefix": "sha-abcdef123456",
       "manifestKey": ".buildchain/deployments/sha-abcdef123456/hub.json",
+      "routing": {
+        "contract": "kungfu-buildchain-web-surface-path-prefix-rewrite",
+        "viewerPathPrefix": "/",
+        "artifactPathPrefix": "",
+        "objectPrefix": "sha-abcdef123456",
+        "directoryIndex": "index.html",
+        "directoryIndexResolution": true
+      },
+      "smokeUrls": [
+        {
+          "kind": "root",
+          "requestPath": "/",
+          "url": "https://sha-abcdef123456.preview.libkungfu.dev/",
+          "required": true
+        }
+      ],
       "noindex": true,
       "accessControl": "none"
     }
@@ -343,6 +363,19 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-staging-apply.json
 ```
 
+For multi-surface sites, each surface host is treated as a root-relative view
+of that surface's artifact path prefix. For example, a `buildchain` surface with
+`path = "/buildchain/"` and preview URL
+`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree
+`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer
+request for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore
+resolves against the artifact's `dist/buildchain/docs/index.html`, not
+`dist/docs/index.html` and not the hub surface root. The deployment manifest
+records this as `routing.contract =
+"kungfu-buildchain-web-surface-path-prefix-rewrite"` with
+`viewerPathPrefix = "/"`, `artifactPathPrefix = "buildchain"`, and
+`directoryIndexResolution = true`.
+
 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:
@@ -414,7 +447,7 @@ The production preflight checks that:
   `kfd.libkungfu.dev`;
 - DNS resolves for every surface host.
 
-After production apply, the workflow runs:
+After preview, staging, and production apply, the workflow runs:
 
 ```bash
 node scripts/web-surface.mjs \
@@ -424,13 +457,18 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-production-health.json
 ```
 
-The health check fetches every surface URL from the apply result and fails
-production if a response is unreachable, returns an unexpected status, or still
-sends `x-robots-tag: noindex`. It 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 was actually covered.
+The health check fetches every surface root URL and the nested smoke URLs
+recorded in each surface binding. Nested smoke URLs are derived from the
+artifact files under the surface path prefix, with directory index resolution
+such as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain
+preview host. This fails closed when a deploy reports success but a 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 nested route was actually covered.
 
 ## Cleanup Plans
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.16-alpha.1",
+  "version": "2.8.16",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,6 +16,7 @@
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./diagnostics": "./packages/core/diagnostics.js",
+    "./homebrew": "./packages/core/homebrew.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./readme-badges": "./packages/core/readme-badges.js",
     "./logging": "./packages/core/logging.js",

package/packages/core/buildchain-config.js

@@ -9,7 +9,7 @@ const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
 const SUPPORTED_VERSION_FILE_TYPES = new Set(["json", "toml", "regex"]);
 const SUPPORTED_VERSION_STRATEGIES = new Set(["semver", "anchored"]);
 const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
-const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract"]);
+const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract", "distribution-index"]);
 const SUPPORTED_PUBLISH_MODES = new Set(["publish-final-version", "promote-existing-version"]);
 const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
@@ -237,7 +237,7 @@ function normalizeProjectSection(project) {
   assertPlainObject(project, "project");
   const type = assertString(project.type, "project.type");
   if (!SUPPORTED_PROJECT_TYPES.has(type)) {
-    throw new Error("project.type must be one of package, web-surface, or infra-contract");
+    throw new Error("project.type must be one of package, web-surface, infra-contract, or distribution-index");
   }
   const normalized = { type };
   for (const key of ["name", "site"]) {

package/packages/core/buildchain-contract.js

@@ -310,6 +310,8 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "validate",
         "lifecycle",
         "badges readme",
+        "homebrew update-formula",
+        "homebrew check",
         "collect github-release",
         "verify release-passport",
         "release-propagation",
@@ -320,6 +322,34 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "README badge block checks and writes are generated from machine-readable repository facts",
       ],
     }),
+    surface(root, {
+      id: "homebrew-distribution-index",
+      kind: "node-api",
+      path: "packages/core/homebrew.js",
+      requiredInputs: ["upstream release passport"],
+      requiredOutputs: [
+        "kungfu-buildchain-homebrew-tap-facts",
+        "kungfu-buildchain-homebrew-tap-manifest",
+        "Formula/*.rb",
+      ],
+      breakingDefaults: {
+        projectType: "distribution-index",
+        tapManifest: "tap-manifest.json",
+        kfdPassedSource: "verified upstream release passport",
+      },
+      optionalInputs: [
+        "buildchain.toml [project] type=distribution-index",
+        "Formula path",
+        "manifest path",
+        "release passport URL or local path",
+      ],
+      guarantees: [
+        "Formula metadata is a deterministic projection of upstream release passport evidence",
+        "tap-manifest.json is checked against upstream version, URLs, SHA-256 digests, and KFD status",
+        "KFD passed claims fail closed unless the upstream release passport verifies the corresponding section",
+        "CLI and JavaScript callers use the same Node API implementation",
+      ],
+    }),
     surface(root, {
       id: "readme-badge-facts",
       kind: "node-api",

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

@@ -12,6 +12,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
+  { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
   { id: "binary-distribution", title: "Binary distribution contract", path: "docs/binary-distribution.md", plane: "verify" },
   { id: "consumer-issue-reporting", title: "Consumer issue reporting", path: "docs/consumer-issue-reporting.md", plane: "use" },
   { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
@@ -70,6 +71,7 @@ const EXTRA_KFD1_FILES = Object.freeze([
   "package.json",
   "bin/buildchain.mjs",
   "packages/core/index.js",
+  "packages/core/homebrew.js",
   "packages/core/release-propagation.js",
   "scripts/generate-site-bundle.mjs",
   "scripts/ensure-github-release.mjs",
@@ -226,6 +228,22 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/buildchain-contract.json",
       ],
     },
+    {
+      id: "claim:buildchain-homebrew-distribution-index",
+      claim: "Buildchain Homebrew tap support generates and verifies Formula metadata as a distribution-index projection of upstream release passport evidence.",
+      sourcePaths: [
+        "packages/core/homebrew.js",
+        "bin/buildchain.mjs",
+        "docs/homebrew.md",
+        "docs/cli.md",
+        "packages/core/buildchain-config.js",
+      ],
+      artifactPaths: [
+        "dist/site/node-api-registry.json",
+        "dist/site/manual-registry.json",
+        "dist/site/buildchain-contract.json",
+      ],
+    },
     {
       id: "claim:buildchain-floating-contract-lock",
       claim: "Consumers using floating Buildchain refs can lock the observed runtime contract and receive drift checks before expensive build or publish work proceeds.",