@kungfu-tech/buildchain 4.0.10-alpha.0 → 4.1.0-alpha.1

package/docs/release-propagation.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-03
+last_reviewed: 2026-09-11
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-03
+  generated_at: 2026-09-09
   invisible_context: not asserted
 ---
 
@@ -420,9 +420,11 @@ base and managed branch, lock path, consumer commands, production status URL,
 and production artifact readback URLs. The sealed workflow rejects extra config
 fields, unknown targets, or a target whose base revision cannot be resolved.
 
-The reusable workflow keeps its prior behavior when `agent-work-mode` is
-`legacy` (the default). Managed Paper callers set `capture-only`; an Agent later
-claims the emitted artifact and resumes from its machine-readable `next_action`.
+The reusable workflow defaults to `agent-work-mode: capture-only`. It emits a
+paused typed Work without writing a downstream release lock. To execute, supply
+`agent-work-mode: execute` and an exact `agent-work-context-json` whose authority
+also declares execution. The same native Work records materialization, verification,
+verified branch push, and the pull request; there is no separate unowned execution path.
 
 Agent entrypoints are machine-readable and restart-safe:
 
@@ -486,14 +488,14 @@ root.
 ## Reusable Workflow
 
 Upstream repositories can call
-`.github/workflows/release-propagation.yml@v3` after release finalization:
+`.github/workflows/public-release-propagation.yml@v4-alpha` after release finalization:
 
 ```yaml
 jobs:
   propagate-site:
-    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-propagation.yml@v4-alpha
     with:
-      buildchain-ref: v3
+      agent-work-mode: capture-only
       graph-json: ${{ needs.release.outputs.propagation-graph-json }}
       upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}
       downstream-target: site-libkungfu-dev
@@ -505,24 +507,22 @@ jobs:
         && 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
+      dry-run: true
     secrets:
       propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
 ```
 
-The downstream branch name may be reused across upstream releases. Before
-replacing an existing managed branch, the workflow reads its exact remote SHA
-and pushes with an explicit `--force-with-lease=<ref>:<sha>`. A surviving branch
-from a merged PR is therefore reconciled without manual deletion, while a
-concurrent writer makes the lease fail closed. The controller receipt includes a
-`propagation-branch-reconciliation` evidence file recording the branch, observed
-remote SHA, pushed SHA, lease mode, and the deterministically created or updated
-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. If
+Execution uses the native Work's exact downstream repository, base revision and
+branch. Push planning verifies that the base has not advanced and is an ancestor
+of the source commit. The provider uses a non-force refspec and reads the remote
+branch back before recording successful push evidence. A divergent surviving
+branch or a concurrent incompatible update fails; the workflow does not replace
+its history. The controller retains the exact branch reconciliation and PR
+coordinates.
+
+The central entry prepares `.buildchain/runtime` once for each execution job.
+The selected runtime owns the propagation plan and lock write; the downstream
+repository checkout is the consumer source. 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
@@ -549,7 +549,7 @@ publication, deployment, and readback entrypoints. A byte-identical rerun is an
 explicit successful no-op, never a synthetic completion.
 
 For unreleased runtime validation, keep the caller's reusable workflow reference
-on `@v3` and pass a temporary train ref through `buildchain-ref`.
+on `@v4` and pass a temporary train through `runtime-ref`.
 
 ## kfd to site-libkungfu-dev
 

package/docs/release-tail-contract.md

@@ -1,72 +1,51 @@
 ---
 status: draft
-period: 2026-08-07
+period: ongoing
 theme: buildchain-release-tail-contract
 doc_type: architecture
 source_level: local-files
 confidence: high
 sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-13
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-09
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-07
-  visible_context: Buildchain dev/v3/v3.0 release workflows, the v4 capability manifest and architecture constitution, promotion Action, transaction and activation code, local exact-head managed-consumer callers, and the Kungfu alpha release-tail implementation.
+  generated_at: 2026-09-09
+  visible_context: Current Buildchain 4.1 workflow and action graph, promotion request schemas, provider transaction implementation and retained historical inventory.
   invisible_context_boundary: Did not read credentials, private logs, signed URLs, provider state, or unpublished release assets.
 ---
 
 # Declarative release-tail contract
 
