@kungfu-tech/buildchain 2.3.1-alpha.0 → 2.3.1-alpha.1

package/docs/cli.md

@@ -27,6 +27,14 @@ pnpm add -D @kungfu-tech/buildchain
 pnpm exec buildchain validate
 ```
 
+Consumers should pin the exact Buildchain version that was validated in their
+repository. When dogfooding a fresh Buildchain release immediately after it is
+published, pnpm may block the install through a minimum release-age policy. In
+that case, add a temporary package/version-specific `minimumReleaseAgeExclude`
+entry, such as `@kungfu-tech/buildchain@2.2.5`, and remove it once the package
+has aged past the normal policy window. Do not replace that with a broad
+registry or scope-wide exclude.
+
 Use the package API directly inside JavaScript build scripts:
 
 ```js
@@ -56,6 +64,10 @@ Supported presets:
 - `--type anchored-package` for packages whose version is anchored to an
   explicit upstream release manifest.
 
+The native preset includes an opt-in `[diagnostics.native]` profile with common
+tool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and
+directory lists, or disable it if a repository does not need native diagnostics.
+
 `buildchain validate` parses `buildchain.toml`, checks configured version-state
 files, and can require named lifecycle stages:
 
@@ -92,6 +104,8 @@ buildchain span --event native.build --phase build -- cmake --build build
 buildchain log warn --event cache.miss --component conan --attribute token=hidden
 buildchain log summary --json
 buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
+buildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json
+buildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20
 ```
 
 During `buildchain lifecycle run`, child processes receive
@@ -116,6 +130,61 @@ Secret-looking attribute keys such as `token`, `password`, `secret`,
 Full command strings are not recorded by `span`; scripts should provide stable
 event names and safe attributes instead.
 
+`buildchain diagnostics summary` reads one or more small diagnostics artifacts
+and emits the same cross-platform summary as the diagnostics SDK:
+
+```bash
+buildchain diagnostics summary \
+  .buildchain/artifacts/linux-x64/diagnostics.json \
+  .buildchain/artifacts/macos-arm64/diagnostics.json \
+  --output .buildchain/artifacts/diagnostics-summary.json \
+  --json
+```
+
+The JSON summary keeps per-platform lifecycle stage tables, adds lifecycle
+total durations, carries top slow spans, aggregates warning/error counts, and
+sorts the slowest platforms. Each platform row carries compact runner facts,
+checked tool versions/missing tools, package manager/cache directory details,
+compiler-cache availability, and a compact process sampler summary: requested
+parallelism, observed max active processes, the ratio between them, sample
+count, process categories, and the top sampled command basenames. This lets
+maintainers inspect matrix timing, runner, tool, cache, and concurrency context
+without downloading large platform binaries or process sidecars first.
+When a sibling `diagnostics-manifest.json` is available, the summary also records
+its file list and verifies the listed `diagnostics.json` byte count and sha256.
+Missing, unreadable, or mismatched sidecar manifests are reported through
+`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`
+field without failing the timing rollup.
+The summary also compares each `diagnostics.json` contract to
+`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through
+`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`
+field so reviewers can separate diagnostics schema drift from lifecycle
+warnings or build failures.
+
+Without `--json`, the command prints a compact lifecycle timing table with
+install/build/verify/publish, artifact scan/upload, total, warning, and error
+columns for each platform, plus `jobs` and `active` columns for requested and
+observed process concurrency when sampler data is present.
+
+`buildchain sample process-tree` wraps a long-running command and periodically
+writes process-tree snapshots:
+
+```bash
+buildchain sample process-tree \
+  --label native-build \
+  --interval-ms 15000 \
+  --output .buildchain/diagnostics/process-samples.jsonl \
+  --summary-output .buildchain/diagnostics/process-summary.json \
+  -- \
+  make -j20
+```
+
+The command returns the wrapped command's exit status. The JSONL file contains
+small timestamped samples; the summary JSON records requested parallelism,
+observed concurrency, sampled CPU, command categories, and top command
+basenames. Use it when a native build requests high parallelism but appears to
+spend long stretches in low-concurrency compile, archive, link, or cache steps.
+
 `buildchain doctor` checks repository readiness before remote side effects:
 
 ```bash
@@ -123,8 +192,27 @@ buildchain doctor --json
 ```
 
 It validates `buildchain.toml`, package-manager detection, Git repository state,
