@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/docs/release-flow.md

@@ -1,6 +1,24 @@
+---
+status: active
+period: ongoing
+theme: buildchain-release-flow
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Release Flow Diagrams
 
-This document describes the Buildchain v2 branch, tag, and version-state flow.
+This document describes the Buildchain v3 branch, tag, and version-state flow.
 See [Release governance](release-governance.md) for the design rationale.
 
 ## Architecture
@@ -46,16 +64,16 @@ for the versioned policy and evidence contract.
 
 | Ref kind | Example | Mutability | Purpose |
 | --- | --- | --- | --- |
-| Development branch | `dev/v2/v2.0` | moves | next source state for a minor line |
-| Alpha branch | `alpha/v2/v2.0` | moves | latest test state for a minor line |
-| Release branch | `release/v2/v2.0` | moves | latest production state for a minor line |
+| Development branch | `dev/v3/v3.0` | moves | next source state for a minor line |
+| Alpha branch | `alpha/v3/v3.0` | moves | latest test state for a minor line |
+| Release branch | `release/v3/v3.0` | moves | latest production state for a minor line |
 | Major gate branch | `publish-gate/major` | moves | reviewed administrator gate for publishing the next major |
-| Exact alpha tag | `v2.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
-| Exact release tag | `v2.0.2` | immutable | audit ref for one production release |
-| Floating alpha tag | `v2.0-alpha` | moves | latest test channel for a minor line |
-| Floating major alpha tag | `v2-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
-| Floating minor tag | `v2.0` | moves | latest production patch on a minor line |
-| Floating major tag | `v2` | moves | selected stable major entrypoint |
+| Exact alpha tag | `v3.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
+| Exact release tag | `v3.0.2` | immutable | audit ref for one production release |
+| Floating alpha tag | `v3.0-alpha` | moves | latest test channel for a minor line |
+| Floating major alpha tag | `v3-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
+| Floating minor tag | `v3.0` | moves | latest production patch on a minor line |
+| Floating major tag | `v3` | moves | selected stable major entrypoint |
 
 ## Ref Protection Contract
 
@@ -69,16 +87,16 @@ refs/tags/v*.*.*
 ```
 
 Do not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain
-must be able to update floating channel tags such as `v2`, `v2.0`, `v2.0-alpha`,
-and `v2-alpha` after the exact tag and publish evidence are valid. A ruleset that
+must be able to update floating channel tags such as `v3`, `v3.0`, `v3.0-alpha`,
+and `v3-alpha` after the exact tag and publish evidence are valid. A ruleset that
 matches all `v*` tags also matches floating tags, so release finalization can
 fail with GitHub protected-ref errors even though the exact release tag and
 published artifacts are already durable.
 
 The intended governance split is:
 
-- exact tags such as `v2.0.14` and `v2.0.15-alpha.0` are immutable audit refs;
-- floating tags such as `v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` are mutable channel refs
+- exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;
+- floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
@@ -94,17 +112,17 @@ The workflow is backed by the CLI command:
 
 ```bash
 buildchain release line open \