-Buildchain's v3 compatibility line lets a consumer repository provide shell
-commands at several points around publication. Those hooks made early adoption
-possible, but they also let a consumer redefine the final release transaction. The
-machine authority for the current inventory is
-[`architecture/release-tail-contract-inventory.json`](../architecture/release-tail-contract-inventory.json).
+The current machine authority is
+[`architecture/release-tail-contract.json`](../architecture/release-tail-contract.json).
+The public promotion workflow accepts one typed request, then dispatches
+QUALIFY, APPLY and SETTLE. APPLY reaches the canonical provider transaction;
+it cannot forward arbitrary publication, activation, commit or evidence commands.
 The declaration schema is
-[`contracts/release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json).
-
-This contract freezes the replacement boundary. The Buildchain-owned provider
-implementation is documented in
-[`release-tail-provider-plane.md`](./release-tail-provider-plane.md). Adding the
-provider plane does not itself cut over a consumer, run a release, or
-reinterpret an already published release.
-
-The v4 line carries this contract as its production release-tail boundary. The
-v4 capability manifest names `typescript-v4` as the sole writer and marks the
-legacy v3 writer retired. Deterministic v4 journal, activation, stable-fence,
-recovery, provider readback, rollback, and N-1 qualification contracts gate
-every provider mutation; the retained v3 release ref is rollback evidence, not
-an active fallback writer.
-
-## Current executable surfaces
-
-The reverse scan classifies 27 workflow, Action, config, and CLI coordinates
-into seven owned surface groups:
-
-| Surface                                                                  | Current role                                              | Replacement                                                 |
-| ------------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------- |
-| `publication-gate-command`, `publication-consumer-qualification-command` | Consumer-owned admission and predicate logic              | Buildchain-evaluated declarative predicates                 |
-| `publish-command`, `lifecycle.publish`                                   | Artifact/package materialization and provider publication | `artifact.publish`                                          |
-| KFD-3, invariant Passport, and attachment commands                       | Product-specific evidence generation                      | Typed evidence requirements and Buildchain-owned projectors |
-| `publication-commit-command`                                             | Final signed or well-known channel authority move         | `signed-channel.commit`                                     |
-| `release-activation-command`                                             | Site activation and production readback                   | `release.activate`                                          |
-| reusable-workflow `release-passport-evidence-command`                    | Receipt-only released-evidence synthesis                  | `released-evidence.synthesize`                              |
-| Action `verification-command`                                            | Version-state verification before release-tail execution  | Separate version-state contract; not part of release tail   |
-
-One name is already ambiguous. In the reusable promotion workflow,
-`release-passport-evidence-command` means post-activation released-evidence
-synthesis. In the lower-level promotion Action, the same name is a deprecated
-alias for `release-passport-attachment-command`. New declarations reject that
-cross-layer alias collision instead of preserving it as a permanent escape
-hatch.
-
-The current v3 managed-caller snapshot covers Buildchain self-bootstrap, both
-Buildchain paper release paths, Kungfu, Libnode, KFD, and the Kungfu product
-white paper. The inventory binds every snapshot to an exact commit, tree,
-workflow path, runtime ref, and the executable surface groups it uses. The
-legacy `agent-hub-demo@v2` caller is recorded but excluded from the v3 contract.
+[`contracts/release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json),
+and provider behavior is documented in [release-tail-provider-plane.md](release-tail-provider-plane.md).
+
+## Current executable boundaries
+
+Four separately owned command surfaces remain outside the canonical promotion
+transaction: consumer admission predicates, the direct ref-promotion Action's
+publication command, product evidence preparation, and version-state verification.
+Their nine workflow, Action, config and CLI coordinates have five execution sites.
+The checker verifies the current Paper and publication-authority callers against
+the actual composite Action graph. These are current contracts with no historical
+aliases, migration window or fallback execution path.
+
+The direct ref-promotion Action accepts `release-passport-attachment-command` for
+product attachments. Its old evidence-command alias is removed. Canonical public
+promotion uses typed publication data and does not call that separate Action.
+
+The exact old managed-consumer snapshot remains in
+[`release-tail-contract-inventory.json`](../architecture/release-tail-contract-inventory.json)
+as historical evidence. It grants no current execution or compatibility authority;
+this change makes no claim about updating those external repositories.
 
 ## Capability declaration
 
