Buildchain release trust and mechanics

primary

Install and Verify

For v3, use the published npm package and verify the release passport before trusting release evidence:

curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json
curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json
npx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json
npx @kungfu-tech/buildchain@3.0.0 version

The v3.0.0 release publishes evidence assets but no standalone platform archives. The names below describe the optional archive contract used by legacy release lines:

• buildchain-x86_64-unknown-linux-gnu.tar.gz
• buildchain-aarch64-apple-darwin.tar.gz
• buildchain-x86_64-pc-windows-msvc.zip
• checksums.txt
• buildchain.release.json
• artifact-evidence.json
• product-mechanism.json
• impact.json
• agent-index.json
• check-report.json
• llms.txt
• buildchain-release-bundle.tar.gz
• buildchain-release-bundle.json

Loose top-level buildchain and buildchain.exe assets are intentionally not published. The executable lives inside each platform archive, which prevents Linux and macOS artifacts from overwriting each other in a merged release lane.

For npm consumers:

npm install -D @kungfu-tech/buildchain
npx buildchain version
npx buildchain doctor --json

The npm package is also the Buildchain toolkit. Use the command when a workflow or shell step needs an executable; use the ESM APIs directly from JavaScript build scripts. JavaScript callers should import the package instead of spawning the CLI or unpacking the standalone binary:

import {
  createBuildchainLogger,
  verifyBuildchainLogEvents,
} from "@kungfu-tech/buildchain/logging";

const logger = createBuildchainLogger({
  path: ".buildchain/logs/native-build.jsonl",
  source: "user",
  component: "native-build",
});

await logger.span("native.compile", { phase: "build" }, async () => {
  await compileNativeTargets();
});

const report = verifyBuildchainLogEvents({
  path: logger.path,
  requireEvents: ["native.compile.start", "native.compile.end"],
});

The package also ships dist/site/ as the Buildchain-owned fact source for buildchain.libkungfu.dev.

Repositories can also generate README status badges from Buildchain-owned facts instead of hand-maintaining badge Markdown:

buildchain badges bundle --check
buildchain badges bundle --write
buildchain badges readme --check
buildchain badges readme --write

primary

Use Buildchain

Bootstrap a repository:

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/v3/v3.0

Buildchain supports package and non-package projects through .buildchain/buildchain.toml. Legacy root buildchain.toml files remain readable, but new consumers should keep Buildchain-owned files under .buildchain/:

.buildchain/buildchain.toml
.buildchain/contract-lock.json
.buildchain/kfd/kfd-3/surfaces.json
.buildchain/release-passport/buildchain.release.json

Lifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom scripts, or any other command that can run in the repository checkout.

The KFD entrypoint is buildchain kfd. Buildchain provides concrete KFD-1 contract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows, plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These gates preserve product-owned qualification and support decisions; they do not turn a schema-valid record into certification or shipped support.

Buildchain’s active GitHub Action surface is deliberately small:

• actions/validate-config
• actions/run-lifecycle
• actions/promote-buildchain-ref
• actions/report-buildchain-issue

The active reusable workflow surfaces are:

• .github/workflows/.gate-profile.yml for project-neutral Shifu Gate profile planning, capability-aware runner dispatch, receipt validation, and one stable aggregate check;
• .github/workflows/.auditable-demo.yml for exact-artifact demo qualification, transcript-bound renderer smoke, and optional media rendering from the exact passing Gate bundle;
• .github/workflows/.build.yml for deterministic multi-platform build and artifact contracts;
• .github/workflows/build.yml for the single-config channel router that uses vN-alpha during development/prerelease work and vN for stable releases;
• .github/workflows/release-candidate-promote.yml for post-merge promote-only publication from a PR-stage release candidate, without a second heavy build;
• .github/workflows/.web-surface.yml for preview, staging, production, and cleanup plans for site/app repositories;
• .github/workflows/buildchain-ref-promotion.yml for protected release promotion and version-state transactions;
• .github/workflows/binary-distribution.yml for Buildchain’s own release passport proof case.

Stable consumers should reference actions and workflows through floating major refs after reviewing the exact release passport:

uses: kungfu-systems/buildchain/actions/validate-config@v3

uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3

uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3