@kungfu-tech/buildchain 4.1.3-alpha.9 → 4.1.4-alpha.0

package/docs/web-surface-deployments.md

@@ -8,16 +8,23 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-11
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-09
+  generated_at: 2026-09-20
   invisible_context_boundary: No credentials, private logs, or unpublished deployment values are included.
+  visible_context: Current two-entry consumer contract and retained internal implementation references.
 ---
 
 # Web-Surface Deployment Contract
 
+This is a reference for the retained internal web deployment engine. It is not
+schema-2 consumer onboarding: web is not an additional product type or public
+reusable entry in the minimal contract. Current consumers use the shared
+normal/recovery pair. The deployment configurations, request envelopes and
+provider ports below belong to the internal engine or historical integrations.
+
 Buildchain supports `project.type = "web-surface"` for repositories that publish
 sites, docs, product pages, operator consoles, or browser apps. These projects
 need auditable deployment semantics, but they are not package release lines and
@@ -179,18 +186,8 @@ Buildchain validates these hard constraints:
 
 ### Floating Runtime Contract Lock
 
-Web-surface repositories can consume the stable Buildchain workflow shell with a
-floating ref, such as:
-
-```yaml
-jobs:
-  web:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-web.yml@v4
-    with:
-      contract-lock: .buildchain/contract-lock.json
-      build-command: pnpm build
-      artifact-path: dist
-```
+The internal web component retains runtime-lock validation before build or
+provider planning. It is not invoked through a separate consumer web caller.
 
 The caller repository commits `.buildchain/contract-lock.json` after reviewing an
 accepted Buildchain runtime SHA and contract digest. The reusable workflow then
@@ -737,259 +734,24 @@ cleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,
 actor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an
 auditable no-op when no aliases are requested.
 