@@ -122,27 +101,12 @@ only retry classes, and no local executor may exceed three attempts. Provider
 conflict, identity drift, missing readback, and exhausted retry remain explicit
 terminal classifications; an adapter cannot convert them into success.
 
-## Compatibility and migration
-
-The compatibility window begins when
-`train/v3/v3.0/release-tail-contract` is published. It closes at the earlier of
-90 days or the first v3.2 stable release, and spans at most two minor lines.
-
-During that window:
-
-- previously published tags, assets, packages, signed channel documents,
-  Passports, and receipts remain immutable;
-- only the exact enumerated callers may use the legacy adapter;
-- every exception has an owner, the common expiry, and a removal test;
-- migrated declarations create new transactions and never reinterpret settled
-  history;
-- no new arbitrary command input or generic plugin is accepted.
+## Publication identity
 
-Cutover order is the Buildchain paper callers plus a self-bootstrap no-command
-regression, Kungfu's complete Alpha tail, Libnode evidence generation,
-KFD/white-paper no-command regression, then deletion of the Action alias and
-all remaining command inputs. This card
-defines that order only; consumer migrations are separate changes.
+Published tags, assets, package coordinates, signed channel documents, Passports
+and receipts remain immutable. Current declarations create their own transactions;
+they never reinterpret settled history. No compatibility reader or migration
+exception is used to admit a current request.
 
 ## Failure rules
 
@@ -153,7 +117,7 @@ The contract fails closed when:
 - an effect lacks stable operation identity;
 - a mutation lacks readback and receipt contracts;
 - local retry is unbounded;
-- an exception lacks an owner, expiry, or executable removal test.
+- an alias or compatibility fallback is introduced into the current contract.
 
 Run the contract check with:
 
@@ -164,4 +128,4 @@ node --test tests/release-tail-contract.test.mjs
 
 The tests mutate the inventory and declaration fixtures to prove that orphaned
 hooks, ambiguous ownership, embedded commands, missing identity/readback,
-unbounded retry, and permanent escape hatches are rejected.
+unbounded retry, command aliases and compatibility fallbacks are rejected.

package/docs/release-tail-provider-plane.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-07
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -30,8 +30,8 @@ The frozen boundary and migration inventory remain in
 - Node: `@kungfu-tech/buildchain/release-tail-provider-plane`,
   `release-tail-provider-adapters`, and `release-tail-compatibility`.
 - CLI: `buildchain release-tail plan|init|status|verify|compat`.
-- Action: `kungfu-systems/buildchain/actions/release-tail@<exact-ref>`.
-- reusable workflow: `kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-ref>`.
+- Action: `kungfu-systems/buildchain/actions/release/tail/settle@<exact-ref>`.
+- reusable workflow: `kungfu-systems/buildchain/.github/workflows/public-release-tail.yml@<exact-ref>`.
 
 The Action is the provider-executing entry point. The CLI compiles, initializes,
 inspects, verifies, and diagnoses bounded v3 compatibility using the same core
@@ -55,9 +55,8 @@ jobs:
   release-tail:
     permissions:
       contents: write
-    uses: kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-buildchain-sha>
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-tail.yml@v4
     with:
-      buildchain-ref: <exact-buildchain-sha>
       declaration-path: .buildchain/release-tail/declaration.json
       provider-bindings-path: .buildchain/release-tail/provider-bindings.json
       execute: true
@@ -116,29 +115,20 @@ Provider execution belongs in the Action or reusable workflow so token handling
 and provider permissions remain explicit. Retain the state artifact: it is the
 resume boundary and evidence source, not a disposable log.
 
-## Buildchain self-dogfood route
+## Buildchain self-promotion route
 
-Buildchain self-release calls the same public reusable workflow coordinate as a
-consumer:
+Buildchain invokes `./.github/workflows/public-release-promote.yml` at the same
+commit as its caller. Admission independently verifies the defining repository,
+exact committed workflow bytes and both consumer lock roots. External consumers
+use the public floating-channel API after publication. See
+[Promotion request](release-promotion-request.md).
 
-```text
-kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@train/v3/v3.0/consumer-equivalent-self-dogfood
-```
-
-The public router resolves the workflow shell and runtime to exact SHAs. For
-alpha self-release, the promotion Action materializes the sealed GitHub Release
-asset declaration, executes it through this provider plane, and retains the
-declaration root, transaction root, state root, receipt roots, controller
-receipt, and route-parity evidence. The legacy GitHub Release helper is not a
-fallback when `declarative-release-tail` is enabled; a provider or readback
-failure fails the authoritative run.
-
-Stable routing remains on the existing `v3` shell and does not receive the new
-alpha-train input. Stable cutover is a separate gate after prerelease dogfood.
-
-## v3 compatibility boundary
+The promotion action executes one declaration-driven GitHub Release transaction.
+Its plan, provider observations and receipts bind the exact subject and asset
+roots. A completed-transaction recovery explicitly verifies the existing public
+Passport and immutable assets before reusing or repairing evidence. A provider
+failure cannot select a different publication implementation.
 
-`release-tail compat --hooks-json <json-or-path>` recognizes only the frozen v3
-hook names. It emits diagnostics for enumerated legacy callers and rejects any
-new command-bearing release-tail field. Compatibility never converts legacy
-shell into a new provider plugin and never reinterprets settled release history.
+Release metadata follows the declared tag and channel. The old mode selector and
+custom title/notes ports are removed. Retired shell-hook compatibility commands
+are absent; the current typed request rejects undeclared fields.

package/docs/reusable-build-surface.md