-  --major 2 \
-  --minor 10 \
-  --source-ref release/v2/v2.9 \
+  --major 3 \
+  --minor 1 \
+  --source-ref release/v3/v3.0 \
   --json
 ```
 
 When the workflow is run with `apply=true`, Buildchain:
 
-- writes the initial version-state commit, such as `2.10.0-alpha.0`;
-- creates `dev/v2/v2.10` from that commit;
-- creates `alpha/v2/v2.10` and `release/v2/v2.10` from the selected source ref;
+- writes the initial version-state commit, such as `3.1.0-alpha.0`;
+- creates `dev/v3/v3.1` from that commit;
+- creates `alpha/v3/v3.1` and `release/v3/v3.1` from the selected source ref;
 - applies branch protection with one approving review and the configured
   required status check; dev starts strict, while alpha and release also require
   the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;
@@ -112,7 +130,7 @@ When the workflow is run with `apply=true`, Buildchain:
   the exact queue parameters and bypass actors from the current default dev
   branch when the policy is `inherit` or absent;
 - switches the repository default branch to the new dev line when requested;
-- opens the first `dev/v2/v2.10 -> alpha/v2/v2.10` channel PR when requested.
+- opens the first `dev/v3/v3.1 -> alpha/v3/v3.1` channel PR when requested.
 
 This makes minor-line creation a single audited operation. The channel PR still
 goes through the normal verify/review/promotion path before an alpha is
@@ -229,26 +247,26 @@ The same minor line can loop through this state machine many times.
 
 ## Version Examples
 
-Assume `v2.0.2-alpha.1` has been tested and a maintainer merges
-`alpha/v2/v2.0 -> release/v2/v2.0`.
+Assume `v3.0.2-alpha.1` has been tested and a maintainer merges
+`alpha/v3/v3.0 -> release/v3/v3.0`.
 
 Buildchain should produce:
 
 ```text
-v2.0.2                  exact production tag
-v2.0                    floating minor tag
-v2                      floating major tag when v2.0 is the selected major line
-release/v2/v2.0         production channel branch
+v3.0.2                  exact production tag
+v3.0                    floating minor tag
+v3                      floating major tag when v3.0 is the selected major line
+release/v3/v3.0         production channel branch
 ```
 
 It should also prepare:
 
 ```text
-v2.0.3-alpha.0          exact next alpha tag
-v2.0-alpha              floating alpha tag
-v2-alpha                floating major alpha tag when v2.0 is the highest published alpha minor
-alpha/v2/v2.0           alpha channel branch
-dev/v2/v2.0             development channel branch
+v3.0.3-alpha.0          exact next alpha tag
+v3.0-alpha              floating alpha tag
+v3-alpha                floating major alpha tag when v3.0 is the highest published alpha minor
+alpha/v3/v3.0           alpha channel branch
+dev/v3/v3.0             development channel branch
 ```
 
 This is expected behavior. A production release closes one patch and opens the

package/docs/release-governance.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-27
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -18,7 +18,7 @@ ai_provenance:
 
 # Release Governance
 
-Buildchain v2 preserves the release semantics of the older ABV workflow while
+Buildchain v3 preserves the release semantics of the older ABV workflow while
 moving the implementation into one modern repository.
 
 The central idea is simple: a reviewed merge into a release channel is the
@@ -37,9 +37,9 @@ Kungfu release automation has to keep four facts aligned:
 
 If any one of these facts is updated by hand, the system can split:
 
-- a consumer can fetch `v2.0` and receive a tree whose package version still
+- a consumer can fetch `v3.0` and receive a tree whose package version still
   says the previous release;
-- a maintainer can move `v2` without producing an exact `v2.0.N` audit tag;
+- a maintainer can move `v3` without producing an exact `v3.0.N` audit tag;
 - an alpha can be promoted to production even though the release tree is not the
   same tree that was tested;
 - a protected branch merge can succeed while the follow-up version commit is
@@ -70,7 +70,7 @@ repositories that usually meant changing `lerna.json` and/or `package.json`.
 That commit is important because the tag alone is not enough evidence: the
 source tree should also declare the version that the tag advertises.
 
-Buildchain v2 treats that as a hard semantic requirement for its own release
+Buildchain v3 treats that as a hard semantic requirement for its own release
 line.
 
 ## Buildchain Implementation
@@ -133,7 +133,7 @@ older Buildchain aggregate context, inspect the exact candidate SHA first:
 GH_TOKEN="$(gh auth token)" npx @kungfu-tech/buildchain@latest \
   release-governance reconcile \
   --repository kungfu-systems/example \
-  --branch release/v2/v2.14 \
+  --branch release/v3/v3.0 \
   --candidate-sha <tested-pr-head-sha> \
   --json
 ```
