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

package/docs/ownership.md

@@ -40,9 +40,9 @@ Any consumer migration must record:
 
 New stable references should use:
 
-- `kungfu-systems/buildchain/actions/validate-config@v3`
-- `kungfu-systems/buildchain/actions/run-lifecycle@v3`
-- `kungfu-systems/buildchain/actions/promote-buildchain-ref@v3`
+- `kungfu-systems/buildchain/actions/build/lifecycle/validate@v3`
+- `kungfu-systems/buildchain/actions/build/lifecycle/run@v3`
+- `kungfu-systems/buildchain/actions/release/promotion/ref@v3`
 - `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`
 
 ## Publishing Rule

package/docs/publication-artifacts.md

@@ -151,12 +151,12 @@ call the build-only wrapper directly:
 ```yaml
 jobs:
   publication:
-    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-build-publication.yml@v3
     with:
       toolchain-type: config
       verify-command: make check
       artifact-name: observer-declared-timelines
-      buildchain-contract-lock-path: .buildchain/contract-lock.json
+      contract-lock: .buildchain/contract-lock.json
 ```
 
 The build-only workflow:
@@ -212,7 +212,7 @@ on:
 
 jobs:
   paper-release:
-    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-paper.yml@v4
     permissions:
       actions: read
       checks: write
@@ -220,12 +220,11 @@ jobs:
       id-token: write
       issues: write
     with:
-      buildchain-ref: <exact-buildchain-sha>
-      publisher-workflow-path: .github/workflows/paper-release.yml
+      publisher-workflow-path: .github/workflows/public-release-paper.yml
       toolchain-type: config
       verify-command: make check
       artifact-paths: _build/paper-name.pdf
-      buildchain-contract-lock-path: .buildchain/contract-lock.json
+      contract-lock: .buildchain/contract-lock.json
     secrets:
       BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
       BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
@@ -298,12 +297,12 @@ before upload if a declared artifact is missing or if its basename would
 collide with another GitHub Release asset.
 
 For npm Trusted Publishing, register the consumer workflow file that calls this
-preset, for example `.github/workflows/paper-release.yml`, against the declared
+preset, for example `.github/workflows/public-release-paper.yml`, against the declared
 package in npm. The trusted publisher is the consumer repository and workflow
 file; the implementation still runs inside Buildchain's reusable workflow.
 
 Standard paper repositories should not carry local copies of
-`scripts/npm-publish-transaction.mjs`, package-generation scripts, or
+`packages/core/publication/commands/npm-publish-transaction.mjs`, package-generation scripts, or
 promotion/ref-lock YAML. If the default package shape is insufficient, extend
 Buildchain rather than forking the mechanics into each paper repository.
 

package/docs/publication-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
@@ -50,7 +50,7 @@ bound by the manifest digest but excluded from the product-byte set because it c
 be finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the
 admitted post-merge source commit tree. It rejects an unknown
 workflow, stale or replayed nonce, runner downgrade, control-plane drift,
-source/runtime mismatch, and artifact substitution. A successful result is a
+source mismatch, and artifact substitution. A successful result is a
 scoped capability receipt, not a bearer credential.
 
 ## Runner and control-plane evidence
@@ -225,7 +225,7 @@ buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
   --branch dev/v3/v3.0 \
   --source-sha <exact-merged-branch-sha> \
-  --workflow .github/workflows/release-candidate-promote.yml \
+  --workflow .github/workflows/public-release-promote.yml \
   --workflow-ref <exact-buildchain-sha> \
   --publisher-workflow .github/workflows/self-release-promote.yml \
   --job promote \
@@ -235,7 +235,7 @@ buildchain audit publication-control-plane \
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
   --branch dev/v3/v3.0 \
-  --workflow .github/workflows/release-candidate-promote.yml \
+  --workflow .github/workflows/public-release-promote.yml \
   --publisher-workflow .github/workflows/self-release-promote.yml \
   --job promote \
   --environment none \
@@ -244,7 +244,7 @@ buildchain audit publication-control-plane \
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
   --branch release/v3/v3.0 \
