Build Facts

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:

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:

buildchain facts module \
  --module native-core \
  --output .buildchain/facts/native-core.json

Override declarative config from a workflow step when needed:

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:

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:

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:

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

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:

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.