-## Reusable Workflow Shape
-
-Buildchain ships `.github/workflows/public-release-web.yml` for repositories that want
-the standard PR review and promotion flow without copying bespoke glue:
-
-```yaml
-jobs:
-  web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-web.yml@v4
-    with:
-      build-command: npm run build
-      verify-command: npm run check
-      artifact-path: dist
-```
-
-The reusable workflow maps GitHub events to Buildchain web-surface semantics:
-
-| Event | Buildchain behavior |
-| --- | --- |
-| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |
-| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |
-| `pull_request` closed for a matching release PR | verify the release intent, then wait for the protected `main` push; do not plan or apply production from `refs/pull/*/merge` |
-| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |
-| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate from the protected mainline ref |
-| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |
-
-The optional `runtime-ref` parameter selects a transient execution runtime.
-An empty value uses the selected consumer contract lock or entry default.
-All preparation goes through the shared [Runtime entry](runtime-entry.md).
-A maintainer can expose a manual input for train validation or repair:
-
-```yaml
-on:
-  workflow_dispatch:
-    inputs:
-      runtime-ref:
-        description: "Temporary Buildchain runtime ref for trusted manual validation"
-        required: false
-        default: ""
-
-jobs:
-  web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-web.yml@v4
-    with:
-      runtime-ref: ${{ inputs.runtime-ref || '' }}
-      build-command: pnpm run build
-      verify-command: pnpm run check
-      artifact-path: dist
-```
-
-Only repository actors with write,
-maintain, or admin permission may use a non-empty runtime override. Train refs
-such as `train/v4/v4.1/site-source-of-truth` are temporary validation refs, not
-stable production dependencies or pending merge targets. They may remain for a
-retention window after release as a fast-use and rollback channel, with old
-trains handled by periodic Buildchain cleanup. The web-surface deployment
-manifest records the resolved runtime SHA as `runtimeId` and the stable
-rollback ref as `rollbackPointer`.
-
-The workflow deliberately plans and emits manifests by default. Live mutation is
-opt-in per channel:
-
-```yaml
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-jobs:
-  web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-web.yml@v4
-    with:
-      build-command: pnpm run build
-      verify-command: pnpm run check
-      artifact-path: dist
-      preview-apply: true
-      preview-cleanup-apply: true
-      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions
-      staging-apply: true
-      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions
-      production-apply: false
-      production-release-on-main: false
-      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
-      production-environment: production
-      release-feedback-actor-privacy: public
-```
-
-When enabled, Buildchain owns the full release apply state machine:
-
-- PR preview deploys run `deploy-apply --dry-run false` with the preview role
-  and update a single idempotent PR comment.
-- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role
-  only.
-- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging
-  role, then write a staging release feedback passport artifact and comment the
-  associated merged PR with the staging URL, source SHA, artifact identity, run
-  URL, and failure context when apply did not complete.
-- When `production-release-on-main=true`, successful staging applies open or
-  update a Buildchain-owned release PR from
-  `release/<channel>-<short-sha>` to `main`, unless the current push already
-  came from a matching release PR merge. The release PR contains one empty
-  release-intent commit, carries `production-release-label`, and includes the
-  staging URLs, source SHA, artifact hash, and staging release-passport artifact
-  link in the PR body.
-- Production release PR handoff is permission-aware. Staging apply and staging
-  health remain successful even when the repository or organization has
-  GitHub Actions workflow permissions set to read-only. In that case Buildchain
-  records `release-pr-status=permission-denied`, uploads the release PR handoff
-  summary/body plus staging release passport artifacts, and writes an exact
-  manual `gh pr create` command to the step summary. Set
-  `fail-on-release-pr-error=true` only when PR creation failure should fail the
-  whole workflow.
-- Release pull requests that match the configured production gate get a
-  Buildchain review comment with the staging URL and production target, so the
-  operator can verify staging from the PR page and use merge as the approval
-  action. Consumers do not need to hand-write `gh pr create` or production
-  release-intent glue.
-- `production-apply=true` enables the production capability; it does not request
-  production for every event. Ordinary `main` pushes remain staging-only and
-  can create or update a release PR. Production runs only when the capability
-  is enabled and either:
-  - a `workflow_dispatch` passes `production-approved=true` and the triggering
-    actor currently has `write`, `maintain`, or `admin` permission; or
-  - `production-release-on-main=true` and the `main` push commit is associated
-    with exactly one same-repository, merged release pull request matching
-    `production-release-label` and `production-release-head-prefix`.
-  The production job is then gated by the configured GitHub Environment.
-- Before production artifact download, Buildchain assembles a managed sealed
-  publication capability from the exact source/runtime SHAs, production plan
-  and artifact hash, a qualifying pre-publication controller receipt, the
-  trusted manual or reviewed-release-PR decision, production Environment and
-  AWS role target, an ephemeral-runner receipt, and a fresh nonce. Production
-  revalidates that capability against the downloaded plan before it downloads
-  product bytes. The later AWS OIDC exchange remains the provider's final
-  transaction-time authorization decision and fails closed before deploy apply.
-- The `publication-*-json` inputs are an advanced external-evidence
-  compatibility path, not a prerequisite for the standard release-PR or trusted
-  manual mechanisms. External evidence must now include
-  `publication-gate-aggregate-json`; supplying only a partial set still fails
-  closed.
-- Production apply writes a production release feedback passport artifact and
-  comments the release PR with the production URL, source SHA, artifact
-  identity, run URL, rollback pointer, and failure context when apply did not
-  complete.
-
-The feedback passport records the release responsibility chain:
-
-- human decision actor;
-- trigger actor;
-- runner/execution actor;
-- OIDC/deploy identity reference;
-- decision type and time;
-- source event, PR number, merge commit, and required gate label/head-prefix.
-
-`release-feedback-actor-privacy` controls actor values in the passport and
-comments. `public` records GitHub actor names, `redacted` records only the actor
-role, and `private-ref` records a stable private reference hash without exposing
-the actor name.
-
-For release-PR publishing, callers opt in explicitly:
-
-```yaml
-jobs:
-  web-surface:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-web.yml@v4
-    with:
-      build-command: npm run build
-      verify-command: npm run check
-      artifact-path: dist
-      production-apply: true
-      production-release-on-main: true
-      production-release-label: buildchain-release
-      production-release-head-prefix: release/
-      production-release-branch-channel: production
-      production-release-pr-mode: auto
-      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
-      production-environment: production
-```
-
-Keep `production-apply` enabled in the caller when the repository supports
-production. Buildchain derives whether the current event may use that
-capability: an ordinary `main` push plans and applies staging, a matching
-reviewed release PR merge authorizes production, and an approved trusted manual
-dispatch authorizes production. Inputs from an untrusted event cannot turn that
-decision on.
-
-`production-release-pr-mode` controls the post-staging handoff:
+## Internal workflow authority
 