-  --workflow .github/workflows/.binary-release-assets.yml \
+  --workflow .github/workflows/.release-binary-assets.yml \
   --job publish \
   --environment buildchain-release-assets \
   --publisher-mode github-token
@@ -253,7 +253,7 @@ buildchain audit publication-control-plane \
   --repository OWNER/CONSUMER \
   --workflow-repository kungfu-systems/buildchain \
   --branch main \
-  --workflow .github/workflows/.web-surface.yml \
+  --workflow .github/workflows/public-release-web.yml \
   --job production-apply \
   --environment production \
   --publisher-mode oidc-role \

package/docs/publish-transaction.md

@@ -53,7 +53,7 @@ It is not the GitHub Actions run id.
 
 ## Durable State
 
-`actions/promote-buildchain-ref` stores release transaction state in a
+`actions/release/promotion/ref` stores release transaction state in a
 machine-managed Git branch:
 
 ```text
@@ -104,7 +104,7 @@ the next version; it never rebinds or overwrites the earlier source lock. The
 same source SHA reuses its own lock so authority planning and mutation stay on
 one exact version.
 
-`release-candidate-promote.yml` can establish or restore this state from an
+`public-release-promote.yml` can establish or restore this state from an
 older successful candidate run through the documented fresh-event recovery
 inputs. The recovery receipt and sealed bundle are verified before the action
 reads or creates transaction state. If `resume-transaction-id` is supplied,
@@ -166,7 +166,7 @@ commands = [
 ]
 ```
 
-`actions/promote-buildchain-ref` runs `lifecycle.publish` only when
+`actions/release/promotion/ref` runs `lifecycle.publish` only when
 `publish-transaction: "true"` is set or when a `publish-command` input is
 provided. The action sets:
 
@@ -197,7 +197,7 @@ Buildchain itself uses this contract for npm publishing:
 
 ```toml
 [lifecycle.publish]
-command = "node scripts/npm-publish-transaction.mjs"
+command = "node packages/core/publication/commands/npm-publish-transaction.mjs"
 ```
 
 That script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs
@@ -314,7 +314,7 @@ 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`
+When the transaction reaches `complete`, `actions/release/promotion/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
@@ -595,15 +595,15 @@ material conflict and blocks recovery.
 Local recovery commands operate on the same state/evidence files:
 
 ```bash
-node scripts/release-transaction.mjs inspect --version v3.0.2
-node scripts/release-transaction.mjs recover --version v3.0.2
-node scripts/release-transaction.mjs finalize --version v3.0.2
-node scripts/release-transaction.mjs abort --version v3.0.2 --superseded-by v3.0.3
+node packages/core/release/commands/release-transaction.mjs inspect --version v3.0.2
+node packages/core/release/commands/release-transaction.mjs recover --version v3.0.2
+node packages/core/release/commands/release-transaction.mjs finalize --version v3.0.2
+node packages/core/release/commands/release-transaction.mjs abort --version v3.0.2 --superseded-by v3.0.3
 ```
 
 The CLI is a diagnostic and local repair surface. It reports the durable
 `state_ref`, but remote durable-ref writes and public Git ref finalization are
-owned by `actions/promote-buildchain-ref`, because that action runs inside the
+owned by `actions/release/promotion/ref`, because that action runs inside the
 same governed GitHub permissions and branch-protection checks as release
 promotion. In other words, CLI `finalize` can mark the local transaction state
 complete after valid evidence; the machine-operated public finalization path is

package/docs/release-activation-transaction.md

@@ -13,7 +13,7 @@ The canonical order is:
 5. `public-readback`
 6. `evidence-synthesized`
 
-`packages/core/release-activation-transaction.js` is the executable authority.
+`packages/core/release/release-activation-transaction.js` is the executable authority.
 Every transaction binds an exact product source SHA, exact reviewed site source
 SHA, tag, channel, version, environment, artifact-set root, and the three
 repository owners. A later phase cannot pass while an earlier phase is

package/docs/release-candidate.md

@@ -59,7 +59,7 @@ release candidate consumed the caller-supplied family evidence exactly.
 Promotion workflows that should not rebuild artifacts can enable:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3
+- uses: kungfu-systems/buildchain/actions/release/promotion/ref@v3
   with:
     token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
     sha: ${{ needs.build.outputs.publish-source-sha }}
