@kungfu-tech/buildchain 4.1.0-alpha.0 → 4.1.0-alpha.2

package/docs/MAP.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-10
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-6
   product: Codex
@@ -170,7 +170,7 @@ replace them.
 | How do ephemeral GitHub-hosted runners share exact dependency or compiler caches without fixed-runner affinity? | [`cli.md`](cli.md#commands) | use/verify | preview |
 | How do I validate an unreleased Buildchain runtime train while keeping `@v3`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
 | How do v4 consumers keep floating selectors while proving exact runtime and lock identity? | [`reusable-build-surface.md`](reusable-build-surface.md#v4-floating-consumer-admission) | verify/use | preview |
-| How can a trusted v4 run use a transient exact runtime and resume sealed Stage Capsules after a floating ref moves? | [`v4-runtime-ref-resume-authority.md`](v4-runtime-ref-resume-authority.md) | use/verify | preview |
+| How does the public entry select a runtime and recover with a repaired train? | [`runtime-entry.md`](runtime-entry.md) | use/verify | preview |
 | How do I automatically qualify alpha candidates and publish the newest non-revoked qualified candidate at a fixed window? | [`stable-candidate-patrol.md`](stable-candidate-patrol.md) | use | preview |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
@@ -214,7 +214,7 @@ replace them.
   [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).
 - **local Git checkout cache / self-hosted source transport** ->
   [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).
-- **runtime train validation / temporary `buildchain-ref` override** ->
+- **runtime train validation / temporary `runtime-ref` override** ->
   [`runtime-train-validation.md`](runtime-train-validation.md) and
   [`reusable-build-surface.md`](reusable-build-surface.md).
 - **consumer workflow feedback / automatic Buildchain GitHub issues** ->

package/docs/auditable-demo.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-05
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -122,7 +122,7 @@ authority.
 jobs:
   demo:
     needs: exact-binary
-    uses: kungfu-systems/buildchain/.github/workflows/public-build-demo.yml@BUILDCHAIN_EXACT_SHA
+    uses: kungfu-systems/buildchain/.github/workflows/public-build-demo.yml@v4
     with:
       source-ref: ${{ github.sha }}
       binary-artifact-name: ${{ needs.exact-binary.outputs.artifact-name }}
@@ -215,7 +215,7 @@ non-symlink, executable file inside the exact checked-out consumer source.
 
 The Gate:
 
-- checks out the exact consumer source and exact called-workflow SHA;
+- prepares the selected execution runtime and checks out the exact consumer source;
 - resolves and downloads one exact same-run GitHub Artifact;
 - invokes the checked-in adapter by argv, never as an evaluated shell string;
 - rejects undeclared adapter outputs, symlinks, invalid UTF-8, invalid scene or
@@ -353,7 +353,7 @@ jobs:
     permissions:
       actions: read
       contents: read
-    uses: kungfu-systems/buildchain/.github/workflows/.build-demo-adapter.yml@BUILDCHAIN_EXACT_SHA
+    uses: kungfu-systems/buildchain/.github/workflows/.build-demo-adapter.yml@v4
     with:
       source-ref: ${{ github.sha }}
       source-artifact-name: ${{ needs.build.outputs.artifact-name }}

package/docs/cli-reference.md

@@ -1818,11 +1818,11 @@ buildchain paper preflight [--cwd <dir>] [--offline] [--json]
 
 - Help: `buildchain paper resume --help`
 - Canonical id: `paper-resume`
-- Options: `--buildchain-ref`, `--cwd`, `--execute`, `--json`
+- Options: `--cwd`, `--execute`, `--json`, `--runtime-ref`
 - Syntax:
 
 ```text
-buildchain paper resume [--cwd <dir>] [--buildchain-ref <ref>] [--execute] [--json]
+buildchain paper resume [--cwd <dir>] [--runtime-ref <ref>] [--execute] [--json]
 ```
 
 ### `buildchain paper scaffold`

package/docs/code-organization.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-10
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-6
   product: Codex
@@ -21,7 +21,7 @@ ai_provenance:
 
 Buildchain 4.1 uses responsibility layers, then capability directories. The
 reusable workflow is the primary consumer API. This development line is
-`4.1.0-alpha.0`; these changes do not themselves publish an alpha release.
+`4.1.0-alpha.1`; these changes do not themselves publish an alpha release.
 
 ```text
 .github/workflows/                 Consumer APIs and hosted job topology
@@ -97,8 +97,9 @@ The development delivery API has six semantic nodes: source admission,
 reservation, native execution, qualification, settlement, and landing. Its
 actions are grouped under `dev-delivery/candidate`, `dev-delivery/native`,
 `dev-delivery/warrant`, and `dev-delivery/queue`.
-Buildchain invokes this public delivery workflow from the same source commit, so
-its workflow, action paths and runtime modules share one implementation identity.
+Buildchain consumes the same public floating entry as other repositories. The
+entry selects one runtime through the shared runtime entry; every business
+action and module comes from that selection, independently of the entry SHA.
 The native node runs in separate hosted jobs where the trust boundary requires
 process and credential isolation.
 Dispatch carries exact source-run coordinates and content roots. When the path

package/docs/controller-evidence.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-14
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -80,7 +80,7 @@ Reusable workflows expose these outputs:
   `controller-receipt-digest`, and `controller-receipt-status`.
 
 Final aggregation uses `always()`. A required missing stage, required missing
-evidence, invalid digest, source/runtime mismatch, or missing receipt cannot be
+evidence, invalid digest, source mismatch, or missing receipt cannot be
 reported as qualifying green. `aggregateControllerReceipts()` reports an
 explicit `receipt-missing` status when a plan has no receipt.
 

package/docs/dev-alpha-candidate-patrol.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-11
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -128,15 +128,15 @@ the rendered bytes. Concurrent qualification progress therefore fails closed
 and is recomputed by the next patrol instead of attaching a declaration to the
 wrong candidate.
 
-The separately permissioned `settle` job checks out the exact Buildchain runtime
-commit used by `observe`, re-runs the exact observation, and compare-and-swap
+The separately permissioned `settle` job prepares the entry-selected runtime,
+re-runs the exact observation, and compare-and-swap
 checks the selected SHA, prior controller root and Release Cut root before any
 write. With no active managed candidate, it reads the candidate tree and creates
 one rooted Release Cut before it creates one branch named from
 the target branch and the first 12 characters of the full source SHA. An
 existing branch must point to the same full SHA or the run fails. With one
-active managed candidate, it validates the candidate ref, tree, Alpha base and
-runtime before returning that same SHA to every checkout/build consumer. It only
+active managed candidate, it validates the candidate ref, tree and Alpha base
+before returning that source SHA to every checkout/build consumer. It only
 updates the machine-readable state marker when a new dev observation or hold
 receipt must be persisted. Repeated events and rapid dev progress cannot create
 another candidate PR or another heavy candidate build. Foreign human-authored

package/docs/dev-delivery-warrant.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-17
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -508,26 +508,16 @@ root still match. A delayed `dequeued` event is ignored when GitHub readback
 shows the same exact PR head is already queued again, so an earlier queue event
 cannot close a newer active Warrant generation.
 
-Buildchain uses the same contract for its own protected dev line through
-`self-ops-dev-delivery.yml`. The manual caller requires the exact PR head and
-semantic source roots, accepts an optional reusable native proof, keeps both
-the durable public selector and explicit runtime input on `v4-alpha`, selects
-`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not
-offer an `off` switch: rollback is a reviewed change to this caller, not an
-operator-time weakening of a specific delivery attempt.
-
-`templates/native-dev-delivery.yml` provides the corresponding protected-dev
-consumer workflow. It supports both explicit dispatch and the bounded wake
-event, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4
-runtime ref that locks every delivery job to the same checkout, and keeps the
-native command in the consumer repository rather than inventing
-provider-specific shards. Both callers explicitly bind the queue-admission
-and active-lease status contexts so write/readback fencing uses the same exact
-names. The reusable workflow defaults the explicit runtime input to
-`v4-alpha`; an empty input or any v3 selector fails before the first runtime
-checkout.
-
-This mechanism schedules protected delivery only. It does not serialize local
-development, source-only checks, unrelated channels, release publication, or
-runner provisioning. It never grants authority to enable cloud runner
-campaigns.
+Buildchain uses the same public contract for its protected dev line through
+`self-ops-dev-delivery.yml`. The caller keeps the durable selector on `@v4`,
+requires exact PR source roots, and selects `delivery-warrant-mode: required`.
+The central runtime entry selects and prepares execution code. Explicit transient
+runtime selection can choose a repaired train without changing the persisted
+caller. There is no per-attempt Warrant bypass.
+
+`templates/native-dev-delivery.yml` supplies the corresponding consumer workflow.
+It supports explicit dispatch and the bounded wake event, preserves the native
+command in the consumer repository, and binds queue-admission and active-lease
+status contexts for provider write/readback fencing. Runtime selection follows
+the shared entry precedence; subsequent delivery nodes do not compare Buildchain
+SHAs.

package/docs/engineering-housekeeper.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: reviewed
-last_reviewed: 2026-08-10
+last_reviewed: 2026-09-11
 ---
 
 # Engineering Housekeeper
@@ -127,8 +127,8 @@ continue.
 | `stale-pull-request-label`  | string  | empty                       | Empty keeps pull requests report-only; non-empty permits labeling, never closure. |
 | `max-actions`               | number  | `20`                        | Positive global apply limit.                                                      |
 | `artifact-retention-days`   | number  | `30`                        | Retention for plan, report, and receipts.                                         |
-| `buildchain-repository`     | string  | `kungfu-systems/buildchain` | Runtime source repository.                                                        |
-| `buildchain-ref`            | string  | `v4`                        | Runtime ref; trusted qualification may pass a train or exact SHA.                 |
+| `runtime-ref` | string | empty | Transient runtime selected by the central entry; otherwise use the lock or entry default. |
+| `contract-lock` | string | empty | Optional consumer-relative contract lock path. |
 
 Stable outputs are `plan-root`, `report-receipt-root`, optional
 `branch-receipt-root` and `pull-request-receipt-root`, `action-count`,

package/docs/github-artifact-attestation.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-24
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -137,9 +137,8 @@ permissions:
 
 jobs:
   promote:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@<exact-buildchain-v3-runtime-sha>
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
     with:
-      buildchain-ref: <exact-buildchain-v3-runtime-sha>
       github-release: true
       release-passport: true
       github-artifact-attestation-policy-json: .buildchain/release-candidate/payload/<artifact>/policy.json
@@ -147,14 +146,14 @@ jobs:
 ```
 
 Promotion binds the policy into the Passport, stages only digest-matching data,
-calls the exact v3 signer, verifies the provider identity a second time, and
+calls the public signer entry, verifies the provider identity a second time, and
 publishes immutable bundle, predicate, verification, evidence, and receipt
 assets beside the release artifact. A same-name Release asset with different
 bytes is rejected instead of overwritten.
 
 Low-level callers may call the reusable attester directly after their Passport
-job. Both the reusable workflow ref and `buildchain-ref` use the same exact
-40-hex signer-bootstrap commit and fail closed if the provider identity differs:
+job. The public entry selects the execution runtime through the same contract as
+build and release. Provider signer identity and subject digests remain mandatory:
 
 ```yaml
 jobs:
@@ -166,9 +165,8 @@ jobs:
       attestations: write
       contents: read
       id-token: write
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-artifact-attestation.yml@<exact-signer-bootstrap-sha>
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-artifact-attestation.yml@v4
     with:
-      buildchain-ref: <exact-signer-bootstrap-sha>
       evidence-run-id: ${{ github.run_id }}
       source-sha: ${{ github.sha }}
       subject-artifact-name: linux-release
@@ -191,10 +189,9 @@ custom predicate, and Buildchain evidence root:
 
 The reusable workflow runs that same exact signer/source verification
 immediately after `actions/attest` and before it finalizes or uploads evidence.
-Passing a different `buildchain-ref` than the commit used to invoke the reusable
-workflow therefore fails in the signer job, not only during later consumption.
-The policy additionally retains the distinct Buildchain runtime SHA that
-created the build and release evidence.
+The provider signer commit identifies the workflow that issued the attestation.
+The selected execution runtime is separate provenance and may differ. Subject,
+signer and evidence-root verification does not compare entry and runtime SHAs.
 
 ```bash
 buildchain verify github-artifact-attestation \

package/docs/github-governance-authority.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -125,9 +125,9 @@ buildchain audit github-governance \
 ```
 
 Protected merge and publication consumers verify the receipt against the exact
-repository, target base ref, policy root, freshness window, and exact
-Buildchain verifier source revision. Non-dry-run publication does not trust a
-caller-supplied JSON hash: it mints a bounded token for the dedicated read-only
+repository, target base ref, policy root and freshness window. The selected
+runtime revision is recorded as provenance, without a downstream SHA comparison.
+Non-dry-run publication does not trust a caller-supplied JSON hash: it mints a bounded token for the dedicated read-only
 governance auditor GitHub App, recollects live provider state with the exact
 Buildchain runtime, requires the resulting single-repository/single-target
 audit to qualify, and consumes that independently generated receipt. Missing