@kungfu-tech/buildchain 2.2.1-alpha.0 → 2.2.1-alpha.1

package/dist/site/cli-registry.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-cli-registry",
+  "binary": "buildchain",
+  "npmPackage": "@kungfu-tech/buildchain",
+  "commands": [
+    {
+      "id": "version",
+      "usage": "buildchain version",
+      "purpose": "Print the package or embedded binary version."
+    },
+    {
+      "id": "init",
+      "usage": "buildchain init [--type package|native|web-surface|anchored-package]",
+      "purpose": "Bootstrap a repository with Buildchain configuration and caller workflow files."
+    },
+    {
+      "id": "validate",
+      "usage": "buildchain validate [--require-version-state]",
+      "purpose": "Validate buildchain.toml and declared lifecycle surfaces."
+    },
+    {
+      "id": "doctor",
+      "usage": "buildchain doctor [--json]",
+      "purpose": "Report local integration readiness."
+    },
+    {
+      "id": "lifecycle",
+      "usage": "buildchain lifecycle run <stage>",
+      "purpose": "Run configured lifecycle commands and write deterministic artifact manifests."
+    },
+    {
+      "id": "release-dry-run",
+      "usage": "buildchain release --dry-run --target-ref <ref>",
+      "purpose": "Explain what a channel merge would publish before the PR is merged."
+    },
+    {
+      "id": "collect-github-release",
+      "usage": "buildchain collect github-release --tag <tag>",
+      "purpose": "Collect release assets into a release passport."
+    },
+    {
+      "id": "verify-release-passport",
+      "usage": "buildchain verify release-passport <file-or-url>",
+      "purpose": "Fail closed unless a release passport and its evidence are complete."
+    },
+    {
+      "id": "logging",
+      "usage": "buildchain log|mark|span|verify observability-log",
+      "purpose": "Emit timestamped build events, summarize logs, and enforce required phases."
+    },
+    {
+      "id": "npm-dry-run",
+      "usage": "buildchain npm dry-run --json",
+      "purpose": "Verify npm publish shape before a release transaction."
+    }
+  ]
+}

package/dist/site/product-mechanism.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-product-mechanism",
+  "name": "Buildchain",
+  "formalName": "Buildchain by Kungfu",
+  "category": "Buildchain Release Passport",
+  "purpose": "A mature product release record for artifacts that users or agents depend on.",
+  "executionSubstrate": "GitHub Actions, protected refs, exact tags, GitHub Releases, npm Trusted Publishing, and machine-readable evidence.",
+  "notA": [
+    "a replacement CI/CD platform",
+    "a binary-only release tool",
+    "a workflow file collection as the product boundary"
+  ],
+  "proofCases": [
+    "multi-platform CLI archives",
+    "npm package publication",
+    "native and multi-artifact release passports",
+    "site facts consumed by buildchain.libkungfu.dev"
+  ]
+}

package/dist/site/release-model.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-release-model",
+  "exactTags": "v-prefixed exact tags are immutable release records.",
+  "floatingTags": "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
+  "channelBranches": [
+    "dev/vX/vX.Y",
+    "alpha/vX/vX.Y",
+    "release/vX/vX.Y",
+    "publish-gate/major"
+  ],
+  "releasePassport": {
+    "entrypoint": "buildchain.release.json",
+    "bundle": "buildchain-release-bundle.tar.gz",
+    "contract": "kungfu-buildchain-release-passport"
+  },
+  "npm": {
+    "package": "@kungfu-tech/buildchain",
+    "command": "./bin/buildchain.mjs",
+    "versionSource": "package.json#version",
+    "alphaDistTag": "alpha",
+    "stableDistTag": "latest"
+  }
+}