@@ -111,11 +111,10 @@ finished uploading evidence, the resolver waits up to ten minutes for the exact
 merged PR's successful workflow run and paired artifacts. Polling remains bound
 to the PR/head identity; timeout or a sibling run still fails closed.
 
-The public promotion router preserves the requested `vN` or `vN-alpha` ref as
-audit metadata, but binds the router to GitHub's selected reusable-workflow SHA
-and resolves each remaining floating shell/runtime ref exactly once. Every
-later checkout and delegated promotion receives those immutable SHAs, so a
-channel tag moving during the run cannot mix two Buildchain revisions.
+The public promotion entry selects one execution runtime through the shared
+[Runtime entry contract](runtime-entry.md). Entry and execution commits may differ.
+Every later job prepares that selection without resolving another Buildchain ref
+or checking entry/runtime SHA equality.
 
 ## Resume from an existing candidate run
 
@@ -128,7 +127,7 @@ See GitHub's [reusable workflow rerun behavior](https://docs.github.com/en/actio
 and [workflow rerun identity rules](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs).
 
 The supported recovery boundary is a new `workflow_dispatch` (or another new
-caller event) that invokes `release-candidate-promote.yml` and supplies the old
+caller event) that invokes `public-release-promote.yml` and supplies the old
 candidate run explicitly:
 
 ```yaml
@@ -139,12 +138,10 @@ on:
       candidate-run-id: { required: true, type: string }
       target-sha: { required: true, type: string }
       expected-tree: { required: true, type: string }
-      candidate-runtime-sha: { required: true, type: string }
-      buildchain-runtime-sha: { required: true, type: string }
-
+      runtime-ref: { required: true, type: string }
 jobs:
   resume:
-    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@<exact-current-buildchain-sha>
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
     permissions:
       actions: write
       checks: write
@@ -153,22 +150,20 @@ jobs:
       pull-requests: write
     secrets: inherit
     with:
-      buildchain-ref: ${{ inputs.buildchain-runtime-sha }}
-      channel: alpha
-      target-ref: alpha/v3/v3.0
-      target-sha: ${{ inputs.target-sha }}
-      artifact-name: product
-      artifact-patterns: product-package-*
-      release-candidate-workflow-file: build.yml
-      release-candidate-workflow-name: Build
-      resume-candidate-repository: ${{ github.repository }}
-      resume-candidate-run-id: ${{ inputs.candidate-run-id }}
-      resume-expected-workflow-file: build.yml
-      resume-expected-workflow-name: Build
-      resume-expected-source-tree: ${{ inputs.expected-tree }}
-      resume-expected-candidate-runtime-sha: ${{ inputs.candidate-runtime-sha }}
-      resume-buildchain-runtime-sha: ${{ inputs.buildchain-runtime-sha }}
-      publish-transaction-override: true
+      runtime-ref: ${{ inputs.runtime-ref }}
+      request-json: >-
+        {"schema":"buildchain.promotion-request/v1",
+        "channel":"alpha", "target-ref":"alpha/v4/v4.1",
+        "target-sha":${{ toJSON(inputs.target-sha) }},
+        "artifact-name":"product", "artifact-patterns":"product-package-*",
+        "release-candidate-workflow-file":"build.yml",
+        "release-candidate-workflow-name":"Build",
+        "resume-candidate-repository":${{ toJSON(github.repository) }},
+        "resume-candidate-run-id":${{ toJSON(inputs.candidate-run-id) }},
+        "resume-expected-workflow-file":"build.yml",
+        "resume-expected-workflow-name":"Build",
+        "resume-expected-source-tree":${{ toJSON(inputs.expected-tree) }},
+        "publish-transaction-override":true}
 ```
 
 `resume-expected-candidate-root` may replace `resume-expected-source-tree`, or
