@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/AGENTS.md

@@ -79,6 +79,45 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
+Buildchain v4 Stage Capsule checkpoint work is governed by
+`architecture/v4-platform-stage-checkpoints.json`. Agents must use that single
+platform/stage declaration for shadow emission and clean-process restore. Do
+not add undeclared runner-only inputs, outputs, environment, provider effects,
+credentials, or production stage-skipping authority.
+
+Stage Capsule resume planning is governed by
+`architecture/v4-stage-capsule-resume-planner.json`. Keep its Rust core and
+TypeScript projection pure and byte-identical; explicit provider/release-tail
+effects always require readback and never become Capsule reuse.
+
+Stage Capsule qualification and Wave 2 reconciliation are governed by
+`architecture/v4-stage-capsule-qualification.json`. Buildchain v4 dogfood is a
+repository invariant, not an implementation convenience: this repository must
+consume `kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml`
+through the same public reusable-workflow contract as every other consumer.
+The caller must remain a thin workflow with no steps or local orchestration,
+and `.buildchain/buildchain.toml` must declare the same real `install`, `build`,
+and `verify` lifecycle. The public workflow binds the exact called-workflow SHA,
+consumer source SHA, platform, commands, manifests, summaries, dependencies,
+and output roots on Linux, macOS, and Windows.
+
+No agent may add or restore a relative/self reusable-workflow call, direct
+qualification job, local action, candidate-branch runtime override,
+Buildchain-only consumer identity/profile, environment-variable escape hatch,
+or any other private self-dogfood path. Generic Stage Capsule internals may be
+called only by the public reusable workflow and tests. `version-state`,
+`publish`, provider, signing, release, credential, AWS, and production-reuse
+effects remain excluded.
+
+If public workflow recursion prevents candidate validation, publish the exact
+candidate at `train/v4/v4.0/<capability>` and make the thin caller consume that
+fully qualified public train ref. Fix failures in the train/public contract;
+never solve recursion with an internal exception. After qualification and
+protected merge, repin the durable caller to the exact protected commit when
+the delivery plan requires it. `pnpm run check` and protected Verify run
+`scripts/check-v4-public-dogfood-contract.mjs`; changing this rule, its gate, or
+the protected caller requires independent `@kungfu-origin` review.
+
 `pnpm run check` validates inventory data, generated public references and site
 bundle drift, lints root workflows, runs unit tests, and rebuilds every action
 bundle.

package/README.md

@@ -61,6 +61,9 @@ The same mechanism releases Buildchain itself.
 | writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |
 | operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |
 
+Production release operators should also read the
+[Buildchain v4 production release runbook](docs/v4-production-release.md).
+
 The Golden Path is the beginner lane. Advanced workflow, signing, publishing,
 and governance manuals remain separate so a first-time consumer does not need
 to understand the entire release control plane before reaching a valid local