-| Mode | Behavior |
-| --- | --- |
-| `auto` | Generate release PR facts, create/update the empty release-intent branch and PR, and label it when token permissions allow. This is the default. |
-| `summary-only` | Generate and upload release PR facts, body, passport evidence, and manual command, but do not call the GitHub PR API. |
-| `disabled` | Record a disabled handoff and skip release PR API calls. |
-
-Automatic release PR creation normally uses the workflow `github.token`.
-Consumers that cannot enable "GitHub Actions can create and approve pull
-requests" globally should prefer the first-class GitHub App path. Pass the App
-client id as an input and the private key as a reusable workflow secret; Buildchain
-creates an installation token inside the release PR job and uses it only for the
-release-intent branch, PR, and label operations:
-
-```yaml
-with:
-  production-release-app-client-id: ${{ vars.KUNGFU_RELEASE_APP_CLIENT_ID }}
-secrets:
-  production-release-app-private-key: ${{ secrets.KUNGFU_RELEASE_APP_PRIVATE_KEY }}
-```
-
-When either side of the App configuration is missing, Buildchain does not hide
-that behind the fallback `github.token`. The handoff JSON and job summary report
-`status: "app-token-unavailable"` with an `appTokenStatus` such as
-`missing-client-id`, `missing-private-key`, or `create-failed`, and still include
-the manual PR creation command. If the repository intentionally uses another
-narrow token, pass it through `production-release-pr-token`.
+`.release-web.yml` retains the web engine's job and credential boundaries.
+It is an internal component, without a public product-specific alias. Its source,
+artifact, runtime, deployment-plan and environment ports must come from admitted
+runtime state; consumers do not write a third web workflow or pass these ports
+through their generated normal/recovery pair.
 
-If a repository already generates its own narrow token or PAT, it can still pass
-that through `production-release-pr-token`:
-
-```yaml
-secrets:
-  production-release-pr-token: ${{ secrets.BUILDCHAIN_RELEASE_PR_TOKEN }}
-```
+Preview, staging and production keep separate provider permissions and evidence.
+Production requires exact source/artifact identity and independent admission;
+untrusted event inputs cannot grant provider mutation. A successful staging
+receipt does not prove production, and an API response does not replace provider
+readback. Provider failures preserve the previously valid public authority.
 