package/dist/site/release-provenance.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-release-provenance",
+  "package": {
+    "name": "@kungfu-tech/buildchain",
+    "versionSource": "package.json#version",
+    "bin": {
+      "buildchain": "./bin/buildchain.mjs"
+    },
+    "exports": {
+      ".": "./packages/core/index.js",
+      "./core": "./packages/core/index.js",
+      "./logging": "./packages/core/logging.js",
+      "./release-passport": "./packages/core/release-passport.js",
+      "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
+      "./site/site-manifest.json": "./dist/site/site-manifest.json",
+      "./site/cli-registry.json": "./dist/site/cli-registry.json",
+      "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
+      "./site/release-model.json": "./dist/site/release-model.json",
+      "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
+      "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
+      "./site/release-provenance.json": "./dist/site/release-provenance.json",
+      "./site/agent-index.json": "./dist/site/agent-index.json",
+      "./package.json": "./package.json"
+    }
+  },
+  "repository": "https://github.com/kungfu-systems/buildchain",
+  "packageManager": "pnpm@11.7.0",
+  "inventoryRelease": "buildchain-v2",
+  "stableRefs": {
+    "actions": "kungfu-systems/buildchain/actions/<name>@v2",
+    "workflows": "kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2"
+  }
+}

package/dist/site/site-manifest.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-site-manifest",
+  "product": {
+    "name": "Buildchain",
+    "formalName": "Buildchain by Kungfu",
+    "category": "Buildchain Release Passport"
+  },
+  "package": {
+    "name": "@kungfu-tech/buildchain",
+    "versionSource": "package.json#version"
+  },
+  "entrypoint": "buildchain-site.json",
+  "docs": [
+    {
+      "id": "install",
+      "title": "Install and verify Buildchain",
+      "path": "docs/install.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "release-passport",
+      "title": "Release Passport protocol",
+      "path": "docs/release-passport.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "binary-distribution",
+      "title": "Binary distribution contract",
+      "path": "docs/binary-distribution.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "toolkit-observability",
+      "title": "Toolkit observability",
+      "path": "docs/toolkit-observability.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "site-bundle-contract",
+      "title": "Site bundle contract",
+      "path": "docs/site-bundle-contract.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "product-mechanism",
+      "title": "Product mechanism",
+      "path": "docs/product-mechanism.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "cli",
+      "title": "CLI and npm package",
+      "path": "docs/cli.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "lifecycle-protocol",
+      "title": "Lifecycle protocol",
+      "path": "docs/lifecycle-protocol.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "reusable-build-surface",
+      "title": "Reusable build surface",
+      "path": "docs/reusable-build-surface.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "publish-transaction",
+      "title": "Publish transaction",
+      "path": "docs/publish-transaction.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "release-governance",
+      "title": "Release governance",
+      "path": "docs/release-governance.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "release-flow",
+      "title": "Release flow",
+      "path": "docs/release-flow.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "versioning",
+      "title": "Versioning",
+      "path": "docs/versioning.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "web-surface-deployments",
+      "title": "Web surface deployments",
+      "path": "docs/web-surface-deployments.md",
+      "plane": "use",
+      "exists": true
+    }
+  ],
+  "facts": [
+    "cli-registry.json",
+    "workflow-registry.json",
+    "release-model.json",
+    "artifact-schemas.json",
+    "product-mechanism.json",
+    "release-provenance.json",
+    "agent-index.json"
+  ]
+}

package/dist/site/workflow-registry.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-workflow-registry",
+  "workflows": [
+    {
+      "id": "build",
+      "path": ".github/workflows/.build.yml",
+      "surface": "reusable-build",
+      "status": "active"
+    },
+    {
+      "id": "web-surface",
+      "path": ".github/workflows/.web-surface.yml",
+      "surface": "site-app-deployment",
+      "status": "active"
+    },
+    {
+      "id": "buildchain-ref-promotion",
+      "path": ".github/workflows/buildchain-ref-promotion.yml",
+      "surface": "release-governance",
+      "status": "active"
+    },
+    {
+      "id": "binary-distribution",
+      "path": ".github/workflows/binary-distribution.yml",
+      "surface": "release-passport",
+      "status": "active"
+    }
+  ],
+  "actions": [
+    {
+      "id": "validate-config",
+      "path": "actions/validate-config",
+      "status": "active"
+    },
+    {
+      "id": "run-lifecycle",
+      "path": "actions/run-lifecycle",
+      "status": "active"
+    },
+    {
+      "id": "promote-buildchain-ref",
+      "path": "actions/promote-buildchain-ref",
+      "status": "active"
+    }
+  ]
+}