@@ -277,7 +272,7 @@ pre-build/artifact evidence into the wrapper:
 ```yaml
 jobs:
   promote:
-    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v3
     with:
       buildchain-channel: auto
       buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json
@@ -321,8 +316,7 @@ and payload bytes. It can read those inputs through
 permission, or provider write permission. Buildchain validates the aggregate
 digest and exact source binding before it seals a capability. Exactly one of
 the supplied aggregate, consumer command, or explicit no-Gate decision is
-allowed. Buildchain still requires caller-owned RC evidence, an exact authority
-runtime and source SHA, a repository-local publisher workflow, matching npm
+allowed. Buildchain still requires caller-owned RC evidence, an exact source SHA and prepared execution runtime, a repository-local publisher workflow, matching npm
 target/package identity or exact caller-bound GitHub Release target, and a
 qualifying control-plane audit.
 

package/docs/release-governance.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-08
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-6
   product: Codex
@@ -80,16 +80,16 @@ Buildchain implements the same governance loop with:
 - `.github/workflows/self-build-release-verify-compat.yml` for PR verification;
 - `.github/workflows/self-release-promote.yml` for post-verify ref
   promotion; this workflow dogfoods the declarative
-  `release-candidate-promote.yml` wrapper and does not hand-wire resolver,
+  `public-release-promote.yml` wrapper and does not hand-wire resolver,
   artifact download, publish-gate, or promote action steps;
 - Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so
   the promote action generates KFD-1 witnesses, KFD-2 public claim JSON, and
   KFD-3 collaboration-interface witnesses from the final version-state workspace
   before release passport finalization. The witness hashes therefore bind to the
   exact published package and site facts from
-  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release
+  `packages/core/adoption/buildchain-kfd-claims.js` instead of relying on prose release
   notes;
-- `actions/promote-buildchain-ref` for branch, tag, version-state, and
+- `actions/release/promotion/ref` for branch, tag, version-state, and
   governance checks;
 - package-manager adapters that can update version state for pnpm, npm, and
   yarn style repositories;
@@ -154,7 +154,7 @@ continue from the same SHA without another native build or an administrator
 merge bypass.
 
 Repositories may also expose a small caller workflow around
-`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,
+`.github/workflows/public-ops-release-governance.yml@v3`. Pass `branch`,
 `candidate-sha`, and `apply`, and provide `governance-token` through the caller's
 secrets. The reusable workflow uploads the JSON reconciliation receipt.
 
@@ -250,7 +250,7 @@ Two independent thin workflows continuously qualify the published channels.
 runs the root project's real install, build, and verify lifecycle.
 `self-build-stable-dogfood.yml` calls `build.yml@v4` with only the nested fixture's
 `config-path`, including native and Linux container builds. Project settings
-live in TOML; the called workflow binds its exact runtime SHA and configuration
+live in TOML; the selected runtime records its execution SHA and configuration
 root into the build receipts. Separate workflow validation allows each channel
 to advance independently during a breaking producer-first release.
 
@@ -548,7 +548,7 @@ sealed publication authority can finish its machine-verified bookkeeping. The
 dry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.
 
 Buildchain provides the reusable
-`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a
+`.github/workflows/public-ops-dev-auto-merge.yml` workflow for repositories that want a
 scheduled or manual "merge ready dev PRs" pass. The consumer repository owns
 the trigger schedule, but the merge decision is declared through workflow
 inputs: target dev branch, required status/check names, ready and block labels,
@@ -631,13 +631,13 @@ complete interface are bound into `contractRoot`; the receipt additionally
 binds the caller commit/tree and both workflow digests.
 
 ```sh
-node .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs check \
+node .buildchain/runtime/packages/core/contracts/commands/workflow-call-contract.mjs check \
   --caller-root . \
   --caller-workflow .github/workflows/self-release-new-version-compat.yml \
   --caller-repository kungfu-systems/example \
   --job promote \
-  --callee-root .buildchain/workflow-contract-runtime \
-  --callee-workflow .github/workflows/release-candidate-promote.yml \
+  --callee-root .buildchain/runtime \
+  --callee-workflow .github/workflows/public-release-promote.yml \
   --callee-repository kungfu-systems/buildchain \
   --trusted-event workflow_dispatch \
   --trusted-event pull_request:closed \