-Token priority is: generated GitHub App installation token,
-`production-release-pr-token`, then `github.token`.
-
-The merge button becomes the production approval only for a PR that carries the
-release label and comes from the configured source-branch prefix. Ordinary pull
-requests merged into `main` deploy staging and open a release-intent PR; merging
-that release PR triggers production. A release PR merge push does not open
-another release PR.
-
-Apply-only inputs are validated before the caller build or verification command
-runs. If the current event would run preview, staging, or production apply,
-missing role inputs, a production apply without `production-approved=true` on
-manual dispatch, or a manual actor without repository write authority fail
-immediately instead of spending the build and plan jobs first.
-
-Callers must grant `id-token: write` for OIDC role assumption. Preview comments
-need `pull-requests: write`. Automatic release PR creation also needs
-`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can
-create the release branch, write the empty release-intent commit, open or update
-the PR, and apply the release label. If these permissions are unavailable,
-Buildchain degrades the release handoff instead of marking a successful staging
-deployment as failed, unless `fail-on-release-pr-error=true`. The AWS roles remain caller-owned and
-should be scoped by channel: preview can mutate only preview resources, staging
-can mutate only staging resources, and production can mutate only production
-resources.
-
-Apply mode fails closed when the deploy config still contains placeholder AWS
-targets such as `pending-preview-distribution`. Planning can use placeholders
-for dry-run-only design work, but live apply requires concrete bucket and
-CloudFront distribution identifiers.
+The component's historical release-PR, cleanup and feedback mechanisms remain
+internal implementation contracts. Their workflow inputs are not schema-2 TOML
+fields or recommended consumer setup. Provider configuration still requires its
+own explicit authority and cannot be inferred from product metadata or evidence.
 
 ## Site Repository Shape
 

package/docs/workflow-catalog.md

@@ -21,9 +21,9 @@ ai_provenance:
 
 Generated from `architecture/workflow-taxonomy.json`. Every workflow has one canonical implementation; alternate paths and historical forwarding aliases are rejected.
 
-Public workflows own the consumer API. Component workflows own reusable multi-job topology. Self workflows own Buildchain repository automation. Actions own execution steps; JS adapters and Rust/WASM own implementation.
+The two public workflows own normal pipeline execution and exact-attempt recovery. Component workflows are internal runtime implementation, including once-only setup and the dispatch signing service; consumers do not wire these components. Self workflows are the generated consumer pair. Actions own execution steps; JS adapters and Rust/WASM own implementation.
 
-Names use `public-<category>-<purpose>.yml`, `.<category>-<purpose>.yml`, and the generated self callers `buildchain.yml` and `buildchain-recover.yml`, with categories `build`, `release`, and `ops`. The primary build API and backbone use `build.yml` and `.build.yml`.
+Names use `public-ops-pipeline.yml`, `public-ops-recover.yml`, internal `.<category>-<purpose>.yml`, and the generated self callers `buildchain.yml` and `buildchain-recover.yml`. Categories are `build`, `release`, and `ops`; the internal build engine retains `.build.yml`.
 
 Register ownership before adding a workflow. `pnpm run check:workflows` validates source, calls, required CI integration and independent review ownership. `pnpm run generate:workflows` regenerates this catalog.
 
@@ -31,53 +31,53 @@ Register ownership before adding a workflow. `pnpm run check:workflows` validate
 
 | Workflow | Category | Invocation | Status | Purpose |
 | --- | --- | --- | --- | --- |
-| [build.yml](../.github/workflows/build.yml) | build | reusable | active | Buildchain Channel Build |
-| [public-build-adopter-qualification.yml](../.github/workflows/public-build-adopter-qualification.yml) | build | reusable | active | V4 Adopter Delivery |
-| [public-build-check.yml](../.github/workflows/public-build-check.yml) | build | reusable | active | Buildchain Check |
-| [public-build-demo.yml](../.github/workflows/public-build-demo.yml) | build | reusable | active | Buildchain Declarative Binary Auditable Demo |
-| [public-build-publication.yml](../.github/workflows/public-build-publication.yml) | build | reusable | active | Buildchain Publication Artifact |
-| [public-build-stage-capsule-canary.yml](../.github/workflows/public-build-stage-capsule-canary.yml) | build | reusable | active | V4 Stage Capsule Canary |
-| [public-ops-alpha-candidate-patrol.yml](../.github/workflows/public-ops-alpha-candidate-patrol.yml) | ops | reusable | active | Buildchain Dev to Alpha Candidate Patrol |
-| [public-ops-bootstrap.yml](../.github/workflows/public-ops-bootstrap.yml) | ops | reusable | active | Buildchain Universal Bootstrap |
-| [public-ops-dev-auto-merge.yml](../.github/workflows/public-ops-dev-auto-merge.yml) | ops | reusable | active | Dev PR Auto Merge |
-| [public-ops-dev-qualification-patrol.yml](../.github/workflows/public-ops-dev-qualification-patrol.yml) | ops | reusable | active | Buildchain Dev Qualification Patrol |
-| [public-ops-housekeeping.yml](../.github/workflows/public-ops-housekeeping.yml) | ops | reusable | active | Engineering Housekeeper |
-| [public-ops-observed-evidence.yml](../.github/workflows/public-ops-observed-evidence.yml) | ops | reusable | active | Patrol Observed Evidence |
-| [public-ops-patrol-daily.yml](../.github/workflows/public-ops-patrol-daily.yml) | ops | reusable | active | Buildchain Patrol Daily |
-| [public-ops-patrol-monthly.yml](../.github/workflows/public-ops-patrol-monthly.yml) | ops | reusable | active | Buildchain Patrol Monthly |
-| [public-ops-patrol-weekly.yml](../.github/workflows/public-ops-patrol-weekly.yml) | ops | reusable | active | Buildchain Patrol Weekly |
-| [public-ops-patrol.yml](../.github/workflows/public-ops-patrol.yml) | ops | reusable | active | Buildchain Patrol |
 | [public-ops-pipeline.yml](../.github/workflows/public-ops-pipeline.yml) | ops | reusable | active | Buildchain pipeline |
 | [public-ops-recover.yml](../.github/workflows/public-ops-recover.yml) | ops | reusable | active | Buildchain recovery |
-| [public-ops-release-governance.yml](../.github/workflows/public-ops-release-governance.yml) | ops | reusable | active | Release Governance Reconcile |
-| [public-ops-stable-candidate-patrol.yml](../.github/workflows/public-ops-stable-candidate-patrol.yml) | ops | reusable | active | Buildchain Stable Candidate Patrol |
-| [public-ops-tail-reseal.yml](../.github/workflows/public-ops-tail-reseal.yml) | ops | reusable | active | V4 Retained Candidate Tail Reseal |
-| [public-ops-warrant-cancel.yml](../.github/workflows/public-ops-warrant-cancel.yml) | ops | reusable | active | Dev Delivery Warrant Queued Candidate Cancel |
-| [public-ops-warrant-close.yml](../.github/workflows/public-ops-warrant-close.yml) | ops | reusable | active | Dev Delivery Warrant Close |
-| [public-release-artifact-attestation.yml](../.github/workflows/public-release-artifact-attestation.yml) | release | reusable | active | Buildchain GitHub Artifact Attestation |
-| [public-release-oci-compose-preview.yml](../.github/workflows/public-release-oci-compose-preview.yml) | release | reusable | active | Buildchain OCI Compose Preview |
-| [public-release-paper.yml](../.github/workflows/public-release-paper.yml) | release | reusable | active | Buildchain Paper Release |
-| [public-release-promote.yml](../.github/workflows/public-release-promote.yml) | release | reusable | active | Release Candidate Promote |
-| [public-release-propagation.yml](../.github/workflows/public-release-propagation.yml) | release | reusable | active | Release Propagation |
-| [public-release-signing-authority.yml](../.github/workflows/public-release-signing-authority.yml) | release | dispatch-service | active | Buildchain Artifact Signing Authority |
-| [public-release-tail.yml](../.github/workflows/public-release-tail.yml) | release | reusable | active | Declarative Release Tail |
-| [public-release-web.yml](../.github/workflows/public-release-web.yml) | release | reusable | active | Buildchain Web Surface |
 
 ## component
 
 | Workflow | Category | Invocation | Status | Purpose |
 | --- | --- | --- | --- | --- |
+| [.build-adopter-qualification.yml](../.github/workflows/.build-adopter-qualification.yml) | build | reusable | active | V4 Adopter Delivery |
+| [.build-candidate.yml](../.github/workflows/.build-candidate.yml) | build | reusable | active | Buildchain Channel Build |
+| [.build-check.yml](../.github/workflows/.build-check.yml) | build | reusable | active | Buildchain Check |
 | [.build-demo-adapter.yml](../.github/workflows/.build-demo-adapter.yml) | build | reusable | active | Buildchain Auditable Demo |
+| [.build-demo.yml](../.github/workflows/.build-demo.yml) | build | reusable | active | Buildchain Declarative Binary Auditable Demo |
 | [.build-gate-profile.yml](../.github/workflows/.build-gate-profile.yml) | build | reusable | active | Buildchain Shifu Gate Profile |
+| [.build-publication.yml](../.github/workflows/.build-publication.yml) | build | reusable | active | Buildchain Publication Artifact |
+| [.build-stage-capsule-canary.yml](../.github/workflows/.build-stage-capsule-canary.yml) | build | reusable | active | V4 Stage Capsule Canary |
 | [.build.yml](../.github/workflows/.build.yml) | build | reusable | active | Buildchain Build |
+| [.ops-alpha-candidate-patrol.yml](../.github/workflows/.ops-alpha-candidate-patrol.yml) | ops | reusable | active | Buildchain Dev to Alpha Candidate Patrol |
+| [.ops-bootstrap.yml](../.github/workflows/.ops-bootstrap.yml) | ops | reusable | active | Buildchain Universal Bootstrap |
+| [.ops-dev-auto-merge.yml](../.github/workflows/.ops-dev-auto-merge.yml) | ops | reusable | active | Dev PR Auto Merge |
+| [.ops-dev-qualification-patrol.yml](../.github/workflows/.ops-dev-qualification-patrol.yml) | ops | reusable | active | Buildchain Dev Qualification Patrol |
 | [.ops-git-sync.yml](../.github/workflows/.ops-git-sync.yml) | ops | reusable | active | sync remote git |
+| [.ops-housekeeping.yml](../.github/workflows/.ops-housekeeping.yml) | ops | reusable | active | Engineering Housekeeper |
+| [.ops-observed-evidence.yml](../.github/workflows/.ops-observed-evidence.yml) | ops | reusable | active | Patrol Observed Evidence |
+| [.ops-patrol-daily.yml](../.github/workflows/.ops-patrol-daily.yml) | ops | reusable | active | Buildchain Patrol Daily |
+| [.ops-patrol-monthly.yml](../.github/workflows/.ops-patrol-monthly.yml) | ops | reusable | active | Buildchain Patrol Monthly |
+| [.ops-patrol-weekly.yml](../.github/workflows/.ops-patrol-weekly.yml) | ops | reusable | active | Buildchain Patrol Weekly |
+| [.ops-patrol.yml](../.github/workflows/.ops-patrol.yml) | ops | reusable | active | Buildchain Patrol |
 | [.ops-pipeline-delivery.yml](../.github/workflows/.ops-pipeline-delivery.yml) | ops | reusable | active | Internal pipeline delivery |
 | [.ops-pipeline-execute.yml](../.github/workflows/.ops-pipeline-execute.yml) | ops | reusable | active | Internal pipeline execution |
+| [.ops-release-governance.yml](../.github/workflows/.ops-release-governance.yml) | ops | reusable | active | Release Governance Reconcile |
+| [.ops-stable-candidate-patrol.yml](../.github/workflows/.ops-stable-candidate-patrol.yml) | ops | reusable | active | Buildchain Stable Candidate Patrol |
+| [.ops-tail-reseal.yml](../.github/workflows/.ops-tail-reseal.yml) | ops | reusable | active | V4 Retained Candidate Tail Reseal |
+| [.ops-warrant-cancel.yml](../.github/workflows/.ops-warrant-cancel.yml) | ops | reusable | active | Dev Delivery Warrant Queued Candidate Cancel |
+| [.ops-warrant-close.yml](../.github/workflows/.ops-warrant-close.yml) | ops | reusable | active | Dev Delivery Warrant Close |
+| [.release-artifact-attestation.yml](../.github/workflows/.release-artifact-attestation.yml) | release | reusable | active | Buildchain GitHub Artifact Attestation |
 | [.release-authority.yml](../.github/workflows/.release-authority.yml) | release | reusable | active | Buildchain Sealed Publication Authority |
 | [.release-binary-assets.yml](../.github/workflows/.release-binary-assets.yml) | release | reusable | active | Buildchain Binary Release Assets |
+| [.release-candidate-promote.yml](../.github/workflows/.release-candidate-promote.yml) | release | reusable | active | Release Candidate Promote |
+| [.release-oci-compose-preview.yml](../.github/workflows/.release-oci-compose-preview.yml) | release | reusable | active | Buildchain OCI Compose Preview |
+| [.release-paper.yml](../.github/workflows/.release-paper.yml) | release | reusable | active | Buildchain Paper Release |
 | [.release-pipeline-products.yml](../.github/workflows/.release-pipeline-products.yml) | release | reusable | active | Internal pipeline product publication |
 | [.release-pipeline-version.yml](../.github/workflows/.release-pipeline-version.yml) | release | reusable | active | Internal pipeline version preparation |
 | [.release-promote.yml](../.github/workflows/.release-promote.yml) | release | reusable | active | Release Candidate Promote Advanced |
+| [.release-propagation.yml](../.github/workflows/.release-propagation.yml) | release | reusable | active | Release Propagation |
+| [.release-signing-authority.yml](../.github/workflows/.release-signing-authority.yml) | release | dispatch-service | active | Buildchain Artifact Signing Authority |
+| [.release-tail.yml](../.github/workflows/.release-tail.yml) | release | reusable | active | Declarative Release Tail |
+| [.release-web.yml](../.github/workflows/.release-web.yml) | release | reusable | active | Buildchain Web Surface |
 
 ## self
 

package/docs/workflow-path-migration.md

@@ -1,5 +1,5 @@
 ---
-status: draft
+status: historical
 period: ongoing
 theme: workflow-path-migration
 doc_type: migration-guide
@@ -8,22 +8,28 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-06
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-05
+  generated_at: 2026-09-20
   visible_context: Exact GitHub channel refs and workflow files on 23 organization default branches
   invisible_context_boundary: Other branches, private or unlisted consumers and future floating ref updates were not established by this audit
 ---
 
 # Version-prefixed workflow path migration
 
+This page retains the dated 2026-09-05/06 migration observations. Its paths and
+channel readbacks are historical, not current consumer instructions. The current
+contract uses `public-ops-pipeline.yml` and `public-ops-recover.yml`; see
+[Getting started](getting-started.md). Former product-specific public workflows
+are now internal components, with no consumer compatibility aliases.
+
 This source change retires three filenames. Their reusable capabilities, inputs,
 outputs, jobs and permission envelopes remain at the canonical paths below.
 Keep the existing channel selector and dual contract-lock policy when migrating.
 
-| Retired path | Canonical path |
+| Retired path at that migration | Replacement observed at that migration |
 | --- | --- |
 | `v4-adopter-delivery.yml` | `public-build-adopter-qualification.yml` |
 | `v4-stage-capsule-canary.yml` | `public-build-stage-capsule-canary.yml` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.1.3-alpha.9",
+  "version": "4.1.4-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -192,8 +192,7 @@
     "ajv": "8.17.1",
     "prettier": "^3.9.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.0",
-    "yaml": "2.8.2"
+    "typescript": "^5.9.0"
   },
   "dependencies": {
     "@actions/artifact": "6.2.1",
@@ -202,6 +201,8 @@
     "@actions/glob": "0.7.0",
     "@electron/osx-sign": "1.3.3",
     "@kungfu-tech/kfd": "1.0.0-alpha.62",
-    "smol-toml": "1.7.0"
+    "acorn": "8.17.0",
+    "smol-toml": "1.7.0",
+    "yaml": "2.8.2"
   }
 }

package/packages/core/adoption/buildchain-kfd-claims.js

@@ -57,15 +57,15 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
 const WORKFLOW_AND_ACTION_FILES = Object.freeze([
   ".github/workflows/.build.yml",
   ".github/workflows/.release-promote.yml",
-  ".github/workflows/public-release-promote.yml",
+  ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/buildchain.yml",
   ".github/workflows/buildchain-recover.yml",
   ".github/workflows/public-ops-pipeline.yml",
   ".github/workflows/public-ops-recover.yml",
-  ".github/workflows/public-release-artifact-attestation.yml",
+  ".github/workflows/.release-artifact-attestation.yml",
   "actions/build/artifact/prepare-attestation/action.yml",
   "actions/build/artifact/prepare-attestation/index.js",
-  ".github/workflows/public-release-propagation.yml",
+  ".github/workflows/.release-propagation.yml",
   "actions/build/credential/macos-island/action.yml",
   "actions/build/credential/macos-island/index.js",
   "actions/release/promotion/ref/action.yml",
@@ -354,7 +354,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "packages/core/contracts/commands/buildchain-contract-lock.mjs",
         ".github/workflows/.build.yml",
         ".github/workflows/.release-promote.yml",
-        ".github/workflows/public-release-promote.yml",
+        ".github/workflows/.release-candidate-promote.yml",
         "docs/reusable-build-surface.md",
       ],
       artifactPaths: [
@@ -370,7 +370,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "actions/release/promotion/ref/action.yml",
         "packages/core/release/commands/ensure-github-release.mjs",
         ".github/workflows/.release-promote.yml",
-        ".github/workflows/public-release-promote.yml",
+        ".github/workflows/.release-candidate-promote.yml",
         "docs/release-governance.md",
       ],
       artifactPaths: [
@@ -384,7 +384,7 @@ export function createBuildchainPublicClaimDefinitions() {
       sourcePaths: [
         "packages/core/release/release-propagation.js",
         "packages/core/release/commands/release-propagation.mjs",
-        ".github/workflows/public-release-propagation.yml",
+        ".github/workflows/.release-propagation.yml",
         "docs/release-propagation.md",
       ],
       artifactPaths: [
@@ -399,7 +399,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "packages/core/publication/commands/npm-publish-transaction.mjs",
         "actions/release/promotion/ref/index.js",
         ".github/workflows/.release-promote.yml",
-        ".github/workflows/public-release-promote.yml",
+        ".github/workflows/.release-candidate-promote.yml",
         "docs/publish-transaction.md",
       ],
       artifactPaths: [

package/packages/core/adoption/cli/output.mjs

@@ -1,12 +1,4 @@
-import {
-  printJson,
-  readBooleanFlag,
-  readFlag,
-  readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
-} from "../../contracts/cli/options.mjs";
+import { printJson } from "../../contracts/cli/options.mjs";
 
 export function printKfdSchemaOrJson({ result, json }) {
   if (json) {

package/packages/core/adoption/cli/product-gate.mjs

@@ -1,17 +1,5 @@
 import path from "node:path";
-import {
-  checkKfdUpstreamFacts,
-  collectKfdAggregate,
-  collectKfdStatus,
-  collectKfdUpstreamFacts,
-  kfd1,
-  kfd2,
-  layout as buildchainLayout,
-  listKfdUpstreamRoles,
-  listKfdSchemas,
-  normalizeKfdStandardId,
-  readKfdSchema,
-} from "../kfd.js";
+import { readKfdSchema } from "../kfd.js";
 import {
   evaluateKfdProductGate,
   validateKfdProductGateResult,
@@ -21,8 +9,6 @@ import {
   readBooleanFlag,
   readFlag,
   readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
   writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 import { printKfdSchemaOrJson } from "./output.mjs";

package/packages/core/adoption/cli/project.mjs

@@ -1,13 +1,10 @@
 import { initBuildchainRepo } from "../commands/init-repo.mjs";
 import { validateBuildchainConfig } from "../../consumer/buildchain-config.js";
+import { validateConsumerWiring } from "../../consumer/contract/local-validation.js";
 import {
   printJson,
   readBooleanFlag,
   readFlag,
-  readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 
 export async function handleInitCommand(args) {
@@ -28,11 +25,13 @@ export async function handleValidateCommand(args) {
     .split(",")
     .map((entry) => entry.trim())
     .filter(Boolean);
-  printJson(
-    validateBuildchainConfig(readFlag(args, "cwd", process.cwd()), {
-      requireVersionState: readBooleanFlag(args, "require-version-state"),
-      requireLifecycleStages: lifecycleStages,
-    }),
-  );
+  const cwd = readFlag(args, "cwd", process.cwd());
+  const result = validateBuildchainConfig(cwd, {
+    requireVersionState: readBooleanFlag(args, "require-version-state"),
+    requireLifecycleStages: lifecycleStages,
+  });
+  if (result.config?.schema === 2)
+    result.consumer = validateConsumerWiring(cwd, result.config.path);
+  printJson(result);
   return;
 }

package/packages/core/adoption/cli/standards.mjs

@@ -1,23 +1,10 @@
 import path from "node:path";
-import {
-  checkKfdUpstreamFacts,
-  collectKfdAggregate,
-  collectKfdStatus,
-  collectKfdUpstreamFacts,
-  kfd1,
-  kfd2,
-  layout as buildchainLayout,
-  listKfdUpstreamRoles,
-  listKfdSchemas,
-  normalizeKfdStandardId,
-  readKfdSchema,
-} from "../kfd.js";
+import { kfd1, kfd2, readKfdSchema } from "../kfd.js";
 import {
   printJson,
   readBooleanFlag,
   readFlag,
   readJsonInput,
-  readRepeatedFlag,
   readRepeatedJsonInputs,
   writeJsonFile,
 } from "../../contracts/cli/options.mjs";