KFD Support

KFD Support

Buildchain implements KFD support as release evidence and product capability facts, not as README prose. The machine-readable sources are:

• dist/site/kfd-claims.json for Buildchain-owned public claims and KFD-3 collaboration surfaces;
• dist/site/public-surface-audit.json for reverse enumeration of exposed CLI, workflow, action, site, and documented command surfaces;
• buildchain.release.json plus its kfd-support.json sibling for release-specific KFD-1/2/3 evidence and the exact KFD-1…13 support projection;
• .buildchain/buildchain.toml for repository-owned Buildchain configuration;
• .buildchain/kfd/kfd-2/registry.json for product-owned KFD-2 public claim declarations;
• .buildchain/kfd/kfd-3/surfaces.json for product-owned KFD-3 surface registration;
• .buildchain/contract-lock.json for accepted floating runtime contracts.

Buildchain still reads the legacy root files buildchain.toml, buildchain.contract-lock.json, buildchain.kfd3.json, and the historical .buildchain/kfd/kfd-3-surfaces.json registry so existing consumers can run buildchain kfd migrate-layout --write. New repositories should keep repo-owned Buildchain files under .buildchain/, with all KFD evidence under .buildchain/kfd/.

Unified Namespace

KFD support is exposed through one first-class namespace:

buildchain kfd status --json
buildchain kfd migrate-layout --write
buildchain kfd schema list --json
buildchain kfd 1 witness --json
buildchain kfd 2 claims --json
buildchain kfd 2 trust-claims --json
buildchain kfd 2 trust-assessment --json
buildchain kfd upstream roles --json
buildchain kfd upstream collect --json
buildchain kfd upstream check --json
buildchain kfd aggregate --json
buildchain kfd 3 query buildchain --json
buildchain kfd 4 schema --json
buildchain kfd 4 gate --input-json kfd-4-gate-input.json --json
buildchain kfd 5 gate --input-json kfd-5-gate-input.json --json
buildchain kfd 7 gate --input-json kfd-7-gate-input.json --json
buildchain kfd support project --matrix-json support-matrix.json \
  --gate-json kfd-4-gate.json --gate-json kfd-5-gate.json \
  --gate-json kfd-7-gate.json --json

KFD-1, KFD-2, and KFD-3 have concrete Buildchain workflows. KFD-4, KFD-5, and KFD-7 additionally have product-evidence gates backed by the installed KFD package and its offline WASM verifier. These gates verify exact source, freshness, record bytes, negative evidence, and product-owned responsibility; they do not self-qualify, self-certify, activate, or silently widen support. KFD-6 remains an explicit unsupported barrier. KFD-8 through KFD-13 remain draft adopter-evidence barriers until their standards and product gates mature.

KFD-4 / KFD-5 / KFD-7 Product Gates

Each gate input uses kungfu-buildchain-kfd-product-gate-input version 1 and binds repository-relative KFD records and evidence by SHA-256. The result uses kungfu-buildchain-kfd-product-gate version 1 and always records qualifying: false and selfCertified: false.

• KFD-4 requires a verified observer perspective, contrastive perspective replay, declared loss, preserved evidence boundaries, projection fsck, and a negative fixture.
• KFD-5 requires an accepted Primitive discovery record whose minimum-closure, deletion, fuse, and dogfood tests pass with retained evidence, plus explicit falsifiers and a negative fixture.
• KFD-7 requires a qualified and activated Domain Profile, independent review, product witnesses, all 13 evidence obligations, and negative evidence.

buildchain kfd support project joins the three gate results with the product-owned KFD-1…13 matrix. It rejects normative metadata drift, source or freshness mismatch, gate/matrix disagreement, KFD-4/5 candidate widening, KFD-6 support, KFD-8…13 promotion, or any unsupported shipped-support claim.

KFD-1

KFD-1 proves that a product release is bound to one contract world. Buildchain uses KFD-1 for its runtime contract, release-passport schemas, packaged docs, Node exports, workflows, actions, and site-consumption facts.

For Buildchain itself, the source registry lives in packages/core/buildchain-kfd-claims.js and is projected to dist/site/kfd-claims.json. Release promotion binds that registry to exact source and artifact hashes in the release passport.

Buildchain exposes KFD-1 through:

buildchain kfd 1 schema --json
buildchain kfd 1 witness --json
buildchain kfd 1 gate --witness-json kfd-1-witness.json --json
buildchain kfd 1 verify --gate-json kfd-1-gate.json --json

KFD-2

KFD-2 requires public trust claims to be backed by machine-readable evidence. Buildchain release passports fail or downgrade claims that only have prose.

Every public claim binds:

• declared source files;
• machine-readable evidence;
• source, evidence, and artifact hashes;
• artifact coordinates;
• verification result;
• audit boundary;
• responsibility state;
• residual risk.

Buildchain exposes KFD-2 through:

buildchain kfd 2 schema --json
buildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json
buildchain kfd 2 claims --json
buildchain kfd 2 product-claims check --json
buildchain kfd 2 product-claims write --json
buildchain kfd 2 product-claims render --json
buildchain kfd 2 trust-claims --json
buildchain kfd 2 trust-assessment --json

Products declare their own public trust intent once in the canonical tracked registry:

.buildchain/kfd/kfd-2/registry.json

The registry uses kungfu-buildchain-kfd-2-product-claims-registry/v1 and binds each claim to a source, machine-readable evidence, artifact coordinates, verification command, audit boundary, responsibility, residual risk, and canonical status. Buildchain does not invent product claims from prose. It validates the declaration, hashes the referenced files, and renders the release-facing outputs:

.buildchain/kfd/kfd-2/release-claims.json
.buildchain/kfd/kfd-2/claims/<claim-id>.json
.buildchain/kfd/kfd-2/buildchain-claim-args.txt

product-claims check is read-only and fails on missing, stale, or unexpected claim projections. write updates only the declared KFD-2 output set and removes stale generated claim JSON files; unrelated files are preserved. render prints the expected document set without writing it. Version is read from the repository’s configured Buildchain version state unless explicitly overridden. Release pipelines may override channel, tag, or source SHA while the registry remains the stable product-intent source.

claims generates Buildchain’s release-passport public claim inputs. The trust-claims and trust-assessment commands expose the latest KFD package’s foundation KFD-2 facts from @kungfu-tech/kfd and validate their taxonomy values against the KFD-owned trust-taxonomy schema. Unknown riskType, trustImpact, machineProvability, or agentAction values fail validation; new values must be requested upstream in kungfu-systems/kfd, not invented in Buildchain.

@kungfu-tech/kfd is a runtime dependency of Buildchain, not a development-only dependency. The public buildchain kfd ... CLI and @kungfu-tech/buildchain/kfd Node API read KFD-owned standards metadata, schemas, foundation trust claims, foundation trust assessments, and taxonomy values at runtime. Moving KFD to devDependencies would make installed Buildchain packages unable to answer KFD queries in consumer repositories.

Upstream KFD Aggregation

Products often depend on multiple KFD-aware upstream components. A product’s own KFD status is not the same thing as the status of those upstreams, but agents still need one machine-readable view of the upstream trust surface.

Buildchain exposes that view through:

buildchain kfd upstream roles --json
buildchain kfd upstream collect --json
buildchain kfd upstream check --json
buildchain kfd aggregate --json

upstream collect reads .buildchain/buildchain.toml, resolves declared packages from the caller repository, hashes declared evidence assets, and emits a kungfu-buildchain-kfd-upstream-aggregate document. upstream check validates that aggregate. aggregate combines the product’s own Buildchain KFD status with the upstream aggregate.

This works in development before the consuming repository has published an alpha or release. In that state Buildchain can collect and check upstream facts, versions, hashes, roles, and residual risk, but the consuming product must not claim its own KFD status as passed until a release passport verifies that product release.

The repository-owned declaration is intentionally small. Consumers normally declare the upstream package identity, not Buildchain’s inferred role or a duplicate semver:

[kfd.upstream]
auto_discover = false

[[kfd.upstream.components]]
id = "kfd"
package = "@kungfu-tech/kfd"
repository = "kungfu-systems/kfd"
evidence = [
  "package:kfd.release.json",
  "package:.buildchain/kfd/kfd-1/contract-world.witness.json",
  "package:.buildchain/kfd/kfd-2/release-claims.json",
  "package:.buildchain/kfd/kfd-3/collaboration-interface.json",
  "package:standards.json",
]