@@ -24,20 +24,26 @@ single-project calls have no inputs:
 
 ```yaml
 permissions:
+  issues: write
   actions: read
   contents: read
-  issues: write
   id-token: write
+  attestations: write
 jobs:
   build:
     uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
-Use `@v4-alpha` to select the alpha runtime. The exact called workflow SHA is
-the runtime SHA; a second runtime selector cannot override it. Both the public
-`build.yml` and the `.build.yml` backbone expose exactly one optional input:
-`config-path`. Neither accepts command overrides, runtime refs, arbitrary JSON
-configuration or legacy aliases.
+Use `@v4-alpha` for the alpha entry. The entry selects the execution runtime
+from a transient `runtime-ref`, the selected `contract-lock`, or its own commit
+by default. The build API also accepts `config-path` and `resume-run-id`;
+`runtime-selection` transports the entry decision through nested workflows.
+All project commands and build options remain in TOML.
+
+A new recovery dispatch can pass a repaired train and the original failed run
+ID through the same entry. It restores matching retained build outputs, executes
+remaining verification and reads back provider effects. An entry defect requires
+an upgraded published entry and a full run. See [Runtime entry](runtime-entry.md).
 
 ## Project discovery
 
@@ -117,8 +123,9 @@ Other optional project sections are:
 | `build.evidence` | Repository files containing gate and candidate-family evidence |
 
 Declarative signing targets continue to belong to `[signing.artifacts]`.
-The formal signing authority remains `authority/v3/v3.0/artifact-signing`
-with the protected `buildchain-artifact-signing` environment.
+Signing uses `public-release-signing-authority.yml@v4`, passes the selected runtime
+through its runtime parameter and retains the protected
+`buildchain-artifact-signing` environment.
 Credentials, authority profiles and signer identities cannot be supplied through
 that declaration. See [Release Candidate](release-candidate.md)
 and [GitHub Artifact Attestation](github-artifact-attestation.md).
@@ -148,14 +155,16 @@ steps. Their shared behavior is owned by these composite actions:
 
 | Action | Owner responsibility |
 | --- | --- |
-| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |
-| `build-signing-request` | Unsigned requests and detached signing control inputs |
-| `build-verification-evidence` | Independent substage verification and failure evidence |
-| `build-attestation-policy` | Source-bound artifact attestation policy |
-| `build-agent-hub-evidence` | Agent Hub conformance evidence |
-| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |
-
-The backbone still owns install → build → verify order, job dependencies,
+| `resolve-build-plan` | Admission and complete plan |
+| `prepare-build-environment` | Source and toolchains |
+| `run-build-stage` | Ordered lifecycle and diagnostics |
+| `transfer-build-artifact` | Exact artifact coordinates and transport |
+| `sign-build-artifact` | Isolated signing and final bytes |
+| `attest-build-artifact` | Provider identity and final-byte attestation |
+| `finalize-build-result` | Complete coverage and final result |
+
+The backbone has six jobs: `plan`, `build-native`, `build-container`, `sign`,
+`attest` and `deliver`. It owns install → build → verify order, job dependencies,
 permissions, signing control, credential-island placement and final aggregation.
 A composite's internal receipt inputs transport already resolved facts; they
 are not additional reusable-workflow configuration inputs.
@@ -181,22 +190,25 @@ must verify the source, artifacts and receipts independently.
 
 ## Evidence and failure behavior
 
-The workflow retains runtime/source identity, build and diagnostics summaries,
-Release Candidate Passport, signing/finalization and controller receipt outputs.
-The public facade forwards those outputs from the single backbone execution.
+The backbone returns one rooted `result` containing source/runtime identity and
+exact provider references for payloads, diagnostics, summary, signing, attestation
+and candidate evidence. The public facade exposes that result plus the candidate
+and controller artifact names for direct `download-artifact` calls.
 Platform manifests include deterministic payload hashes; transport preserves
 hidden artifacts and provenance. Substage failure evidence is collected even
 when verify fails. Untrusted events cannot reach build runners.
 
-Signing authority and credential-island jobs remain separate from ordinary
-build execution. Imported signed bytes undergo consumer verification before
+The `sign` matrix uses separate ordinary artifact and protected macOS credential
+instances. The credential instance never checks out or executes consumer source.
+A hosted artifact instance may use its platform when final-byte verification
+requires that operating system; it receives no certificate or notary inputs. Imported signed bytes undergo consumer verification before
 manifests are recomputed. Release builds produce candidates; registry publishing
 belongs to the protected release path.
 
 ## Maintaining the contract
 
 Update the TOML parser and plan resolver, owner contracts, affected consumers
-and tests together. Run `node scripts/generate-channel-build-workflow.mjs`,
+and tests together. Run
 `pnpm run generate:workflows`, generated reference/site checks and the full
 `pnpm run check`. Breaking input removal is intentional: migrate old `with`
 settings to TOML and remove them from calls; no compatibility forwarding exists.

package/docs/runtime-entry.md

@@ -0,0 +1,111 @@
+---
+status: draft
+period: ongoing
+theme: unified-runtime-entry
+doc_type: implementation-contract
+source_level: user-consensus
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-11
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-11
+  visible_context: Explicit user-approved runtime selection, recovery and alpha publication requirements.
+  invisible_context_boundary: This contract does not claim implementation or hosted qualification is complete.
+---
+
+# Runtime entry contract
+
+Consumers persist a public workflow reference at `@v4` or `@v4-alpha`.
+GitHub resolves that entry to a commit. The entry selects execution runtime X
+from an explicit transient parameter, the selected contract lock, or the entry
+commit default, in that order. The entry commit and runtime commit may differ.
+
+`actions/runtime/environment/prepare` is the sole runtime preparation owner.
+Selection is resolved once per execution. Each executing job prepares that
+selected runtime through the same implementation. Business workflows and
+actions cannot acquire, replace, reselect or install their own Buildchain
+runtime. All business composites, JavaScript modules, WASM and resources come
+from X. Runtime identity is retained as provenance; subsequent business nodes
+do not compare Buildchain SHAs or require equality with the workflow commit.
+
+A runtime failure can start a recovery execution through the same public
+entry with a transient repaired train branch or tag. The new execution selects
+runtime Y and retains the original task, source and evidence. Valid completed
+results can be reused; provider effects require readback before further writes.
+Switching runtimes does not automatically qualify all previous results for reuse.
+Neither the persisted caller nor its contract lock needs a train rewrite.
+
+An entry failure is repaired by publishing and adopting a corrected entry and
+starting a complete run. Recovering an invalid entry is not a runtime feature.
+Buildchain self-dogfood uses exactly the same consumer contract and has no
+repository-specific execution or recovery route.
+
+Source checkouts are separate business inputs. Building Buildchain itself may
+check out its source, but that source cannot implicitly replace the selected
+execution runtime. Source, artifact and publication-effect checks retain their
+business meaning; they do not reintroduce downstream Buildchain SHA checks.
+
+Acceptance requires a complete workflow/action acquisition inventory, enforced
+single preparation ownership, different entry/runtime execution, train recovery,
+platform and multi-job qualification, and validation of the published consumer
+entry. A source test or a successful package import alone is insufficient.
+
+## Consumer build and recovery
+
+```yaml
+on:
+  push:
+  workflow_dispatch:
+    inputs:
+      runtime-ref:
+        description: Optional repaired train for this execution
+        default: ""
+        type: string
+      resume-run-id:
+        description: Original failed build run to recover
+        default: ""
+        type: string
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
+    with:
+      runtime-ref: ${{ inputs.runtime-ref || '' }}
+      resume-run-id: ${{ inputs.resume-run-id || '' }}
+```
+
+Ordinary executions use `.buildchain/contract-lock.json`; the alpha entry defaults
+to `.buildchain/alpha-contract-lock.json`. `contract-lock` selects another relative
+lock path. A missing default lock falls back to the entry commit; an invalid lock
+or an unreadable source fails preparation. A supplied runtime parameter overrides
+the lock and requires a caller repository actor with write, maintain or admin access.
+Branches and tags are resolved to an immutable commit during selection.
+
+For a Buildchain runtime fault, dispatch the same consumer workflow with
+`runtime-ref: train/v4/v4.1/<repair>` and the original `resume-run-id`. The entry
+retains the original source commit and rejects unrelated workflows or fork runs.
+Install hydrates the new workspace; completed build outputs are restored only
+when source, configuration, platform, tools, artifact producer and all retained
+bytes qualify. The remaining verification runs with the repaired runtime.
+Existing provider effects use their transaction evidence and live readbacks.
+A failed-job rerun cannot supply new inputs; recovery therefore starts a new run.
+
+`runtime-selection` is an internal reusable-workflow transport for an already
+selected runtime. Components forward it unchanged instead of resolving another
+reference. Consumers normally supply `runtime-ref` or a lock, not this transport.
+
+Nested components preserve the selected runtime and contract metadata without
+re-reading the lock or comparing the runtime SHA. The internal transport carries
+a trusted entry output; consumer source binding and override authorization remain
+entry concerns. Recovery selectors request `actions: read` to read the original
+run in private repositories as well as public repositories.
+
+Business adapters also keep the runtime installation directory separate from the
+consumer workspace. Queue reconciliation, npm preview, runner qualification and
+binary packaging read consumer source from the workspace while executing selected
+runtime code. Directory equality is not an admission rule; source SHA and artifact
+containment checks still apply. The architecture gate parses business JavaScript
+and rejects direct or aliased runtime/source directory equality comparisons.

package/docs/runtime-train-validation.md

@@ -18,44 +18,33 @@ ai_provenance:
 
 # Runtime Train Validation
 
-Ordinary builds use the public `build.yml@v4` or `build.yml@v4-alpha`
-workflow and select all project settings from `buildchain.toml`. The called
-workflow SHA also selects the runtime; there is no second runtime selector.
-See [Reusable Build Surface](reusable-build-surface.md) for configuration,
-zero-input calls and the optional nested-project locator.
-
-## Alpha qualification
-
-Buildchain changes enter the protected development branch after review and
-checks. Publish an alpha through the protected release workflow, then exercise
-that public alpha on the exact consumer source. Record the called workflow SHA,
-source SHA, channel-matching contract lock, configuration root and artifact
-manifests. Promote stable only after the required alpha evidence succeeds.
-
-For a breaking build-interface change, publish the producer before changing
-its own public consumers. Retain the callers and locks for the currently
-published interface while creating the first alpha from a successful PR-stage
-candidate. Then migrate the callers and accept the published alpha contract,
-qualify that public interface, and publish the completed alpha and stable.
-This ordering adds no compatibility inputs to the new build workflow.
-
-Source checks verify each consumer lock against the immutable source contract
-at its accepted SHA. Hosted consumer admission separately verifies the actual
-called floating workflow; unpublished producer code is not that dependency.
-
-A train branch is a temporary diagnostic pointer, never a release channel or a
-persisted consumer dependency. Ordinary builds do not accept train, SHA or
-`buildchain-ref` inputs. Initialization does not create a runtime pass-through.
-
-## Specialized release and recovery
-
-Release and recovery entry points retain their own bounded runtime admission
-contracts. Their runtime override capability does not extend to ordinary builds.
-Follow [Release Flow](release-flow.md) and the particular entry point's contract;
-a diagnostic train does not authorize publication, signing, or floating-ref
-movement. Preserve existing source locks, exact candidate lineage and terminal
-receipts when recovering a release.
-
-The Buildchain self-build callers exercise the public floating channels using
-root or fixture TOML. They do not commit a private runtime selector to qualify
-that channel.
+A train repairs the execution runtime without changing the consumer's durable
+public entry. All public workflows, including ordinary builds, use the same
+[Runtime entry contract](runtime-entry.md). The transient runtime parameter
+wins over the consumer lock. Buildchain dogfood follows this same path.
+
+## Validate a runtime change
+
+1. Commit the candidate with its action bundles, WASM and runtime contract.
+2. Publish the candidate at `train/v4/v4.1/<capability>`.
+3. Dispatch the consumer's existing public entry with `runtime-ref` set to that
+   train. Record the selected runtime, consumer source and resulting evidence.
+4. After checks and independent review, merge into protected Dev and publish
+   the requested Alpha. Qualify the published entry before Stable promotion.
+
+Train selection is a trusted non-persistent runtime input. It never grants
+publication or signing authority by itself; those business effects retain their
+provider credentials, capability constraints and readback requirements.
+
+## Recover a runtime failure
+
+Start a new dispatch through the same public entry with the repaired train.
+For builds, supply `resume-run-id`; for release promotion, preserve the original
+candidate run and transaction in the typed request. The entry prepares runtime
+Y while the task keeps its original source and valid completed evidence.
+A GitHub failed-job rerun does not change its inputs and cannot select a new
+runtime. Do not persist the train into the caller workflow or contract lock.
+
+If the public entry itself is defective, publish and adopt the corrected entry
+and start a full run. Copied consumer recovery packages and alternate recovery
+workflows are not part of the runtime contract.