@@ -645,11 +645,11 @@ node .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs ch
   --output .buildchain/workflow-call-receipts/release-new-version.json
 ```
 
-The checkout at `.buildchain/workflow-contract-runtime` must use the same
-40-character SHA written in the caller's `uses:` edge. To accept an intentional
-contract change, first run without `--expected-contract-root`, review the full
-diagnostic and exact coordinates, then replace only the committed root. The
-ordinary PR check runs this command before any candidate or promotion dispatch.
+Use the runtime prepared by the central entry for this offline contract audit.
+The caller persists a floating entry; its resolved API definition is distinct
+from the selected execution runtime. To accept an intentional contract change,
+review the full diagnostic and source coordinates before replacing the committed
+contract root. This audit does not add a runtime-SHA equality gate to execution.
 Local pre-commit rehearsal may add `--allow-dirty`; that result is marked
 `receiptReusable: false` and cannot replace the clean exact-source receipt.
 
@@ -662,7 +662,7 @@ command = "cargo test --workspace --locked"
 ```
 
 Consumers that want Buildchain to own the check wrapper can call
-`.github/workflows/check.yml@v3`. The wrapper runs the declared
+`.github/workflows/public-build-check.yml@v4`. The wrapper runs the declared
 `lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when
 either declaration is missing or the command exits non-zero.
 
@@ -689,7 +689,7 @@ on:
 
 jobs:
   merge-dev:
-    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-dev-auto-merge.yml@v3
     permissions:
       contents: write
       pull-requests: write
@@ -714,17 +714,17 @@ status to failure, while the merge group must still produce its own final check.
 
 ## Buildchain Patrol
 
-`dev-pr-auto-merge.yml` remains the focused merge primitive. For repositories
+`public-ops-dev-auto-merge.yml` remains the focused merge primitive. For repositories
 that want a stable day-to-day operations contract, Buildchain also exposes a
 patrol workflow family:
 
 | Workflow                                         | Intended cadence                   | Default intent                                                                             |
 | ------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------ |
-| `.github/workflows/patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |
-| `.github/workflows/patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |
-| `.github/workflows/patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |
-| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
-| `.github/workflows/stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |
+| `.github/workflows/public-ops-patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |
+| `.github/workflows/public-ops-patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |
+| `.github/workflows/public-ops-patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |
+| `.github/workflows/public-ops-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
+| `.github/workflows/public-ops-stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |
 
 The cadence names describe patrol intensity, not release cadence:
 
@@ -764,7 +764,7 @@ on:
 
 jobs:
   patrol:
-    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-patrol-daily.yml@v3
     with:
       dry-run: false
       max-actions: 1
@@ -775,7 +775,7 @@ Weekly and monthly callers use the matching wrapper:
 ```yaml
 jobs:
   patrol:
-    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-patrol-weekly.yml@v3
     with:
       dry-run: true
 ```
@@ -846,7 +846,7 @@ with one required approving review, required GitHub Actions checks, administrato
 enforcement, conversation resolution, no force pushes, and no deletions. Each
 target uses the exact check set, GitHub App identity, and strictness declared by
 the governance authority descriptor. The
-reusable `release-candidate-promote.yml` wrapper defaults
+reusable `public-release-promote.yml` wrapper defaults
 `branch-protection-bypass-apps` to `github-actions`, which lets the workflow's
 automation identity apply generated version-state or post-publish channel
 bookkeeping after the reviewed channel PR has merged. Direct
@@ -941,18 +941,18 @@ or release-material SHAs, but new tags are source-bound.
 
 Every Buildchain publish model that can run registry side effects must bind the
 publish entrypoint to an immutable `publish-gate/*` source lock. The reusable