@@ -93,17 +96,18 @@ New repository adopters should follow the [15–30 minute Golden Path](docs/gett
 The commands below are the shorter verification-only route for an existing
 consumer.
 
-For v3, use the published npm package and verify the release passport before
+For v4, use the published npm package and verify the release passport before
 trusting release evidence:
 
 ```bash
-curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json
-curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json
-npx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json
-npx @kungfu-tech/buildchain@3.0.0 version
+curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/buildchain.release.json
+curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/artifact-evidence.json
+npx @kungfu-tech/buildchain@4.0.0 verify release-passport buildchain.release.json
+npx @kungfu-tech/buildchain@4.0.0 version
 ```
 
-The v3.0.0 release publishes evidence assets but no standalone platform archives.
+The v4.0.0 release publishes evidence assets and platform archives through the
+same protected promotion transaction.
 The names below describe the optional archive contract used by legacy release
 lines:
 
@@ -211,13 +215,13 @@ Consumers can report Buildchain-owned workflow failures directly to the
 Buildchain repository with a scoped issue-write token:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3
+- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v4
   if: failure()
   with:
     token: ${{ steps.buildchain-issue-token.outputs.token }}
     summary: "Reusable build failed before artifact finalization"
     failure-code: reusable-build-failed
-    buildchain-ref: v3
+    buildchain-ref: v4
     diagnostics-path: .buildchain/artifacts/diagnostics.json
 ```
 
@@ -233,7 +237,7 @@ Bootstrap a repository:
 ```bash
 npx @kungfu-tech/buildchain init --type package --package-manager pnpm
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0
 ```
 
 Bootstrap and inspect a governed paper repository through one interface:
@@ -242,7 +246,7 @@ Bootstrap and inspect a governed paper repository through one interface:
 npx @kungfu-tech/buildchain paper scaffold \
   --package @kungfu-tech/paper-example \
   --repository kungfu-systems/paper-example
-pnpm add -D @kungfu-tech/buildchain@<exact-v3-version>
+pnpm add -D @kungfu-tech/buildchain@<exact-v4-version>
 pnpm exec buildchain paper work start <topic>
 pnpm exec buildchain paper work submit
 pnpm exec buildchain paper preflight --offline
@@ -327,15 +331,15 @@ Stable consumers should reference actions and workflows through floating major
 refs after reviewing the exact release passport:
 
 ```yaml
-uses: kungfu-systems/buildchain/actions/validate-config@v3
+uses: kungfu-systems/buildchain/actions/validate-config@v4
 ```
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3
+uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3
+uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4
 ```
 
 ## Release Model

package/actions/promote-buildchain-ref/README.md

@@ -328,7 +328,6 @@ BUILDCHAIN_SEALED_NPM_TARBALL
 BUILDCHAIN_SEALED_NPM_INTEGRITY
 BUILDCHAIN_SEALED_NPM_SHA256
 BUILDCHAIN_REQUIRED_ARTIFACTS
-BUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH
 ```
 
 `BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the
@@ -338,10 +337,6 @@ declared provenance to the current release coordinate. Template expansion
 happens after exact version selection; ambiguous or unsupported templates fail
 before `lifecycle.publish`. Requirement descriptors may omit `digest`; final
 publish evidence may not.
-The action also writes that normalized array to
-`BUILDCHAIN_PUBLISH_REQUIRED_ARTIFACTS_PATH`. To stay below operating-system
-process environment limits, large arrays are available through the file path
-only; small arrays retain the inline variable for compatibility.
 
 The action outputs `transaction-id`, `transaction-state`,
 `transaction-publication-state`, `transaction-sealed-bundle-root`,
@@ -500,11 +495,6 @@ governance semantics:
 - alpha promotion must come from a merged same-repository PR
   `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line
   `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;
-  an immutable recovery receipt may instead admit the exact current alpha
-  channel SHA only when its sealed candidate tree is byte-equivalent and its
-  publication version is bound by that receipt; when administrative protection
-  details are hidden, the provider-visible protected head and required check
-  must still match that exact recovered SHA;
 - release promotion must come from a merged same-repository PR
   `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line
   `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;

package/actions/release-tail/README.md

@@ -1,17 +1,13 @@
 # Declarative Release Tail
 
-This Action restores one content-addressed
-`kungfu.buildchain.publication-rehearsal-capsule/v1` and invokes the same public
-rehearsal runtime used by the local CLI. The capsule binds the versioned
-`buildchain.release-tail/v1` declaration, candidate files, policies, Passport,
-transaction, data-only provider bindings and observations. It does not accept
-a command, script, executable path, plugin, repository callback, implicit
-workspace or GitHub runner semantic input.
+This Action executes the versioned `buildchain.release-tail/v1` declaration
+through one durable Buildchain transaction. It accepts only data bindings for
+sealed artifacts, rooted JSON documents, HTTP provider endpoints and released
+evidence inputs. It does not accept a command, script, executable path, plugin
+or repository callback.
 
 Every mutation is preceded and followed by provider readback. Buildchain core,
 not the adapter, compares the observed subject and target roots, owns retry and
 terminal classification, checkpoints state and emits the standardized receipt.
 Tokens remain Action inputs and are never written to the transaction or
-receipt. The wrapper contributes only credentials, GitHub/HTTPS transport and
-real provider observations. The rooted provider transcript and rehearsal
-evidence are retained with the transaction state.
+receipt.