package/docs/MAP.md

@@ -17,8 +17,10 @@ running artifact), *use* (consume / extend) - and a **status**:
 | Your question | Document | Plane | Status |
 | --- | --- | --- | --- |
 | What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |
+| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |
 | How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |
-| How do I install or run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |
+| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |
+| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |
 | How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
 | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
@@ -27,7 +29,10 @@ running artifact), *use* (consume / extend) - and a **status**:
 | 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 publish or verify binary release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | 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 |
+| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md) | use | stable |
@@ -53,10 +58,18 @@ running artifact), *use* (consume / extend) - and a **status**:
 - **libnode / native artifacts / self-hosted runner matrix** ->
   [`reusable-build-surface.md`](reusable-build-surface.md) and
   [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).
+- **standalone binary install / platform archives / GitHub Release bundle** ->
+  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),
+  and [`release-passport.md`](release-passport.md).
 - **Trusted Publishing / npm / publish evidence / recovery** ->
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
 - **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->
-  [`release-passport.md`](release-passport.md) and [`cli.md`](cli.md).
+  [`release-passport.md`](release-passport.md),
+  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).
+- **Buildchain logging / timestamps / consumer build phase timing** ->
+  [`toolkit-observability.md`](toolkit-observability.md) and [`cli.md`](cli.md).
+- **buildchain.libkungfu.dev / package-owned site facts** ->
+  [`site-bundle-contract.md`](site-bundle-contract.md).
 - **sites / web previews / staging / production gates** ->
   [`web-surface-deployments.md`](web-surface-deployments.md).
 

package/docs/binary-distribution.md

@@ -0,0 +1,70 @@
+# Binary Distribution
+
+Buildchain's binary distribution is the first high-pressure proof case for the
+Release Passport protocol. It is not the boundary of the product.
+
+## Asset Rules
+
+GitHub Release assets use platform-specific archives:
+
+- `buildchain-x86_64-unknown-linux-gnu.tar.gz`
+- `buildchain-aarch64-apple-darwin.tar.gz`
+- `buildchain-x86_64-pc-windows-msvc.zip`
+
+The release lane does not upload loose top-level `buildchain` or
+`buildchain.exe` assets. Linux and macOS both name the executable `buildchain`
+inside their archives, so top-level loose assets would collide when matrix
+artifacts are merged.
+
+Each archive is accompanied by:
+
+- a platform manifest from the standalone binary builder;
+- platform observability event logs and summaries;
+- `checksums.txt`;
+- Release Passport evidence files;
+- `buildchain-release-bundle.tar.gz`;
+- `buildchain-release-bundle.json`.
+
+## Runner Policy
+
+Production binary builds use GitHub-hosted runners:
+
+- `ubuntu-24.04`
+- `macos-latest`
+- `windows-2022`
+
+Self-hosted runners are compatibility fixtures. They can prove that consumers
+with private runner fleets can still use the protocol, but Buildchain's public
+binary distribution should stay reproducible on GitHub-hosted runners.
+
+## Evidence Bundle
+
+`buildchain-release-bundle.tar.gz` groups release assets and passport evidence
+under one archive:
+
+```text
+buildchain-release-bundle/
+  release-assets/
+  release-passport/
+  buildchain-release-bundle.index.json
+```
+
+`buildchain-release-bundle.json` records the bundle digest and every included
+file digest. Consumers can download the bundle when they want one artifact for
+offline review, mirroring, or site ingestion.
+
+## Local Smoke
+
+```bash
+node scripts/build-standalone-binary.mjs --version v0.0.0-local --output-dir dist/binary
+node bin/buildchain.mjs collect github-release \
+  --tag v0.0.0-local \
+  --assets-dir dist/binary \
+  --output-dir .buildchain/release-passport
+node scripts/create-release-bundle.mjs \
+  --assets-dir dist/binary \
+  --passport-dir .buildchain/release-passport \
+  --output-dir .buildchain/release-passport \
+  --tag v0.0.0-local
+```
+