-and the reusable workflow caller. The JSON result is shaped for future
-`buildchain.libkungfu.dev` fact ingestion.
+and the reusable workflow caller. For `version.strategy = "anchored"` with
+`version.next = "manual"`, it also embeds the anchored package release contract
+check: anchor manifest readability, configured version files, trusted
+publishing, package publish order, and required lifecycle stages. Add
+`--require-publish-source-lock` inside a publish job when the doctor report
+should also fail unless the job is running from a resolved `publish-gate/*`
+source lock.
+
+Anchored/manual package publish jobs can run the narrower source-lock gate
+directly:
+
+```bash
+buildchain publish-source validate-anchored-release --json
+```
+
+The command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,
+`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the
+reusable build workflow outputs. It fails closed for direct `alpha/*` or
+`release/*` channel-branch publication, and checks the publish-gate consumer
+version against configured version files and the anchor manifest. The JSON
+result is shaped for future `buildchain.libkungfu.dev` fact ingestion.
 
 `buildchain release`, `buildchain web-surface`, `buildchain publish-source`,
 and `buildchain build-contract` route to the same scripts used by Buildchain's
@@ -148,6 +236,41 @@ and `llms.txt`. Production binary distribution defaults to GitHub-hosted
 runners so other projects can reproduce the release lane; self-hosted runners
 remain compatibility fixtures and are recorded as runner facts when used.
 
+For publish-transaction releases, pass the additional evidence inputs so
+`buildchain.release.json` becomes the unified passport instead of a binary-only
+asset summary:
+
+```bash
+buildchain collect github-release \
+  --tag v2.3.2 \
+  --repository kungfu-systems/buildchain \
+  --assets-dir dist \
+  --publish-evidence-json .buildchain/release-evidence/v2.3.2/evidence.json \
+  --transaction-json .buildchain/release-state/v2.3.2/state.json \
+  --package-set-json package-set.json \
+  --trusted-publishing-json trusted-publishing.json \
+  --anchor-manifest-json libnode.release.json \
+  --build-summary-json .buildchain/artifacts/build-summary.json \
+  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \
+  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
+  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
+  --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \
+  --release-extra-json '{"channel":"release","targetRef":"release/v2/v2.3"}' \
+  --output-dir .buildchain/release-passport
+```
+
+The generated passport records the main and platform packages, npm dist-tags,
+published versions, release source/ref state, anchor manifest digest, registry
+artifact digests, trusted publishing evidence, and Buildchain transaction
+result. It also records `buildSummary`, `platformArtifactManifests`, and
+`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the
+ordered package set; `publish.packages[]` is the agent-readable npm publication
+summary for each main/platform package. For Buildchain releases, verification
+expects the supplied package set to include the main package plus the three
+platform packages with version, dist-tag, and digest evidence. Verification
+fails closed if supplied sections are internally incomplete or point to
+artifacts without matching evidence.
+
 Buildchain dogfoods its observability toolkit in this lane. The standalone
 builder writes API-generated events, while the workflow uses `buildchain mark`,
 `buildchain span`, `buildchain verify observability-log`, and `buildchain log

package/docs/install.md

@@ -54,6 +54,31 @@ npx buildchain doctor --json
 Alpha releases publish to the `alpha` npm dist-tag. Stable releases publish to
 `latest`. Both are created by the protected Buildchain promotion transaction.
 
+Stable consumers should pin the exact Buildchain version they have validated,
+for example:
+
+```bash
+pnpm add -D @kungfu-tech/buildchain@2.2.5
+```
+
+If a repository dogfoods a just-published Buildchain version and pnpm's release
+age policy blocks the install, use a temporary package/version-specific
+`minimumReleaseAgeExclude` entry instead of weakening the registry policy for
+all packages:
+
+```json
+{
+  "pnpm": {
+    "minimumReleaseAgeExclude": [
+      "@kungfu-tech/buildchain@2.2.5"
+    ]
+  }
+}
+```
+
+Remove that entry after the package is old enough for the repository's normal
+policy. Do not use a broad exclude such as `@kungfu-tech/*` for this case.
+
 ## Repository Integration
 
 ```bash
@@ -75,4 +100,3 @@ buildchain explain release --passport buildchain.release.json --for agent --json
 
 The verifier fails closed when the passport or its sibling evidence files are
 missing required fields or mismatching artifact digests.
-

package/docs/publish-transaction.md

@@ -150,6 +150,14 @@ For package sets, `package_set_order = "platforms-first-main-last"` makes the
 main package the visibility gate. Platform package side effects are planned or
 retried first, and the main package or main dist-tag move happens last.
 
+When the transaction reaches `complete`, `actions/promote-buildchain-ref`
+generates `.buildchain/release-passport/buildchain.release.json` and persists
+the `release-passport/*` files into the durable `buildchain/release-state/...`
+ref. The passport is the stable release artifact for agents and people: it
+links the package set, npm publish evidence, dist-tag evidence, build summary,
+platform artifact manifests, trusted publishing metadata, release-state ref,
+and transaction result in one schema.
+
 ## Evidence
 
 The publish lifecycle must write JSON evidence. Buildchain validates common
@@ -188,6 +196,8 @@ The generic contract is intentionally small:
 
 - `version`, `channel`, `source_sha`, `release_sha`, and `target_ref` must match
   the promotion run;
+- dist-tag promotion evidence is written beside the publish evidence as
+  `dist-tag-evidence.json` and is referenced from the generated passport;
 - required artifacts must appear in evidence;
 - evidence used by a GitHub-hosted rerun must either be stored in the durable
   state ref or be reconstructed by a machine-verifiable consumer command;

package/docs/release-passport.md

@@ -27,6 +27,25 @@ P0 protocol artifacts:
 
 `buildchain.release.json` is the first file an agent should read. It points to
 artifact evidence, impact, recovery, product mechanism, and agent index facts.
+It is also the unified release responsibility summary: when publish
+transactions are used, the same passport records the package set, npm dist-tags,
+release source refs, release-state ref, anchor manifest, registry artifact
+digests, trusted publishing evidence, and transaction result.
+
+Additive passport sections:
+
+- `release`: exact tag, line, channel, source SHA, target ref, release SHA,
+  release material SHA, publish tooling SHA, and durable release-state ref.
+- `packageSet`: main package, platform packages, package-set order, registry,
+  versions, dist-tags, and package digests.
+- `anchorManifest`: anchored/manual version manifest path, digest, and fields.
+- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether
+  trusted publishing was enabled.
+- `transaction`: durable Buildchain release transaction id, state, exact tag,
+  release SHA, state ref, and state SHA.
+- `artifacts`: release assets and registry artifacts in one list, each pointing
+  back to the evidence file that proves its digest.
+
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:
 
@@ -65,9 +84,25 @@ buildchain collect github-release \
   --tag v2.2.0 \
   --repository kungfu-systems/buildchain \
   --assets-dir dist \
+  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \
+  --transaction-json .buildchain/release-state/v2.2.0/state.json \
+  --package-set-json package-set.json \
+  --anchor-manifest-json libnode.release.json \
+  --build-summary-json .buildchain/artifacts/build-summary.json \
+  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \
+  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
+  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
+  --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \
   --output-dir .buildchain/release-passport
 ```
 
+`packageSet` records the ordered main-plus-platform package set.
+`publish.packages[]` summarizes each published npm package with its version,
+dist-tag, registry, role, platform, and digest, so agents do not need to stitch
+npm facts back together from the lower-level evidence files.
+`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the
+build and npm dist-tag evidence chain in the same passport.
+
 Verify a release passport:
 
 ```bash

package/docs/reusable-build-surface.md

@@ -24,6 +24,7 @@ jobs:
         build/stage
       expected-artifacts-json: >-
         {"minFiles":2,"requiredPaths":["dist/libnode.tar.gz","dist/checksums.txt"]}
+      process-summary-path: .buildchain/diagnostics/process-summary.json
       publish-channel: release
       publish-source-ref: publish-gate/release/v22/v22.22/22.22.3-kf.0
 ```
@@ -108,6 +109,74 @@ Do not use `kungfu-verify` for stages that need CMake, Ninja, ccache, Conan, or
 Docker image publishing. Those should use a heavier native-build image or remain
 on a host runner until their image contract is explicit.
 
+## Buildchain Runtime Override
+
+Stable consumers should keep the reusable workflow pinned to stable refs such as
+`@v2`. The optional `buildchain-ref` input is empty by default; empty means
+Buildchain resolves and executes the stable runtime selected by the workflow
+shell. The full train validation protocol is documented in
+[`runtime-train-validation.md`](runtime-train-validation.md).
+
+For one-off manual validation, a trusted maintainer can run the caller workflow
+with a temporary runtime override:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      buildchain-ref:
+        description: "Temporary Buildchain runtime ref for trusted manual validation"
+        required: false
+        default: ""
+
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    with:
+      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
+```
+
+Allowed override refs are deliberately narrow:
+
+| Ref form | Meaning |
+| --- | --- |
+| `train/v2/v2.3/<capability>` | Temporary capability train under the active minor line |
+| `refs/heads/train/v2/v2.3/<capability>` | Explicit branch ref for the same train |
+| `<40-character SHA>` | Exact immutable Buildchain runtime commit |
+
+Override requests fail closed unless the event is `workflow_dispatch` and the
+actor has write, maintain, or admin permission on the caller repository.
+Pull requests, including same-repository pull requests and fork-originated pull
+requests, cannot use `buildchain-ref` override. This keeps automated PR builds on
+the stable runtime surface.
+
+Every run resolves the runtime ref to an immutable SHA before checkout. The job
+summary and aggregate build summary record the workflow shell ref, requested
+runtime ref, resolved runtime ref, runtime SHA, stability class, trust decision,
+and rollback ref. Train refs are development validation refs: they do not move
+`v2`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they
+must not be pinned as long-term production dependencies.
+
+Runtime override validates Buildchain runtime scripts, CLI code, local actions,
+config parsing, and lifecycle behavior. It cannot validate changes that require
+the outer reusable workflow YAML itself to change, such as new jobs,
+permissions, workflow outputs, or matrix topology. Those changes need a canary
+workflow path or a temporary explicit workflow ref.
+
+When a Buildchain maintainer asks for downstream validation, the expected
+request is:
+
+```text
+Buildchain train ready: buildchain-ref=train/v2/v2.3/<capability>.
+Keep uses: ...@v2; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
+```
+
+After validation succeeds, the Buildchain change should continue through the
+normal mainline and release path. Do not treat the train as a pending merge
+item; it is only a temporary fast-use, diagnostic, and rollback channel. It may
+remain for a retention window after release, with old trains handled by a
+separate periodic cleanup task.
+
 ## Workflow Outputs
 
 The reusable workflow exposes the resolved contract:
@@ -120,8 +189,15 @@ The reusable workflow exposes the resolved contract:
 | `linux-container-enabled`         | `true` when Linux platforms are routed through a job container                  |
 | `linux-container-image`           | Resolved digest-pinned Linux job container image                                |
 | `build-summary-artifact`          | Uploaded aggregate summary artifact name                                        |
+| `build-diagnostics-summary-artifact` | Uploaded aggregate diagnostics summary artifact name                         |
 | `build-summary-json`              | Compact aggregate JSON with platform count, file count, and byte total          |
+| `build-diagnostics-summary-json`  | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |
 | `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |
+| `buildchain-runtime-ref`          | Runtime ref selected after applying the empty-default or override policy        |
+| `buildchain-runtime-sha`          | Immutable Buildchain runtime commit used by all runtime checkouts               |
+| `buildchain-runtime-class`        | `stable`, `alpha`, `train`, `exact-sha`, or `development`                       |
+| `buildchain-runtime-override`     | `true` when a non-empty `buildchain-ref` override was accepted                  |
+| `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |
 | `publish-channel`                 | Resolved publish channel requested by the caller                                |
 | `publish-allowed`                 | `true` only when this event/ref may publish after verification                  |
 | `publish-reason`                  | Human-readable reason for the publish gate decision                             |
@@ -133,10 +209,29 @@ The reusable workflow exposes the resolved contract:
 | `publish-source-consumer-version` | Consumer package version parsed from source refs                                |
 | `release-manifest-json`           | Resolved release manifest including source lock, version state, and anchor data |
 
-The aggregate summary is intentionally an artifact as well as an output. GitHub
+The aggregate summaries are intentionally artifacts as well as outputs. GitHub
 Actions matrix outputs are not a reliable place to carry every platform's full
 manifest, so Buildchain uploads each platform manifest and then emits one
-aggregate summary artifact after the matrix completes.
+aggregate build summary artifact after the matrix completes. Buildchain uploads
+`diagnostics-summary.json` as a separate aggregate diagnostics summary artifact,
+a compact rollup of each platform's small diagnostics upload. The rollup keeps
+per-platform runner facts, checked tool versions/missing tools, package
+manager/cache directory details, compiler-cache availability, lifecycle timing,
+process sampler context, and links back to the exact platform artifacts. Each
+platform diagnostics upload includes `diagnostics.json`,
+`diagnostics-manifest.json`, the lifecycle `events.jsonl`, and process sampler
+sidecars when enabled, so slow-build diagnosis does not require downloading the
+binary platform artifact or the aggregate build summary. The sidecar manifest
+records the uploaded diagnostics files with bytes and sha256 hashes. Each
+`diagnostics.json` also records the related binary artifact name, manifest
+artifact name, diagnostics artifact name, diagnostics sidecar manifest path, and
+platform id in `links`, so a reviewer can navigate from the small diagnostics
+artifact back to the exact platform outputs when deeper inspection is needed.
+The workflow output `build-diagnostics-summary-json` includes
+`diagnosticsContractWarningCount` and `diagnosticsManifestWarningCount` so
+release jobs can detect drifting diagnostics JSON contracts and missing or
+drifting diagnostics sidecar manifests without downloading the per-platform
+diagnostics artifacts first.
 
 ## Publish Gate
 
@@ -240,6 +335,38 @@ If the branch tip no longer matches the manifest SHA, the publish job must fail
 closed. Moving a gate branch creates a new publish decision and should produce a
 new build run.
 
+Anchored/manual package release jobs should also make the Buildchain promotion
+action validate that publication is entering through the same
+`publish-gate/{alpha,release,major}` source-lock contract before any package
+publish side effect:
+
+```yaml
+- name: Promote release ref and publish npm package set
+  uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  with:
+    sha: ${{ needs.build.outputs.publish-source-sha }}
+    target-ref: release/v22/v22.22
+    require-publish-source-lock: 'true'
+    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}
+    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}
+    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}
+```
+
+`target-ref` stays the Buildchain channel promotion target, such as
+`alpha/v22/v22.22`, `release/v22/v22.22`, or `publish-gate/major`.
+`publish-source-ref` is the reviewed source-lock branch that authorized this
+specific package publication. For alpha and release package publications, the
+source-lock branch must point at the exact channel-line commit that promotion is
+validating; it is not a replacement for `target-ref`.
+
+This keeps the version bump commit, publish authorization, and auditable publish
+entrypoint on the Buildchain source-lock protocol. The CLI form
+`buildchain publish-source validate-anchored-release --json` is still useful for
+custom publish scripts, but the preferred GitHub Actions gate is the promotion
+action input above. A publish job that still runs directly from `alpha/*` or
+`release/*` channel branches fails this check because those refs are channel
+state, not publish-gate decisions.
+
 ## Package-Set Publish Plan
 
 Projects that publish multiple packages should treat package publication as a
@@ -281,6 +408,28 @@ with:
   verify-command: ctest --test-dir build --output-on-failure
 ```
 
+The reusable build workflow samples the build lifecycle by default and carries
+the generated summary into the final verify diagnostics. Callers can override
+the sidecar path or disable sampling:
+
+```yaml
+with:
+  sample-process-tree: true
+  process-summary-path: .buildchain/diagnostics/process-summary.json
+  process-sample-interval-ms: 15000
+  requested-parallelism: 20
+```
+
+When `sample-process-tree` is true, Buildchain wraps either `build-command` or
+the configured `lifecycle.build` stage with `buildchain sample process-tree`.
+The path is relative to the checked-out workspace and is read again during the
+final verify lifecycle. Custom workflows can still write their own sampler
+summary and pass `process-summary-path`; Buildchain reads the file after the
+lifecycle command finishes, so it may be produced during the same invocation.
+When the build stage is optional, the reusable workflow treats the default
+sampler path as optional during verify; an explicitly supplied
+`process-summary-path` remains required.
+
 For custom workflows, use the action directly:
 
 ```yaml
@@ -400,7 +549,7 @@ the publish gate: pull requests remain non-publishing events.
 `fixtures/libnode-shaped` is the contract fixture. It has:
 
 - `package.json` version state;
-- `buildchain.toml` with `install`, `build`, and `verify`;
+- `buildchain.toml` with `install`, `build`, `verify`, and `publish`;
 - cross-platform Node scripts that create small `dist/` outputs;
 - `Build Surface Fixture` workflow coverage.