{
"schemaVersion": 1,
"contract": "kungfu-buildchain-site-page-registry",
"package": "@kungfu-tech/buildchain",
"sourceOfTruth": "npm package @kungfu-tech/buildchain/dist/site/page-registry.json",
"rendererBoundary": {
"contentOwner": "Buildchain",
"rendererOwner": "site repository",
"rule": "Site repositories render these markdown pages and metadata; they do not maintain separate Buildchain product copy."
},
"pageCount": 94,
"categories": [
"action",
"api",
"fixture",
"manual",
"overview"
],
"capabilityGroups": [
"getting-started",
"release-passport-trust",
"reusable-build",
"kfd-trust",
"site-and-propagation",
"distribution-indexes",
"observability-diagnostics",
"governance-versioning",
"api-cli-reference"
],
"pages": [
{
"id": "overview:home",
"title": "Buildchain",
"route": "/",
"category": "overview",
"capabilityGroup": "getting-started",
"audience": [
"consumer",
"agent"
],
"maturity": "stable",
"sourcePath": "README.md",
"digest": "sha256:d317837aff09de98d525f09f3d78db6510c6f0578d7b9f80cb3376b0114fe5b3",
"headings": [
{
"level": 1,
"title": "Buildchain",
"anchor": "buildchain"
},
{
"level": 2,
"title": "Buildchain beginner bootstrap",
"anchor": "buildchain-beginner-bootstrap"
},
{
"level": 2,
"title": "Choose Your Path",
"anchor": "choose-your-path"
},
{
"level": 2,
"title": "Where Buildchain sits in the Agent Supply Chain",
"anchor": "where-buildchain-sits-in-the-agent-supply-chain"
},
{
"level": 2,
"title": "Install and Verify",
"anchor": "install-and-verify"
},
{
"level": 2,
"title": "Project Governance",
"anchor": "project-governance"
},
{
"level": 2,
"title": "Use Buildchain",
"anchor": "use-buildchain"
},
{
"level": 2,
"title": "Consumer workflow contract",
"anchor": "consumer-workflow-contract"
},
{
"level": 2,
"title": "Release Model",
"anchor": "release-model"
},
{
"level": 2,
"title": "Toolkit Observability",
"anchor": "toolkit-observability"
},
{
"level": 2,
"title": "Site Fact Source",
"anchor": "site-fact-source"
},
{
"level": 2,
"title": "Homepage Content Contract",
"anchor": "homepage-content-contract"
},
{
"level": 2,
"title": "Local Verification",
"anchor": "local-verification"
},
{
"level": 2,
"title": "Read Next",
"anchor": "read-next"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-layered-architecture\ndoc_type: implementation-guide\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-24\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-24\n visible_context: Buildchain 4.1 source, architecture registries and local validation.\n invisible_context_boundary: No unpublished release or external consumer qualification is claimed.\n---\n\n# Buildchain\n\nDevelopment continues on `dev/v4/v4.1`. The package version and published\nRelease Passport identify source and release state. See\n[Code organization](docs/code-organization.md) for the workflow, action,\nJavaScript and Rust implementation layers.\n\nThe retained animation below demonstrates an older initializer. For the current\nschema-2 caller pair, follow the [Golden Path](docs/getting-started.md).\n\n\n\n## Buildchain beginner bootstrap\n\n[](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/public-evidence.json)\n\nAnimation scenario:\n\n```text\n$ buildchain init --cwd ./starter --type package --package-manager npm\n$ buildchain layout --cwd ./starter --json\n$ buildchain version\n```\n\nNative renditions: [1080p MP4](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo.mp4) · [1080p WebM](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo.webm) · [720p MP4](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo-720p.mp4) · [720p WebM](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo-720p.webm)\n\n[Static poster / reduced-motion fallback](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/poster.png)\n\n\nEvidence and claim boundary
\n\nThis exact standalone-binary scenario proves deterministic local bootstrap behavior only; it does not grant release, repository, network, or production authority.\n\n[Release Passport](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/release-passport.json) · [auditable evidence](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/public-evidence.json)\n\n \n\n\n\n\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain.yml)\n\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Choose Your Path\n\n| You are... | Start here | You will get... |\n| -------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md) | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |\n| looking up a CLI command | [Generated CLI Reference](docs/cli-reference.md) | governed syntax, options, aliases, and side-effect-free help paths |\n| writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |\n| operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |\n\nProduction release operators should also read the\n[release governance guide](docs/release-governance.md).\n\nThe Golden Path is the beginner lane. Advanced workflow, signing, publishing,\nand governance manuals remain separate so a first-time consumer does not need\nto understand the entire release control plane before reaching a valid local\nconfiguration.\n\n## Where Buildchain sits in the Agent Supply Chain\n\nBuildchain binds a product's declarations to the exact source cut, build,\nartifacts, checks, and promotion record that produced a release. In the wider\nAgent Supply Chain it sits between KFD-3 product discovery and KFD-2\npurpose-bound assessment:\n\n```text\nKFD-3 declaration -> Buildchain exact-artifact evidence -> KFD-2 assessment\n```\n\nBuildchain can prove that a declared claim and an exact artifact remain\nconsistent, or fail/downgrade when their evidence drifts. It does not invent\nthe product fact, decide whether a receiver should trust it for a purpose,\ncertify every platform, or prove external adoption. Receivers and downstream\nKFD-2 assessors retain the admission decision and residual risk.\n\nTo evaluate the layer, inspect a release's `buildchain.release.json` and\n`artifact-evidence.json`, verify them with the CLI, and report missing product\nor protocol evidence through the repository issue tracker.\n\n## Install and Verify\n\nNew repository adopters should follow the [15–30 minute Golden Path](docs/getting-started.md).\nThe commands below are the shorter verification-only route for an existing\nconsumer.\n\nFor v4, use the published npm package and verify the release passport before\ntrusting release evidence:\n\n```bash\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@4.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@4.0.0 version\n```\n\nThe v4.0.0 release publishes evidence assets and platform archives through the\nsame protected promotion transaction.\nThe names below describe the optional archive contract used by legacy release\nlines:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n createBuildchainLogger,\n verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n path: \".buildchain/logs/native-build.jsonl\",\n source: \"user\",\n component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n path: logger.path,\n requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n posture for GitHub, npm, cloud, credential, release evidence, and other\n provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n collectBuildchainDiagnostics,\n collectRunnerDiagnostics,\n writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n contract: \"consumer-build-diagnostics\",\n buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n runner: collectRunnerDiagnostics(),\n});\n```\n\n## Use Buildchain\n\nIn an existing npm product with a versioned `package.json` and build/check scripts:\n\n```bash\npnpm add -D --save-exact @kungfu-tech/buildchain\npnpm exec buildchain init --type npm --package-manager pnpm\npnpm exec buildchain validate --require-version-state\npnpm exec buildchain doctor --json\n```\n\nUse `--type binary` for a CMake product or `--type paper` for an existing PDF\nproduct. The initializer writes the shared caller pair and product declarations;\nedit the TOML to match your product's build, verification and artifact paths.\n\nTo create Paper source as well as the shared configuration:\n\n```bash\npnpm exec buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\npnpm exec buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example --write\npnpm exec buildchain paper preflight --offline\npnpm exec buildchain paper status\n```\n\nScaffolding first shows the planned files; `--write` creates them. Paper products\npublish PDFs as GitHub Release assets through the same pipeline as other products.\nSee [Paper products and migration](docs/publication-artifacts.md) for source\nprerequisites and preservation of historical publication records.\n\nAfter one-time repository/provider setup, commit your product and generated\nconfiguration and open a protected channel PR. Buildchain handles delivery and\npublication. Recover an interrupted operation by selecting its exact attempt in\n`buildchain-recover.yml`. npm Trusted Publishing authenticates hosted npm releases.\n\nProduct commands can use pnpm, npm, yarn, pip, Conan, CMake, Make or repository\nbuild scripts. They produce and verify product artifacts; the published runtime\nowns release orchestration and its evidence.\n\n## Consumer workflow contract\n\nNew consumers use the same two generated files:\n\n- `.github/workflows/buildchain.yml` calls `public-ops-pipeline.yml@v4`.\n- `.github/workflows/buildchain-recover.yml` calls `public-ops-recover.yml@v4`.\n\nDeclare npm packages, binary archives or Paper PDFs in\n`.buildchain/buildchain.toml`. Their install, build and verification commands\nremain product code. Open the appropriate protected channel PR to request a\nrelease. The runtime manages publication, provider readback and completion.\nRecovery takes an exact attempt and, when needed, one temporary repaired runtime.\n\nThe [workflow catalog](docs/workflow-catalog.md) distinguishes the two public\nentries from internal components. New integrations declare products in TOML and\nuse these entries for release orchestration.\nThe three [standard examples](templates/minimal-consumer/) share identical caller\nbytes; their TOML and product source differ. Tool-maintained locks bind the\npublished runtime. Existing npm Trusted Publishing continues to authenticate\npublication in the hosted workflow.\n\nExisting consumers can retain the registered historical workflow paths and their\nschema-1 product configuration. See [Compatible upgrades](docs/getting-started.md#migrating-old-callers)\nfor the supported interfaces and validation boundary.\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path | Meaning | Exact tag | Floating refs |\n| --------------------------------------- | ------------------------------------------------------ | ---------------- | ---------------------------------------------------- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y` | publish the next testable alpha for a minor line | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y` |\n| `alpha/vX/vX.Y -> release/vX/vX.Y` | publish production for that minor line | `vX.Y.Z` | `vX.Y`, usually `vX`, `release/vX/vX.Y` |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0` | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n binary verification.\n- Use signal: the start of `Use Buildchain`, especially the shared normal and recovery\n workflow callers.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [GitHub governance authority](docs/github-governance-authority.md)\n- [GitHub-native Linux artifact attestation](docs/github-artifact-attestation.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Shifu Gate profile orchestration](docs/shifu-gate-profiles.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Declarative release-tail contract](docs/release-tail-contract.md)\n- [v4 declarative release-tail migration](docs/v4-declarative-release-tail-migration.md)\n- [Release governance](docs/release-governance.md)",
"slug": "home"
},
{
"id": "action:build/artifact/prepare-attestation",
"title": "Prepare a GitHub artifact attestation",
"route": "/actions/build/artifact/prepare-attestation",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/artifact/prepare-attestation/README.md",
"digest": "sha256:b3c567926ed486ad6c256c6e86827ec4d002030dbcf2dbe1700e0a9697b1314c",
"headings": [
{
"level": 1,
"title": "Prepare a GitHub artifact attestation",
"anchor": "prepare-a-github-artifact-attestation"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: github-artifact-attestation\ndoc_type: action-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Action metadata and attestation transaction source.\n invisible_context_boundary: No hosted publication qualification is claimed.\n---\n\n# Prepare a GitHub artifact attestation\n\nValidate the exact subject bytes, platform manifest, release Passport and signer policy before calling the external attestation action. The action runs on Node 24 and verifies the selected Buildchain runtime commit.\n\nSupply `runtime-sha`, `subject-path`, `platform-manifest-path`, `release-passport-path` and `policy-json`. The outputs include the verified subject digest, predicate path and `preparation-json` consumed by the sealing action.\n\nUse the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact input/output contract; [`seal-attestation`](../seal-attestation/README.md) verifies the provider result.",
"slug": "build/artifact/prepare-attestation"
},
{
"id": "action:build/artifact/seal-attestation",
"title": "Seal a GitHub artifact attestation",
"route": "/actions/build/artifact/seal-attestation",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/artifact/seal-attestation/README.md",
"digest": "sha256:a1fed088050b41480c3d074dcdf22da83fa3c3b5af168fea0402145db8400b9b",
"headings": [
{
"level": 1,
"title": "Seal a GitHub artifact attestation",
"anchor": "seal-a-github-artifact-attestation"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: github-artifact-attestation\ndoc_type: action-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Action metadata and attestation transaction source.\n invisible_context_boundary: No hosted publication qualification is claimed.\n---\n\n# Seal a GitHub artifact attestation\n\nVerify the external provider result against the preparation record and unchanged subject bytes, then retain the attestation bundle and rooted evidence. The action runs on Node 24 and rechecks the exact selected runtime commit.\n\nSupply `runtime-sha`, `preparation-json`, `bundle-path`, `attestation-id`, `attestation-url` and an explicit read `token`. The outputs identify the retained bundle digest and evidence root. Provider failure or subject drift prevents sealing.\n\nUse the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact contract; [`prepare-attestation`](../prepare-attestation/README.md) owns pre-provider validation.",
"slug": "build/artifact/seal-attestation"
},
{
"id": "action:build/credential/macos-island",
"title": "macOS Credential Island",
"route": "/actions/build/credential/macos-island",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/credential/macos-island/README.md",
"digest": "sha256:174ffb3e3424effc02164ad3577268fc060bfeefb223d0a2bc8d4cc43e66b110",
"headings": [
{
"level": 1,
"title": "macOS Credential Island",
"anchor": "macos-credential-island"
}
],
"markdown": "# macOS Credential Island\n\nThis action signs one sealed macOS application on an isolated macOS runner. It\ndoes not check out consumer source and does not execute files from the input\nartifact. Buildchain validates the source-bound input manifest, imports one\nexact Developer ID Application identity into a temporary keychain, signs the\napplication, submits Apple notarization, staples the application and DMG,\nverifies Gatekeeper, and writes bounded JSON evidence.\n\nDMG assembly uses a unique execution- and attempt-bound image path and volume\nname. Only the exact `hdiutil: create failed - Resource busy` failure is retried,\nwith three attempts and a total retry delay of seven seconds. Certificate,\nentitlement, signature, notarization, provenance, and policy failures remain\nterminal. Attempt artifacts stay below the owned temporary root, and successful\nevidence binds the request, unsigned archive, runtime, runner attempt, toolchain,\nretry history, cleanup result, and signed output digests.\n\nThe reusable Buildchain workflow invokes this action from a job bound to the\ncaller's protected GitHub Environment. The job downloads the exact sealed\nBuildchain input and immutable action runtime, then uploads the signed payload\nand its Buildchain platform manifest. It has no consumer checkout. Do not add a\npackage manager, lifecycle, hook, or consumer-script execution to that job.\n\nThe supported `electron-desktop-v1` entitlements profile is owned by\nBuildchain. Consumer-provided entitlement files are intentionally unsupported;\notherwise pull-request bytes could expand the signing authority.",
"slug": "build/credential/macos-island"
},
{
"id": "action:build/lifecycle/run",
"title": "run-lifecycle",
"route": "/actions/build/lifecycle/run",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/lifecycle/run/README.md",
"digest": "sha256:e9af3a6d3bca4650704228b950b36a9d8e72b323f3c9e427d21ac4a3de8792c8",
"headings": [
{
"level": 1,
"title": "run-lifecycle",
"anchor": "run-lifecycle"
}
],
"markdown": "# run-lifecycle\n\nRun a Buildchain lifecycle stage or an explicit command and write a deterministic\nartifact manifest.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/build/lifecycle/run@v3\n with:\n stage: build\n required: \"true\"\n artifact-name: my-product-linux-x64-${{ github.sha }}\n artifact-paths: |\n dist\n build/stage\n```\n\nWhen `command` is provided, it overrides `buildchain.toml` for that invocation.\nWhen `command` is empty, the action loads `buildchain.toml` and runs the named\nstage.\n\n`timeout-minutes` defaults to 120 and bounds either command source. A\nstage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout\nerrors identify the lifecycle stage and platform so a hung self-hosted build can\nbe diagnosed after the runner is released.\n\nThe action writes both a full manifest and a compact summary. It also exposes\nthe summary as outputs for reusable workflow callers:\n\nFor a `build` stage, paths selected by `[[signing.artifacts]]` for the current\n`platform-id` are automatically included in the lifecycle manifest even when\nthey sit outside `artifact-paths`. This binds every byte sent to the signing\nauthority without changing which ordinary product paths the caller uploads.\n\n| Output | Meaning |\n| --- | --- |\n| `manifest-path` | Full manifest path |\n| `summary-path` | Compact summary path |\n| `artifact-name` | Resolved artifact name |\n| `artifact-file-count` | Number of manifest files |\n| `artifact-total-bytes` | Total manifest bytes |\n| `artifact-summary-json` | One-line JSON summary |\n| `expected-artifacts-ok` | `true` when expectations passed |\n\n`expected-artifacts-json` can require exact paths, file count bounds, and a\nminimum byte total:\n\n```yaml\nwith:\n expected-artifacts-json: >-\n {\"minFiles\":2,\"requiredPaths\":[\"dist/app.tar.gz\",\"dist/checksums.txt\"]}\n```\n\nFor long native builds, set `sample-process-tree: \"true\"` and pass\n`process-summary-path`. The action wraps either the explicit `command` or the\nconfigured lifecycle stage with `buildchain sample process-tree`, then embeds\nthe produced summary in the lifecycle diagnostics artifact:\n\n```yaml\nwith:\n stage: build\n sample-process-tree: \"true\"\n process-summary-path: .buildchain/diagnostics/process-summary.json\n```\n\nCustom wrappers can still pass an existing sampler report or summary with\n`process-summary-path`; the action reads it after the lifecycle command\nfinishes, so commands may generate the file during the same invocation.\nSet `process-summary-required: \"false\"` when the summary is an optional sidecar,\nfor example when a reusable workflow may skip an optional build stage.\nThe diagnostics directory also includes `diagnostics-manifest.json`, a compact\ninventory of the diagnostics sidecars with byte counts and sha256 hashes.",
"slug": "build/lifecycle/run"
},
{
"id": "action:build/lifecycle/validate",
"title": "validate-config",
"route": "/actions/build/lifecycle/validate",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/lifecycle/validate/README.md",
"digest": "sha256:14e58dd47b8b617512608e89fd1887b28ef2aa1a545ee89936710a78cfe8d2bd",
"headings": [
{
"level": 1,
"title": "validate-config",
"anchor": "validate-config"
},
{
"level": 2,
"title": "Usage",
"anchor": "usage"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-config-validation-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# validate-config\n\nBuildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle\ncommands.\n\nUse this action during repository migration when a heavyweight project needs to\nprove that its Buildchain version state and lifecycle declaration are ready, but\nthe actual build should not run yet.\n\n## Usage\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/build/lifecycle/validate@v3\n with:\n require-version-state: \"true\"\n require-lifecycle-stages: \"install,build,verify\"\n```\n\nThe action checks:\n\n- `buildchain.toml` exists and uses schema `1`;\n- configured version-state files exist and expose a string version;\n- anchored/manual version strategy declarations and JSON/TOML anchor manifests\n are structurally valid when configured;\n- web-surface project, channel, deploy adapter, retention, and staging security\n declarations are structurally valid when configured;\n- required lifecycle stages are declared and structurally valid.\n\nIt does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,\nor any other lifecycle command.\n\nOutputs include `project-type`, `project-name`, `project-site`, `channels`, and\n`deploy-adapters-json`, so callers can route site workflows without reparsing\nTOML in every repository.",
"slug": "build/lifecycle/validate"
},
{
"id": "action:governance/incident/report",
"title": "report-buildchain-issue",
"route": "/actions/governance/incident/report",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/governance/incident/report/README.md",
"digest": "sha256:1f5b90a11274f9e5e0bfa73192f007e5604d3c0d8425f7f2bff1088dcbf722ae",
"headings": [
{
"level": 1,
"title": "report-buildchain-issue",
"anchor": "report-buildchain-issue"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-consumer-issue-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# report-buildchain-issue\n\nCreate or update a Buildchain repository issue from a consumer workflow or from\nBuildchain's own workflow-friction feedback loop.\n\nThis action is intended for consumer repositories that need to report\nBuildchain-owned failures with enough evidence for maintainers to act. It\nrequires a token that can write issues on the target Buildchain repository.\nFor cross-repository consumers, generate that token with a GitHub App\ninstallation token or another scoped credential owned by the consumer\norganization.\n\n```yaml\n- uses: actions/create-github-app-token@v2\n id: buildchain-issue-token\n with:\n app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n owner: kungfu-systems\n repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/governance/incident/report@v3\n if: failure()\n with:\n token: ${{ steps.buildchain-issue-token.outputs.token }}\n summary: \"Reusable build failed before artifact finalization\"\n failure-code: reusable-build-failed\n buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}\n diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action computes a stable fingerprint from the consumer repository,\nworkflow, job, failure code, and Buildchain ref. When an open issue already\nexists for that fingerprint, it comments with the new run instead of opening a\nduplicate issue.\n\nBy default issue reporting is fail-soft:\n\n- `fail-on-error: \"false\"` prevents a reporting outage from hiding the original\n build failure.\n- transient GitHub API 429/5xx errors and connection failures are retried.\n- if a configured label is missing, issue creation is retried without labels.\n- if issue creation/commenting is still unavailable, the action writes the full\n copyable issue title, fingerprint, and body into the workflow summary.\n- common token, private-key, password, and authorization values are redacted\n before submission.\n\nUse `dry-run: \"true\"` to verify the computed fingerprint and body shape without\ncalling GitHub.\n\nFor Buildchain-owned workflow friction, use `report-kind: workflow-friction`.\nThis uses a separate marker and default labels so duplicate PRs, duplicate\nbuilds, transient API failures, stale release-state, or missing RC evidence can\nbe grouped without mixing with consumer failure reports:\n\n```yaml\npermissions:\n issues: write\n\nsteps:\n - uses: actions/create-github-app-token@v2\n id: buildchain-issue-token\n with:\n app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n owner: kungfu-systems\n repositories: buildchain\n\n - uses: kungfu-systems/buildchain/actions/governance/incident/report@v3\n if: failure()\n with:\n token: ${{ steps.buildchain-issue-token.outputs.token || secrets.BUILDCHAIN_ISSUE_TOKEN || secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token }}\n report-kind: workflow-friction\n target-repository: kungfu-systems/buildchain\n repository: ${{ github.repository }}\n workflow: ${{ github.workflow }}\n run-id: ${{ github.run_id }}\n run-attempt: ${{ github.run_attempt }}\n channel: alpha/v3/v3.0\n source-sha: ${{ github.sha }}\n friction-class: duplicate-build\n related-runs-json: ${{ steps.classify.outputs.related-runs-json }}\n heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}\n comment-cooldown-hours: \"24\"\n```\n\n`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain\nstill deduplicates by fingerprint but skips adding another comment if the\nexisting issue already received a recent update.",
"slug": "governance/incident/report"
},
{
"id": "action:release/promotion/candidate",
"title": "v4 release-candidate promote action",
"route": "/actions/release/promotion/candidate",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/promotion/candidate/README.md",
"digest": "sha256:b50fc4f13ea9c680142df79c5ab984522cd85893f1ce12f1427e094569329746",
"headings": [
{
"level": 1,
"title": "v4 release-candidate promote action",
"anchor": "v4-release-candidate-promote-action"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: protected-publication-source\ndoc_type: reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-06\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-06\n visible_context: Publication adapter, regression tests, and public GitHub commit metadata.\n invisible_context_boundary: No credentials or private runtime state inspected.\n---\n\n# v4 release-candidate promote action\n\nThis internal action validates a sealed v4 publication qualification receipt, aggregates the Buildchain Release Passport, and executes the fixed four-capability Release Tail Provider Plane. It has no command or shell extension input and is invoked by the v4 branch of the reusable `release-candidate-promote` workflow.\n\nThe protected publication source must match the qualified candidate's exact\nGit tree. An exact commit is accepted directly; a final PR merge may also bind\nthrough identical ordered parents. For repositories requiring linear history,\n`squash-equivalent` requires a protected commit with one parent, a qualified\nmerge candidate with two parents, and the same first parent. GitHub must report\nthe exact PR as merged into the protected commit, and its head must equal the\ncandidate's second parent. Candidate qualification, workflow and repository\nprovenance, and artifact verification remain required before publication.",
"slug": "release/promotion/candidate"
},
{
"id": "action:release/promotion/ref",
"title": "Release promotion adapter",
"route": "/actions/release/promotion/ref",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/promotion/ref/README.md",
"digest": "sha256:17d8f91ffb09312732737165b85e55f2533e2aab010ce7cf0ac078cff7f47d6e",
"headings": [
{
"level": 1,
"title": "Release promotion adapter",
"anchor": "release-promotion-adapter"
},
{
"level": 2,
"title": "Admitted promotion inputs",
"anchor": "admitted-promotion-inputs"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-release-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Current promotion adapters, public workflow and request contract.\n invisible_context_boundary: No external publication or consumer qualification is claimed.\n---\n\n# Release promotion adapter\n\nThe consumer API is\n[.release-candidate-promote.yml](../../../../.github/workflows/.release-candidate-promote.yml).\nIt admits one closed JSON request, qualifies exact source and runtime identities,\napplies the admitted publication plan, and settles provider evidence in separate\npermission boundaries. See the [request contract](../../../../docs/release-promotion-request.md).\n\nThis Node action binds GitHub Actions inputs and outputs to the promotion\ncoordinator. Its implementation lives in\n[packages/core/release/promote-ref](../../../../packages/core/release/promote-ref).\nThe entrypoint contains no business logic; `inputs.js`, `request.js`, `source-lock.js`,\n`outputs.js` and the internal capability modules own their respective operations.\n\nThe canonical channel graph is\n`dev/vX/vX.Y -> alpha/vX/vX.Y -> release/vX/vX.Y`, with\n`publish-gate/major` as the explicit major transition. An exact release tag,\nfloating channel and version-state commit are separate evidence coordinates.\nRetired branch aliases and publisher-selection inputs are not accepted.\n\nOrdinary GitHub Release publication uses the declarative provider adapter.\nComplete-transaction recovery first proves the retained transaction and exact\nprovider assets. A missing asset never permits replacement of an existing asset\nwith a different digest. The full existing asset set is checked before any upload.\n\nVersion-state discovery reads declared TOML settings and package-manager workspace\nmetadata, including nested action packages. Anchored/manual products retain their\nexplicit upstream anchor; semver/auto products prepare the next development version\nthrough the governed next-development transition.\n\nDry-run reports the exact intended effects and performs bounded read-only provider\nlookups. It does not authorize publication. Live publication requires the admitted\nsource lock, runtime identity, candidate evidence, provider policy and protected\nchannel transaction. See [release governance](../../../../docs/release-governance.md)\nand [provider-plane settlement](../../../../docs/release-tail-provider-plane.md).\n\nGenerated JavaScript and the Rust domain WASM are committed under `dist` and must\nmatch the source. Run `pnpm run build` and `pnpm run check` from the repository root.\nThe 4.1 development restructuring itself does not publish an alpha or move a floating tag.\n\n## Admitted promotion inputs\n\nThe workflow's apply node supplies these source-lock and candidate inputs to the\nadapter. This fragment documents the internal action ports; consumer callers use\nthe public request contract linked above.\n\n```yaml\nwith:\n target-ref: release/v22/v22.22\n require-publish-source-lock: \"true\"\n publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n promote-only-release-candidate: \"true\"\n release-candidate-family-evidence-required: \"true\"\n publish-rematerialize-on-resume: true\n```\n\n`target-ref` remains the channel promotion target. Direct `alpha/*` or `release/*` channel refs\nare not publish source locks. A mismatched source SHA fails before any promotion or publish side effects begin.\nThe exact candidate Passport, family evidence and reconciliation workspace are\nvalidated before provider effects; rematerialization requires the sealed recovery contract.\n\nPassport evidence ports bind product-owned evidence to the resulting release:\n`release-passport-kfd-1-witness-jsons`, `release-passport-kfd-2-claim-jsons`,\n`release-passport-kfd-3-prebuild-witness-jsons`,\n`release-passport-kfd-adopter-manifest-json`,\n`release-passport-kfd-support-matrix-json`, and\n`release-passport-kfd-product-gate-jsons` carry the corresponding KFD evidence.\n`release-passport-evidence-jsons` carries additional evidence documents;\n`release-passport-invariant-passport-command` and\n`release-passport-attachment-command` identify the declared product-owned evidence\noperations. These ports do not replace consumer qualification or provider readback.",
"slug": "release/promotion/ref"
},
{
"id": "action:release/tail/settle",
"title": "Declarative Release Tail",
"route": "/actions/release/tail/settle",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/tail/settle/README.md",
"digest": "sha256:bdc41acd1ead3565f34427a7c996e97df8dcbb6132c4d35afc1e44e150620f71",
"headings": [
{
"level": 1,
"title": "Declarative Release Tail",
"anchor": "declarative-release-tail"
}
],
"markdown": "# Declarative Release Tail\n\nThis Action executes the versioned `buildchain.release-tail/v1` declaration\nthrough one durable Buildchain transaction. It accepts only data bindings for\nsealed artifacts, rooted JSON documents, HTTP provider endpoints and released\nevidence inputs. It does not accept a command, script, executable path, plugin\nor repository callback.\n\nEvery mutation is preceded and followed by provider readback. Buildchain core,\nnot the adapter, compares the observed subject and target roots, owns retry and\nterminal classification, checkpoints state and emits the standardized receipt.\nTokens remain Action inputs and are never written to the transaction or\nreceipt.\n\nWhen `rehearsal-capsule` is supplied, the same Action switches to the v4\nPublication Rehearsal Capsule boundary. `simulate` and `replay` remain\neffect-disabled. `provider` additionally requires exact capsule-bound\nrehearsal authority, consumes only the capsule-rooted data bindings, and\nrecords every request/readback while still emitting\n`productionAuthority: false` and no Release Passport. See\n[`docs/v4-publication-rehearsal.md`](../../docs/v4-publication-rehearsal.md).",
"slug": "release/tail/settle"
},
{
"id": "api:node-package",
"title": "Buildchain Core",
"route": "/api/node-package",
"category": "api",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "packages/core/README.md",
"digest": "sha256:11d963d9b8f241769d34e45b2fa04831c414fb8ee24e980633f0f1a15669f5b6",
"headings": [
{
"level": 1,
"title": "Buildchain Core",
"anchor": "buildchain-core"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-layered-architecture\ndoc_type: implementation-guide\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Buildchain 4.1 source, architecture registries and local validation.\n invisible_context_boundary: No unpublished release or external consumer qualification is claimed.\n---\n\n# Buildchain Core\n\nCore contains JavaScript business logic and provider IO, grouped by the closed\ncapabilities in [`architecture/code-layout.json`](../../architecture/code-layout.json).\nSee [Code organization](../../docs/code-organization.md) for the complete layout.\n\nEach capability groups its business transactions, action adapters and supporting\nmodules by responsibility. Action adapters invoke named transaction APIs; they do\nnot dispatch old CLI steps. Command-line handlers live in `cli/`, and executable\ncapability tools in `commands/` delegate to the same core modules. The root `index.js` is the public API aggregation;\nimplementation modules import their actual owner directly.\n\nCore cannot depend on `actions`, `.github/workflows`, `bin`, or repository\n`scripts`. Rust-owned domain decisions are called through the existing WASM/host\nboundary and have no JavaScript fallback.\n\nUse the generated [Node API Reference](../../docs/node-api-reference.md) for\ncurrent package subpaths, symbols and signatures. For example:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI is the adapter for shells and non-JavaScript tools. Core modules can be\nused directly by JavaScript callers. Both paths share the same implementations.",
"slug": "node-package"
},
{
"id": "manual:artifact-verification-envelope",
"title": "Artifact Verification Envelope",
"route": "/docs/artifact-verification-envelope",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/artifact-verification-envelope.md",
"digest": "sha256:514911d2a5ee8ea65e070ffb0fc81a87f0ae35d7d87ff61999e47f784a7e9769",
"headings": [
{
"level": 1,
"title": "Artifact Verification Envelope",
"anchor": "artifact-verification-envelope"
},
{
"level": 2,
"title": "Public API",
"anchor": "public-api"
},
{
"level": 2,
"title": "Canonicalization and roots",
"anchor": "canonicalization-and-roots"
},
{
"level": 2,
"title": "Fail-closed behavior",
"anchor": "fail-closed-behavior"
}
],
"markdown": "# Artifact Verification Envelope\n\nBuildchain can turn a passing exact-artifact passport verification into one\nsealed, versioned input for Kungfu KFX admission. The envelope carries the\npublic verification result together with exact package, source, dependency,\nbuild-plan, toolchain, artifact, qualification, and verifier roots; issuer and\npublisher identity; lifecycle and revocation facts; and an existing ADR-0052\nKFD assessment.\n\nThe envelope does not create a second KFD evaluator. It validates and binds an\nassessment produced by the Kungfu KFD lifecycle. It also does not claim that an\nartifact is malware-free, universally safe, fit for every workspace, or\nauthorized as a Product System component.\n\n## Public API\n\nImport the dedicated package subpath:\n\n```js\nimport {\n projectArtifactVerificationEnvelopeToKfx,\n sealArtifactVerificationReport,\n verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\n`verifyArtifactPassport` also accepts an optional `verificationEnvelope`\nobject. Existing callers that omit it receive the unchanged\n`kungfu-buildchain-artifact-verification` v1 result.\n\n```js\nconst attestation = await verifyArtifactPassport({\n subject: \"dist/example.kfx\",\n passportLocation: \"dist/buildchain.release.json\",\n verificationEnvelope: {\n bindings,\n kfdAssessment,\n issuedAt,\n expiresAt,\n revocation,\n },\n});\n```\n\nThe result keeps the artifact-verification v1 fields that existing consumers\nunderstand and adds:\n\n- `bindings`: the schema-closed `kungfu.kfx-trust-inputs/v1` exact roots and\n identities;\n- `issuedAt`, `expiresAt`, `revoked`, and a root-bound `revocation` fact;\n- `kfdAssessment`: the pinned fresh `kungfu.trust.assessment/v1` lifecycle\n result;\n- `envelope`: the envelope contract, canonicalization version, and exact\n content root.\n\n`projectArtifactVerificationEnvelopeToKfx` returns the same sealed report as\n`attestation`, its exact `bindings` as `trustInputs`, and its existing\n`kfdAssessment`. A consumer does not reconstruct fields, recompute the KFD\ndecision, or inspect private Buildchain structures.\n\nThe read-only CLI uses those same functions for portable verification and\nprojection:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n --assessment-time 150 \\\n --expected-root sha256:... \\\n --expected-issuer buildchain.libkungfu.dev \\\n --expected-publisher kungfu-systems \\\n --expected-contract buildchain.release/v1 \\\n --json\n\nbuildchain project kfx-admission envelope.json \\\n --assessment-time 150 \\\n --json\n```\n\nThe projection's `envelopeRoot` is the same root returned by the Node verifier.\nThe CLI never adds consumer-side bindings or KFD conclusions.\n\n## Canonicalization and roots\n\nThe v1 envelope uses `buildchain-stable-json/v1`: object keys are sorted\nrecursively, array order is retained, and the root is lowercase SHA-256 with a\n`sha256:` prefix. `envelope.root` is excluded from its own root basis.\n\nThe KFD report hash is independently recomputed over the report with\n`report_hash` removed. The envelope is accepted only when:\n\n- the base artifact passport verification passes;\n- `bindings.artifactRoot` equals both the exact subject digest and the matched\n passport artifact digest;\n- every binding root is canonical lowercase SHA-256;\n- `bindings.qualificationRoot` equals the recomputed KFD `report_hash`;\n- the assessment key matches the report and its lifecycle state is `fresh`;\n- the report binds purpose, query proof, contract world, policy, and at least\n one fact-surface root;\n- lifecycle bounds are active and revocation facts are internally consistent;\n- any caller-pinned envelope root, issuer, publisher, or contract version\n matches exactly.\n\n## Fail-closed behavior\n\n`verifyArtifactVerificationEnvelope` returns a machine-readable check report.\nIt rejects sibling artifacts, root tampering, identity drift, invalid contract\nversions, expired or revoked envelopes, stale assessments, altered KFD report\ncontent, and missing fact-surface bindings. Callers may pin expected authority\nfields without changing the envelope.\n\nThe canonical root detects changed serialized content; authenticity still\ndepends on the pinned Buildchain verifier and release passport authority. The\nenvelope is supply-chain and evidence input. Kungfu Product and Workspace\npolicy retain operation, capability, and System-role authority."
},
{
"id": "manual:auditable-demo",
"title": "Auditable Demo Pipeline",
"route": "/docs/auditable-demo",
"category": "manual",
"capabilityGroup": "reusable-build",
"audience": [
"consumer",
"agent"
],
"maturity": "preview",
"sourcePath": "docs/auditable-demo.md",
"digest": "sha256:c04ec63055c0bfd2270adf94163e69380a1ccf3ac7ca49d7795a382dd6893b6a",
"headings": [
{
"level": 1,
"title": "Auditable Demo Pipeline",
"anchor": "auditable-demo-pipeline"
},
{
"level": 2,
"title": "Declarative Standalone Binary Scenarios",
"anchor": "declarative-standalone-binary-scenarios"
},
{
"level": 2,
"title": "Authority Boundary",
"anchor": "authority-boundary"
},
{
"level": 2,
"title": "Required Gate",
"anchor": "required-gate"
},
{
"level": 2,
"title": "Selective Render",
"anchor": "selective-render"
},
{
"level": 2,
"title": "Media Qualification Profiles",
"anchor": "media-qualification-profiles"
},
{
"level": 2,
"title": "Consumer Example",
"anchor": "consumer-example"
},
{
"level": 2,
"title": "Failure Evidence",
"anchor": "failure-evidence"
}
],
"markdown": "---\nstatus: draft\nperiod: 2026-07\ntheme: auditable-demo-pipeline\ndoc_type: technical-contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-20\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-20\n invisible_context_boundary: No hidden model build, parameter count, or private corpus is asserted.\n visible_context: Current two-entry consumer contract and retained internal implementation references.\n---\n\n# Auditable Demo Pipeline\n\nBuildchain's auditable demo workflow turns an exact GitHub build artifact into\ntwo distinct evidence products:\n\n1. a required qualified Gate bundle; and\n2. an optional rendered media bundle that can exist only after that exact Gate\n bundle passes.\n\nThe internal `.build-demo-adapter.yml` and `.build-demo.yml` components own\nadapter execution and standalone CLI demo qualification. Their artifact, scenario,\nGate, renderer and materializer ports are runtime implementation details.\nConsumers use the shared normal/recovery pair and do not copy a separate demo\nworkflow or pass artifact handoff parameters into consumer YAML.\n\n## Declarative Standalone Binary Scenarios\n\nThe schema is `contracts/auditable-demo-scenario-v1.schema.json`. One scenario\ncan declare up to eight demos, and each demo can contain up to twelve ordered\nliteral argv steps. Steps in one demo share a disposable workspace; separate\ndemos and the two rendition captures do not. Commands are never accepted as a\nshell string. An omitted or explicit `standard` duration class remains bounded\nto 60 seconds. A reviewed `execution.durationClass: long-form` declaration may\nraise the scenario and literal step ceilings to 180 seconds; it does not change\nthe default. Both classes retain 4 MiB per step, a clean Home/XDG environment,\nno inherited credentials, and a network-disabled read-only container with\nbounded tmpfs.\n\nConsumers may optionally add a\n`buildchain.declarative-demo-presentation/v1` presentation. This contract\nbinds one consumer-owned proof label, question, summary, and optional\ntransition to every demo in declared order. Buildchain verifies that each\nquestion is the same title used by capture and media; it does not invent or\nreinterpret the product argument.\n\nThe presentation also chooses one of two README materialization modes. The\ndefault, when no presentation is declared, remains the original full generated\nblock with commands, renditions, evidence, and claim boundary. `media-only`\nupdates only the image inside each existing README marker so consumer-authored\nnarrative and transitions survive regeneration. The generated technical\ndetails move to a separately declared Markdown specification, where stable\nper-demo markers preserve proof order and idempotent updates. The publication\npull request stages that specification together with the README and\ncontent-addressed evidence. No presentation field grants publication or Work\nauthority.\n\nThe optional top-level `compositionMode` is an explicit visual contract.\nOmitting it preserves `presentation-framed`; declaring `terminal-fill` makes\nthe bounded PTY replay the complete pixel surface without renderer-owned\nwindow chrome. Buildchain carries that choice into both native scenes. It does\nnot infer full-frame intent from output resolution.\n\nThe optional `buildchain.declarative-demo-playback/v1` contract separates\nobserved command latency from presentation timing. Its\n`deterministic-readable` mode preserves the captured terminal event payloads\nand their order, records the observed final-event time as non-authoritative\nevidence, and maps event ordinals onto the declared `activeDurationMs` before a\nbounded `finalHoldMs`. Both native renditions therefore replay at the same\nreadable pace even when an identical command runs faster or slower. Omitting\nthe contract preserves the original PTY timestamp behavior.\n\nThe uploaded metadata must bind the executable SHA-256, declare an empty\nruntime dependency set, and provide a bounded `executableFiles` array of exact\nartifact-relative paths and SHA-256 digests. GitHub Artifact transport does not\nretain Unix executable modes, so Buildchain restores mode `0755` only for this\ndigest-verified executable closure and verifies the same closure again inside\nthe network-disabled capture boundary. It never recursively changes artifact\nmodes. This metadata controls assembly only and grants no execution,\npublication, or identity authority. Capture rejects an artifact name or upload\ndigest that does not resolve to exactly one live artifact from the current workflow run.\n\nConsumers may also declare one bounded, non-interactive `transportSmoke` argv\nin the same scenario and opt the reusable build into\n`pre-upload-transport-smoke-scenario-path`. Before any GitHub Artifact or S3\nrelay upload, Buildchain copies the exact distribution directory, removes Unix\nexecute bits to simulate transport, restores only the digest-bound executable\nclosure, and runs that real binary with a clean Home/XDG environment. A missing\nlauncher, runtime, or embedded interpreter therefore fails before the expensive\nupload begins. This is a transport diagnostic with no authority grants; the\nlater network-disabled capture and Gate remain the qualification authority.\nIt retains ANSI terminal bytes with the real PTY read timestamps, verifies\ndeclared stdout and JSON file facts, enforces the total deadline while a step is\nrunning, and removes the disposable workspace before emitting evidence.\n\nInternal callers select Gate-only or full rendering under the same capture and\nmaterialization contracts. An admitted materialization capability, independent\nGate result and exact retained bytes remain necessary for any write. Product\nmetadata and generated evidence do not grant mutation authority.\n\nBuildchain retains its scenario in `.buildchain/auditable-demo.json`. The former\nstandalone self-demo caller is retired. Existing media is historical evidence;\na source or document change does not regenerate or qualify that media.\n\n## Authority Boundary\n\nThe retained build output is authoritative. The adapter reads that exact\nartifact and projects three files:\n\n```text\ncomplete-transcript.txt\npublic-projection.json\nscene.json\n```\n\nIt may additionally emit one declared `terminal-capture.json` using\n`kungfu.terminal-capture/v1`. The optional capture is bounded to 60 seconds by\ndefault or 180 seconds only when its scene explicitly declares `long-form`,\nfixed 80-200 by 24-80 terminal cells, 10,000 events, and 4 MiB of canonical\nbase64 bytes. It must contain a qualified completion sentinel and an explicitly\nempty authority-grant list. Existing three-file adapters remain valid.\n\nThe completion sentinel names a consumer-owned versioned schema, the exact\n`qualified` status, a content root, and an event count. Buildchain validates\nthat envelope generically; it does not reinterpret a command-specific result\nas Agent Work Lab evidence or grant authority from the schema name. The\nconsumer projection and its retained source artifact remain responsible for\nthe exact claim boundary.\n\nTerminal bytes are volatile observations, not Work, Warrant, capability, or\npublication authority. First-party or System identity, KFD compliance, Product\nSystem metadata, package metadata, scan output, registry history, and\nstandalone generation remain non-authoritative unless an exact higher-level\ncontract independently admits them.\n\nThe adapter must not rebuild or rerun the product. It receives:\n\n```text\n--artifact-root PATH\n--output PATH\n--source-coordinate PATH\n```\n\nConsumers with one shared adapter for several deterministic demos may also set\n`adapter-arguments-json` to a bounded JSON array. Buildchain parses the array,\nrejects malformed values, newlines, NUL bytes, more than 32 arguments, values\nlonger than 256 bytes, and attempts to override the three coordinate flags\nabove, then appends the accepted strings directly to the adapter argv. It never\nevaluates a shell command. The exact argument vector and its content root are\nretained in `adapter.json`; the Gate receipt binds that root. Adapter arguments\nselect consumer-owned capture behavior only and grant no authority.\n\n`--source-coordinate` identifies the caller repository, run, artifact id,\nartifact name, upload digest, expiry, and exact source SHA. The workflow finds\nexactly one live artifact with the requested name in the current caller run and\nrejects a digest mismatch before invoking the adapter. Callers must pass the\ndigest emitted by their own `upload-artifact` step; a name resolved later from\nthe Actions API is discovery evidence, not a substitute for that producer\noutput.\n\nBuildchain's reusable build workflow exposes `artifact-coordinates-json` after\nall resolved platform uploads complete. That producer-owned output binds every\nplatform id to its same-run artifact id, name, upload digest, URL, and expiry,\nso a consumer that delegates its build to Buildchain can pass an exact\ncoordinate without rediscovering authority in a downstream job. The build\naggregate fails closed if any declared platform lacks one live, digest-bearing\nartifact coordinate. The compact coordinate set is sorted by platform id so\ndownstream machine consumers do not depend on matrix completion order.\n\nThe adapter runs with a disposable Home/XDG/npm prefix, a minimal environment,\nand no GitHub, npm, or cloud credential injection. It must be a regular,\nnon-symlink, executable file inside the exact checked-out consumer source.\n\n## Required Gate\n\nThe Gate:\n\n- prepares the selected execution runtime and checks out the exact consumer source;\n- resolves and downloads one exact same-run GitHub Artifact;\n- invokes the checked-in adapter by argv, never as an evaluated shell string;\n- rejects undeclared adapter outputs, symlinks, invalid UTF-8, invalid scene or\n projection or terminal-capture schemas, implicit capture grants,\n out-of-range transcript references, and oversized input;\n- derives a one-second compatibility scene from the consumer projection;\n- anonymously pulls an immutable `image@sha256:digest` renderer;\n- runs it as non-root with `--network none`, a read-only root filesystem, and a\n bounded tmpfs;\n- verifies the renderer manifest, media probe, exact input roots, exact output\n member set, and complete checksums;\n- independently verifies the requested composition mode, browser-observed\n content viewport, PTY rows and columns, and deterministic cell geometry for\n every frame set; `terminal-fill` is rejected unless the viewport and cell\n grid resolve to the complete declared frame;\n- uploads a content-addressed qualified bundle plus an independent GitHub\n Artifact id, URL, archive digest, and expiry-bearing source coordinate.\n\nThe Gate bundle contains the complete consumer transcript/projection/scene,\nsource artifact coordinate, adapter identity, bounded renderer evidence, a\npassed gate receipt, and checksums covering every member exactly once.\n\n## Selective Render\n\n`render-media: true` enables the full-media step only after every declared demo\nhas passed the required Gate. It recomputes each Gate member root, verifies the\nexact source SHA and renderer digest, and only then renders the complete\nqualified scene.\n\nThe media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,\nrenderer checksums, passed Gate receipt, a versioned media receipt, and\ndistribution checksums. A web-delivery profile also retains\n`media-inspection.json`, whose content root is bound into the receipt.\n`render-media: false` does not weaken or skip the Gate.\n\n`render-failure-advisory: true` makes only the full-media step advisory. A\nrender failure remains visible as a failed step and workflow warning, while the\nrequired Gate keeps its normal failure semantics. Failed or partial media can\nnever open a materialization PR. Use this for an Alpha lane whose binary\npublication must not depend on animation capacity; keep the default `false`\nfor explicit media refreshes and other workflows that require complete media.\n\nWhen the Gate bundle contains a qualified terminal capture, the render job\npasses it read-only to the immutable renderer. The renderer manifest binds the\ncapture root and terminal-state-machine version, but raw capture bytes remain\nin the Gate bundle rather than being copied into the public media bundle.\nMissing, malformed, out-of-bounds, non-full-frame, rendition-mismatched, or\ninternally drifted composition evidence fails before media finalization.\n\n## Media Qualification Profiles\n\nThe single machine-readable source is\n`contracts/auditable-demo-media-profiles-v1.json`. Callers select one reviewed\nprofile through `media-profile`; they cannot pass ffmpeg commands, codec flags,\nshell fragments, arbitrary profile paths, or transcoding instructions.\n\n| Profile | Meaning |\n| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |\n| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |\n| `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |\n| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |\n| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |\n\nFor web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation\ninside the same immutable, network-disabled renderer image. That command is\nBuildchain-controlled; the producer cannot inject flags. The resulting witness\nrecords exact roots and byte counts plus container, codec, pixel format,\ndimensions, duration, frame rate, audio stream count, and progressive-download\nevidence. Finalization re-hashes the retained bytes, rechecks the witness root,\nand parses MP4 top-level boxes itself. The producer's `media-probe.json.passed`\nfield remains supporting evidence, never sufficient authority.\n\nThe default `archive-v1` path preserves the existing v1 media receipt exactly.\nAn explicitly selected web-delivery profile emits a v2 media receipt with a\ncontent-addressed rendition list and explicit roles, MIME types, dimensions,\nand dimension policy. Agents and site builds select `primary-video`,\n`alternate-video`, `responsive-primary-video`,\n`responsive-alternate-video`, `browser-poster`, or evidence-only roles from\nthat receipt; they do not infer semantics from extensions or filenames.\nProfile-declared responsive renditions must match their exact dimensions,\nremain within the source scene, and preserve its aspect ratio. Additional\nproducer-declared renditions remain bounded by the selected profile and cannot\nraise their own byte ceiling. Unbound outputs, implicit upscales, aspect-ratio\ndrift, duplicate singleton roles, unknown profiles, or unsupported required\nversions fail closed.\n\nThe required Gate binds the exact selected media profile and the smoke media\nqualification root before optional full rendering starts. Gate-only validation\nand full rendering therefore exercise the same profile contract; a later media\njob cannot silently switch rendition authority.\n\nInitial byte ceilings are derived from the checked-in\n`auditable-demo-web-delivery-v1` fixture rendered by Build Images\n`v1.3.0-alpha.16` at its exact source SHA and image digest. GIF, MP4, WebM, and\nPNG ceilings are the next power of two above sixteen times the measured member\nbytes. The explicit responsive long-form profile derives its 4 MiB video and\n8 MiB GIF ceilings from the same observed bytes at a bounded 128-times\nmultiplier; it does not change another profile. The not-yet-produced WebP poster\nuses eight times the measured lossless PNG as its conservative proxy. The path-scoped qualification workflow\nregenerates the content-addressed evidence and fails on any byte or fact drift.\nIts matrix retains the original 1280x720 web-delivery baseline on the renderer\nthat produced it and separately measures the responsive profile against a\n1920x1080 fixture and the first exact renderer release that emits both\nsource-resolution and 720p renditions. This keeps historical budget evidence\nreproducible while giving the responsive contract its own immutable\nqualification root.\n\n## Consumer Example\n\nThe build job must expose both the exact artifact name and the digest returned\nby `upload-artifact`:\n\n```yaml\njobs:\n build:\n runs-on: ubuntu-24.04\n outputs:\n artifact-name: product-linux-${{ github.sha }}\n artifact-digest: ${{ steps.upload.outputs.artifact-digest }}\n steps:\n - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09\n - run: ./scripts/build-product\n - id: upload\n uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n with:\n name: product-linux-${{ github.sha }}\n path: dist\n if-no-files-found: error\n retention-days: 14\n compression-level: 0\n\n auditable-demo:\n needs: build\n permissions:\n actions: read\n contents: read\n uses: kungfu-systems/buildchain/.github/workflows/.build-demo-adapter.yml@v4\n with:\n source-ref: ${{ github.sha }}\n source-artifact-name: ${{ needs.build.outputs.artifact-name }}\n source-artifact-digest: ${{ needs.build.outputs.artifact-digest }}\n adapter-path: scripts/auditable-demo-adapter\n adapter-arguments-json: '[\"--demo-id\",\"agent-work-lab\"]'\n renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST\n render-media: false\n media-profile: archive-v1\n```\n\nReplace both placeholders with reviewed immutable SHAs or digests. An eligible\nbuild should always call the reusable workflow. Selection policy changes only\n`render-media`; it must never condition away the Gate job.\n\nUse `web-delivery-v1` only when the rendered bundle is intended to become a\nqualified web-delivery source. Use `site-hero-v1` when an optimized browser\nposter is also required. Select `responsive-long-form-web-delivery-v1` only\nwith an explicit long-form scenario. Profile qualification does not prove browser playback,\nresponsive layout, reduced-motion behavior, accessibility, or production\ndeployment; those remain site responsibilities.\n\n## Failure Evidence\n\nGate and render jobs use bounded timeouts and non-cancelling concurrency.\nDiagnostics artifacts are attempted with `always()` so adapter stdout/stderr\nand the resolved source coordinate remain available when qualification fails.\nNo production deployment, publication authority, token, or provider mutation\nis part of this workflow."
},
{
"id": "manual:aws-us-elastic-runner-burst-plane",
"title": "AWS US elastic runner burst plane",
"route": "/docs/aws-us-elastic-runner-burst-plane",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/aws-us-elastic-runner-burst-plane.md",
"digest": "sha256:8d0594d546dff2a33d465ecbc6adc6a3a925d1cd6bed6875cf292f13eebb14b2",
"headings": [
{
"level": 1,
"title": "AWS US elastic runner burst plane",
"anchor": "aws-us-elastic-runner-burst-plane"
},
{
"level": 2,
"title": "Phase 1 contract",
"anchor": "phase-1-contract"
},
{
"level": 2,
"title": "Cost and kill-switch envelope",
"anchor": "cost-and-kill-switch-envelope"
},
{
"level": 2,
"title": "Qualification evidence",
"anchor": "qualification-evidence"
},
{
"level": 3,
"title": "Phase 1 recorded outcome",
"anchor": "phase-1-recorded-outcome"
},
{
"level": 2,
"title": "Phase 2 contract",
"anchor": "phase-2-contract"
},
{
"level": 3,
"title": "Phase 2 operator workflow",
"anchor": "phase-2-operator-workflow"
},
{
"level": 3,
"title": "Lower-level campaign and launch controllers",
"anchor": "lower-level-campaign-and-launch-controllers"
},
{
"level": 2,
"title": "Phase 3 contract",
"anchor": "phase-3-contract"
},
{
"level": 3,
"title": "Phase 3 lifecycle controller",
"anchor": "phase-3-lifecycle-controller"
},
{
"level": 2,
"title": "Provider lifecycle",
"anchor": "provider-lifecycle"
},
{
"level": 2,
"title": "Source boundaries",
"anchor": "source-boundaries"
}
],
"markdown": "---\nstatus: draft\nperiod: 2026-07-28\ntheme: aws-us-elastic-runner-burst-plane\ndoc_type: design\nsource_level: local-files-and-provider-docs\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-08-03\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-08-03\n invisible_information: No hidden model checkpoint, parameters, or private training data were available.\n---\n\n# AWS US elastic runner burst plane\n\nThe local runner fleet remains the normal Kungfu build plane. This AWS US plane\nis an explicit, temporary overflow mechanism with sequential qualification:\n\n1. Linux CodeBuild proof of concept under USD 50.\n2. Windows EC2 one-job JIT runners.\n3. One bounded 24-hour EC2 Mac campaign.\n\nNo later phase can start from design intent alone. The preceding phase must\nproduce a qualifying source-bound receipt, actual cost, and zero-resource\ncleanup proof.\n\n## Phase 1 contract\n\n`aws-us-codebuild-linux` is a Linux-only runner preset. It requires the exact\nCodeBuild project name and resolves the runner label at workflow evaluation\ntime:\n\n```text\ncodebuild---\n```\n\nThe GitHub-hosted `trust-gate` remains ahead of the matrix job. A fork pull\nrequest therefore fails or skips before the CodeBuild `runs-on` label exists as\na queued job. The dedicated consumer workflow is manual-only and does not add\nthe preset to dev, alpha, release, signing, notarization, deployment, or\npublication workflows.\n\nThe CodeBuild project is:\n\n- repository-scoped through an AWS CodeConnections GitHub App;\n- one ephemeral runner and one GitHub job per CodeBuild build;\n- outside a VPC, with no idle VM, NAT gateway, public ingress, SSH, or persistent\n workspace;\n- limited to two concurrent builds, 15 queued minutes, and 40 execution\n minutes;\n- allowed to write only its dedicated CloudWatch log group and request a token\n from its dedicated GitHub App connection;\n- forbidden from receiving signing, notarization, package publication, release,\n deploy, static AWS, long-lived GitHub, or SSH credentials.\n\nThe AWS-managed Ubuntu 24.04 standard image is the immutable base. Before a\nnative lifecycle starts, Buildchain installs the distribution's `gcc-14` and\n`g++-14` packages, exposes only per-job `gcc`/`g++` aliases, and downloads the\npinned Kitware CMake 3.31.6 archive after verifying its reviewed SHA256. The\nresolved package manager, versions, and CMake source digest are retained as\n`aws-native-toolchain.json`; no toolchain state survives the ephemeral\nCodeBuild execution. The toolchain adapter also retains the reviewed Amazon\nLinux 2023 `gcc14` path for compatible projects.\n\n## Cost and kill-switch envelope\n\nThe 2026-07-28 AWS Price List entry for\n`BUILD_GENERAL1_XLARGE` Linux in `us-east-1` is USD 0.0798 per build minute.\nThe contract rounds that rate up to USD 0.08. Twelve fully timed-out accepted\nbuilds reserve at most USD 38.40. At project concurrency two, the fail-closed\ncontroller can see at most two over-cap builds. The envelope conservatively\ncharges both race builds for their complete 40-minute timeout rather than\nassuming fast EventBridge delivery. The bounded CodeBuild maximum is therefore\nUSD 44.80, below the dedicated USD 49 budget and leaving USD 4.20 for the small\ncontroller, state, notification, and log charges.\n\nThe controller stores an idempotent build-id ledger, an atomic accepted-build\ncounter, and worst-case reservation in DynamoDB. Duplicate EventBridge delivery\ndoes not consume the bounded build allowance. It deletes the CodeBuild webhook\nand stops the triggering build when:\n\n- the accepted-build or reserved-cost cap is reached;\n- actual-cost telemetry is missing or more than six hours old;\n- actual CodeBuild spend reaches the budget;\n- AWS Budgets sends the 80% or 95% actual-spend notification;\n- the kill switch was already set.\n\nThe stack starts fail closed: it has no cost telemetry item and CloudFormation\ndoes not create the webhook. Before arming the webhook, the operator must write\na current Cost Explorer observation to the `COST` item, clear only the dedicated\ncontroller's killed state, and create the exact workflow-filtered webhook.\nRe-arming after any kill is a separate provider mutation and requires a new\nexplicit approval.\n\n## Qualification evidence\n\nEach successful job uploads `aws-runner-burst.json`, binding:\n\n- consumer repository, exact source SHA and ref;\n- GitHub run id, attempt and job;\n- CodeBuild project, build id, build ARN and initiator;\n- observation timestamp and canonical digest.\n\nLinux qualification requires:\n\n- at least 10 trusted exact-source successful jobs;\n- observed concurrency of at least two;\n- p95 queue-to-start of at most five minutes;\n- actual incremental AWS spend below USD 49;\n- no idle build and no active cloud residue.\n\n`node packages/core/providers/commands/aws-runner-burst.mjs verify-linux --input ` fails\nclosed when cost telemetry is missing/stale or any acceptance predicate is\nfalse.\n\n### Phase 1 recorded outcome\n\nThe Linux phase passed on 2026-07-29. Ten trusted exact-source Kungfu jobs\ncompleted successfully, including four overlapping two-job waves. The observed\nCodeBuild queue-to-start p95 was 0.696 seconds. All 16 paid executions,\nincluding six diagnostic runs, produced a conservative incremental compute\nupper bound of USD 25.798 by rounding every execution up to a whole minute at\nthe live AWS Price List rate.\n\nThe global webhook kill switch was exercised after the tenth qualifying job.\nThe project then reported no webhook or in-progress build, and the card-owned\nEC2 inventory was empty. AWS Billing and Cost Explorer still reported an\nestimated zero during their provider ingestion delay; the retained\nexecution-derived upper bound is therefore the immediate cost proof and must be\nreconciled with the eventual AWS line item in the final campaign report.\n\nThe source-bound evidence and deterministic phase receipt are:\n\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-input.json`\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-receipt.json`\n\n## Phase 2 contract\n\nThe Windows phase uses the explicit `aws-us-ec2-windows-jit` runner preset.\nIts caller supplies one bounded label under\n`aws-us-ec2-windows-jit--`, and Buildchain\nresolves exactly one Windows x64 native lane. The reusable trust gate still\nruns on a GitHub-hosted runner before the JIT label can select EC2.\n\nThe provider creates repository-level GitHub JIT configuration for\n`kungfu-systems/kungfu`. Its `labels` request must contain all four scheduling\nlabels: `self-hosted`, `Windows`, `X64`, and the card-scoped\n`aws-us-ec2-windows-jit--` label. The workflow\ndisplay title also carries both identities, allowing the launch controller to\nverify the queued run against its campaign plan. GitHub's JIT endpoint does\nnot infer the default OS and architecture labels when they are omitted. The\nencoded configuration is never placed in EC2 user data, a tag, a command log,\nor an artifact. The operator writes it to a card-scoped SSM SecureString under\n`/kungfu/burst/windows/`; the instance role can read and delete only that\nprefix. Bootstrap reads the value once, deletes the parameter immediately, and\npasses it only to the pinned runner process.\n\nEach runner uses:\n\n- Amazon's current Windows Server 2025 Full Base AMI, resolved through the\n public SSM AMI parameter and retained by exact AMI id and name;\n- `c7i.4xlarge`, one instance and one JIT runner per job;\n- GitHub Actions Runner 2.336.0 with the official Windows x64 SHA256;\n- PowerShell 7.6.4 with the official Windows x64 MSI SHA256 and Microsoft\n Authenticode verification;\n- pinned PortableGit 2.55.0.3 with its GitHub release SHA256, exposing only its\n `cmd` directory so POSIX compatibility tools cannot shadow Windows tools;\n- a Microsoft Authenticode-verified Visual Studio 2022 Build Tools bootstrap;\n- IMDSv2, an encrypted root volume with delete-on-termination, no inbound\n security-group rule, no key pair, and no warm Auto Scaling capacity.\n\nRunner diagnostics and a redacted lifecycle record are uploaded to the\nprovider's encrypted, private evidence bucket under the exact campaign, run,\nattempt, and instance identity. The runner process exits after one job, Windows\nshuts down, and EC2's instance-initiated shutdown behavior is set to\n`terminate`. A five-minute reaper terminates card-owned stopped or\nthree-hour-old instances and deletes only their dedicated JIT parameter.\n\nAt the 2026-07-29 AWS Price List rate of USD 1.45 per Windows\n`c7i.4xlarge` hour, each accepted instance reserves its complete three-hour\nUSD 4.35 fail-closed lifetime before `RunInstances`. A DynamoDB transaction\nbinds the exact campaign and source, creates an idempotent run ledger entry,\nand atomically refuses a sixth accepted instance. Five accepted instances\ntherefore reserve at most USD 21.75. The campaign also persists the\noperator-observed spend from earlier Windows work, and refuses to arm unless\nthat baseline, all five reservations, and one USD 4.35 fail-closed race\nallowance remain below the USD 110 phase cap.\n\nThe campaign starts unarmed and expires within 24 hours. Its `CONTROL` record\ncan be created only once: a killed or expired campaign cannot be re-armed by\nthe campaign tool. A budget notification or any instance lifetime violation\npersists `KILLED` before cleanup, so later workflow dispatches fail before a\npaid launch. Reservations are never refunded: a controller crash, ambiguous\nlaunch, or successful launch all remain charged to the campaign, favoring a\nfalse stop over an accidental budget overrun.\n\nThe 2026-08-03 timeout-only campaign decision narrows the campaign to two\naccepted instances with one active instance at a time. The second reservation\nis an operator-gated repair retry: it may be used only after the first attempt\nis classified as non-counting and runner, EC2, EBS, SSM, and workflow residue\nhave returned to zero. The two-slot ledger is a maximum spend boundary, not an\nauthorization to consume both reservations.\n\nEach stack owns a stack-scoped reaper log group, so an independent retained\none-shot campaign stack can be created without colliding with another\ncampaign's audit log resource.\n\nThe account-native AWS Budget is defense in depth, not the authoritative launch\ngate. It is owned by the singleton\n`kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained\ncampaign stack. This prevents Budget-name collisions and prevents a stale\ncampaign reaper from becoming the provider-wide cost authority. The Budget\nfilters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,\n`OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and\n95% actual notifications persist the provider kill sentinel, terminate every\ntagged Windows JIT instance, and delete scoped JIT parameters. Every launch\ncontroller refuses to proceed when the sentinel exists or when the Budget\nidentity or dimension filter does not match.\n\nBudget installation is intentionally deployable by the workload account without\nAWS Organizations management-account access. It fails closed unless Cost\nExplorer exposes all three AWS-owned billing dimensions in the requested phase\nwindow. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for\nownership, cleanup, and IAM scoping, but it is not a billing filter. Do not\ncreate an unfiltered fallback Budget or treat an incomplete dimension readback\nas evidence.\nThe DynamoDB campaign reservation remains the atomic launch authority because\nCost Explorer and AWS Budgets can lag provider activity.\n\nQualification requires one runner-profile smoke and three trusted exact-source\nfull Windows jobs all bound to the same campaign, independent cancellation and\ntimeout cleanup exercises, and zero repository runner, EC2 instance,\ndisposable volume, min capacity, and desired capacity within 15 minutes of the\nfinal job.\n\n### Phase 2 operator workflow\n\n`pnpm operator:windows-jit` is the reusable lifecycle entrypoint. Its default\nmode is `plan`, which performs no AWS or GitHub call. A plan binds the account,\nregion, unique campaign and stack names, source SHA/ref, Cost Explorer window,\nworkflow id, network, OIDC provider, expiry, slot ceiling, singleton Budget\nidentity, and exact confirmation digest.\n\nThe modes are deliberately separated:\n\n- `plan` emits the deterministic mutation boundary and digest.\n- `audit` reads AWS and GitHub only. It verifies the account, disabled workflow,\n singleton guard stack, exact Budget filter, SNS thresholds/subscribers,\n provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner\n residue.\n- `install-budget --execute` deploys or updates only the singleton Budget guard.\n It refuses to mutate unless all exact Windows billing dimensions are visible,\n the Windows workflow is disabled, and the account, campaign, source, Budget,\n and plan digest confirmations match.\n- `prepare --execute` requires the installed Budget guard, absent kill\n sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,\n `RunInstances:0002`, and `us-east-1`, zero residue, a\n never-used campaign stack name, and the disabled workflow. The receipt binds\n the query timestamp and exact filter identity. Preparation deploys the\n campaign stack and atomically arms the ledger with that provider-spend\n baseline. It never enables or dispatches the workflow and never creates EC2\n capacity.\n- `close --execute` disables the workflow first, persists `KILLED`, publishes\n the campaign kill switch, and reports terminal success only after EC2, EBS,\n SSM, JIT parameter, and GitHub runner residue is zero. It is safe to rerun\n while the reaper settles.\n\nAll mutating modes require `--execute`, `--confirm-plan-digest`,\n`--confirm-account-id`, `--confirm-campaign-id`, and\n`--confirm-source-sha`. Budget installation and preparation additionally\nrequire `--confirm-budget-name`. A future paid workload still requires a\nseparate exact workflow/run authorization and uses\n`packages/core/providers/commands/aws-windows-jit-controller.mjs`; preparation is not paid-launch\nauthority.\n\nStart by recording one reproducible plan:\n\n```bash\npnpm operator:windows-jit plan \\\n --aws-profile us \\\n --account-id 727884401362 \\\n --campaign-id win-REPLACE \\\n --source-sha REPLACE_WITH_EXACT_40_CHARACTER_SHA \\\n --source-ref refs/heads/dev/v4/v4.0 \\\n --observed-at REPLACE_WITH_ISO_TIMESTAMP \\\n --expires-at REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS \\\n --cost-start REPLACE_WITH_PHASE_START_DATE \\\n --cost-end REPLACE_WITH_EXCLUSIVE_END_DATE \\\n --max-accepted-instances 1 \\\n --workflow-id 322620360 \\\n --vpc-id REPLACE_WITH_VPC_ID \\\n --subnet-id REPLACE_WITH_SUBNET_ID \\\n --oidc-provider-arn REPLACE_WITH_GITHUB_OIDC_PROVIDER_ARN\n```\n\nReuse those exact arguments for `audit`, `install-budget`, `prepare`, or\n`close`; never regenerate `--observed-at` between the plan and its confirmed\nmutation. Capture stdout as the operator receipt. Do not put credentials,\ntokens, JIT configuration, or signed URLs in arguments or receipts.\n\n### Lower-level campaign and launch controllers\n\n`packages/core/providers/commands/aws-windows-jit-campaign-core.mjs` owns the pure one-shot ledger\ncontract used by the operator and launch controller. Arming creates `CONTROL`\nand `CAMPAIGN#` with `attribute_not_exists` conditions, so DynamoDB refuses\na second campaign in the same retained state table. There is deliberately no\nclear or re-arm operation.\n\nEvery `packages/core/providers/commands/aws-windows-jit-controller.mjs --execute` call must provide the\nsame `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,\nand `--confirm-state-table`. Before GitHub JIT material is created, the\ncontroller verifies the exact provider Budget/dimension filter and proves the\nglobal Budget kill sentinel absent. After the GitHub, AMI, active-instance,\nSSM, and EC2 DryRun checks pass, the controller\natomically reserves one run. Duplicate run-attempt-qualification identities,\nsource mismatch, expiry, `KILLED`, the sixth accepted instance, or a\nreservation that would exceed the USD 110 ceiling after combining the persisted\nfresh Cost Explorer baseline with all in-flight campaign reservations all fail\nclosed in one DynamoDB transaction before `RunInstances`. AWS Budget alarms are\ndefense in depth for delayed billing telemetry; the atomic ledger is the\nauthoritative launch-time guard. The operator is the only supported mutation\nsurface for campaign preparation and closeout; direct imports of the core are\nnot operator authority.\n\n## Phase 3 contract\n\nThe macOS phase uses the explicit `aws-us-ec2-macos-jit` runner preset. Its\ncaller supplies one unique label under\n`aws-us-ec2-macos-jit-`, and Buildchain resolves exactly one\nnative macOS ARM64 lane with `self-hosted`, `macOS`, `ARM64`, and the unique\ncampaign label. The reusable trust gate remains ahead of the JIT runner.\n\nUnlike Windows, the Mac campaign deliberately reuses one instance on one\n`mac2.metal` Dedicated Host. The operator allocates exactly one tagged host,\nlaunches exactly one tagged instance, and sends three sequential SSM bootstrap\ncommands. Each command consumes and immediately deletes a distinct repository\nJIT SecureString under `/kungfu/burst/macos/`, then runs GitHub Actions Runner\n2.336.0 for exactly one job. The runner archive is pinned to the official\nmacOS ARM64 SHA256. No GitHub, signing, notarization, publication, SSH, or\nstatic AWS credential is admitted to the instance.\n\nThe instance uses the exact retained Amazon EC2 macOS AMI, IMDSv2, an encrypted\ndelete-on-termination root volume, no inbound security-group rule, and the\nAMI's preinstalled SSM Agent and AWS CLI v2. The three accepted jobs must bind\nto the same host id, instance id, AMI id, source SHA, and campaign. At least one\njob must exercise the full native lifecycle.\n\nAWS imposes a 24-hour minimum Dedicated Host allocation. The contract therefore\nkeeps the one host for at least 24 hours even if all three jobs finish earlier.\nAt the recorded USD 0.6498 hourly rate, the minimum commitment rounds to USD\n15.60. A 30-hour fail-closed ceiling rounds to USD 19.49, below the dedicated\nUSD 25 budget. A ten-minute reaper terminates an expired campaign instance and\nretries host release after the minimum allocation and Apple scrub constraints\nallow it. Budget notifications at 80% and 95% invoke the same card-scoped kill\nswitch.\n\nQualification requires three trusted exact-source one-job JIT runs on the one\nhost, including at least one full run, plus proof that:\n\n- the instance terminated and the encrypted disposable volume disappeared;\n- Apple host scrub completed;\n- the Dedicated Host was released between 24 and 30 hours after allocation;\n- the repository has no registered campaign runner;\n- AWS has no active campaign instance or allocated campaign host;\n- actual incremental spend remained below USD 25.\n\n### Phase 3 lifecycle controller\n\n`packages/core/providers/commands/aws-macos-jit-controller.mjs` is the operator boundary for the paid\ncampaign. It has three explicit mutation modes:\n\n- `launch-campaign` binds the exact repository source, AMI, availability zone,\n tagged Dedicated Host, and reusable instance. It rejects pre-existing Mac\n capacity and requires successful `AllocateHosts` and `RunInstances` DryRuns\n before either real call.\n- `run-job` binds one queued exact-source GitHub job to the existing campaign\n host and instance. It writes the repository JIT configuration through a\n mode-0600 temporary file into a distinct SSM SecureString, sends only the\n credential-free bootstrap through SSM, and removes the parameter plus runner\n registration if command delivery fails.\n- `close-campaign` refuses execution before the provider's 24-hour minimum,\n verifies the encrypted delete-on-termination root volume, removes scoped JIT\n residue, terminates the exact instance, and requires a `ReleaseHosts` DryRun\n before release. If Apple host scrubbing is still in progress, it reports\n `release-pending`; the ten-minute card-scoped reaper remains the bounded\n retry path.\n\nEvery execute mode requires the exact source SHA and campaign id to be repeated\nthrough `--confirm-source-sha` and `--confirm-campaign-id`. `run-job` also\nrequires `--confirm-run-id`. Omitting `--execute` emits a deterministic plan\nwithout changing AWS or GitHub state.\n\n## Provider lifecycle\n\nThe three infrastructure templates live under\n`infra/aws-us-elastic-runner-burst-plane/`. Creating a change set is the review\nboundary. Executing it, completing the GitHub App connection, creating or\nre-arming a webhook, allocating or releasing a Dedicated Host, writing cost\ntelemetry, dispatching paid jobs, operating a kill switch, and deleting a stack\nare all explicit provider mutations.\n\nThe reviewed Phase 1 provider sequence is below. It deliberately separates\nconnection creation, change-set inspection, stack execution, cost observation,\nand webhook arming:\n\n```bash\nburst_profile=us\nburst_region=us-east-1\nburst_stack=kungfu-buildchain-linux-burst-poc\nburst_project=kungfu-buildchain-linux-burst-poc\nburst_connection_name=kungfu-linux-burst-poc\nburst_change_set=phase1-linux-codebuild-poc\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections create-connection \\\n --provider-type GitHub \\\n --connection-name \"$burst_connection_name\" \\\n --tags Key=kungfu:owner,Value=buildchain \\\n Key=kungfu:plane,Value=aws-us-elastic-runner-burst\n```\n\nThe returned connection is `PENDING` until an operator completes the GitHub App\nhandshake in AWS. Read back `ConnectionStatus=AVAILABLE` before creating the\nchange set. Do not put an OAuth token or GitHub token in the shell:\n\nAWS CodeConnections connection names are limited to 32 characters, so keep the\nshorter connection name even when the stack and project use the longer\nBuildchain-specific name.\n\n```bash\nburst_connection_arn=REPLACE_WITH_AVAILABLE_CONNECTION_ARN\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections get-connection \\\n --connection-arn \"$burst_connection_arn\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation create-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\" \\\n --change-set-type CREATE \\\n --template-body \\\n file://infra/aws-us-elastic-runner-burst-plane/codebuild-poc.template.yml \\\n --capabilities CAPABILITY_IAM \\\n --parameters \\\n ParameterKey=GitHubConnectionArn,ParameterValue=\"$burst_connection_arn\" \\\n ParameterKey=ProjectName,ParameterValue=\"$burst_project\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait change-set-create-complete \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation describe-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n```\n\nOnly after the change-set resource list and IAM diff are accepted:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation execute-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait stack-create-complete \\\n --stack-name \"$burst_stack\"\n```\n\nArming requires a fresh, operator-observed CodeBuild cost value. `COST` is the\nonly mutable telemetry item and `CONTROL` is the only state cleared:\n\n```bash\nburst_table=$(\n aws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation describe-stacks \\\n --stack-name \"$burst_stack\" \\\n --query \"Stacks[0].Outputs[?OutputKey=='StateTable'].OutputValue\" \\\n --output text\n)\nburst_observed_at=$(date -u +%s)\nburst_actual_usd=REPLACE_WITH_CURRENT_CODEBUILD_ACTUAL_USD\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n dynamodb put-item \\\n --table-name \"$burst_table\" \\\n --item \"{\\\"pk\\\":{\\\"S\\\":\\\"COST\\\"},\\\"actual_usd\\\":{\\\"N\\\":\\\"$burst_actual_usd\\\"},\\\"observed_at\\\":{\\\"N\\\":\\\"$burst_observed_at\\\"}}\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n dynamodb delete-item \\\n --table-name \"$burst_table\" \\\n --key '{\"pk\":{\"S\":\"CONTROL\"}}'\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codebuild create-webhook \\\n --project-name \"$burst_project\" \\\n --filter-groups \\\n '[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"},{\"type\":\"WORKFLOW_NAME\",\"pattern\":\"^AWS US Linux Burst Qualification$\"}]]'\n```\n\nThe immediate global kill is idempotent and targets only the dedicated project:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codebuild delete-webhook \\\n --project-name \"$burst_project\"\n```\n\nAfter preserving the qualification evidence and proving no build is in\nprogress, rollback removes only the card-owned stack and connection:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation delete-stack \\\n --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait stack-delete-complete \\\n --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections delete-connection \\\n --connection-arn \"$burst_connection_arn\"\n```\n\nPhase cleanup evidence must include:\n\n- CodeBuild batch/list results showing no in-progress build;\n- controller state and accepted-build ledger;\n- CodeBuild actual cost observation and its timestamp;\n- no EC2 instance, volume, launch template, Auto Scaling group, or dedicated\n host created by this phase;\n- the CodeBuild webhook deleted or the whole stack deleted.\n\n## Source boundaries\n\nThe design follows the current AWS CodeBuild GitHub Actions runner contract:\n`WORKFLOW_JOB_QUEUED` starts an ephemeral runner, the run id maps cancellation,\nand the build terminates after one job. It uses the current GitHub guidance to\nprefer ephemeral autoscaled self-hosted runners and to retain runner logs\nexternally. Provider documentation and the live AWS Price List query are the\nauthoritative external sources; this document is an auditable cache."
},
{
"id": "manual:binary-distribution",
"title": "Binary Distribution",
"route": "/docs/binary-distribution",
"category": "manual",
"capabilityGroup": "release-passport-trust",
"audience": [
"release-operator",
"agent"
],
"maturity": "stable",
"sourcePath": "docs/binary-distribution.md",
"digest": "sha256:fe01140ac9ff62da7f9c077df538792a588eb1cb609f997eaf1ce56a7965a982",
"headings": [
{
"level": 1,
"title": "Binary Distribution",
"anchor": "binary-distribution"
},
{
"level": 2,
"title": "Asset Rules",
"anchor": "asset-rules"
},
{
"level": 2,
"title": "KFD-3 Distribution Declaration",
"anchor": "kfd-3-distribution-declaration"
},
{
"level": 2,
"title": "Runner Policy",
"anchor": "runner-policy"
},
{
"level": 2,
"title": "Evidence Bundle",
"anchor": "evidence-bundle"
},
{
"level": 2,
"title": "Local Smoke",
"anchor": "local-smoke"
}
],
"markdown": "# Binary Distribution\n\nBuildchain's binary distribution is the first high-pressure proof case for the\nRelease Passport protocol. It is not the boundary of the product.\n\n## Asset Rules\n\nGitHub Release assets use platform-specific archives:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe release lane does not upload loose top-level `buildchain` or\n`buildchain.exe` assets. Linux and macOS both name the executable `buildchain`\ninside their archives, so top-level loose assets would collide when matrix\nartifacts are merged.\n\n`Binary Distribution` is evidence-only. It never receives `contents: write`\nand never calls `gh release upload`; `upload-release=true` is rejected before\nthe matrix starts. A completed promotion explicitly dispatches the workflow at\nthe exact public tag because tags created by `GITHUB_TOKEN` do not recursively\nstart ordinary `push` workflows.\n\nAfter all three runners qualify, the workflow seals a\n`binary-distribution` controller receipt over the exact source/runtime SHA,\nrelease bundle, and Release Passport. `Binary Release Assets` observes the\nsuccessful evidence run, rechecks that its source SHA still equals the exact\ntag, derives the governed alpha/release branch, and asks the credential-free\npublication authority to assemble a short-lived capability. Only the nested\npublisher owns `contents: write`, and it runs behind the protected\n`buildchain-release-assets` Environment.\n\nGitHub Release metadata remains deterministic and tag-derived. Exact alpha tags such\nas `v2.6.2-alpha.0` are created or updated with `prerelease=true` and\n`make_latest=false`; exact stable tags such as `v2.6.1` are created or updated\nwith `prerelease=false` and `make_latest=true`. The sealed publisher uses\n`packages/core/release/commands/ensure-github-release.mjs` before asset upload instead of relying on\nGitHub's default latest-release heuristic.\n\nEach archive is accompanied by:\n\n- a platform manifest from the standalone binary builder;\n- platform observability event logs and summaries;\n- `checksums.txt`;\n- Release Passport evidence files;\n- `buildchain-release-bundle.tar.gz`;\n- `buildchain-release-bundle.json`.\n\nLinux archives may also be accompanied by a GitHub/Sigstore bundle and\n`buildchain.github-artifact-attestation-evidence/v1`. These prove the exact\nGitHub signer workflow and source digest while preserving the original compiler\nrunner in the platform manifest. The GitHub-hosted signer does not rebuild or\nexecute consumer source. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n## KFD-3 Distribution Declaration\n\nBuildchain self-describes this release lane in `dist/site/kfd-claims.json` as\nthe KFD-3 surface `distribution:buildchain-standalone`. Its declaration assigns\nregistration to Shifu, names `binary:build` as the reproducible task, and lists\nthe artifact kind, platform, and path glob for all three archives. Shifu should\ndiscover the registry through `buildchain layout --json`, not by copying the\nregistry path.\n\nThe repository-owned task is:\n\n```bash\npnpm binary:build\n```\n\nThe release workflow still builds each target on its declared runner. The local\ntask is the stable task identity used by the KFD declaration and local smoke\nchecks; it does not replace the three-platform release matrix.\n\n## Runner Policy\n\nProduction binary builds use GitHub-hosted runners:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners are compatibility fixtures. They can prove that consumers\nwith private runner fleets can still use the protocol, but Buildchain's public\nbinary distribution should stay reproducible on GitHub-hosted runners.\n\n## Evidence Bundle\n\n`buildchain-release-bundle.tar.gz` groups release assets and passport evidence\nunder one archive:\n\n```text\nbuildchain-release-bundle/\n release-assets/\n release-passport/\n buildchain-release-bundle.index.json\n```\n\n`buildchain-release-bundle.json` records the bundle digest and every included\nfile digest. Consumers can download the bundle when they want one artifact for\noffline review, mirroring, or site ingestion.\n\nPublication fails closed unless the bundle contains all three archives,\n`checksums.txt`, and `buildchain.release.json`; its archive digest, controller\nreceipt, live control-plane audit, runner provenance, source/runtime SHA, and\nexact target tag must all match the sealed admission.\n\n## Local Smoke\n\n```bash\npnpm binary:build -- --version v0.0.0-local\nnode bin/buildchain.mjs collect github-release \\\n --tag v0.0.0-local \\\n --assets-dir dist/binary \\\n --output-dir .buildchain/release-passport\nnode packages/core/publication/commands/create-release-bundle.mjs \\\n --assets-dir dist/binary \\\n --passport-dir .buildchain/release-passport \\\n --output-dir .buildchain/release-passport \\\n --tag v0.0.0-local\n```"
},
{
"id": "manual:bootstrap-recovery",
"title": "Consumer recovery",
"route": "/docs/bootstrap-recovery",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/bootstrap-recovery.md",
"digest": "sha256:b33b67e345c1e9b4cb65c4ebd7678827a5ff7c3e0f7743419530468deaa14c28",
"headings": [
{
"level": 1,
"title": "Consumer recovery",
"anchor": "consumer-recovery"
},
{
"level": 2,
"title": "Normal execution",
"anchor": "normal-execution"
},
{
"level": 2,
"title": "Recover an interrupted attempt",
"anchor": "recover-an-interrupted-attempt"
},
{
"level": 2,
"title": "Retired bootstrap distribution",
"anchor": "retired-bootstrap-distribution"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: consumer-attempt-recovery\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-20\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-20\n visible_context: Schema-2 consumer contract, pipeline and recovery entries, and internal release implementations.\n invisible_context_boundary: No unobserved hosted publication or external consumer migration is claimed.\n---\n\n# Consumer recovery\n\nA current consumer keeps the generated `buildchain.yml` and\n`buildchain-recover.yml` beside `.buildchain/buildchain.toml`.\n[Initialize the consumer](getting-started.md) to obtain both caller files from\nthe same Buildchain package. No consumer-owned recovery implementation, copied\nJavaScript closure or additional bootstrap workflow is required.\n\n## Normal execution\n\n`buildchain.yml` invokes `public-ops-pipeline.yml` through the published channel.\nThe runtime owns event routing, source qualification, publication and durable\nattempt records. Product install, build and verification commands belong in TOML.\n\n## Recover an interrupted attempt\n\nOpen the generated **Buildchain recovery** workflow and provide its exact\n`attempt`. If execution requires a repaired runtime, provide the optional\n`runtime-ref` for that recovery. The caller invokes `public-ops-recover.yml`.\nKeep the durable caller on its published floating channel; the repair selector\nis transient and does not replace the attempt's original source or material.\n\nRecovery reads retained records and provider state before issuing remaining\neffects. It preserves published bytes and immutable history. A successful build\nor a green dispatch alone does not prove publication or terminal settlement.\n\nThe recovery form does not accept request JSON, Discussion/run/transaction\nselector combinations, replacement artifacts or provider commands. Retained\nhistorical formats are decoded by runtime-owned readers.\n\n## Retired bootstrap distribution\n\nThe earlier copied bootstrap recovery workflow and `.buildchain/bootstrap-recovery/`\nimplementation are historical distribution artifacts. They are not part of the\nschema-2 consumer contract and must not be added to new consumers. Internal\nbootstrap components and their qualification tests may retain this material for\nimplementation validation; that does not make it a consumer API.\n\nSee [Release discussions](release-discussions.md) for immutable record ownership\nand [Release governance](release-governance.md) for the human release flow."
},
{
"id": "manual:build-facts",
"title": "Build Facts",
"route": "/docs/build-facts",
"category": "manual",
"capabilityGroup": "observability-diagnostics",
"audience": [
"maintainer",
"agent"
],
"maturity": "stable",
"sourcePath": "docs/build-facts.md",
"digest": "sha256:75dcf7a6628dac9e982a455de9966044ae771611d4efc04e7264a2d4adb0bd3e",
"headings": [
{
"level": 1,
"title": "Build Facts",
"anchor": "build-facts"
},
{
"level": 2,
"title": "Config",
"anchor": "config"
},
{
"level": 2,
"title": "CLI",
"anchor": "cli"
},
{
"level": 2,
"title": "Node API",
"anchor": "node-api"
},
{
"level": 2,
"title": "Release Passport Integration",
"anchor": "release-passport-integration"
},
{
"level": 2,
"title": "Kungfu Legacy Projection",
"anchor": "kungfu-legacy-projection"
}
],
"markdown": "# Build Facts\n\nBuild Facts are Buildchain's machine-readable record of what a repository\nbuilt. They sit between lifecycle logs and release passports:\n\n- lifecycle logs explain what ran and how long it took;\n- module build facts bind one module to its Git source digest, version source,\n platform, lifecycle invocation, and output digests;\n- product build facts aggregate module facts and product artifacts;\n- release passports can carry build facts as first-class evidence.\n\nThe goal is to remove handwritten build metadata from consumer repositories.\nConsumers declare where their version and outputs live; Buildchain collects and\nverifies the facts.\n\n## Config\n\nDeclare build facts in `buildchain.toml`:\n\n```toml\nschema = 1\n\n[[facts.version_sources]]\nid = \"package\"\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[[facts.modules]]\nid = \"native-core\"\nroot = \"src/core\"\nscope = \"core\"\nversion_source = \"package\"\nlifecycle = \"build\"\noutputs = [\"dist/core.node\"]\n\n[[facts.products]]\nid = \"kungfu\"\nmodule_facts = [\".buildchain/facts/native-core.json\"]\nartifacts = [\"dist/kungfu.zip\"]\n\n[[facts.legacy_projections]]\ntype = \"kungfu-buildinfo\"\nmodule = \"native-core\"\npath = \"framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\"\n```\n\nSupported version sources:\n\n- `static`: an explicit `value`;\n- `json`: a JSON file plus dotted `key`;\n- `toml`: a TOML file plus dotted `key`;\n- `regex`: a text file plus regex `pattern`, using a named `version` group or\n the first capture group;\n- `command`: an explicit command whose output is the version.\n\nPrefer file-based sources. Command sources are allowed for legacy projects but\nare marked as less reproducible because the command output is not a static\nsource file.\n\n## CLI\n\nCollect a module fact:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json\n```\n\nOverride declarative config from a workflow step when needed:\n\n```bash\nbuildchain facts module \\\n --cwd \"$GITHUB_WORKSPACE\" \\\n --module native-core \\\n --module-root src/core \\\n --version-source package \\\n --output-path dist/core.node \\\n --output .buildchain/facts/native-core.json \\\n --json\n```\n\nWrite the Kungfu legacy `kungfubuildinfo.json` projection from the same module\nfact:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json \\\n --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n```\n\nAggregate product facts:\n\n```bash\nbuildchain facts aggregate \\\n --product kungfu \\\n --module-fact .buildchain/facts/native-core.json \\\n --artifact dist/kungfu.zip \\\n --output .buildchain/facts/kungfu.json\n```\n\nVerify a fact before publishing:\n\n```bash\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nVerification fails closed when a declared output is missing, an output digest is\nstale, a module fact was collected from a different Git `HEAD`, or a source\ndigest no longer matches the tracked source files.\n\n## Node API\n\n```js\nimport {\n aggregateBuildFacts,\n collectModuleBuildFacts,\n verifyBuildFacts,\n writeBuildFacts,\n writeKungfuBuildInfoProjection,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst moduleFact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact: moduleFact, output: \".buildchain/facts/native-core.json\" });\n\nconst productFact = aggregateBuildFacts({ productId: \"kungfu\" });\nconst verification = verifyBuildFacts({ fact: productFact });\n```\n\nThe root package export also re-exports these APIs from\n`@kungfu-tech/buildchain`.\n\n## Release Passport Integration\n\nPass build facts into a release passport:\n\n```bash\nbuildchain collect github-release \\\n --tag \"$TAG\" \\\n --assets-dir dist \\\n --build-facts-json .buildchain/facts/native-core.json \\\n --build-facts-json .buildchain/facts/kungfu.json \\\n --output-dir .buildchain/release-passport\n```\n\nThe passport records the full build facts in `buildFacts[]` and a compact\nevidence index in `evidence.buildFacts[]`. Agents can start from\n`buildchain.release.json`, discover the module/product facts, and verify that\nthe released artifacts still match the declared source, version, and output\nfacts.\n\n## Kungfu Legacy Projection\n\nKungfu historically consumes `kungfubuildinfo.json`. Buildchain now treats that\nfile as a projection of module build facts, not as an independent source of\ntruth. The projection preserves legacy fields such as `version`,\n`python_version`, `git_branch`, `git_revision`, and `git_pristine`, while adding\na `buildchain` section that points back to the module fact digest, version\nsource digest, and source digest.\n\nRepositories that no longer need the legacy file should consume the module and\nproduct facts directly."
},
{
"id": "manual:cli",
"title": "Buildchain CLI, npm Package, and Toolkit API",
"route": "/docs/cli",
"category": "manual",
"capabilityGroup": "api-cli-reference",
"audience": [
"agent",
"developer"
],
"maturity": "stable",
"sourcePath": "docs/cli.md",
"digest": "sha256:02c3993f39db07f7c42898901c651d4a75afecec38164baed9cdef6e3eb3bb27",
"headings": [
{
"level": 1,
"title": "Buildchain CLI, npm Package, and Toolkit API",
"anchor": "buildchain-cli-npm-package-and-toolkit-api"
},
{
"level": 2,
"title": "Install and Run",
"anchor": "install-and-run"
},
{
"level": 2,
"title": "Node API and Package Exports",
"anchor": "node-api-and-package-exports"
},
{
"level": 2,
"title": "Commands",
"anchor": "commands"
},
{
"level": 3,
"title": "Paper product source",
"anchor": "paper-product-source"
},
{
"level": 2,
"title": "V4 Adopter Delivery",
"anchor": "v4-adopter-delivery"
},
{
"level": 2,
"title": "npm Publish Gate",
"anchor": "npm-publish-gate"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-cli\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-20\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-20\n visible_context: Schema-2 consumer initialization, CLI validation, and internal pipeline npm publication implementation.\n invisible_context_boundary: Local validation does not prove provider authorization or hosted publication.\n---\n\n# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@4.1.3`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude. For an existing `pnpm-workspace.yaml`, Paper\nmigration maintains an exclusion for the selected exact Buildchain version.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { verifyGitHubArtifactAttestationEvidence } from \"@kungfu-tech/buildchain/github-artifact-attestation\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\nimport { collectPaperStatus } from \"@kungfu-tech/buildchain/paper\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport { createBuildchainLayoutDiscovery } from \"@kungfu-tech/buildchain/buildchain-layout\";\nimport { createPortableDevCachePlan } from \"@kungfu-tech/buildchain/portable-dev-cache\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v4`.\n\nFor exhaustive lookup, use the generated references rather than scanning this\nconceptual guide:\n\n- [`cli-reference.md`](cli-reference.md) is projected from the governed usage\n model and runtime command registry. `buildchain --help` is intercepted\n before dispatch at every listed path, exits zero, and has no command side\n effects.\n- [`node-api-reference.md`](node-api-reference.md) is projected from\n `package.json#exports` and exact ESM export declarations. The packaged\n `dist/site/node-api-registry.json` carries the same per-symbol signatures,\n parameters, conservative return/error boundaries, side-effect classification,\n maturity, example import, and source location.\n\n## Commands\n\n`buildchain create github-artifact-attestation-policy` seals the expected\nartifact, caller source, original Linux build, immutable Buildchain signer, and\nGitHub permission set before the Release Passport is collected.\n`buildchain verify github-artifact-attestation` invokes `gh attestation verify`\nwith the exact signer/source policy and then verifies the retained bundle,\npredicate, platform manifest, Passport, and Buildchain evidence locally. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n### Paper product source\n\nPaper uses the same schema-2 policy and two caller files as npm and binary\nproducts. For an existing source tree, use `buildchain init --type paper`.\nTo create a new LaTeX source tree:\n\n```bash\nbuildchain paper scaffold --name paper-example --title \"Example Paper\" \\\n --repository example/paper-example --json\nbuildchain paper scaffold --name paper-example --title \"Example Paper\" \\\n --repository example/paper-example --write --json\nmake pdf\nmake check\nbuildchain validate --require-lifecycle-stages build,verify\nbuildchain paper preflight --json\nbuildchain paper status --json\n```\n\nScaffold plans all files before writing. `--write` creates missing files only;\nconflicting content, extra workflows and symlinked write parents stop the whole\nwrite. Repeating an unchanged scaffold is idempotent. `--package` optionally\nnames the private source package; its version is the product version authority.\nTitle and homepage stay in that product manifest.\n\nThe generated TOML declares the PDF and a GitHub Release target. The generated\n`buildchain.yml` and `buildchain-recover.yml` are byte-identical to the other\nproduct templates. Open the appropriate protected channel PR to request\npublication. Recovery uses the common exact-attempt entry.\n\nFor schema-2 Paper repositories, preflight and status inspect local configuration\nand caller bytes. Their `localOnly` result and `publication.status=not-observed`\ndo not claim a successful hosted build, admission or release. They perform no\nnpm login, bootstrap, trust setup or GitHub account operation. Provider permissions\nand any tool-maintained runtime locks belong to the common setup/runtime contract.\n\nThe previous schema-1 npm-paper contract, three-workflow scaffold and repository\nprovisioning authority are retired from new scaffolds. Existing paper repositories\nneed a reviewed migration; historical publication receipts remain historical\nfacts and do not become new runtime configuration.\n\n`buildchain layout` is the stable machine question for repository layout. Tools\nsuch as Shifu should call it instead of copying `.buildchain/` path constants:\n\n```bash\nbuildchain layout --cwd /path/to/repository --json\n```\n\nThe result identifies the Buildchain version pin, repository root and config,\nthe canonical and currently resolved KFD-3 registry paths, and the KFD field\nused to declare Shifu jurisdiction. A repository is in Shifu's distribution\njurisdiction only when a KFD-3 surface explicitly declares\n`distribution.registrar=\"shifu\"`; the presence of Buildchain configuration is\nnot sufficient. The same contract is available through\n`createBuildchainLayoutDiscovery()` from\n`@kungfu-tech/buildchain/buildchain-layout`.\n\n`buildchain init` writes a schema-2 `.buildchain/buildchain.toml` and the shared\n`.github/workflows/buildchain.yml` / `buildchain-recover.yml` caller pair.\nProduct build and verification belong in TOML. Publication and recovery stay in\nthe published runtime; consumers do not call the internal commands below as\nrelease lifecycle hooks. See the [Golden Path](getting-started.md).\n\n`buildchain portable-cache plan` turns a consumer-owned, secret-free manifest\ninto GitHub Actions cache inputs without letting each consumer invent key or\nrestore-prefix semantics. The exact key binds source SHA and the consumer plan\ndigest; the compatible restore prefix still requires the same provider schema,\nlayer, roots, runner image, platform/architecture, toolchain, dependency lock,\nand build profile.\n\n```bash\nbuildchain portable-cache plan \\\n --manifest .buildchain/portable-cache.json \\\n --output .buildchain/portable-cache-plan.json \\\n --github-output \"$GITHUB_OUTPUT\"\n```\n\nThe emitted `cache-key`, `restore-keys`, and `cache-paths` values are intended\nfor pinned `actions/cache/restore` and `actions/cache/save` actions. After\nrestore and a consumer validation probe, seal the provider result:\n\n```bash\nbuildchain portable-cache receipt \\\n --plan .buildchain/portable-cache-plan.json \\\n --matched-key \"$CACHE_MATCHED_KEY\" \\\n --cache-hit \"$CACHE_HIT\" \\\n --validation-status pass \\\n --cold-fallback-status passed \\\n --output .buildchain/portable-cache-receipt.json\n```\n\nThe receipt distinguishes `exact`, `compatible`, `miss`, and `corrupt`.\nUnknown or contradictory provider evidence fails closed. A miss or corruption\nrequires the consumer's audited cold path; a cache never substitutes for the\nconsumer's current build or tests. Roots must be workspace-relative or under\n`~/`, and manifests cannot carry credentials, absolute host paths, or escape\nsegments. `cold-fallback-status=passed` qualifies a miss only after the current\nsource has completed its normal build and test path.\n\nSupported initialization types:\n\n- `npm` or `package`: an npm product with an existing versioned `package.json`.\n- `binary` or `native`: a CMake product producing an archive.\n- `paper` or `publication-artifact`: a product producing a PDF.\n- `anchored-package`: an npm product with reviewed, manually maintained version authority.\n\nThese choices change TOML product declarations, never the two YAML templates.\nThe old `web-surface`, `infra-contract` and distribution initialization modes\nare outside the current schema-2 product set and are rejected before writing.\nInternal libraries for those capabilities are separate from consumer initialization.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured\nversion files and the exact shared caller bytes, and can require named commands\non every declared product:\n\n```bash\nbuildchain validate \\\n --require-version-state \\\n --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run ` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n --artifact-path dist \\\n --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain dev merge-queue` plans a GitHub merge-queue policy for a protected\nBuildchain dev channel. Declare every workflow that emits a required check; the\ncommand fails closed unless each file handles both `pull_request` and\n`merge_group` without reading `github.event.pull_request` directly:\n\n```bash\nbuildchain dev merge-queue \\\n --repository kungfu-systems/example \\\n --branch dev/v4/v4.0 \\\n --workflow .github/workflows/source-acceptance.yml \\\n --workflow .github/workflows/affected-native-pr.yml\n```\n\nThe default output is a read-only plan. Add `--apply` only after reviewing it.\nApply creates the exact-branch merge-queue ruleset before changing classic\nrequired status checks from strict to loose, preserves the required check\nidentities, and is safe to repeat. `gh` must be authenticated with repository\nAdministration write permission for apply mode.\n\nRepositories can make that policy declarative in `buildchain.toml`:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"enabled\" # enabled, inherit, or disabled\nrequired_workflows = [\".github/workflows/verify.yml\"]\ncheck_response_timeout_minutes = 120\nmax_entries_to_build = 1\nbypass_users = [\"release-owner\"]\n```\n\nUse `buildchain dev merge-queue --from-config` to resolve and reconcile the\ndeclaration. `enabled` requires an exact queue on the target dev branch;\n`disabled` suppresses automatic queue creation; `inherit` copies the active\ndefault dev branch's queue parameters and bypass actors. When the table is\nabsent, release-line bootstrap uses the backward-compatible `inherit` mode.\nEvery inherited or explicitly enabled queue still validates each declared\nrequired workflow before any mutation. For a legacy repository with no table,\nan already-active exact queue on the current default dev branch is accepted as\nthe inheritance evidence; new declarations should list the workflows so future\nchanges are revalidated from source.\nThe `Dev Merge Queue Governance` workflow runs this reconciliation after\ngovernance-relevant changes land on a dev branch; its manual dispatch remains\ndry-run by default.\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n --major 4 \\\n --minor 1 \\\n --source-ref release/v4/v4.0 \\\n --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, reconciles declared or\ninherited merge-queue governance, switches the default branch only after that\nreconciliation succeeds, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n --major 4 \\\n --minor 1 \\\n --source-ref release/v4/v4.0 \\\n --write \\\n --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n collectPublicSurfaceReverseAudit,\n assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(\n collectPublicSurfaceReverseAudit({ root: process.cwd() }),\n);\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4, KFD-5, and KFD-7 expose fail-closed\nproduct-evidence gate and verification protocols; passing those protocols does\nnot itself qualify, certify, activate, or ship support.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd 4 gate --input-json kfd-4-gate-input.json --output kfd-4-gate.json\nbuildchain kfd 5 gate --input-json kfd-5-gate-input.json --output kfd-5-gate.json\nbuildchain kfd 7 gate --input-json kfd-7-gate-input.json --output kfd-7-gate.json\nbuildchain kfd support project --manifest-json adopter-manifest.json \\\n --manifest-gate-json adopter-manifest-gate.json --output kfd-support.json\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence. Product repositories use the `product-claims` subcommand to\nvalidate and render their own declared KFD-2 release claims under the canonical\nBuildchain KFD layout:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 product-claims check --json\nbuildchain kfd 2 product-claims write --json\nbuildchain kfd 2 product-claims render --json\n```\n\nThe default source is `.buildchain/kfd/kfd-2/registry.json`; outputs are\n`.buildchain/kfd/kfd-2/release-claims.json`, per-claim release-passport inputs\nunder `claims/`, and `buildchain-claim-args.txt`. Use `--registry` or\n`--output-dir` only for an explicit product packaging projection. `check` never\nwrites and exits non-zero when outputs drift.\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe JSON summary also includes an additive `controlPlane` block. It counts\nworkflow-friction incident outcomes and production release-intent outcomes,\nincluding incident reuse rate, release-intent suppression rate, and suppression\nreasons. Buildchain writes those outcome events locally; it does not send\ntelemetry outside the runner.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n source: \"user\",\n component: \"native-build\",\n});\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n .buildchain/artifacts/linux-x64/diagnostics.json \\\n .buildchain/artifacts/macos-arm64/diagnostics.json \\\n --output .buildchain/artifacts/diagnostics-summary.json \\\n --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json \\\n --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n --product kungfu \\\n --module-fact .buildchain/facts/native-core.json \\\n --artifact dist/kungfu.zip \\\n --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n --label native-build \\\n --interval-ms 15000 \\\n --output .buildchain/diagnostics/process-samples.jsonl \\\n --summary-output .buildchain/diagnostics/process-summary.json \\\n -- \\\n make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nFor schema-2 consumers it validates TOML, Git repository state, the exact normal\nand recovery caller pair, and package-manager discovery when an npm product is\npresent. A mixed channel pair or a consumer-edited YAML fails validation.\nBinary and Paper products do not need an npm package manager merely to use\nBuildchain. The report grants no publication authority.\n\nThe remaining source-lock and schema-1 checks below describe internal runtime\nand historical product tooling. They are not extra steps in the current\nconsumer release path.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --json\n```\n\nRun the fail-closed clean-room gate before Alpha or release admission:\n\n```bash\nbuildchain publication-artifact reproducibility \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --promote \\\n --json\n```\n\nThe command checks two independent clones of the exact commit, isolates caches,\nderives `SOURCE_DATE_EPOCH` from Git, and compares every declared artifact,\nsource bundle, publication evidence file, npm package file, and actual npm\ntarball. It writes\n`.buildchain/publication/reproducibility-receipt.json`. Only a byte-identical\nbuild using the digest-pinned `latex-docker` toolchain is qualifying.\n`--allow-unpinned-toolchain` exists for local diagnostics and never changes the\nreceipt's `qualifying` field.\n\nGenerate the Buildchain-owned npm paper package contents from declared\npublication facts:\n\n```bash\nbuildchain publication-artifact npm-package --json\n```\n\nThis command reads `project.type = \"publication-artifact\"`,\n`publication.version`, and `[publish] kind = \"npm-paper-package\"` plus\n`publish.package`; it writes `.buildchain/publication/npm-package` by default.\nThese are retained schema-1 package-generation fields. Current schema-2 Paper\nconsumers declare PDF artifacts and a GitHub Release target in TOML; they do\nnot add an npm publication workflow. Use the Paper migration command before\nusing a legacy repository with the shared caller pair.\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n --package buildchain \\\n --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json \\\n --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n --tag v3.0.0 \\\n --repository kungfu-systems/buildchain \\\n --assets-dir dist \\\n --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n --tag v3.0.0 \\\n --repository kungfu-systems/buildchain \\\n --assets-dir dist \\\n --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n --package-set-json package-set.json \\\n --impact-json impact.json \\\n --trusted-publishing-json trusted-publishing.json \\\n --anchor-manifest-json libnode.release.json \\\n --build-summary-json .buildchain/artifacts/build-summary.json \\\n --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v3/v3.0\"}' \\\n --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\n\n`--invariant-passport-json` attaches a product-owned invariant Passport to the\nrelease gate and may be repeated. `--invariant-passport-cmd` runs a product\ncommand that emits one Passport JSON document. Buildchain verifies the\nPassport root, exact clean source identity, `verified` verdict, complete\nplatform coverage, and residual-risk shape; it does not redefine the product's\ninvariant semantics. Declared invariant Passport input is fail-closed.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nFor a promote-only stable transaction, Buildchain can derive a patch-level\nrelease-governance ledger when the PR-stage release-candidate passport proves\nthe stable source tree is exactly the previously qualified candidate tree.\nThis fallback is unavailable when candidate evidence is absent, stale, or not\ntree-equivalent.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n --repository kungfu-systems/libnode \\\n --tag v22.22.3-kf.3-alpha.18 \\\n --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:@` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry `\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport `.\n2. Sidecar pointer, such as `.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n Release asset URLs, or `--repository --tag `.\n6. Custom `--locator-config `.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n \"locators\": [\n {\n \"match\": {\n \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n \"digest\": \"sha256:...\"\n },\n \"passport\": \"../release-passport/buildchain.release.json\"\n }\n ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:@`, `oci:...`, `s3:...`,\n`github-release:@/`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nSeal an exact artifact verification with the Node API, then verify or project\nthe resulting KFX admission envelope without reconstructing its roots:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n --assessment-time 150 \\\n --expected-root sha256:... \\\n --expected-issuer buildchain.libkungfu.dev \\\n --expected-publisher kungfu-systems \\\n --expected-contract buildchain.release/v1 \\\n --json\n\nbuildchain project kfx-admission envelope.json \\\n --assessment-time 150 \\\n --json\n```\n\nBoth commands call the public artifact-verification-envelope verifier. The\nprojected `attestation`, `trustInputs`, and `kfdAssessment` are direct copies of\nthe sealed envelope, and `envelopeRoot` stays identical across Node and CLI.\nSee [`artifact-verification-envelope.md`](artifact-verification-envelope.md).\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v4/v4.0\nbuildchain release --dry-run --target-ref release/v4/v4.0 --sha \nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v4/v4.0\nbuildchain release explain --target-ref alpha/v4/v4.0 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v4.0.1-alpha.2\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/release/promotion/ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag ` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## V4 Adopter Delivery\n\n`buildchain adopter-delivery` exposes the public v4 driver gate, exact\nreadback, N-1 bootstrap lineage, and published archive loader. `run` emits a\nrooted non-authoritative readback, `verify` recomputes it, `bootstrap` binds the\nexact v3 authority and v4 base, and `archive` verifies public npm archive bytes\nand package identity. See [`v4-adopter-delivery.md`](v4-adopter-delivery.md).\n\n## npm Publish Gate\n\nBuildchain consumes its own generated `buildchain.yml` entry, which invokes\n`public-ops-pipeline.yml@v4`. Its schema-2 TOML declares the npm package product,\nbuild/verification commands and npm target. A legal channel PR expresses the\nrelease intent; the runtime manages qualification, version materialization,\npublication, provider readback and follow-up development work.\n\nThe internal\n[`.release-pipeline-products.yml`](../.github/workflows/.release-pipeline-products.yml)\nworkflow owns the separate product build, qualification, publication and\nsettlement jobs. Its publication job runs on a GitHub-hosted runner with\n`id-token: write`. For the configured npm Trusted Publisher, the publish client\nuses GitHub Actions OIDC. Routine releases require no interactive npm login,\nbootstrap publication or manually supplied npm token.\n\nThe runtime publishes the admitted sealed package version and retains exact\nregistry integrity and GitHub Release evidence. Prereleases use the `alpha`\ndist-tag; stable releases use `latest`. An ordinary source build or floating\nref update alone is not publication authority.\n\nConsumers do not call the npm transaction CLI, select candidate run IDs, pass\nrequest JSON, or add a separate npm release workflow. If an existing attempt\nneeds recovery, use `buildchain-recover.yml` with its exact attempt and an\noptional repaired runtime. If a failed alpha is abandoned, keep its historical\nstate intact and publish a new admitted candidate/version."
},
{
"id": "manual:cli-reference",
"title": "Buildchain CLI Reference",
"route": "/docs/cli-reference",
"category": "manual",
"capabilityGroup": "api-cli-reference",
"audience": [
"agent",
"developer",
"operator"
],
"maturity": "stable",
"sourcePath": "docs/cli-reference.md",
"digest": "sha256:e5aef9d294c4773292f4c8710ebb5a223ecc0bb878c4ac016c4f64cb38c586ed",
"headings": [
{
"level": 1,
"title": "Buildchain CLI Reference",
"anchor": "buildchain-cli-reference"
},
{
"level": 2,
"title": "`adopter-delivery`",
"anchor": "adopter-delivery"
},
{
"level": 3,
"title": "`buildchain adopter-delivery`",
"anchor": "buildchain-adopter-delivery"
},
{
"level": 3,
"title": "`buildchain adopter-delivery run`",
"anchor": "buildchain-adopter-delivery-run"
},
{
"level": 3,
"title": "`buildchain adopter-delivery verify`",
"anchor": "buildchain-adopter-delivery-verify"
},
{
"level": 2,
"title": "`architecture`",
"anchor": "architecture"
},
{
"level": 3,
"title": "`buildchain architecture`",
"anchor": "buildchain-architecture"
},
{
"level": 3,
"title": "`buildchain architecture list`",
"anchor": "buildchain-architecture-list"
},
{
"level": 3,
"title": "`buildchain architecture qualify`",
"anchor": "buildchain-architecture-qualify"
},
{
"level": 3,
"title": "`buildchain architecture show`",
"anchor": "buildchain-architecture-show"
},
{
"level": 3,
"title": "`buildchain architecture validate`",
"anchor": "buildchain-architecture-validate"
},
{
"level": 2,
"title": "`audit`",
"anchor": "audit"
},
{
"level": 3,
"title": "`buildchain audit`",
"anchor": "buildchain-audit"
},
{
"level": 3,
"title": "`buildchain audit github-governance`",
"anchor": "buildchain-audit-github-governance"
},
{
"level": 3,
"title": "`buildchain audit publication-control-plane`",
"anchor": "buildchain-audit-publication-control-plane"
},
{
"level": 2,
"title": "`badges`",
"anchor": "badges"
},
{
"level": 3,
"title": "`buildchain badges`",
"anchor": "buildchain-badges"
},
{
"level": 3,
"title": "`buildchain badges bundle`",
"anchor": "buildchain-badges-bundle"
},
{
"level": 3,
"title": "`buildchain badges readme`",
"anchor": "buildchain-badges-readme"
},
{
"level": 2,
"title": "`build-contract`",
"anchor": "build-contract"
},
{
"level": 3,
"title": "`buildchain build-contract`",
"anchor": "buildchain-build-contract"
},
{
"level": 2,
"title": "`candidate`",
"anchor": "candidate"
},
{
"level": 3,
"title": "`buildchain candidate`",
"anchor": "buildchain-candidate"
},
{
"level": 3,
"title": "`buildchain candidate timeline`",
"anchor": "buildchain-candidate-timeline"
},
{
"level": 2,
"title": "`collect`",
"anchor": "collect"
},
{
"level": 3,
"title": "`buildchain collect`",
"anchor": "buildchain-collect"
},
{
"level": 3,
"title": "`buildchain collect github-release`",
"anchor": "buildchain-collect-github-release"
},
{
"level": 2,
"title": "`create`",
"anchor": "create"
},
{
"level": 3,
"title": "`buildchain create`",
"anchor": "buildchain-create"
},
{
"level": 3,
"title": "`buildchain create github-artifact-attestation-policy`",
"anchor": "buildchain-create-github-artifact-attestation-policy"
},
{
"level": 3,
"title": "`buildchain create publication-admission`",
"anchor": "buildchain-create-publication-admission"
},
{
"level": 3,
"title": "`buildchain create runner-provenance`",
"anchor": "buildchain-create-runner-provenance"
},
{
"level": 2,
"title": "`dev`",
"anchor": "dev"
},
{
"level": 3,
"title": "`buildchain dev`",
"anchor": "buildchain-dev"
},
{
"level": 3,
"title": "`buildchain dev authority admit-merge-group`",
"anchor": "buildchain-dev-authority-admit-merge-group"
},
{
"level": 3,
"title": "`buildchain dev authority complete-qualification`",
"anchor": "buildchain-dev-authority-complete-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority heartbeat-landing`",
"anchor": "buildchain-dev-authority-heartbeat-landing"
},
{
"level": 3,
"title": "`buildchain dev authority heartbeat-qualification`",
"anchor": "buildchain-dev-authority-heartbeat-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority lease-landing`",
"anchor": "buildchain-dev-authority-lease-landing"
},
{
"level": 3,
"title": "`buildchain dev authority lease-qualification`",
"anchor": "buildchain-dev-authority-lease-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority migrate`",
"anchor": "buildchain-dev-authority-migrate"
},
{
"level": 3,
"title": "`buildchain dev authority observe`",
"anchor": "buildchain-dev-authority-observe"
},
{
"level": 3,
"title": "`buildchain dev authority recover`",
"anchor": "buildchain-dev-authority-recover"
},
{
"level": 3,
"title": "`buildchain dev authority settle`",
"anchor": "buildchain-dev-authority-settle"
},
{
"level": 3,
"title": "`buildchain dev authority submit`",
"anchor": "buildchain-dev-authority-submit"
},
{
"level": 3,
"title": "`buildchain dev merge-queue`",
"anchor": "buildchain-dev-merge-queue"
},
{
"level": 3,
"title": "`buildchain dev pr-admit`",
"anchor": "buildchain-dev-pr-admit"
},
{
"level": 3,
"title": "`buildchain dev proof classify`",
"anchor": "buildchain-dev-proof-classify"
},
{
"level": 3,
"title": "`buildchain dev proof classify-native`",
"anchor": "buildchain-dev-proof-classify-native"
},
{
"level": 3,
"title": "`buildchain dev proof integration`",
"anchor": "buildchain-dev-proof-integration"
},
{
"level": 3,
"title": "`buildchain dev proof native`",
"anchor": "buildchain-dev-proof-native"
},
{
"level": 3,
"title": "`buildchain dev proof replay`",
"anchor": "buildchain-dev-proof-replay"
},
{
"level": 3,
"title": "`buildchain dev proof source`",
"anchor": "buildchain-dev-proof-source"
},
{
"level": 3,
"title": "`buildchain dev proof verify-integration`",
"anchor": "buildchain-dev-proof-verify-integration"
},
{
"level": 3,
"title": "`buildchain dev proof verify-native`",
"anchor": "buildchain-dev-proof-verify-native"
},
{
"level": 3,
"title": "`buildchain dev proof verify-native-reuse`",
"anchor": "buildchain-dev-proof-verify-native-reuse"
},
{
"level": 3,
"title": "`buildchain dev proof verify-source`",
"anchor": "buildchain-dev-proof-verify-source"
},
{
"level": 3,
"title": "`buildchain dev two-phase`",
"anchor": "buildchain-dev-two-phase"
},
{
"level": 3,
"title": "`buildchain dev warrant cancel-queued`",
"anchor": "buildchain-dev-warrant-cancel-queued"
},
{
"level": 3,
"title": "`buildchain dev warrant close`",
"anchor": "buildchain-dev-warrant-close"
},
{
"level": 3,
"title": "`buildchain dev warrant heartbeat`",
"anchor": "buildchain-dev-warrant-heartbeat"
},
{
"level": 3,
"title": "`buildchain dev warrant observe`",
"anchor": "buildchain-dev-warrant-observe"
},
{
"level": 3,
"title": "`buildchain dev warrant qualify`",
"anchor": "buildchain-dev-warrant-qualify"
},
{
"level": 3,
"title": "`buildchain dev warrant recover`",
"anchor": "buildchain-dev-warrant-recover"
},
{
"level": 3,
"title": "`buildchain dev warrant select`",
"anchor": "buildchain-dev-warrant-select"
},
{
"level": 3,
"title": "`buildchain dev warrant settle`",
"anchor": "buildchain-dev-warrant-settle"
},
{
"level": 3,
"title": "`buildchain dev warrant submit`",
"anchor": "buildchain-dev-warrant-submit"
},
{
"level": 2,
"title": "`diagnostics`",
"anchor": "diagnostics"
},
{
"level": 3,
"title": "`buildchain diagnostics`",
"anchor": "buildchain-diagnostics"
},
{
"level": 3,
"title": "`buildchain diagnostics summary`",
"anchor": "buildchain-diagnostics-summary"
},
{
"level": 2,
"title": "`doctor`",
"anchor": "doctor"
},
{
"level": 3,
"title": "`buildchain doctor`",
"anchor": "buildchain-doctor"
},
{
"level": 2,
"title": "`explain`",
"anchor": "explain"
},
{
"level": 3,
"title": "`buildchain explain`",
"anchor": "buildchain-explain"
},
{
"level": 3,
"title": "`buildchain explain artifact`",
"anchor": "buildchain-explain-artifact"
},
{
"level": 3,
"title": "`buildchain explain release`",
"anchor": "buildchain-explain-release"
},
{
"level": 2,
"title": "`facts`",
"anchor": "facts"
},
{
"level": 3,
"title": "`buildchain facts`",
"anchor": "buildchain-facts"
},
{
"level": 3,
"title": "`buildchain facts aggregate`",
"anchor": "buildchain-facts-aggregate"
},
{
"level": 3,
"title": "`buildchain facts compatibility project`",
"anchor": "buildchain-facts-compatibility-project"
},
{
"level": 3,
"title": "`buildchain facts compatibility query`",
"anchor": "buildchain-facts-compatibility-query"
},
{
"level": 3,
"title": "`buildchain facts compatibility query-template`",
"anchor": "buildchain-facts-compatibility-query-template"
},
{
"level": 3,
"title": "`buildchain facts compatibility verify`",
"anchor": "buildchain-facts-compatibility-verify"
},
{
"level": 3,
"title": "`buildchain facts module`",
"anchor": "buildchain-facts-module"
},
{
"level": 3,
"title": "`buildchain facts verify`",
"anchor": "buildchain-facts-verify"
},
{
"level": 2,
"title": "`github-governance`",
"anchor": "github-governance"
},
{
"level": 3,
"title": "`buildchain github-governance`",
"anchor": "buildchain-github-governance"
},
{
"level": 3,
"title": "`buildchain github-governance apply`",
"anchor": "buildchain-github-governance-apply"
},
{
"level": 3,
"title": "`buildchain github-governance plan`",
"anchor": "buildchain-github-governance-plan"
},
{
"level": 3,
"title": "`buildchain github-governance protection-policy-plan`",
"anchor": "buildchain-github-governance-protection-policy-plan"
},
{
"level": 3,
"title": "`buildchain github-governance rollback`",
"anchor": "buildchain-github-governance-rollback"
},
{
"level": 3,
"title": "`buildchain github-governance ruleset-policy-plan`",
"anchor": "buildchain-github-governance-ruleset-policy-plan"
},
{
"level": 2,
"title": "`help`",
"anchor": "help"
},
{
"level": 3,
"title": "`buildchain help`",
"anchor": "buildchain-help"
},
{
"level": 2,
"title": "`homebrew`",
"anchor": "homebrew"
},
{
"level": 3,
"title": "`buildchain homebrew`",
"anchor": "buildchain-homebrew"
},
{
"level": 3,
"title": "`buildchain homebrew check`",
"anchor": "buildchain-homebrew-check"
},
{
"level": 3,
"title": "`buildchain homebrew update-formula`",
"anchor": "buildchain-homebrew-update-formula"
},
{
"level": 2,
"title": "`infra-contract`",
"anchor": "infra-contract"
},
{
"level": 3,
"title": "`buildchain infra-contract`",
"anchor": "buildchain-infra-contract"
},
{
"level": 2,
"title": "`init`",
"anchor": "init"
},
{
"level": 3,
"title": "`buildchain init`",
"anchor": "buildchain-init"
},
{
"level": 2,
"title": "`inspect`",
"anchor": "inspect"
},
{
"level": 3,
"title": "`buildchain inspect`",
"anchor": "buildchain-inspect"
},
{
"level": 3,
"title": "`buildchain inspect artifact`",
"anchor": "buildchain-inspect-artifact"
},
{
"level": 3,
"title": "`buildchain inspect release`",
"anchor": "buildchain-inspect-release"
},
{
"level": 2,
"title": "`kfd`",
"anchor": "kfd"
},
{
"level": 3,
"title": "`buildchain kfd`",
"anchor": "buildchain-kfd"
},
{
"level": 3,
"title": "`buildchain kfd 1 gate`",
"anchor": "buildchain-kfd-1-gate"
},
{
"level": 3,
"title": "`buildchain kfd 1 schema`",
"anchor": "buildchain-kfd-1-schema"
},
{
"level": 3,
"title": "`buildchain kfd 1 verify`",
"anchor": "buildchain-kfd-1-verify"
},
{
"level": 3,
"title": "`buildchain kfd 1 witness`",
"anchor": "buildchain-kfd-1-witness"
},
{
"level": 3,
"title": "`buildchain kfd 2 claims`",
"anchor": "buildchain-kfd-2-claims"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims check`",
"anchor": "buildchain-kfd-2-product-claims-check"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims render`",
"anchor": "buildchain-kfd-2-product-claims-render"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims write`",
"anchor": "buildchain-kfd-2-product-claims-write"
},
{
"level": 3,
"title": "`buildchain kfd 2 schema`",
"anchor": "buildchain-kfd-2-schema"
},
{
"level": 3,
"title": "`buildchain kfd 2 taxonomy`",
"anchor": "buildchain-kfd-2-taxonomy"
},
{
"level": 3,
"title": "`buildchain kfd 2 trust-assessment`",
"anchor": "buildchain-kfd-2-trust-assessment"
},
{
"level": 3,
"title": "`buildchain kfd 2 trust-claims`",
"anchor": "buildchain-kfd-2-trust-claims"
},
{
"level": 3,
"title": "`buildchain kfd 3`",
"anchor": "buildchain-kfd-3"
},
{
"level": 3,
"title": "`buildchain kfd 3 audit`",
"anchor": "buildchain-kfd-3-audit"
},
{
"level": 3,
"title": "`buildchain kfd 3 detect`",
"anchor": "buildchain-kfd-3-detect"
},
{
"level": 3,
"title": "`buildchain kfd 3 query`",
"anchor": "buildchain-kfd-3-query"
},
{
"level": 3,
"title": "`buildchain kfd 3 register binary`",
"anchor": "buildchain-kfd-3-register-binary"
},
{
"level": 3,
"title": "`buildchain kfd 3 register cli`",
"anchor": "buildchain-kfd-3-register-cli"
},
{
"level": 3,
"title": "`buildchain kfd 3 register documentation`",
"anchor": "buildchain-kfd-3-register-documentation"
},
{
"level": 3,
"title": "`buildchain kfd 3 register node-api`",
"anchor": "buildchain-kfd-3-register-node-api"
},
{
"level": 3,
"title": "`buildchain kfd 3 register python-api`",
"anchor": "buildchain-kfd-3-register-python-api"
},
{
"level": 3,
"title": "`buildchain kfd 3 register site-bundle`",
"anchor": "buildchain-kfd-3-register-site-bundle"
},
{
"level": 3,
"title": "`buildchain kfd 3 witness`",
"anchor": "buildchain-kfd-3-witness"
},
{
"level": 3,
"title": "`buildchain kfd 4 gate`",
"anchor": "buildchain-kfd-4-gate"
},
{
"level": 3,
"title": "`buildchain kfd 4 schema`",
"anchor": "buildchain-kfd-4-schema"
},
{
"level": 3,
"title": "`buildchain kfd 4 verify`",
"anchor": "buildchain-kfd-4-verify"
},
{
"level": 3,
"title": "`buildchain kfd 5 gate`",
"anchor": "buildchain-kfd-5-gate"
},
{
"level": 3,
"title": "`buildchain kfd 5 schema`",
"anchor": "buildchain-kfd-5-schema"
},
{
"level": 3,
"title": "`buildchain kfd 5 verify`",
"anchor": "buildchain-kfd-5-verify"
},
{
"level": 3,
"title": "`buildchain kfd 7 gate`",
"anchor": "buildchain-kfd-7-gate"
},
{
"level": 3,
"title": "`buildchain kfd 7 schema`",
"anchor": "buildchain-kfd-7-schema"
},
{
"level": 3,
"title": "`buildchain kfd 7 verify`",
"anchor": "buildchain-kfd-7-verify"
},
{
"level": 3,
"title": "`buildchain kfd aggregate`",
"anchor": "buildchain-kfd-aggregate"
},
{
"level": 3,
"title": "`buildchain kfd hub explain`",
"anchor": "buildchain-kfd-hub-explain"
},
{
"level": 3,
"title": "`buildchain kfd hub init`",
"anchor": "buildchain-kfd-hub-init"
},
{
"level": 3,
"title": "`buildchain kfd hub inspect`",
"anchor": "buildchain-kfd-hub-inspect"
},
{
"level": 3,
"title": "`buildchain kfd hub test`",
"anchor": "buildchain-kfd-hub-test"
},
{
"level": 3,
"title": "`buildchain kfd migrate-layout`",
"anchor": "buildchain-kfd-migrate-layout"
},
{
"level": 3,
"title": "`buildchain kfd schema list`",
"anchor": "buildchain-kfd-schema-list"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-1`",
"anchor": "buildchain-kfd-schema-show-kfd-1"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-2`",
"anchor": "buildchain-kfd-schema-show-kfd-2"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-3`",
"anchor": "buildchain-kfd-schema-show-kfd-3"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-4`",
"anchor": "buildchain-kfd-schema-show-kfd-4"
},
{
"level": 3,
"title": "`buildchain kfd status`",
"anchor": "buildchain-kfd-status"
},
{
"level": 3,
"title": "`buildchain kfd support project`",
"anchor": "buildchain-kfd-support-project"
},
{
"level": 3,
"title": "`buildchain kfd support verify`",
"anchor": "buildchain-kfd-support-verify"
},
{
"level": 3,
"title": "`buildchain kfd upstream check`",
"anchor": "buildchain-kfd-upstream-check"
},
{
"level": 3,
"title": "`buildchain kfd upstream collect`",
"anchor": "buildchain-kfd-upstream-collect"
},
{
"level": 3,
"title": "`buildchain kfd upstream roles`",
"anchor": "buildchain-kfd-upstream-roles"
},
{
"level": 2,
"title": "`layout`",
"anchor": "layout"
},
{
"level": 3,
"title": "`buildchain layout`",
"anchor": "buildchain-layout"
},
{
"level": 2,
"title": "`lifecycle`",
"anchor": "lifecycle"
},
{
"level": 3,
"title": "`buildchain lifecycle`",
"anchor": "buildchain-lifecycle"
},
{
"level": 3,
"title": "`buildchain lifecycle run`",
"anchor": "buildchain-lifecycle-run"
},
{
"level": 2,
"title": "`log`",
"anchor": "log"
},
{
"level": 3,
"title": "`buildchain log`",
"anchor": "buildchain-log"
},
{
"level": 3,
"title": "`buildchain log error`",
"anchor": "buildchain-log-error"
},
{
"level": 3,
"title": "`buildchain log info`",
"anchor": "buildchain-log-info"
},
{
"level": 3,
"title": "`buildchain log summary`",
"anchor": "buildchain-log-summary"
},
{
"level": 3,
"title": "`buildchain log warn`",
"anchor": "buildchain-log-warn"
},
{
"level": 2,
"title": "`mark`",
"anchor": "mark"
},
{
"level": 3,
"title": "`buildchain mark`",
"anchor": "buildchain-mark"
},
{
"level": 2,
"title": "`next-development`",
"anchor": "next-development"
},
{
"level": 3,
"title": "`buildchain next-development`",
"anchor": "buildchain-next-development"
},
{
"level": 3,
"title": "`buildchain next-development materialize`",
"anchor": "buildchain-next-development-materialize"
},
{
"level": 2,
"title": "`npm`",
"anchor": "npm"
},
{
"level": 3,
"title": "`buildchain npm`",
"anchor": "buildchain-npm"
},
{
"level": 3,
"title": "`buildchain npm dry-run`",
"anchor": "buildchain-npm-dry-run"
},
{
"level": 2,
"title": "`paper`",
"anchor": "paper"
},
{
"level": 3,
"title": "`buildchain paper`",
"anchor": "buildchain-paper"
},
{
"level": 3,
"title": "`buildchain paper agent verify`",
"anchor": "buildchain-paper-agent-verify"
},
{
"level": 3,
"title": "`buildchain paper fleet audit`",
"anchor": "buildchain-paper-fleet-audit"
},
{
"level": 3,
"title": "`buildchain paper fleet update`",
"anchor": "buildchain-paper-fleet-update"
},
{
"level": 3,
"title": "`buildchain paper migrate`",
"anchor": "buildchain-paper-migrate"
},
{
"level": 3,
"title": "`buildchain paper preflight`",
"anchor": "buildchain-paper-preflight"
},
{
"level": 3,
"title": "`buildchain paper scaffold`",
"anchor": "buildchain-paper-scaffold"
},
{
"level": 3,
"title": "`buildchain paper status`",
"anchor": "buildchain-paper-status"
},
{
"level": 3,
"title": "`buildchain paper work start`",
"anchor": "buildchain-paper-work-start"
},
{
"level": 3,
"title": "`buildchain paper work submit`",
"anchor": "buildchain-paper-work-submit"
},
{
"level": 2,
"title": "`portable-cache`",
"anchor": "portable-cache"
},
{
"level": 3,
"title": "`buildchain portable-cache`",
"anchor": "buildchain-portable-cache"
},
{
"level": 3,
"title": "`buildchain portable-cache plan`",
"anchor": "buildchain-portable-cache-plan"
},
{
"level": 3,
"title": "`buildchain portable-cache receipt`",
"anchor": "buildchain-portable-cache-receipt"
},
{
"level": 2,
"title": "`project`",
"anchor": "project"
},
{
"level": 3,
"title": "`buildchain project`",
"anchor": "buildchain-project"
},
{
"level": 3,
"title": "`buildchain project kfx-admission`",
"anchor": "buildchain-project-kfx-admission"
},
{
"level": 2,
"title": "`publication-artifact`",
"anchor": "publication-artifact"
},
{
"level": 3,
"title": "`buildchain publication-artifact`",
"anchor": "buildchain-publication-artifact"
},
{
"level": 3,
"title": "`buildchain publication-artifact manifest`",
"anchor": "buildchain-publication-artifact-manifest"
},
{
"level": 3,
"title": "`buildchain publication-artifact npm-package`",
"anchor": "buildchain-publication-artifact-npm-package"
},
{
"level": 3,
"title": "`buildchain publication-artifact reproducibility`",
"anchor": "buildchain-publication-artifact-reproducibility"
},
{
"level": 2,
"title": "`publish-source`",
"anchor": "publish-source"
},
{
"level": 3,
"title": "`buildchain publish-source`",
"anchor": "buildchain-publish-source"
},
{
"level": 3,
"title": "`buildchain publish-source lock`",
"anchor": "buildchain-publish-source-lock"
},
{
"level": 3,
"title": "`buildchain publish-source manifest`",
"anchor": "buildchain-publish-source-manifest"
},
{
"level": 3,
"title": "`buildchain publish-source validate-anchored-release`",
"anchor": "buildchain-publish-source-validate-anchored-release"
},
{
"level": 3,
"title": "`buildchain publish-source verify-channel-ref`",
"anchor": "buildchain-publish-source-verify-channel-ref"
},
{
"level": 3,
"title": "`buildchain publish-source verify-lock`",
"anchor": "buildchain-publish-source-verify-lock"
},
{
"level": 2,
"title": "`release`",
"anchor": "release"
},
{
"level": 3,
"title": "`buildchain release`",
"anchor": "buildchain-release"
},
{
"level": 3,
"title": "`buildchain release --dry-run`",
"anchor": "buildchain-release-dry-run"
},
{
"level": 3,
"title": "`buildchain release abort`",
"anchor": "buildchain-release-abort"
},
{
"level": 3,
"title": "`buildchain release dry-run`",
"anchor": "buildchain-release-dry-run"
},
{
"level": 3,
"title": "`buildchain release explain`",
"anchor": "buildchain-release-explain"
},
{
"level": 3,
"title": "`buildchain release finalize`",
"anchor": "buildchain-release-finalize"
},
{
"level": 3,
"title": "`buildchain release inspect`",
"anchor": "buildchain-release-inspect"
},
{
"level": 3,
"title": "`buildchain release line open`",
"anchor": "buildchain-release-line-open"
},
{
"level": 3,
"title": "`buildchain release recover`",
"anchor": "buildchain-release-recover"
},
{
"level": 2,
"title": "`release-governance`",
"anchor": "release-governance"
},
{
"level": 3,
"title": "`buildchain release-governance`",
"anchor": "buildchain-release-governance"
},
{
"level": 3,
"title": "`buildchain release-governance reconcile`",
"anchor": "buildchain-release-governance-reconcile"
},
{
"level": 2,
"title": "`release-propagation`",
"anchor": "release-propagation"
},
{
"level": 3,
"title": "`buildchain release-propagation`",
"anchor": "buildchain-release-propagation"
},
{
"level": 3,
"title": "`buildchain release-propagation entry`",
"anchor": "buildchain-release-propagation-entry"
},
{
"level": 3,
"title": "`buildchain release-propagation pickup`",
"anchor": "buildchain-release-propagation-pickup"
},
{
"level": 3,
"title": "`buildchain release-propagation plan`",
"anchor": "buildchain-release-propagation-plan"
},
{
"level": 3,
"title": "`buildchain release-propagation work`",
"anchor": "buildchain-release-propagation-work"
},
{
"level": 3,
"title": "`buildchain release-propagation write-lock`",
"anchor": "buildchain-release-propagation-write-lock"
},
{
"level": 2,
"title": "`release-tail`",
"anchor": "release-tail"
},
{
"level": 3,
"title": "`buildchain release-tail`",
"anchor": "buildchain-release-tail"
},
{
"level": 3,
"title": "`buildchain release-tail init`",
"anchor": "buildchain-release-tail-init"
},
{
"level": 3,
"title": "`buildchain release-tail plan`",
"anchor": "buildchain-release-tail-plan"
},
{
"level": 3,
"title": "`buildchain release-tail rehearse`",
"anchor": "buildchain-release-tail-rehearse"
},
{
"level": 3,
"title": "`buildchain release-tail status`",
"anchor": "buildchain-release-tail-status"
},
{
"level": 3,
"title": "`buildchain release-tail verify`",
"anchor": "buildchain-release-tail-verify"
},
{
"level": 2,
"title": "`sample`",
"anchor": "sample"
},
{
"level": 3,
"title": "`buildchain sample`",
"anchor": "buildchain-sample"
},
{
"level": 3,
"title": "`buildchain sample process-tree`",
"anchor": "buildchain-sample-process-tree"
},
{
"level": 2,
"title": "`span`",
"anchor": "span"
},
{
"level": 3,
"title": "`buildchain span`",
"anchor": "buildchain-span"
},
{
"level": 2,
"title": "`tail-reseal`",
"anchor": "tail-reseal"
},
{
"level": 3,
"title": "`buildchain tail-reseal`",
"anchor": "buildchain-tail-reseal"
},
{
"level": 3,
"title": "`buildchain tail-reseal admit`",
"anchor": "buildchain-tail-reseal-admit"
},
{
"level": 3,
"title": "`buildchain tail-reseal plan`",
"anchor": "buildchain-tail-reseal-plan"
},
{
"level": 3,
"title": "`buildchain tail-reseal seal`",
"anchor": "buildchain-tail-reseal-seal"
},
{
"level": 3,
"title": "`buildchain tail-reseal verify-platform`",
"anchor": "buildchain-tail-reseal-verify-platform"
},
{
"level": 2,
"title": "`transaction`",
"anchor": "transaction"
},
{
"level": 3,
"title": "`buildchain transaction`",
"anchor": "buildchain-transaction"
},
{
"level": 3,
"title": "`buildchain transaction inspect`",
"anchor": "buildchain-transaction-inspect"
},
{
"level": 2,
"title": "`validate`",
"anchor": "validate"
},
{
"level": 3,
"title": "`buildchain validate`",
"anchor": "buildchain-validate"
},
{
"level": 2,
"title": "`verify`",
"anchor": "verify"
},
{
"level": 3,
"title": "`buildchain verify`",
"anchor": "buildchain-verify"
},
{
"level": 3,
"title": "`buildchain verify artifact dir`",
"anchor": "buildchain-verify-artifact-dir"
},
{
"level": 3,
"title": "`buildchain verify artifact file`",
"anchor": "buildchain-verify-artifact-file"
},
{
"level": 3,
"title": "`buildchain verify artifact github-release:...`",
"anchor": "buildchain-verify-artifact-github-release"
},
{
"level": 3,
"title": "`buildchain verify artifact npm:...`",
"anchor": "buildchain-verify-artifact-npm"
},
{
"level": 3,
"title": "`buildchain verify artifact oci:...`",
"anchor": "buildchain-verify-artifact-oci"
},
{
"level": 3,
"title": "`buildchain verify artifact url`",
"anchor": "buildchain-verify-artifact-url"
},
{
"level": 3,
"title": "`buildchain verify artifact-envelope`",
"anchor": "buildchain-verify-artifact-envelope"
},
{
"level": 3,
"title": "`buildchain verify github-artifact-attestation`",
"anchor": "buildchain-verify-github-artifact-attestation"
},
{
"level": 3,
"title": "`buildchain verify infra-contract-evidence-bundle`",
"anchor": "buildchain-verify-infra-contract-evidence-bundle"
},
{
"level": 3,
"title": "`buildchain verify observability-log`",
"anchor": "buildchain-verify-observability-log"
},
{
"level": 3,
"title": "`buildchain verify publication-admission`",
"anchor": "buildchain-verify-publication-admission"
},
{
"level": 3,
"title": "`buildchain verify release-passport`",
"anchor": "buildchain-verify-release-passport"
},
{
"level": 2,
"title": "`version`",
"anchor": "version"
},
{
"level": 3,
"title": "`buildchain version`",
"anchor": "buildchain-version"
},
{
"level": 2,
"title": "`web-surface`",
"anchor": "web-surface"
},
{
"level": 3,
"title": "`buildchain web-surface`",
"anchor": "buildchain-web-surface"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-generated-reference\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: generated\nlast_reviewed: 2026-08-01\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-08-01\n invisible_context: not asserted\n---\n\n# Buildchain CLI Reference\n\n> Generated from `BUILDCHAIN_USAGE` and the runtime command registry. Do not edit this file by hand.\n\nEvery listed help command is intercepted before dispatch, exits zero, and performs no command side effects.\n\n## `adopter-delivery`\n\n### `buildchain adopter-delivery`\n\n- Help: `buildchain adopter-delivery --help`\n- Canonical id: `adopter-delivery`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain adopter-delivery\n```\n\n### `buildchain adopter-delivery run`\n\n- Help: `buildchain adopter-delivery run --help`\n- Canonical id: `adopter-delivery`\n- Options: `--input`, `--output`\n- Syntax:\n\n```text\nbuildchain adopter-delivery run --input [--output ]\n```\n\n### `buildchain adopter-delivery verify`\n\n- Help: `buildchain adopter-delivery verify --help`\n- Canonical id: `adopter-delivery`\n- Options: `--input`, `--output`, `--readback`\n- Syntax:\n\n```text\nbuildchain adopter-delivery verify --input --readback [--output ]\n```\n\n## `architecture`\n\n### `buildchain architecture`\n\n- Help: `buildchain architecture --help`\n- Canonical id: `architecture`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain architecture\n```\n\n### `buildchain architecture list`\n\n- Help: `buildchain architecture list --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture list [--cwd ] [--json]\n```\n\n### `buildchain architecture qualify`\n\n- Help: `buildchain architecture qualify --help`\n- Canonical id: `architecture`\n- Options: `--authority-revision`, `--candidate-revision`, `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture qualify --authority-revision [--candidate-revision ] [--cwd ] [--json]\n```\n\n### `buildchain architecture show`\n\n- Help: `buildchain architecture show --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture show [--cwd ] [--json]\n```\n\n### `buildchain architecture validate`\n\n- Help: `buildchain architecture validate --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture validate [--cwd ] [--json]\n```\n\n## `audit`\n\n### `buildchain audit`\n\n- Help: `buildchain audit --help`\n- Canonical id: `audit`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain audit\n```\n\n### `buildchain audit github-governance`\n\n- Help: `buildchain audit github-governance --help`\n- Canonical id: `audit`\n- Options: `--allow-nonqualifying`, `--environment`, `--job`, `--json`, `--npm-trust-json`, `--organization`, `--output`, `--package`, `--provider-audit-json`, `--publisher-mode`, `--repository`, `--require-qualifying`, `--source-sha`, `--workflow`, `--workflow-ref`, `--workflow-repository`\n- Syntax:\n\n```text\nbuildchain audit github-governance [--organization ] [--repository ] [--output ] [--require-qualifying] [--json] [--source-sha ] [--workflow-repository ] [--workflow ] [--workflow-ref ] [--job ] [--environment ] [--package ] [--publisher-mode npm-trusted-publisher|github-token|oidc-role] [--npm-trust-json ] [--provider-audit-json ] [--output ] [--allow-nonqualifying]\n```\n\n### `buildchain audit publication-control-plane`\n\n- Help: `buildchain audit publication-control-plane --help`\n- Canonical id: `audit`\n- Options: `--branch`, `--repository`\n- Syntax:\n\n```text\nbuildchain audit publication-control-plane --repository --branch \n```\n\n## `badges`\n\n### `buildchain badges`\n\n- Help: `buildchain badges --help`\n- Canonical id: `badges`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain badges\n```\n\n### `buildchain badges bundle`\n\n- Help: `buildchain badges bundle --help`\n- Canonical id: `badges-bundle`\n- Options: `--check`, `--claims`, `--cwd`, `--json`, `--readme`, `--write`\n- Syntax:\n\n```text\nbuildchain badges bundle [--cwd ] [--readme ] [--claims ] [--check] [--write] [--json]\n```\n\n### `buildchain badges readme`\n\n- Help: `buildchain badges readme --help`\n- Canonical id: `badges-readme`\n- Options: `--check`, `--cwd`, `--json`, `--readme`, `--write`\n- Syntax:\n\n```text\nbuildchain badges readme [--cwd ] [--readme ] [--check] [--write] [--json]\n```\n\n## `build-contract`\n\n### `buildchain build-contract`\n\n- Help: `buildchain build-contract --help`\n- Canonical id: `build-contract`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain build-contract ...\n```\n\n## `candidate`\n\n### `buildchain candidate`\n\n- Help: `buildchain candidate --help`\n- Canonical id: `candidate`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain candidate\n```\n\n### `buildchain candidate timeline`\n\n- Help: `buildchain candidate timeline --help`\n- Canonical id: `candidate`\n- Options: `--input`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain candidate timeline --input [--output ] [--json]\n```\n\n## `collect`\n\n### `buildchain collect`\n\n- Help: `buildchain collect --help`\n- Canonical id: `collect`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain collect\n```\n\n### `buildchain collect github-release`\n\n- Help: `buildchain collect github-release --help`\n- Canonical id: `collect-github-release`\n- Options: `--adopter-delivery-json`, `--anchor-manifest-json`, `--assets-dir`, `--assets-json`, `--base-passport-json`, `--build-facts-json`, `--build-summary-json`, `--dist-tag-evidence-json`, `--github-artifact-attestation-policy-json`, `--impact-json`, `--invariant-passport-cmd`, `--invariant-passport-json`, `--json`, `--kfd-1-witness-json`, `--kfd-2-claim-json`, `--kfd-3-artifact-verify-cmd`, `--kfd-3-artifact-witness-json`, `--kfd-3-prebuild-witness-json`, `--kfd-adopter-manifest-json`, `--kfd-agent-hub-evidence-json`, `--kfd-product-gate-json`, `--kfd-support-matrix-json`, `--output-dir`, `--package-set-json`, `--platform-manifest-json`, `--product-name`, `--publish-evidence-json`, `--publish-json`, `--release-evidence-json`, `--release-extra-json`, `--release-json`, `--repository`, `--require-base-kfd`, `--tag`, `--transaction-json`, `--trusted-publishing-json`\n- Syntax:\n\n```text\nbuildchain collect github-release --tag [--repository ] [--adopter-delivery-json ] [--assets-dir ] [--assets-json ] [--release-json ] [--package-set-json ] [--product-name ] [--publish-evidence-json ] [--trusted-publishing-json ] [--transaction-json ] [--anchor-manifest-json ] [--impact-json ] [--build-summary-json ] [--build-facts-json ]... [--platform-manifest-json ]... [--dist-tag-evidence-json ] [--kfd-1-witness-json ]... [--kfd-2-claim-json ]... [--kfd-3-prebuild-witness-json ]... [--kfd-3-artifact-witness-json ]... [--kfd-3-artifact-verify-cmd ] [--kfd-adopter-manifest-json ] [--kfd-support-matrix-json ] [--kfd-product-gate-json ]... [--invariant-passport-json ]... [--invariant-passport-cmd ] [--release-evidence-json ]... [--github-artifact-attestation-policy-json ]... [--kfd-agent-hub-evidence-json ] [--base-passport-json ] [--require-base-kfd] [--release-extra-json ] [--publish-json ] [--output-dir ] [--json]\n```\n\n## `create`\n\n### `buildchain create`\n\n- Help: `buildchain create --help`\n- Canonical id: `create`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain create\n```\n\n### `buildchain create github-artifact-attestation-policy`\n\n- Help: `buildchain create github-artifact-attestation-policy --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create github-artifact-attestation-policy --input-json [--output ] [--json]\n```\n\n### `buildchain create publication-admission`\n\n- Help: `buildchain create publication-admission --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create publication-admission --input-json [--output ] [--json]\n```\n\n### `buildchain create runner-provenance`\n\n- Help: `buildchain create runner-provenance --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create runner-provenance --input-json [--output ] [--json]\n```\n\n## `dev`\n\n### `buildchain dev`\n\n- Help: `buildchain dev --help`\n- Canonical id: `dev`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain dev\n```\n\n### `buildchain dev authority admit-merge-group`\n\n- Help: `buildchain dev authority admit-merge-group --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority complete-qualification`\n\n- Help: `buildchain dev authority complete-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority heartbeat-landing`\n\n- Help: `buildchain dev authority heartbeat-landing --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority heartbeat-qualification`\n\n- Help: `buildchain dev authority heartbeat-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority lease-landing`\n\n- Help: `buildchain dev authority lease-landing --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority lease-qualification`\n\n- Help: `buildchain dev authority lease-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority migrate`\n\n- Help: `buildchain dev authority migrate --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority observe`\n\n- Help: `buildchain dev authority observe --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority recover`\n\n- Help: `buildchain dev authority recover --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority settle`\n\n- Help: `buildchain dev authority settle --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority submit`\n\n- Help: `buildchain dev authority submit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev merge-queue`\n\n- Help: `buildchain dev merge-queue --help`\n- Canonical id: `dev`\n- Options: `--apply`, `--branch`, `--check-response-timeout-minutes`, `--cwd`, `--from-config`, `--max-entries-to-build`, `--repository`, `--workflow`\n- Syntax:\n\n```text\nbuildchain dev merge-queue --repository --branch [--from-config | --workflow ...] [--cwd ] [--check-response-timeout-minutes ] [--max-entries-to-build ] [--apply]\n```\n\n### `buildchain dev pr-admit`\n\n- Help: `buildchain dev pr-admit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--expected-head`, `--json`, `--output`, `--pull-request`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev pr-admit --repository --branch --pull-request --expected-head [--execute] [--output ] [--json]\n```\n\n### `buildchain dev proof classify`\n\n- Help: `buildchain dev proof classify --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof classify-native`\n\n- Help: `buildchain dev proof classify-native --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof integration`\n\n- Help: `buildchain dev proof integration --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof native`\n\n- Help: `buildchain dev proof native --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof replay`\n\n- Help: `buildchain dev proof replay --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof source`\n\n- Help: `buildchain dev proof source --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-integration`\n\n- Help: `buildchain dev proof verify-integration --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-native`\n\n- Help: `buildchain dev proof verify-native --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-native-reuse`\n\n- Help: `buildchain dev proof verify-native-reuse --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-source`\n\n- Help: `buildchain dev proof verify-source --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev two-phase`\n\n- Help: `buildchain dev two-phase --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--expected-head`, `--json`, `--native-command`, `--native-proof`, `--output`, `--pull-request`, `--repository`, `--warrant-result`\n- Syntax:\n\n```text\nbuildchain dev two-phase --repository --branch --pull-request --expected-head --warrant-result --native-command [--native-proof ] [--output ] [--json]\n```\n\n### `buildchain dev warrant cancel-queued`\n\n- Help: `buildchain dev warrant cancel-queued --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant close`\n\n- Help: `buildchain dev warrant close --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant heartbeat`\n\n- Help: `buildchain dev warrant heartbeat --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant observe`\n\n- Help: `buildchain dev warrant observe --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant qualify`\n\n- Help: `buildchain dev warrant qualify --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant recover`\n\n- Help: `buildchain dev warrant recover --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant select`\n\n- Help: `buildchain dev warrant select --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant settle`\n\n- Help: `buildchain dev warrant settle --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant submit`\n\n- Help: `buildchain dev warrant submit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n## `diagnostics`\n\n### `buildchain diagnostics`\n\n- Help: `buildchain diagnostics --help`\n- Canonical id: `diagnostics`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain diagnostics\n```\n\n### `buildchain diagnostics summary`\n\n- Help: `buildchain diagnostics summary --help`\n- Canonical id: `diagnostics-summary`\n- Options: `--artifact`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain diagnostics summary