package/docs/install.md

@@ -0,0 +1,78 @@
+# Install and Verify Buildchain
+
+Buildchain can be consumed as a standalone binary, an npm package, or a
+repository workflow surface. In every case, verify the release record before
+adopting a new version.
+
+## Standalone Binary
+
+Use the archive that matches the platform:
+
+| Platform | Asset |
+| --- | --- |
+| Linux x64 | `buildchain-x86_64-unknown-linux-gnu.tar.gz` |
+| macOS arm64 | `buildchain-aarch64-apple-darwin.tar.gz` |
+| Windows x64 | `buildchain-x86_64-pc-windows-msvc.zip` |
+
+Linux example:
+
+```bash
+tag=v2.2.1
+base="https://github.com/kungfu-systems/buildchain/releases/download/${tag}"
+curl -LO "${base}/buildchain-x86_64-unknown-linux-gnu.tar.gz"
+curl -LO "${base}/buildchain.release.json"
+curl -LO "${base}/artifact-evidence.json"
+npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
+tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz
+./buildchain version
+```
+
+Windows example:
+
+```powershell
+$tag = "v2.2.1"
+$base = "https://github.com/kungfu-systems/buildchain/releases/download/$tag"
+Invoke-WebRequest "$base/buildchain-x86_64-pc-windows-msvc.zip" -OutFile buildchain.zip
+Invoke-WebRequest "$base/buildchain.release.json" -OutFile buildchain.release.json
+Invoke-WebRequest "$base/artifact-evidence.json" -OutFile artifact-evidence.json
+npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
+Expand-Archive buildchain.zip -DestinationPath .
+.\buildchain.exe version
+```
+
+The GitHub Release page does not publish loose top-level `buildchain` or
+`buildchain.exe` files. The executable is inside each platform archive.
+
+## npm Package
+
+```bash
+npm install -D @kungfu-tech/buildchain
+npx buildchain version
+npx buildchain doctor --json
+```
+
+Alpha releases publish to the `alpha` npm dist-tag. Stable releases publish to
+`latest`. Both are created by the protected Buildchain promotion transaction.
+
+## Repository Integration
+
+```bash
+npx @kungfu-tech/buildchain init --type package --package-manager pnpm
+npx @kungfu-tech/buildchain validate --require-version-state
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2
+```
+
+Use `buildchain.toml` to declare lifecycle commands. The commands may use Node
+package managers or non-Node tools such as pip, Conan, CMake, Make, or project
+scripts.
+
+## Verify a Release Passport
+
+```bash
+buildchain verify release-passport buildchain.release.json
+buildchain explain release --passport buildchain.release.json --for agent --json
+```
+
+The verifier fails closed when the passport or its sibling evidence files are
+missing required fields or mismatching artifact digests.
+

package/docs/product-mechanism.md

