@kungfu-tech/buildchain 3.0.3-alpha.1 → 3.0.3-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -4
- package/bin/buildchain.mjs +2 -256
- package/dist/site/buildchain-contract.json +5 -5
- package/dist/site/buildchain-site.json +19 -14
- package/dist/site/capability-registry.json +2 -2
- package/dist/site/cli-registry.json +72 -0
- package/dist/site/kfd-claims.json +95 -11
- package/dist/site/kfd-upstream-aggregate.json +1 -1
- package/dist/site/manual-registry.json +1 -1
- package/dist/site/node-api-registry.json +7 -7
- package/dist/site/page-registry.json +13 -8
- package/dist/site/public-surface-audit.json +72 -14
- package/dist/site/publication-registry.json +4 -4
- package/dist/site/site-manifest.json +5 -5
- package/docs/cli.md +31 -7
- package/docs/publication-artifacts.md +27 -0
- package/package.json +1 -1
- package/packages/core/README.md +3 -2
- package/packages/core/github-governance-authority.js +10 -25
- package/packages/core/index.js +1 -1
- package/packages/core/paper-fleet.js +260 -0
- package/packages/core/paper-repository.js +210 -0
- package/packages/core/paper-work.js +365 -0
- package/packages/core/paper.js +117 -163
- package/packages/core/public-surface-audit.js +26 -78
- package/packages/core/public-surface-cli.js +117 -0
- package/scripts/buildchain-cli-help.mjs +256 -0
- package/scripts/generate-site-bundle.mjs +1 -187
- package/scripts/paper-work-fleet-cli.mjs +563 -0
- package/scripts/paper.mjs +31 -45
- package/scripts/site-capability-metadata.mjs +202 -0
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"contract": "kungfu-buildchain-site-bundle",
|
|
4
|
-
"generatedAt": "2026-07-
|
|
5
|
-
"publishedAt": "2026-07-
|
|
4
|
+
"generatedAt": "2026-07-31T15:25:20.771Z",
|
|
5
|
+
"publishedAt": "2026-07-31T15:25:20.771Z",
|
|
6
6
|
"reproducible": true,
|
|
7
7
|
"timestampPolicy": "ci-injected",
|
|
8
8
|
"deterministicInputs": [
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"declared Buildchain surface manifest contract"
|
|
20
20
|
],
|
|
21
21
|
"sourceDateEpoch": "0",
|
|
22
|
-
"sourceRevision": "
|
|
22
|
+
"sourceRevision": "00a07a9a2eb0e4839727cf455fa209066166abbf",
|
|
23
23
|
"timestampPolicyDetails": {
|
|
24
24
|
"contract": "kungfu-buildchain-surface-timestamp-policy",
|
|
25
25
|
"timestampFields": [
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"package": {
|
|
39
39
|
"name": "@kungfu-tech/buildchain",
|
|
40
|
-
"version": "3.0.3-alpha.
|
|
40
|
+
"version": "3.0.3-alpha.2",
|
|
41
41
|
"versionSource": "package.json#version"
|
|
42
42
|
},
|
|
43
43
|
"source": {
|
|
@@ -106,7 +106,7 @@
|
|
|
106
106
|
],
|
|
107
107
|
"maturity": "stable",
|
|
108
108
|
"sourcePath": "README.md",
|
|
109
|
-
"digest": "sha256:
|
|
109
|
+
"digest": "sha256:f238209650d3eee529616542d556fd62b9bfeb2d71333cdfcb90ffe74052f5d7",
|
|
110
110
|
"headings": [
|
|
111
111
|
{
|
|
112
112
|
"level": 1,
|
|
@@ -164,7 +164,7 @@
|
|
|
164
164
|
"anchor": "read-next"
|
|
165
165
|
}
|
|
166
166
|
],
|
|
167
|
-
"markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\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/verify.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\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## 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\nFor v3, 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/v3.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@3.0.0 version\n```\n\nThe v3.0.0 release publishes evidence assets but no standalone platform archives.\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`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@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: v3\n diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\nnpx @kungfu-tech/buildchain paper preflight --offline\nnpx @kungfu-tech/buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files; external mutations such as npm bootstrap, Alpha PR creation,\nand release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains six active entries. Four are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer list from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n planning, capability-aware runner dispatch, receipt validation, and one\n stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n qualification, transcript-bound renderer smoke, optional media rendering\n from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n promote-only publication from a PR-stage release candidate, without a second\n heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```\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 reusable workflow\n and action surfaces.\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- [Release governance](docs/release-governance.md)",
|
|
167
|
+
"markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\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/verify.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\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## 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\nFor v3, 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/v3.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@3.0.0 version\n```\n\nThe v3.0.0 release publishes evidence assets but no standalone platform archives.\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`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@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: v3\n diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\npnpm add -D @kungfu-tech/buildchain@<exact-v3-version>\npnpm exec buildchain paper work start <topic>\npnpm exec buildchain paper work submit\npnpm exec buildchain paper preflight --offline\npnpm exec buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files. `work start` and `work submit` validate the canonical remote,\nexact development SHA, clean source, safe branch, and fast-forward boundary\nbefore changing local or GitHub state. External mutations such as npm\nbootstrap, Alpha PR creation, and release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains six active entries. Four are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer list from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n planning, capability-aware runner dispatch, receipt validation, and one\n stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n qualification, transcript-bound renderer smoke, optional media rendering\n from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n promote-only publication from a PR-stage release candidate, without a second\n heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```\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 reusable workflow\n and action surfaces.\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- [Release governance](docs/release-governance.md)",
|
|
168
168
|
"slug": "home"
|
|
169
169
|
},
|
|
170
170
|
{
|
|
@@ -326,7 +326,7 @@
|
|
|
326
326
|
],
|
|
327
327
|
"maturity": "stable",
|
|
328
328
|
"sourcePath": "packages/core/README.md",
|
|
329
|
-
"digest": "sha256:
|
|
329
|
+
"digest": "sha256:a73db80985e32c2ebb4ae94e30bc0e9bdc06f04eae189e8af25f89e901c14573",
|
|
330
330
|
"headings": [
|
|
331
331
|
{
|
|
332
332
|
"level": 1,
|
|
@@ -339,7 +339,7 @@
|
|
|
339
339
|
"anchor": "toolkit-imports"
|
|
340
340
|
}
|
|
341
341
|
],
|
|
342
|
-
"markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n `@kungfu-tech/buildchain/release-passport`.\n- anchored/manual derived witness preflight and exact-tree evidence through\n `@kungfu-tech/buildchain/anchored-version-material`.\n- sealed exact-root and KFD assessment inputs for KFX admission through\n `@kungfu-tech/buildchain/artifact-verification-envelope`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n through `@kungfu-tech/buildchain/badges`.\n- publication artifact manifests, source bundles, and publication artifact\n passports through `@kungfu-tech/buildchain/publication-artifact`.\n- two-clean-build byte reproducibility receipts through\n `@kungfu-tech/buildchain/publication-reproducibility`.\n- build-once publication bundle manifests and exact-byte verification through\n `@kungfu-tech/buildchain/publication-sealed-bundle`.\n- governed
|
|
342
|
+
"markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n `@kungfu-tech/buildchain/release-passport`.\n- anchored/manual derived witness preflight and exact-tree evidence through\n `@kungfu-tech/buildchain/anchored-version-material`.\n- sealed exact-root and KFD assessment inputs for KFX admission through\n `@kungfu-tech/buildchain/artifact-verification-envelope`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n through `@kungfu-tech/buildchain/badges`.\n- publication artifact manifests, source bundles, and publication artifact\n passports through `@kungfu-tech/buildchain/publication-artifact`.\n- two-clean-build byte reproducibility receipts through\n `@kungfu-tech/buildchain/publication-reproducibility`.\n- build-once publication bundle manifests and exact-byte verification through\n `@kungfu-tech/buildchain/publication-sealed-bundle`.\n- governed Paper work-branch start/submit, fleet audit/update, scaffold,\n preflight, status, npm bootstrap, build, Alpha, and resume plans through\n `@kungfu-tech/buildchain/paper`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n collectRunnerDiagnostics,\n summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } =\n await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } =\n await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nBuild facts consumers can collect source-bound module/product facts before\npublishing and pass those facts into the release passport:\n\n```js\nimport {\n collectModuleBuildFacts,\n writeBuildFacts,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst fact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact, output: \".buildchain/facts/native-core.json\" });\n```\n\nKFX producers can seal one passing artifact verification with exact roots,\nidentity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers\nverify or project the same envelope instead of reconstructing bindings:\n\n```js\nimport {\n projectArtifactVerificationEnvelopeToKfx,\n verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\nPublication repositories can produce site-consumable paper/report facts without\nbecoming web-surface repositories. When `[publication.archive]` is configured,\nthe same API also maintains the append-only publication registry used by site\nrepositories for latest and historical version pages. The preferred\n`latex-docker` toolchain records the pinned build-images LaTeX builder digest in\nthe publication artifact passport:\n\n```js\nimport { writePublicationArtifact } from \"@kungfu-tech/buildchain/publication-artifact\";\n\nwritePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });\n```\n\nBefore publication admission, prove the exact PDF, source bundle, manifests,\nand npm tarball twice from the same Git commit:\n\n```js\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nconst receipt = verifyPublicationReproducibility({\n sourceSha: process.env.GITHUB_SHA,\n promote: true,\n});\nif (!receipt.qualifying) throw new Error(\"publication is not reproducible\");\n```\n\nBind the promoted bytes into the durable build-once publication envelope:\n\n```js\nimport {\n createPublicationSealedBundle,\n verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\nThe sealed manifest names the exact npm tarball and release assets. Promotion\npersists those binary files before registry publication and verifies them again\nwhen a fresh runner resumes.\n\nPaper automation can use the same typed contracts as the CLI:\n\n```js\nimport {\n collectPaperPreflight,\n collectPaperStatus,\n planPaperMigration,\n planPaperScaffold,\n writePaperMigration,\n} from \"@kungfu-tech/buildchain/paper\";\n```\n\nPlanning and observation are side-effect free. `writePaperScaffold()` and\n`writePaperMigration()` perform the bounded local writes, while external\nmutations remain explicit CLI operations guarded by `--execute`.\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public badge subpath and treat\nMarkdown as a projection of the returned facts:\n\n```js\nimport {\n collectBadgeBundleFacts,\n renderBadgeBundleBlock,\n} from \"@kungfu-tech/buildchain/badges\";\n\nconst facts = await collectBadgeBundleFacts({ cwd: process.cwd() });\nconst markdown = renderBadgeBundleBlock(facts);\n```\n\nThe older `@kungfu-tech/buildchain/readme-badges` subpath remains available for\ncallers that need the full README badge surface instead of the default\nKFD-1 / KFD-2 / KFD-3 / Release Passport bundle.",
|
|
343
343
|
"slug": "node-package"
|
|
344
344
|
},
|
|
345
345
|
{
|
|
@@ -597,7 +597,7 @@
|
|
|
597
597
|
],
|
|
598
598
|
"maturity": "stable",
|
|
599
599
|
"sourcePath": "docs/cli.md",
|
|
600
|
-
"digest": "sha256:
|
|
600
|
+
"digest": "sha256:9afe80ef29fb5cce140ffc7980c41172495878726e5504e47914b8dc7af8fc1f",
|
|
601
601
|
"headings": [
|
|
602
602
|
{
|
|
603
603
|
"level": 1,
|
|
@@ -630,7 +630,7 @@
|
|
|
630
630
|
"anchor": "npm-publish-gate"
|
|
631
631
|
}
|
|
632
632
|
],
|
|
633
|
-
"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-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# 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@3.0.0`, 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.\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 `@v3`.\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### Governed paper lifecycle\n\n`buildchain paper` is the unified operator surface for a paper repository. Its\neight subcommands return versioned JSON contracts with `--json`:\n\n```bash\nbuildchain paper scaffold --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\nbuildchain paper migrate --json\nbuildchain paper preflight --offline --json\nbuildchain paper bootstrap npm --json\nbuildchain paper build --json\nbuildchain paper alpha --json\nbuildchain paper status --json\nbuildchain paper resume --json\n```\n\nThe safety and authority boundary is explicit:\n\n- `scaffold` plans a 14-file, no-overwrite repository shape by default; add\n `--write` to create only missing files.\n- `migrate` plans the five Buildchain-owned control-file changes needed by an\n existing paper repository. Add `--write` only after reviewing exact old and\n new digests; paper content and publication configuration are never rewritten.\n- The scaffolded `.buildchain/paper/provisioning-authority.json` binds both\n caller workflow byte digests, their exact reusable-workflow SHA, the runtime\n SHA, contract-lock bytes, npm registry and trusted-publisher coordinates, and\n the repository Actions/generated-write policy under one digest. A floating\n Buildchain ref cannot change release policy after that authority is accepted.\n- `preflight` separates local readiness from readiness for external mutation.\n `--offline` skips live GitHub and npm observations without treating them as\n local failures. Live readiness requires default workflow permissions `read`,\n Actions pull-request approval disabled, and GitHub App or equivalent narrow\n generated-write credential metadata.\n- `bootstrap npm` always performs npm pack and publish dry-runs first. A real\n public bootstrap requires both `--execute` and\n `--confirm-public-package <exact-name>`, uses only the official npm registry,\n fixes the bootstrap version at `0.0.0-bootstrap.0`, and returns only npm URLs\n observed from command output. Success requires public package readback and\n the exact repository/workflow/environment trusted-publisher binding. For\n GitHub, the npm coordinate is the workflow filename (`paper-release.yml`),\n not its `.github/workflows/` repository path.\n- `build` plans the two-clean-build reproducibility proof. Add `--execute` to\n create and verify the sealed publication bundle.\n- `alpha` plans or opens the protected Alpha pull request; it never merges,\n publishes, or advances a floating ref.\n- `status` reports only evidence found in the repository or external\n observations. It never infers a later lifecycle state from an earlier one.\n- `resume` plans or dispatches the repository's thin release workflow; the\n protected workflow remains the release authority.\n\nThe ordered evidence states are `scaffolded`, `governed`, `admitted`,\n`bootstrapped`, `trust-bound`, `content-ready`, `artifact-sealed`,\n`package-published`, `alpha-complete`, `staging-visible`, and\n`production-visible`. A state can be `satisfied`, `not-reached`, `blocked`, or\n`unknown`; consumers must not collapse those distinctions.\n\nThe corresponding Node surface is\n`@kungfu-tech/buildchain/paper`. Planning and status functions are read-only;\n`writePaperScaffold()` and `writePaperMigration()` are the bounded local\nwriters, and\n`executePaperNpmBootstrap()` preserves the same confirmation boundary used by\nthe CLI.\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 starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\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 presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n validation, observation, contract publication, and downstream propagation\n planning without default mutation. Provider adapters expose built-in command\n plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n publication repositories that produce PDFs, metadata, source bundles, and\n site-consumable manifests without becoming web-surface repositories. The\n scaffold uses Buildchain's pinned\n `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n --require-version-state \\\n --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` 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 3 \\\n --minor 1 \\\n --source-ref release/v3/v3.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 3 \\\n --minor 1 \\\n --source-ref release/v3/v3.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 --matrix-json support-matrix.json \\\n --gate-json kfd-4-gate.json --gate-json kfd-5-gate.json \\\n --gate-json kfd-7-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\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\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.\nThe `paper-release.yml@v3` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\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:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\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 <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.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 <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\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:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, 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/v3/v3.0\nbuildchain release --dry-run --target-ref release/v3/v3.0 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v3/v3.0\nbuildchain release explain --target-ref alpha/v3/v3.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 v3.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/promote-buildchain-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 <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v3.0.3-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v3.0.2` publishes to npm with dist-tag `latest`.\n- moving refs such as `v3`, `v3.0`, and `v3.0-alpha` do not match the publish\n workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
|
|
633
|
+
"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-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# 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@3.0.0`, 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.\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 `@v3`.\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### Governed paper lifecycle\n\n`buildchain paper` is the unified operator surface for one paper repository or\na discovered fleet. Every subcommand returns a versioned JSON contract with\n`--json`:\n\n```bash\nbuildchain paper scaffold --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\nbuildchain paper migrate --json\nbuildchain paper work start golden-path --json\nbuildchain paper work submit --json\nbuildchain paper fleet audit --root ../papers --json\nbuildchain paper fleet update --root ../paper-worktrees --json\nbuildchain paper preflight --offline --json\nbuildchain paper bootstrap npm --json\nbuildchain paper build --json\nbuildchain paper alpha --json\nbuildchain paper status --json\nbuildchain paper resume --json\n```\n\nThe safety and authority boundary is explicit:\n\n- `scaffold` plans a 14-file, no-overwrite repository shape by default; add\n `--write` to create only missing files.\n- `migrate` plans the Buildchain-owned authority, workflow, contract lock,\n version pin, and package control changes needed by an existing paper\n repository. It pins an exact v3 dependency and adds pnpm-backed paper scripts.\n Add `--write` only after reviewing exact old and new digests; paper content\n and publication configuration are never rewritten. Refresh\n `pnpm-lock.yaml` with `pnpm install --lockfile-only` after a write.\n- `work start` derives the protected development branch from the configured\n publication semver line and creates a safe local work branch only when the\n worktree is clean, the sole `origin` is the canonical `kungfu-systems`\n repository, and local HEAD equals the exact remotely observed development\n SHA. It never fetches or merges silently.\n- `work submit` accepts only an allowed non-protected work branch that contains\n the exact remote development commit. It rejects divergent remote work,\n wrong-base pull requests, dirty trees, forks, and ambiguous remotes; execution\n uses a normal non-force push and opens or reuses a PR to the derived\n development branch.\n- `fleet audit` discovers `paper-*` repositories from a root and emits one\n deterministic audit root over exact runtime, dependency, lockfile, workflow,\n authority, and repository observations. `fleet update` reuses the migration\n contract for every discovered repository, remains dry-run by default, and\n refuses protected or non-work branches.\n- The scaffolded `.buildchain/paper/provisioning-authority.json` binds both\n caller workflow byte digests, their exact reusable-workflow SHA, the runtime\n SHA, contract-lock bytes, npm registry and trusted-publisher coordinates, and\n the repository Actions/generated-write policy under one digest. A floating\n Buildchain ref cannot change release policy after that authority is accepted.\n- `preflight` separates local readiness from readiness for external mutation.\n `--offline` skips live GitHub and npm observations without treating them as\n local failures. Live readiness requires default workflow permissions `read`,\n Actions pull-request approval disabled, and GitHub App or equivalent narrow\n generated-write credential metadata.\n- `bootstrap npm` always performs npm pack and publish dry-runs first. A real\n public bootstrap requires both `--execute` and\n `--confirm-public-package <exact-name>`, uses only the official npm registry,\n fixes the bootstrap version at `0.0.0-bootstrap.0`, and returns only npm URLs\n observed from command output. Success requires public package readback and\n the exact repository/workflow/environment trusted-publisher binding. For\n GitHub, the npm coordinate is the workflow filename (`paper-release.yml`),\n not its `.github/workflows/` repository path.\n- `build` plans the two-clean-build reproducibility proof. Add `--execute` to\n create and verify the sealed publication bundle.\n- `alpha` plans or opens the protected Alpha pull request; it never merges,\n publishes, or advances a floating ref.\n- `status` reports only evidence found in the repository or external\n observations. It never infers a later lifecycle state from an earlier one.\n- `resume` plans or dispatches the repository's thin release workflow; the\n protected workflow remains the release authority.\n\nThe ordered evidence states are `scaffolded`, `governed`, `admitted`,\n`bootstrapped`, `trust-bound`, `content-ready`, `artifact-sealed`,\n`package-published`, `alpha-complete`, `staging-visible`, and\n`production-visible`. A state can be `satisfied`, `not-reached`, `blocked`, or\n`unknown`; consumers must not collapse those distinctions.\n\nThe corresponding Node surface is\n`@kungfu-tech/buildchain/paper`. Planning and status functions are read-only;\n`writePaperScaffold()`, `writePaperMigration()`, and\n`writePaperFleetUpdate()` are the bounded local writers. Work plans expose\nseparate rechecking executors for local branch creation and normal push, and\n`executePaperNpmBootstrap()` preserves the same confirmation boundary used by\nthe CLI.\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 starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\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 presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n validation, observation, contract publication, and downstream propagation\n planning without default mutation. Provider adapters expose built-in command\n plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n publication repositories that produce PDFs, metadata, source bundles, and\n site-consumable manifests without becoming web-surface repositories. The\n scaffold uses Buildchain's pinned\n `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n --require-version-state \\\n --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` 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 3 \\\n --minor 1 \\\n --source-ref release/v3/v3.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 3 \\\n --minor 1 \\\n --source-ref release/v3/v3.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 --matrix-json support-matrix.json \\\n --gate-json kfd-4-gate.json --gate-json kfd-5-gate.json \\\n --gate-json kfd-7-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\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\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.\nThe `paper-release.yml@v3` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\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:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\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 <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.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 <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\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:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, 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/v3/v3.0\nbuildchain release --dry-run --target-ref release/v3/v3.0 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v3/v3.0\nbuildchain release explain --target-ref alpha/v3/v3.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 v3.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/promote-buildchain-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 <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v3.0.3-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v3.0.2` publishes to npm with dist-tag `latest`.\n- moving refs such as `v3`, `v3.0`, and `v3.0-alpha` do not match the publish\n workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
|
|
634
634
|
},
|
|
635
635
|
{
|
|
636
636
|
"id": "manual:consumer-issue-reporting",
|
|
@@ -1439,7 +1439,7 @@
|
|
|
1439
1439
|
],
|
|
1440
1440
|
"maturity": "stable",
|
|
1441
1441
|
"sourcePath": "docs/publication-artifacts.md",
|
|
1442
|
-
"digest": "sha256:
|
|
1442
|
+
"digest": "sha256:bbe9aab15731a9145cacad8a9795c24a86a56fcdbf8cbf8ad3e9b5d4b6e57dba",
|
|
1443
1443
|
"headings": [
|
|
1444
1444
|
{
|
|
1445
1445
|
"level": 1,
|
|
@@ -1476,13 +1476,18 @@
|
|
|
1476
1476
|
"title": "Unified paper operator surface",
|
|
1477
1477
|
"anchor": "unified-paper-operator-surface"
|
|
1478
1478
|
},
|
|
1479
|
+
{
|
|
1480
|
+
"level": 1,
|
|
1481
|
+
"title": "edit, test, and commit paper source",
|
|
1482
|
+
"anchor": "edit-test-and-commit-paper-source"
|
|
1483
|
+
},
|
|
1479
1484
|
{
|
|
1480
1485
|
"level": 2,
|
|
1481
1486
|
"title": "Site Consumption",
|
|
1482
1487
|
"anchor": "site-consumption"
|
|
1483
1488
|
}
|
|
1484
1489
|
],
|
|
1485
|
-
"markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n prefix such as\n `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reproducibility Gate\n\nAlpha and release admission require\n`.buildchain/publication/reproducibility-receipt.json`. Buildchain creates the\nreceipt by cloning the exact checked-out Git commit into two independent local\nrepositories, assigning each build a separate home and npm cache, and deriving\n`SOURCE_DATE_EPOCH` from the source commit. A pinned `latex-docker` build runs\nwith UTC, `C.UTF-8`, no build-time network, and the exact image digest declared\nin `[publication.toolchain]`.\n\nEach clean build independently creates the PDF set, source bundle, publication\nmanifest and passport, append-only registry, synthesized npm package directory,\nand an actual npm tarball. After qualification, Buildchain copies the first\nqualifying tarball into the promoted publication candidate instead of deleting\nit with the temporary clean build. The receipt compares exact bytes and records:\n\n- source repository, commit, tree, and `SOURCE_DATE_EPOCH`;\n- toolchain image, digest, command, and toolchain identity root;\n- every artifact and evidence path with byte size and SHA-256;\n- npm tarball SHA-256, SHA-1 shasum, and `sha512` integrity;\n- per-build output-set roots and the first differing field or artifact.\n\nThe gate is fail-closed. A build-only `custom-command` run can diagnose byte\ndrift and promote its byte-identical local output with\n`--allow-unpinned-toolchain`, but it is never a qualifying publication receipt.\nAny workflow that prepares a publishable paper package accepts only a\ndigest-pinned toolchain and promotes the first clean build into the publication\ncandidate only after both builds are byte-identical. The receipt remains\noutside the npm tarball to avoid a circular digest; it binds the tarball bytes\nfrom the surrounding sealed publication evidence.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n publication:\n uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3\n with:\n toolchain-type: config\n verify-command: make check\n artifact-name: observer-declared-timelines\n buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n workflow inputs;\n- hydrates authenticated registry history before building so both clean\n candidates include the same append-only history;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n runs two independent clean builds with the reproducibility policy above;\n- for `custom-command`, runs the declared command and records the lower-trust\n boundary in the passport, but refuses publication qualification;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- writes a qualifying\n `.buildchain/publication/reproducibility-receipt.json`;\n- when `[publication.archive]` is configured, writes\n `.buildchain/publication/publication-registry.json` and verifies same-version\n immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n push:\n branches:\n - alpha/v1/v1.0\n - release/v1/v1.0\n workflow_dispatch:\n\njobs:\n paper-release:\n uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>\n permissions:\n actions: read\n checks: write\n contents: read\n id-token: write\n issues: write\n with:\n buildchain-ref: <exact-buildchain-sha>\n publisher-workflow-path: .github/workflows/paper-release.yml\n toolchain-type: config\n verify-command: make check\n artifact-paths: _build/paper-name.pdf\n buildchain-contract-lock-path: .buildchain/contract-lock.json\n secrets:\n BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}\n BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}\n BUILDCHAIN_GENERATED_WRITE_TOKEN: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}\n```\n\nThe sealed preset does not use a long-lived token for npm publication. It\nprefers a repository-scoped GitHub App installation token for generated\nrepository writes and accepts `BUILDCHAIN_GENERATED_WRITE_TOKEN` as an\nequivalent narrow compatibility authority. The deprecated\n`BUILDCHAIN_PROMOTION_TOKEN` name remains accepted for existing consumers, but\nthere is no `github.token` fallback for generated writes. npm publication\nremains bound to GitHub OIDC trusted publishing. The preset builds and packages the\npaper in a read-only job, then a credential-free authority job downloads that\nexact candidate, audits the external control plane, and seals a capability over\nthe source tree, Buildchain runtime, controller receipt, PDF, and npm package\nbytes. Only the final job receives write and OIDC permissions; it downloads the\nadmitted candidate, recomputes the capability binding, and publishes without\nexecuting consumer build commands. npm binds the OIDC identity to the consumer\nworkflow named by `publisher-workflow-path`.\n\nThe preset:\n\n- uses the exact Buildchain SHA admitted by the provisioning authority and\n binds it into the caller bytes, contract lock, publication candidate, and\n authority capability;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n command in a read-only job;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n channel commit and requires `promote-buildchain-ref` to verify that lock\n before any publish side effect;\n- verifies the complete candidate again after authority and publishes the\n package through npm Trusted Publishing without rebuilding or repacking it;\n- writes a typed sealed-bundle manifest that binds the candidate root, exact\n npm tarball, every GitHub Release asset, durable storage path, and resume\n command;\n- persists the complete binary bundle to the transaction's durable release-state\n ref before npm receives credentials, allowing an empty runner to restore and\n verify the same bytes after interruption;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n every file declared by `publication.primary_artifact` and\n `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nThe transaction exposes a stable publication progression:\n\n```text\nprepared -> sealed -> package-published -> alpha-complete\n```\n\nStable publication ends at `release-complete`. If a run stops after npm but\nbefore GitHub Release completion, the next run starts from\n`package-published`, restores the sealed PDF and companion assets, and finishes\nthe release without invoking the paper build or `npm pack` again.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\n### Unified paper operator surface\n\nThe `buildchain paper` command family assembles the existing publication\nprimitives into a resumable operator flow:\n\n```text\nscaffold/new or migrate/existing -> preflight -> bootstrap npm -> build -> alpha -> status -> resume\n```\n\nEach command emits a typed JSON envelope with `--json`. Dry-run is the default\nfor every external mutation. `scaffold --write` is limited to no-overwrite\nlocal file creation. `migrate --write` is limited to the Buildchain-owned\ncontract lock, version pin, thin workflows, and provisioning authority; paper\ncontent and publication configuration are preserved. `bootstrap npm --execute`, `alpha --execute`, and\n`resume --execute` cross external authority boundaries and therefore require\nexplicit execution.\n\nThe evidence model is intentionally non-inferential:\n\n| State | Required evidence |\n| -------------------- | -------------------------------------------------------- |\n| `scaffolded` | Complete managed scaffold inventory |\n| `governed` | Compatible Buildchain contract lock |\n| `admitted` | Repository admission receipt |\n| `bootstrapped` | Successful public npm bootstrap receipt or registry fact |\n| `trust-bound` | Trusted publisher binding receipt |\n| `content-ready` | Declared source paths present |\n| `artifact-sealed` | Verified sealed publication bundle |\n| `package-published` | Exact package version visible in npm |\n| `alpha-complete` | Protected Alpha PR completion evidence |\n| `staging-visible` | Staging route evidence |\n| `production-visible` | Production route evidence |\n\n`paper status` reports `satisfied`, `not-reached`, `blocked`, or `unknown` for\neach state. It does not promote a state merely because a prior state is\ncomplete. This makes a later `paper resume` safe: the command dispatches the\nthin repository release workflow, while the workflow re-verifies durable\nevidence and remains the publication authority.\n\nOperationally, responsibility remains split:\n\n- the paper repository owns content, declared metadata, and its thin\n build/release workflow;\n- Buildchain owns scaffold shape, evidence contracts, reproducibility, sealed\n bundle mechanics, npm transaction mechanics, and resumption planning;\n- GitHub branch protection and trusted publishing own authority transitions;\n- the papers site consumes publication evidence and owns reader-facing\n rendering.\n\nRun a local readiness check without network observations:\n\n```sh\nbuildchain paper preflight --offline --json\nbuildchain paper status --json\n```\n\nBefore real npm bootstrap, first inspect the default dry-run result:\n\n```sh\nbuildchain paper bootstrap npm --json\n```\n\nOnly after reviewing the package, repository, workflow, and dry-run evidence:\n\n```sh\nbuildchain paper bootstrap npm \\\n --execute \\\n --confirm-public-package @kungfu-tech/paper-example \\\n --json\n```\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nProve the complete candidate from two clean builds:\n\n```sh\nbuildchain publication-artifact reproducibility \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --promote \\\n --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n collectPublicationArtifact,\n writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n collectPublicationPackageFacts,\n preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nimport {\n createPublicationSealedBundle,\n verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
|
|
1490
|
+
"markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n prefix such as\n `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reproducibility Gate\n\nAlpha and release admission require\n`.buildchain/publication/reproducibility-receipt.json`. Buildchain creates the\nreceipt by cloning the exact checked-out Git commit into two independent local\nrepositories, assigning each build a separate home and npm cache, and deriving\n`SOURCE_DATE_EPOCH` from the source commit. A pinned `latex-docker` build runs\nwith UTC, `C.UTF-8`, no build-time network, and the exact image digest declared\nin `[publication.toolchain]`.\n\nEach clean build independently creates the PDF set, source bundle, publication\nmanifest and passport, append-only registry, synthesized npm package directory,\nand an actual npm tarball. After qualification, Buildchain copies the first\nqualifying tarball into the promoted publication candidate instead of deleting\nit with the temporary clean build. The receipt compares exact bytes and records:\n\n- source repository, commit, tree, and `SOURCE_DATE_EPOCH`;\n- toolchain image, digest, command, and toolchain identity root;\n- every artifact and evidence path with byte size and SHA-256;\n- npm tarball SHA-256, SHA-1 shasum, and `sha512` integrity;\n- per-build output-set roots and the first differing field or artifact.\n\nThe gate is fail-closed. A build-only `custom-command` run can diagnose byte\ndrift and promote its byte-identical local output with\n`--allow-unpinned-toolchain`, but it is never a qualifying publication receipt.\nAny workflow that prepares a publishable paper package accepts only a\ndigest-pinned toolchain and promotes the first clean build into the publication\ncandidate only after both builds are byte-identical. The receipt remains\noutside the npm tarball to avoid a circular digest; it binds the tarball bytes\nfrom the surrounding sealed publication evidence.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n publication:\n uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3\n with:\n toolchain-type: config\n verify-command: make check\n artifact-name: observer-declared-timelines\n buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n workflow inputs;\n- hydrates authenticated registry history before building so both clean\n candidates include the same append-only history;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n runs two independent clean builds with the reproducibility policy above;\n- for `custom-command`, runs the declared command and records the lower-trust\n boundary in the passport, but refuses publication qualification;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- writes a qualifying\n `.buildchain/publication/reproducibility-receipt.json`;\n- when `[publication.archive]` is configured, writes\n `.buildchain/publication/publication-registry.json` and verifies same-version\n immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n push:\n branches:\n - alpha/v1/v1.0\n - release/v1/v1.0\n workflow_dispatch:\n\njobs:\n paper-release:\n uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>\n permissions:\n actions: read\n checks: write\n contents: read\n id-token: write\n issues: write\n with:\n buildchain-ref: <exact-buildchain-sha>\n publisher-workflow-path: .github/workflows/paper-release.yml\n toolchain-type: config\n verify-command: make check\n artifact-paths: _build/paper-name.pdf\n buildchain-contract-lock-path: .buildchain/contract-lock.json\n secrets:\n BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}\n BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}\n BUILDCHAIN_GENERATED_WRITE_TOKEN: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}\n```\n\nThe sealed preset does not use a long-lived token for npm publication. It\nprefers a repository-scoped GitHub App installation token for generated\nrepository writes and accepts `BUILDCHAIN_GENERATED_WRITE_TOKEN` as an\nequivalent narrow compatibility authority. The deprecated\n`BUILDCHAIN_PROMOTION_TOKEN` name remains accepted for existing consumers, but\nthere is no `github.token` fallback for generated writes. npm publication\nremains bound to GitHub OIDC trusted publishing. The preset builds and packages the\npaper in a read-only job, then a credential-free authority job downloads that\nexact candidate, audits the external control plane, and seals a capability over\nthe source tree, Buildchain runtime, controller receipt, PDF, and npm package\nbytes. Only the final job receives write and OIDC permissions; it downloads the\nadmitted candidate, recomputes the capability binding, and publishes without\nexecuting consumer build commands. npm binds the OIDC identity to the consumer\nworkflow named by `publisher-workflow-path`.\n\nThe preset:\n\n- uses the exact Buildchain SHA admitted by the provisioning authority and\n binds it into the caller bytes, contract lock, publication candidate, and\n authority capability;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n command in a read-only job;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n channel commit and requires `promote-buildchain-ref` to verify that lock\n before any publish side effect;\n- verifies the complete candidate again after authority and publishes the\n package through npm Trusted Publishing without rebuilding or repacking it;\n- writes a typed sealed-bundle manifest that binds the candidate root, exact\n npm tarball, every GitHub Release asset, durable storage path, and resume\n command;\n- persists the complete binary bundle to the transaction's durable release-state\n ref before npm receives credentials, allowing an empty runner to restore and\n verify the same bytes after interruption;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n every file declared by `publication.primary_artifact` and\n `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nThe transaction exposes a stable publication progression:\n\n```text\nprepared -> sealed -> package-published -> alpha-complete\n```\n\nStable publication ends at `release-complete`. If a run stops after npm but\nbefore GitHub Release completion, the next run starts from\n`package-published`, restores the sealed PDF and companion assets, and finishes\nthe release without invoking the paper build or `npm pack` again.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\n### Unified paper operator surface\n\nThe `buildchain paper` command family assembles the existing publication\nprimitives into a resumable operator flow:\n\n```text\nscaffold/new or migrate/existing -> preflight -> bootstrap npm -> build -> alpha -> status -> resume\n```\n\nEach command emits a typed JSON envelope with `--json`. Dry-run is the default\nfor every external mutation. `scaffold --write` is limited to no-overwrite\nlocal file creation. `migrate --write` is limited to the Buildchain-owned\ncontract lock, version pin, thin workflows, and provisioning authority; paper\ncontent and publication configuration are preserved. `bootstrap npm --execute`, `alpha --execute`, and\n`resume --execute` cross external authority boundaries and therefore require\nexplicit execution.\n\nThe evidence model is intentionally non-inferential:\n\n| State | Required evidence |\n| -------------------- | -------------------------------------------------------- |\n| `scaffolded` | Complete managed scaffold inventory |\n| `governed` | Compatible Buildchain contract lock |\n| `admitted` | Repository admission receipt |\n| `bootstrapped` | Successful public npm bootstrap receipt or registry fact |\n| `trust-bound` | Trusted publisher binding receipt |\n| `content-ready` | Declared source paths present |\n| `artifact-sealed` | Verified sealed publication bundle |\n| `package-published` | Exact package version visible in npm |\n| `alpha-complete` | Protected Alpha PR completion evidence |\n| `staging-visible` | Staging route evidence |\n| `production-visible` | Production route evidence |\n\n`paper status` reports `satisfied`, `not-reached`, `blocked`, or `unknown` for\neach state. It does not promote a state merely because a prior state is\ncomplete. This makes a later `paper resume` safe: the command dispatches the\nthin repository release workflow, while the workflow re-verifies durable\nevidence and remains the publication authority.\n\nOperationally, responsibility remains split:\n\n- the paper repository owns content, declared metadata, and its thin\n build/release workflow;\n- Buildchain owns scaffold shape, evidence contracts, reproducibility, sealed\n bundle mechanics, npm transaction mechanics, and resumption planning;\n- GitHub branch protection and trusted publishing own authority transitions;\n- the papers site consumes publication evidence and owns reader-facing\n rendering.\n\nDaily work begins and ends through the repository-pinned v3 CLI:\n\n```sh\npnpm paper:work:start -- golden-path\n# edit, test, and commit paper source\npnpm paper:work:submit\n```\n\nThe start plan derives `dev/vN/vN.M` from `publication.version` and requires\nlocal HEAD to equal the exact canonical remote development SHA. The submit plan\nallows only a non-protected work branch containing that SHA, a clean committed\ntree, a normal fast-forward push, and a pull request back to the same derived\ndevelopment branch. Neither command force-pushes, guesses a fork target, or\nsilently fetches and merges stale state.\n\nMaintainers can inspect a sibling fleet without per-repository command copies:\n\n```sh\nbuildchain paper fleet audit --root /path/to/papers --json\nbuildchain paper fleet update --root /path/to/isolated-paper-worktrees --json\n```\n\nFleet update is dry-run first and accepts only isolated work branches. Its\ntyped plan carries exact-old and expected-new digests for the same owned\nsurfaces as `paper migrate`; `--write` also refreshes each pnpm lockfile. It\nnever rewrites paper content or publication configuration.\n\nRun a local readiness check without network observations:\n\n```sh\nbuildchain paper preflight --offline --json\nbuildchain paper status --json\n```\n\nBefore real npm bootstrap, first inspect the default dry-run result:\n\n```sh\nbuildchain paper bootstrap npm --json\n```\n\nOnly after reviewing the package, repository, workflow, and dry-run evidence:\n\n```sh\nbuildchain paper bootstrap npm \\\n --execute \\\n --confirm-public-package @kungfu-tech/paper-example \\\n --json\n```\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nProve the complete candidate from two clean builds:\n\n```sh\nbuildchain publication-artifact reproducibility \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --promote \\\n --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n collectPublicationArtifact,\n writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n collectPublicationPackageFacts,\n preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nimport {\n createPublicationSealedBundle,\n verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
|
|
1486
1491
|
},
|
|
1487
1492
|
{
|
|
1488
1493
|
"id": "manual:publication-authority",
|
|
@@ -2859,7 +2864,7 @@
|
|
|
2859
2864
|
"homepagePriority": 20,
|
|
2860
2865
|
"defaultPresentation": "workflow-surface-list",
|
|
2861
2866
|
"includeInFirstScreen": true,
|
|
2862
|
-
"markdown": "Bootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\
|
|
2867
|
+
"markdown": "Bootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\npnpm add -D @kungfu-tech/buildchain@<exact-v3-version>\npnpm exec buildchain paper work start <topic>\npnpm exec buildchain paper work submit\npnpm exec buildchain paper preflight --offline\npnpm exec buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files. `work start` and `work submit` validate the canonical remote,\nexact development SHA, clean source, safe branch, and fast-forward boundary\nbefore changing local or GitHub state. External mutations such as npm\nbootstrap, Alpha PR creation, and release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains six active entries. Four are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer list from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n planning, capability-aware runner dispatch, receipt validation, and one\n stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n qualification, transcript-bound renderer smoke, optional media rendering\n from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n promote-only publication from a PR-stage release candidate, without a second\n heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```"
|
|
2863
2868
|
},
|
|
2864
2869
|
{
|
|
2865
2870
|
"id": "release-model",
|
|
@@ -3100,7 +3105,7 @@
|
|
|
3100
3105
|
"path": "docs/cli.md",
|
|
3101
3106
|
"plane": "use",
|
|
3102
3107
|
"exists": true,
|
|
3103
|
-
"digest": "sha256:
|
|
3108
|
+
"digest": "sha256:9afe80ef29fb5cce140ffc7980c41172495878726e5504e47914b8dc7af8fc1f"
|
|
3104
3109
|
},
|
|
3105
3110
|
{
|
|
3106
3111
|
"id": "build-facts",
|