@@ -181,32 +181,32 @@ workflow preflight cannot receive a second set of publication side effects.
 ## Version Lines
 
 Kungfu uses Python-like version lines where a minor line can represent a
-long-lived product train. A line such as `v2.0` can produce many production
+long-lived product train. A line such as `v3.0` can produce many production
 patch releases:
 
 ```text
-v2.0.0
-v2.0.1
-v2.0.2
+v3.0.0
+v3.0.1
+v3.0.2
 ...
-v2.0.1234
+v3.0.1234
 ```
 
 This is why Buildchain maintains both exact and floating refs:
 
-- `v2.0.2` is immutable release evidence;
-- `v2.0` is the latest production release on the `2.0` line;
-- `v2` is the selected stable major-line entrypoint;
-- `v2.0.3-alpha.0` is immutable alpha evidence;
-- `v2.0-alpha` is the latest test channel for the `2.0` line.
-- `v3-alpha` is the latest test channel on the highest published alpha minor in major `2`.
+- `v3.0.2` is immutable release evidence;
+- `v3.0` is the latest production release on the `3.0` line;
+- `v3` is the selected stable major-line entrypoint;
+- `v3.0.3-alpha.0` is immutable alpha evidence;
+- `v3.0-alpha` is the latest test channel for the `3.0` line.
+- `v3-alpha` is the latest test channel on the highest published alpha minor in major `3`.
 
 A release does not mean "minor is complete." It means "this patch on this minor
 line is now production."
 
 GitHub repository rules must preserve that distinction. Exact tags such as
-`v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as
-`v2`, `v2.0`, `v2.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion
+`v3.0.2` and `v3.0.3-alpha.0` should be immutable. Floating channel tags such as
+`v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion
 token after governance checks and publish evidence pass. A tag ruleset that
 protects every `refs/tags/v*` ref is too broad because it also locks the
 floating channel tags that Buildchain is required to update. Prefer exact-tag
@@ -239,7 +239,7 @@ line-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`
 channel backward. Exact prerelease versions remain installable directly.
 
 This keeps the test channel self-describing. If a consumer checks out
-`v2.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major
+`v3.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major
 alpha ref removes routine consumer edits when Buildchain opens a newer minor,
 while exact tags and SHAs remain the reproducible audit choice.
 
@@ -248,7 +248,7 @@ while exact tags and SHAs remain the reproducible audit choice.
 Buildchain continuously consumes its own current major alpha through
 `.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
 released channel router at `build.yml@v3-alpha`. The auto lane must resolve
-`v3-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
+`v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same
 declared install, build, and verify fixture, proving that a single consumer
 surface routes to distinct released runtimes without duplicating lifecycle
 configuration in the consumer.
@@ -260,6 +260,13 @@ Developer ID, Windows Authenticode, and detached cryptographic signatures share
 the request/receipt model, while each profile retains its honest platform
 semantics and fail-closed verification requirements.
 
+The authority verifies the complete result set on GitHub-hosted infrastructure
+before delivery. The consumer controller also performs final result verification,
+exact-byte import, manifest recomputation, and deterministic-artifact replacement
+on a GitHub-hosted lane. Self-hosted build runners do not download authority
+result payloads, and aggregate/release evidence fails closed until this
+finalization succeeds.
+
 The central `buildchain-artifact-signing` environment reuses the established
 macOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,
 `BUILDCHAIN_MACOS_NOTARY_API_*`, and
@@ -278,7 +285,7 @@ reviewed alpha SHA and compatibility digest; it does not replace the stable
 consumer lock. A later alpha with only compatible additive drift continues,
 while a changed breaking digest fails until the new alpha contract is reviewed.
 
-The evidence job resolves `v3-alpha` and `v2` through the GitHub refs API,
+The evidence job resolves `v3-alpha` and `v3` through the GitHub refs API,
 compares those immutable SHAs with the reusable workflow outputs, verifies the
 `alpha` and `stable` classifications, and uploads a JSON evidence artifact.
 The canary runs after successful Buildchain ref promotion, on a daily fallback
@@ -611,7 +618,7 @@ jobs:
       checks: read
       statuses: read
     with:
-      target-branch: dev/v2/v2.6
+      target-branch: dev/v3/v3.0
       required-status-checks: check / check
       ready-label: ready
       block-labels: blocked,do-not-merge
@@ -681,7 +688,7 @@ jobs:
       dry-run: true
 ```
 