@@ -0,0 +1,56 @@
+# Product Mechanism
+
+Buildchain's product boundary is the Release Passport: a mature product release
+record for artifacts that users or agents depend on.
+
+## Design Pressure
+
+Many repositories can already compile, test, and upload artifacts. The hard
+problem is proving what a release means after it has been promoted:
+
+- which reviewed source state was released;
+- which exact version-state commit and tag represent that release;
+- which artifacts were created;
+- which checks and publish steps were allowed to run;
+- which floating channel refs now point at that release;
+- how another human or agent can verify, explain, mirror, or roll back the
+  release without asking the maintainer to reconstruct the story.
+
+Buildchain uses GitHub as the substrate for this proof. It does not require a
+project to abandon its existing build system.
+
+## What the Passport Solves
+
+The passport turns a release into a durable record:
+
+- exact tags are immutable release identities;
+- floating refs are explicitly machine-updated channel pointers;
+- version files are changed by version-state commits, not by unpublished local
+  edits;
+- build and publish evidence is machine-readable;
+- release checks fail closed when evidence is incomplete;
+- site and documentation facts can be generated from the package instead of
+  being copied by hand.
+
+## Why Binary Distribution Matters
+
+Binary artifacts are a strong proof case because users and agents may execute
+them directly. That makes checksums, runner facts, package evidence, and
+rollback instructions more urgent.
+
+The protocol is not binary-bound. The same release passport model applies to
+npm packages, Python wheels, OCI images, native SDK archives, web-surface
+deployments, and multi-artifact product releases.
+
+## Naming
+
+Use these names consistently:
+
+- Product name: `Buildchain`
+- Formal first mention: `Buildchain by Kungfu`
+- Category anchor: `Buildchain Release Passport`
+- Core release record: `buildchain.release.json`
+
+Avoid defining Buildchain as only a workflow collection, a binary distributor,
+or a replacement CI/CD platform.
+

package/docs/release-passport.md

@@ -1,8 +1,12 @@
-# Release Passport and Binary Distribution
+# Release Passport
 
-Buildchain v2.2 adds a GitHub-native release passport protocol for binary and
-multi-artifact products. The protocol is meant for projects that want release
-evidence without migrating their whole CI/CD system to Buildchain.
+Buildchain Release Passport is the core product mechanism: a mature product
+release record for artifacts that users or agents depend on.
+
+The protocol is GitHub-native because it uses protected refs, reviewed
+promotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and
+machine-readable evidence. A project can keep its existing build system and use
+Buildchain to make the release record auditable.
 
 ## Contract
 
@@ -16,7 +20,10 @@ P0 protocol artifacts:
 - `artifact-evidence.json`
 - `impact.json`
 - `agent-index.json`
+- `check-report.json`
 - `llms.txt`
+- `buildchain-release-bundle.json`
+- `buildchain-release-bundle.tar.gz`
 
 `buildchain.release.json` is the first file an agent should read. It points to
 artifact evidence, impact, recovery, product mechanism, and agent index facts.
@@ -28,6 +35,11 @@ the Buildchain logging API and CLI:
 - `buildchain-log-events-passport.jsonl`
 - `buildchain-log-summary-passport.json`
 
+`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers
+that want one file for offline inspection, mirroring, or site ingestion.
+`buildchain-release-bundle.json` records its digest and the digest of every
+included file.
+
 ## Runner Policy
 
 Production binary distribution should use GitHub-hosted runners by default:
@@ -81,7 +93,20 @@ Initial binary distribution stays lightweight:
 - GitHub Release assets.
 - `checksums.txt`.
 - release passport artifacts.
-- install scripts and Homebrew tap fixtures after the passport is reliable.
+- a single release evidence bundle.
+- install scripts and Homebrew tap fixtures after the passport path is reliable.
+
+Buildchain publishes platform-specific archives, not loose top-level
+executables:
+
+- `buildchain-x86_64-unknown-linux-gnu.tar.gz`
+- `buildchain-aarch64-apple-darwin.tar.gz`
+- `buildchain-x86_64-pc-windows-msvc.zip`
+
+The executable name inside each archive stays natural for the platform
+(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not
+uploaded, because Linux and macOS would otherwise collide when GitHub Actions
+matrix artifacts are merged.
 
 Heavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or
 asdf are out of the P0/P1 scope until there is real external demand.
@@ -97,3 +122,6 @@ steps with `buildchain mark`, `buildchain span`,
 a hard release gate: missing events, error events, or missing required phases
 fail the job before assets are uploaded. The verified logs are release assets
 and are covered by the release passport digest checks.
+
+See also [`binary-distribution.md`](binary-distribution.md) for asset naming and
+bundle details, and [`install.md`](install.md) for consumer commands.