The upstream package version is a single source of truth owned by the package manager. Put the dependency in package.json / the lockfile, then let Buildchain read the installed package’s real package.json:

{
  "devDependencies": {
    "@kungfu-tech/kfd": "1.0.0-alpha.21"
  }
}

Most consumers should keep @kungfu-tech/kfd in devDependencies: Buildchain uses it during CI, development checks, release evidence collection, and site generation. Move it to dependencies only if the product’s own runtime imports KFD directly. Buildchain itself keeps KFD in dependencies because its public CLI and Node API resolve KFD standards, schemas, taxonomy, and foundation trust facts at runtime.

Do not repeat upstream semver values in .buildchain/buildchain.toml. Repeating versions in both package.json and Buildchain config creates stale facts. upstream collect records the actual installed package version and evidence hashes in the aggregate output.

kfd_1, kfd_2, kfd_3, and kfd_4 are optional capability-state hints. When omitted, Buildchain treats the component as declared. Use explicit values only when the upstream package really exposes the corresponding machine evidence, for example:

kfd_1 = "exported-witness"
kfd_2 = "exported-claim"
kfd_3 = "exported-collaboration-interface"
kfd_4 = "schema-metadata"

An upstream component may be declared, aligned, exported-*, or another explicit non-passed state when the evidence is package-local. A component may claim passed only when the aggregate also binds that component to a release passport. Upstream passed never upgrades the product’s own KFD status; it only describes the upstream trust surface consumed by the product.

Upstream Roles

Consumers should normally omit role. Buildchain owns the role vocabulary and infers the role from package identity and evidence. The aggregate records:

• role - the normalized Buildchain-managed role;
• roleSource - known-package, evidence, default, or explicit;
• roleReason - the machine-readable explanation for the chosen role.

The managed role registry is queryable:

buildchain kfd upstream roles --json

Current roles are:

If a consumer explicitly writes role, it must be one of that registry. Unknown explicit values fail closed during upstream check; Buildchain will not let repositories invent local role spellings that later fragment aggregate reports.

Buildchain dogfoods this model with @kungfu-tech/kfd as its upstream standard-and-schema provider. The generated site bundle includes dist/site/kfd-upstream-aggregate.json so downstream sites and agents can read Buildchain’s upstream KFD facts from the npm package instead of scraping repository scripts.

KFD-3

KFD-3 closes participant-facing collaboration surfaces over a declared public interface. Buildchain supports two complementary KFD-3 layers.

The first layer is Buildchain self-verification. Buildchain reverse-enumerates real CLI commands, reusable workflow inputs, action inputs, site pages, and documented command references, then compares those facts with the generated registries in dist/site/. A missing registry entry fails pnpm run check.

The second layer is product surface registration. Products can ask Buildchain to detect standard public surfaces, write a small product-owned registry, audit the registry against the current artifact/source tree, generate a release-passport compatible witness, and query the resulting capability map.

Shifu Discovery and Distribution Declarations

Buildchain owns the repository-layout question; product tools must not copy its internal paths. Shifu and other consumers use this sequence:

1. read the welded .buildchain-version pin to select Buildchain;
2. run buildchain layout --cwd <repository> --json;
3. read the returned kfd.registries["kfd-3"].path;
4. treat a surface as Shifu-managed only when its declaration contains distribution.registrar="shifu".

The layout response uses the kungfu-buildchain-layout-discovery contract with an explicit schema version. Changing or removing its fields is a public contract change. Consumers must not fall back to a hard-coded registry location when the command is unavailable or returns an unsupported contract.

A Shifu distribution declaration must contain at least one task and one artifact. Every artifact declares kind, platform, and pathGlob; an optional sha256 is a lowercase 64-character hexadecimal digest. This makes artifact form and platform machine-readable without asking Shifu to infer them from filenames:

{
  "distribution": {
    "registrar": "shifu",
    "tasks": ["binary:build"],
    "artifacts": [
      {
        "kind": "binary",
        "platform": "linux",
        "pathGlob": "dist/binary/example-x86_64-unknown-linux-gnu.tar.gz"
      }
    ]
  }
}

Buildchain validates this shape whenever a KFD-3 registry is read or written. Repositories that do not declare the registrar remain outside Shifu’s distribution jurisdiction.