-All three wrappers default to the `v2` floating Buildchain runtime. When
+All three wrappers default to the `v3` floating Buildchain runtime. When
 `target-branch` is omitted, the caller's current/default branch selects the
 active semver dev line, so consumers do not pin patrol to a stale minor branch.
 The separate workflow names keep consumer schedules readable and stable while
@@ -713,7 +720,7 @@ when that is explicitly allowed by the caller.
 
 ## Lifecycle Configuration
 
-`buildchain.toml` is the v2 user configuration format. It lets a repository
+`.buildchain/buildchain.toml` is the v3 user configuration format. It lets a repository
 declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
@@ -778,13 +785,13 @@ bypass actor.
 
 When the loop succeeds, maintainers and consumers can rely on these facts:
 
-- every production release has an exact tag such as `v2.0.2`;
-- every production minor line has a floating tag such as `v2.0`;
-- every selected stable major has a floating tag such as `v2`;
+- every production release has an exact tag such as `v3.0.2`;
+- every production minor line has a floating tag such as `v3.0`;
+- every selected stable major has a floating tag such as `v3`;
 - every next-major release is driven by a reviewed `release -> publish-gate/major` PR,
   not a hidden manual button;
-- every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;
-- every alpha minor line has a floating tag such as `v2.0-alpha`;
+- every test channel has an exact alpha tag such as `v3.0.3-alpha.0`;
+- every alpha minor line has a floating tag such as `v3.0-alpha`;
 - every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;
 - version manifests match the tag visible from the same commit;
 - production releases are derived from the alpha tree that was tested;
@@ -880,8 +887,8 @@ Buildchain also does not maintain bare exact tags such as `1.0.0`. The supported
 exact release and alpha refs are v-prefixed:
 
 ```text
-v2.0.0
-v2.0.1-alpha.0
+v3.0.0
+v3.0.1-alpha.0
 ```
 
 ## Operational Reading Order

package/docs/release-passport.md

@@ -99,6 +99,10 @@ Additive passport sections:
   semantic Passport root, exact clean source revision, complete platform
   coverage, verdict, and residual risk. Buildchain owns release admission, not
   the meaning of the product invariants.
+- `releaseEvidence`: typed references to product-owned JSON evidence copied
+  beside the Passport. Buildchain does not interpret product or legal meaning;
+  it binds each document's canonical JSON digest and exact source SHA, tag, and
+  channel, then independently re-verifies the sibling document.
 - `githubArtifactAttestations`: expected GitHub keyless attestation identities
   for Linux release artifacts, including subject, caller source, original build
   evidence, exact Buildchain signer workflow digest, and least-privilege

package/docs/release-propagation.md

@@ -132,6 +132,13 @@ This lets a site repository render the latest reader page and historical
 version index from release facts while keeping old PDFs, source bundles,
 manifests, and passports immutable.
 
+When the downstream consumer is expected to update an exact npm paper pin, the
+upstream envelope must carry both `package` and `publicationArtifact`. The
+consumer can then prove that package name, version, sha512 integrity,
+publication URLs, and immutable artifact digests all describe the same release.
+`publicationArtifact` without `package` remains valid for evidence-only
+propagation, but it cannot qualify a package-pin fast path.
+
 ## CLI
 
 Generate a propagation plan:
@@ -164,7 +171,34 @@ The written lock has contract
 - release passport URL and SHA-256;
 - optional site bundle manifest SHA-256;
 - downstream repository, channel, base ref, lock path;
-- edge id and channel policy.
+- edge id and channel policy;
+- a deterministic propagation key and branch derived from the exact upstream
+  repository/version/channel plus downstream repository.
+
+Repeated runs for the same release identity reuse that branch and lock. A
+different release version or channel receives a different branch, so concurrent
+releases cannot collapse into one mutable propagation PR.
+
+Create the exact propagation receipt after the lock/PR outcome is known:
+
+```bash
+buildchain release-propagation receipt \
+  --plan .buildchain/release-propagation-plan.json \
+  --lock-result .buildchain/release-propagation-write-lock.json \
+  --pr-outcome .buildchain/release-propagation-pr-outcome.json \
+  --target site-libkungfu-dev \
+  --output .buildchain/release-propagation-receipt.json \
+  --json
+```
+
+The receipt keeps four machine states separate:
+
+- `package-published`: exact npm name/version/integrity exists;
+- `alpha-complete`: the upstream alpha passport/tag is complete;
+- `staging-visible`: the downstream staging surface is actually visible;
+- `production-visible`: the production surface is actually visible.
+
+Package publication or alpha completion never implies either visibility state.
 
 ## Reusable Workflow
 
@@ -181,7 +215,11 @@ jobs:
       upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}
       downstream-target: site-libkungfu-dev
       downstream-repository: kungfu-systems/site-libkungfu-dev
-      downstream-base-ref: main
+      downstream-base-ref: dev/v2/v2.7
+      downstream-update-command: >-
+        node scripts/paper-propagation.cjs consume
+        --lock "$BUILDCHAIN_PROPAGATION_LOCK_PATH"
+        && corepack pnpm install --lockfile-only --ignore-scripts
       downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts
       downstream-verify-command: pnpm run check
       dry-run: false
@@ -201,8 +239,14 @@ open PR.
 The workflow checks out the Buildchain runtime selected by
 `buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes
 that runtime for the propagation plan and lock write, then checks out the
-downstream repository and writes the exact lock. A consumer that must pin the
-exact upstream package or regenerate deterministic files declares
+downstream repository and writes the exact lock. If
+`downstream-update-command` is set, Buildchain runs that consumer-owned command
+after writing the lock and exposes the exact lock path, lock SHA-256,
+propagation key, branch, and upstream release JSON as
+`BUILDCHAIN_PROPAGATION_*` environment variables. The command is part of the
+downstream PR diff; it is not a deployment hook.
+
+A consumer that must perform further deterministic preparation can declare
 `downstream-prepare-command`. The command receives
 `BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and
 `BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an
@@ -210,14 +254,15 @@ existing `<!-- buildchain:badges:start -->` README block by default. Consumers
 can disable that step with `refresh-managed-readme-badges: false`.
 
 `downstream-verify-command` runs against the final tree before any commit or
-push, so consumers can use the same check as their PR workflow. Preparation,
-badge refresh, and verification failures all fail closed. The workflow stages
-the complete deterministic result, signs the propagation commit with DCO, and
-then opens or updates the PR. It does not publish the downstream release
-directly. The downstream repository keeps its normal Buildchain governance: the
-PR updates source-of-truth facts, then downstream alpha or release publication
-runs through its own protected channel. A byte-identical rerun is an explicit
-successful no-op.
+push, so consumers can use the same check as their PR workflow. Update,
+preparation, badge refresh, and verification failures all fail closed. The
+workflow stages the complete deterministic result, signs the propagation
+commit with DCO, and then opens or updates the PR. It does not publish the
+downstream release directly. The downstream repository keeps its normal
+Buildchain governance: the PR updates source-of-truth facts, then downstream
+alpha or release publication runs through its own protected channel. A
+byte-identical rerun is an explicit successful no-op.
+
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v3` and pass a temporary train ref through `buildchain-ref`.