-`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and
+`public-release-promote.yml@v3` wrapper creates or updates that gate ref and
 passes `require-publish-source-lock`, `publish-source-ref`,
 `publish-source-sha`, and `publish-source-locked` to
 `promote-buildchain-ref`. Direct action callers must pass the same four inputs
 from the reusable build outputs. Workflows that only collect passports or run
 dry-run package checks do not move publish refs and are not publish-gate
-publication models. A dry-run of `release-candidate-promote.yml` computes and
+publication models. A dry-run of `public-release-promote.yml` computes and
 reports the exact `publish-gate/*` source lock that a real promotion would use,
 but does not read, create, or move that ref.
 
 Semver GitHub Release publication is owned by `promote-buildchain-ref`, not by
-consumer shell glue. Consumers normally use the `release-candidate-promote.yml`
+consumer shell glue. Consumers normally use the `public-release-promote.yml`
 generated channel router, where GitHub Release publication is enabled by default and can be
 disabled with `github-release: false`; the wrapper passes that declaration to
 the action. After the publish transaction reaches `complete`, Buildchain creates
@@ -1012,10 +1012,10 @@ When debugging or extending release behavior, read in this order:
 1. `docs/release-flow.md`
 2. `.github/workflows/self-build-release-verify-compat.yml`
 3. `.github/workflows/self-release-promote.yml`
-4. `.github/workflows/release-candidate-promote.yml`
-5. `.github/workflows/.release-candidate-promote.yml`
-6. `actions/promote-buildchain-ref/README.md`
-7. `actions/promote-buildchain-ref/src/`
+4. `.github/workflows/public-release-promote.yml`
+5. `.github/workflows/.release-promote.yml`
+6. `actions/release/promotion/ref/README.md`
+7. `actions/release/promotion/ref/src/`
 8. `docs/migration-inventory.md`
 
 That path gives the policy first, the workflow trigger second, and the action

package/docs/release-passport.md

@@ -307,7 +307,7 @@ bound to evidence" without reading release notes.
 
 For Buildchain's own releases, public release claims are not authored in prose
 inside the workflow. The source registry is
-`packages/core/buildchain-kfd-claims.js`, published as
+`packages/core/adoption/buildchain-kfd-claims.js`, published as
 `dist/site/kfd-claims.json` and exported as
 `@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the
 version-invariant source of public claims and collaboration surfaces: it does
@@ -340,7 +340,7 @@ participant-facing collaboration/control surface is closed over its declared
 interface.
 
 For Buildchain itself, the declared interface starts in
-`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The
+`packages/core/adoption/buildchain-kfd-claims.js`, not in this Markdown file. The
 registry enumerates public human/agent surfaces across manuals, schema and
 standard metadata, package exports, site-consumption contracts, workflows, and
 actions. `dist/site/kfd-claims.json` is the packaged machine-readable form used

package/docs/release-promotion-request.md

@@ -0,0 +1,57 @@
+---
+status: draft
+period: ongoing
+theme: release-promotion-api
+doc_type: manual
+source_level: local-files
+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-09
+  visible_context: Current promotion workflows, JSON schemas, request binding implementation and focused tests.
+  invisible_context_boundary: No alpha publication or production promotion was performed.
+---
+
+# Release promotion request
+
+`public-release-promote.yml` is the public API. Its single `request-json` input
+uses [`promotion-request-v1.schema.json`](../contracts/promotion-request-v1.schema.json).
+The schema owns field types and defaults. Unknown fields, stringified booleans,
+historical command hooks and caller-supplied internal authority fields are rejected.
+
+```yaml
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4-alpha
+    with:
+      request-json: |
+        {
+          "schema": "buildchain.promotion-request/v1",
+          "target-ref": "alpha/v4/v4.1",
+          "target-sha": ${{ toJSON(github.sha) }},
+          "dry-run": true
+        }
+    secrets: inherit
+```
+
+Serialize dynamic values with `toJSON` so quotes, newlines, numbers and booleans
+retain their original meaning. Permissions remain an explicit caller responsibility;
+an input cannot grant a job credentials or provider authority.
+
+The public workflow selects one runtime through the central runtime entry, admits
+the consumer source and constructs the internal
+[`promotion-invocation-v1.schema.json`](../contracts/promotion-invocation-v1.schema.json)
+document. QUALIFY, APPLY and SETTLE prepare that selected runtime and retain their
+separate job permissions. Later nodes validate source, artifact and publication
+evidence without comparing Buildchain SHAs.
+
+Buildchain dogfood and external consumers use the same `@v4` or `@v4-alpha`
+public entry. The entry commit owns the API shell; the selected runtime owns
+business actions, modules and resources. A transient `runtime-ref` can select a
+repaired train while preserving the original publication source and evidence.
+See [Runtime entry](runtime-entry.md) for selection precedence and recovery.