KFD-3 surface audits also bind a detected artifact to its owning declared surface when the detected kind and path match one of these distribution artifacts. This lets one participant-facing CLI remain the declared interface while its platform binaries are proved as distributions of that interface, instead of being reported as unrelated unregistered surfaces.

Detected, Declared, Enforced

KFD-3 surface registration uses three states.

Detection does not silently become product intent. register is the boundary decision. Existing consumers are unaffected until they opt in.

CLI

Inspect KFD-owned schema facts:

buildchain kfd schema list --json
buildchain kfd schema show kfd-1 --json
buildchain kfd 4 schema --json
buildchain kfd 5 schema --json
buildchain kfd 7 schema --json

The KFD schema namespace is discovered from @kungfu-tech/kfd/standards.json. For KFD-2 this includes trustClaims, trustAssessment, trustTaxonomy, releaseClaims, and releaseTrustPassport. KFD-4 exposes both observerPerspective and perspectiveReplay; KFD-5 exposes primitiveDiscovery; KFD-7 exposes domainProfileDeclaration.

Detect public surface candidates:

buildchain kfd 3 detect --json
buildchain kfd 3 detect --kind node-api --kind cli --json

Register standard surface classes:

buildchain kfd 3 register node-api --product Buildchain
buildchain kfd 3 register cli
buildchain kfd 3 register python-api --artifact dist/wheel-unpacked

Audit detected, declared, and enforced surfaces:

buildchain kfd 3 audit --json

Generate a witness for release passport collection:

buildchain kfd 3 witness \
  --kind prebuild \
  --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json

Query capability facts for agents or downstream sites:

buildchain kfd 3 query buildchain --json
buildchain kfd 3 query --passport .buildchain/release-passport/buildchain.release.json --json

Node API

The CLI is a thin wrapper over the public Node API:

import {
  kfd1,
  kfd2,
  kfd3,
  kfd4,
  upstream,
  collectKfdAggregate,
  collectKfdStatus,
  collectKfdUpstreamFacts,
  checkKfdUpstreamFacts,
  listKfdUpstreamRoles,
  listKfdSchemas,
  readKfdSchema,
} from "@kungfu-tech/buildchain/kfd";

Agents should start with collectKfdStatus() to learn which standards are implemented and where the repository-owned Buildchain files live. For capability use decisions, prefer kfd3.queryCapabilities(). The query result connects each capability to:

• KFD-3 surface identity and state;
• KFD-1 basis facts such as source and artifact paths or digests;
• KFD-2 trust evidence when a release passport is attached;
• residual risk and recommended agent action.

Standard Detectors

The initial detector set is intentionally conservative:

• npm packages: package.json exports, main, types, and bin;
• Python wheels: unpacked .dist-info/METADATA, RECORD, entry_points.txt, and top_level.txt;
• CLI binaries: package.json#bin and files under bin/;
• standalone binaries and archives: common binary/archive outputs under artifact directories such as dist/;
• documentation: README.md, AGENTS.md, and docs/*.md;
• site bundles: dist/site/*.json.

Python importability alone is not considered public API. A product can extend the registry over time, but the first boundary is metadata-based.

Buildchain Self Dogfood

Buildchain dogfoods this model in two ways:

• buildchain kfd 1 witness --json generates Buildchain’s own KFD-1 contract world witness;
• buildchain kfd 2 claims --json generates Buildchain’s own KFD-2 public claim evidence;
• buildchain kfd 2 trust-claims --json and buildchain kfd 2 trust-assessment --json expose and validate the KFD package’s foundation KFD-2 trust facts against the latest KFD taxonomy;
• dist/site/kfd-claims.json declares Buildchain’s own KFD-3 collaboration interface, including a Shifu-owned standalone binary distribution surface;
• buildchain kfd 3 query buildchain --json resolves the packaged Buildchain capability map from that site fact source.

This lets downstream agents discover Buildchain’s supported CLI, Node API, release passport, workflow, and site bundle surfaces from the npm package instead of scraping source files or README examples.

Known Gaps

Archive unpacking for .whl, .tar.gz, .zip, and platform-native installers is intentionally not part of the first detector. Callers can point --artifact at an unpacked artifact directory. Future Buildchain versions can add archive readers without changing the registry contract.