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

package/docs/stable-candidate-patrol.md

@@ -8,17 +8,23 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-14
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-14
+  generated_at: 2026-09-20
   visible_context: User-directed zero-delay self release policy, required provider evidence and regression tests.
   invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.
 ---
 
 # Stable Candidate Patrol
 
+This page describes the retained internal `.ops-stable-candidate-patrol.yml`
+mechanism. Current consumer release intent is a legal channel PR through the
+normal pipeline. Consumers do not add a scheduled stable caller or provider-token
+inputs. The policy and ledger fields below belong to internal or historical
+qualification, not schema-2 TOML extensions.
+
 Buildchain can treat every exact alpha as an independent stable candidate. A
 new alpha creates a new candidate; it does not silently revoke an older alpha
 that already completed its checks and soak interval.
@@ -102,68 +108,10 @@ release fact. Repositories that intentionally disable GitHub Releases omit
 `alpha-release` and declare their own exact-SHA workflow/status evidence; tag
 commit time remains the earliest possible soak start.
 
-`publish_at` and `timezone` are the auditable policy declaration. GitHub only
-starts scheduled workflows from caller-owned cron, so the thin caller keeps the
-matching UTC trigger:
-
-```yaml
-name: Stable Candidate Patrol
-
-on:
-  schedule:
-    - cron: "0 19 * * *" # 03:00 Asia/Shanghai
-  workflow_dispatch:
-    inputs:
-      release-now:
-        description: Exact alpha selected by explicit human authority
-        required: false
-        default: ""
-
-permissions:
-  contents: write
-  pull-requests: write
-  checks: read
-  statuses: read
-
-jobs:
-  stable:
-    uses: kungfu-systems/buildchain/.github/workflows/public-ops-stable-candidate-patrol.yml@v4
-    with:
-      release-now: ${{ inputs.release-now }}
-      dry-run: false
-    secrets:
-      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
-      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}
-```
-
-The promotion token must be repository-owned and capable of creating the
-machine ledger branch, exact source-lock branch, and pull request. Repositories
-that require an approving review can pass an independent repository-owned App,
-bot, or human service-account token as `approval-token`. The approval identity
-must differ from the promotion token identity that opens the PR. When no
-`approval-token` is passed, `auto-approve: true` falls back to the caller
-`github.token` and therefore requires GitHub Actions approval permission. The
-generated PR may use auto-merge, but it never bypasses the target branch
-checks. Callers can select `merge-method: merge`, `squash`, or `rebase`; the
-default is `merge` for compatibility. Unsupported values fail closed before
-GitHub is called.
-
-Before enabling `auto-approve` and `auto-merge`, the caller repository must
-provide one approval path and enable auto-merge:
-
-- pass an independent `approval-token`; or enable **Actions > General >
-  Workflow permissions > Allow GitHub Actions to create and approve pull
-  requests**, so the caller `github.token` can approve independently from the
-  promotion token that opened the PR;
-- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the
-  protected merge while required reviews and checks are still pending.
-
-GitHub rejects approval from the same identity that opened the pull request;
-Patrol propagates that review failure instead of reporting success.
-
-Patrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run
-must not report publication authority when GitHub accepted the HTTP request but
-returned a GraphQL error in the response body.
+The retained scheduling policy does not add a consumer-owned cron workflow.
+Any internal patrol mutation must use independently admitted write authority,
+revalidate its exact candidate and honor protected reviews/checks. An HTTP-success
+response with GraphQL errors is not accepted publication or landing authority.
 
 ## Exact-source stable promotion
 
@@ -181,8 +129,7 @@ passport, registry, tag, and floating-ref checks still run.
 
 ## Hold, revoke, and immediate release
 
-Persistent repository controls can be supplied as reusable-workflow inputs or
-repository variables:
+The internal component retains these persistent control ports:
 
 ```text
 BUILDCHAIN_STABLE_HOLD=true

package/docs/v4-adopter-delivery.md

@@ -8,24 +8,24 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-10
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-10
+  generated_at: 2026-09-20
   visible_context: Current adopter runtime, public workflow, composite actions and local execution tests.
   invisible_context_boundary: No hosted cross-platform execution or publication was performed for this documentation.
 ---
 
-# Public Adopter Delivery
+# Internal adopter qualification
 
-The public entry is `kungfu-systems/buildchain/.github/workflows/public-build-adopter-qualification.yml`.
-Consumers call its floating `@v4` or `@v4-alpha` channel and retain matching dual
-contract locks. The workflow owns the Linux, macOS and Windows job matrix;
-`actions/adoption` owns admission, conformance and reconciliation;
-`packages/core/adoption` owns driver coordination and exact readback.
+The internal `.build-adopter-qualification.yml` component owns its platform
+qualification jobs. `actions/adoption` owns admission, conformance and
+reconciliation; `packages/core/adoption` owns driver coordination and readback.
+Consumers use the shared normal/recovery pair and do not add an adopter-specific
+caller or qualification request to their TOML. See [Getting started](getting-started.md).
 
-## Public contract
+## Driver contract
 
 The [input schema](../contracts/v4-adopter-delivery-v1.schema.json) requires an
 exact protocol driver and artifact profile. Built-in driver selectors are
@@ -53,11 +53,11 @@ rooted evidence fail. The API has two operations: `run` and `verify`.
 ## Configuration
 
 The closed JSON input owns `driverSelector`, `artifactProfileSelector`, `request`
-and `context`. The public workflow's `input-path` names that document; CLI
+and `context`. The internal component's `input-path` names that document; CLI
 `--input`, `--readback` and `--output` arguments locate the request and evidence.
 Build configuration contains no duplicate Adopter Delivery declaration.
 
-Paths must stay inside the consumer repository. Workflow inputs name `consumer`
+For internal qualification, paths stay inside the admitted source. Component inputs name `consumer`
 and `input-path`. External qualification additionally requires the complete
 `consumer-repository`, exact `consumer-ref` and `invocation-source-path` tuple.
 The admission node verifies the checked-out source and defining runtime before
@@ -75,7 +75,7 @@ use the same runtime; each consumer must use the same source and input across
 platforms. Missing, duplicate, inconsistent or modified reports fail.
 Qualification has no production, provider or release authority.
 
-Buildchain's [thin dogfood caller](../.github/workflows/self-build-adopter-dogfood.yml)
-uses the same public entry. Historical parity research remains historical
-evidence; current qualification does not download old Buildchain packages or
-require an old release's bootstrap lineage.
+The former standalone adopter dogfood caller is historical. Current self product
+verification is declared in TOML and runs through the normal pipeline.
+Historical parity research remains historical evidence; it does not create an
+additional consumer public API or prove current hosted qualification.

package/docs/v4-declarative-release-tail-migration.md

@@ -8,31 +8,33 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-10
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-10
+  generated_at: 2026-09-20
   visible_context: Buildchain 4.1 source, architecture registries and local validation.
   invisible_context_boundary: No unpublished release or external consumer qualification is claimed.
 ---
 
-# Adopt the current release promotion API
+# Adopt the minimal consumer pipeline
 
-Call `public-release-promote.yml` with the closed `request-json` contract after
-the selected floating channel publishes this API. Keep both channel contract
-locks in the consumer repository. See [Promotion request](release-promotion-request.md)
-for the complete request and examples.
+Use the generated `buildchain.yml` and `buildchain-recover.yml` with the schema-2
+`.buildchain/buildchain.toml`. The shared public workflows are
+`public-ops-pipeline.yml` and `public-ops-recover.yml`. See
+[Getting started](getting-started.md) for initialization.
 
-The declaration-driven provider plane is the sole publisher. There is no mode
-switch, command-hook adapter or retained v3 execution path. Candidate identity,
-sealed artifact manifests, qualification and provider receipt roots determine
-execution and recovery.
+The normal pipeline owns the declaration-driven provider plane. Products declare
+build/verify commands, artifacts and publication targets in TOML. Consumers do not
+call a separate promotion workflow, supply request JSON, or implement release-tail
+command hooks. Candidate identity, sealed materials, qualification and provider
+receipts remain internal runtime authority.
 
-On interruption, resume the same candidate and transaction state. The workflow
-verifies the source, artifact and policy roots, then continues the incomplete
-operations. Completed publication recovery reads the existing evidence and
-preserves immutable product bytes.
+On interruption, select the exact attempt in the generated recovery workflow.
+An optional repaired runtime can continue remaining work while preserving the
+original source, published bytes and historical evidence. Do not combine
+candidate/run/Discussion/transaction selectors in consumer wiring.
 
-The 4.1 development merge is not an alpha publication. Consumer adoption waits
-for the corresponding published channel contract and refreshed locks.
+A development merge is not a published entry. Adopt the changed contract only
+after its selected channel publishes and qualifies it, then refresh the
+corresponding tool-maintained locks through the supported acceptance path.

package/docs/v4-production-release.md

@@ -1,22 +1,27 @@
 ---
-status: active
+status: historical
 period: ongoing
 theme: buildchain-v4-production-release
-doc_type: runbook
+doc_type: historical-reference
 source_level: repository-contracts + protected-provider-readback
 confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-08
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-08
-  invisible_context: Provider credentials and private provider state were not read.
+  generated_at: 2026-09-20
+  visible_context: Reclassified the retained v4.0 protocol and linked current pipeline guidance; historical body preserved.
+  invisible_context_boundary: No current provider state or credentials were inspected for this documentation change.
 ---
 
-# Buildchain v4 production release
+# Historical Buildchain v4.0 production release
+
+This document preserves the retired v4.0 workflow protocol. Current release
+operations use the shared pipeline and exact-attempt recovery described in
+[release governance](release-governance.md) and [release flow](release-flow.md).
 
 Buildchain v4 is the production release authority for the `v4.0` line. The
 protected source path is:

package/docs/v4-publication-rehearsal.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-09-11
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-16
+  generated_at: 2026-09-20
   visible_context: Exact v3 rehearsal runtime, v4 release-tail core, Stage Capsule contracts, public workflow and offline vectors.
   invisible_context_boundary: No credentials, private provider state, signed URLs or production publication receipts were read.
 ---
@@ -90,33 +90,18 @@ all three modes. The API delegates planning, transaction initialization, and
 execution to the same `release-tail-provider-plane` functions used by the
 production Action.
 
-## Config and public workflow
+## Internal configuration and component
 
-The consumer config is closed and effect-disabled:
+The internal `.release-tail.yml` component and rehearsal CLI consume the closed
+capsule, candidate, state and evidence paths. Simulation remains effect-disabled;
+provider mode requires independently verified authority and exact provider
+bindings. A rehearsal result never grants production publication authority.
 
-```toml
-[publication_rehearsal]
-contract = "buildchain-v4-publication-rehearsal-capsule/v1"
-capsule_path = "contracts/fixtures/v4-publication-rehearsal-v1/capsule.json"
-candidate_root = "contracts/fixtures/v4-publication-rehearsal-v1/candidate"
-state_path = ".buildchain/publication-rehearsal/state.json"
-evidence_path = ".buildchain/publication-rehearsal/evidence.json"
-effect_default = "disabled"
-```
-
-The public reusable
-[`public-release-tail.yml`](../.github/workflows/public-release-tail.yml) accepts the same
-capsule, candidate root, mode, state and evidence paths. Before publication,
-Buildchain dogfoods that public surface through the same floating `@v4` entry
-as external consumers. The shared entry selects the runtime from the transient
-parameter, consumer lock, or entry default, and prepares it in each job. The reusable is
-permission-neutral and the self-dogfood caller stays `contents: read`, passes
-`execute: false`, and therefore cannot inherit or synthesize production write
-authority. Effectful production callers must explicitly declare their own
-provider permission. Durable external consumers use `@v4` or `@v4-alpha`. Provider mode additionally requires the exact authority
-path. Provider bindings come from the capsule; an optional external bindings
-input is accepted only when its canonical exact root and payload equal the
-capsule binding. Ordinary calls default to `simulate`.
+The former `[publication_rehearsal]` consumer table and standalone public caller
+are not accepted schema-2 wiring. Current consumers use the normal pipeline and
+exact-attempt recovery. Internal fixtures retain the rehearsal inputs for
+mechanism qualification, without adding a third workflow or request JSON to a
+consumer repository.
 
 ## Offline portability vectors
 

package/docs/v4-stage-capsule.md

@@ -8,11 +8,11 @@ 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-5
   product: Codex
-  generated_at: 2026-08-10
+  generated_at: 2026-09-20
   invisible_context: not asserted
 ---
 
@@ -133,24 +133,18 @@ shadow-only: it does not skip a v3 production stage or move v3 authority.
 
 ## Three-platform qualification and Wave reconciliation
 
-`architecture/stage-capsule-qualification.json` closes the Wave 2
-qualification boundary. Buildchain and external repositories use the same
-Buildchain-owned public reusable workflow,
-`.github/workflows/public-build-stage-capsule-canary.yml`. Buildchain's caller is the thin
-`.github/workflows/self-build-public-consumer-dogfood.yml`; it has no steps, copied
-orchestration, local action, direct qualification invocation, or private
-consumer profile. The persisted caller uses `@v4`. Candidate validation passes
-`train/v4/v4.1/<capability>` as the transient `runtime-ref` input, through the
-same central selection and preparation entry as external consumers.
-
-The called workflow prepares the selected runtime and reads the consumer's
-tracked `.buildchain/buildchain.toml`, and executes only `install`, `build`,
-and `verify` on GitHub-hosted Linux x64, macOS arm64, and Windows x64 runners.
-Each stage binds its declared command, dependency edge, exact consumer source,
-platform, lifecycle manifest, summary, and real output roots into the campaign
-profile. `publish` is explicitly classified as a provider mutation and is not
-executed. The caller supplies only its stable consumer name and the real output
-paths; it does not copy the campaign orchestration.
+`architecture/stage-capsule-qualification.json` owns the Wave 2 qualification
+boundary. The former standalone public canary and self caller are historical;
+the retained `.build-stage-capsule-canary.yml` component is internal. Current
+Buildchain self verification runs the declared platform checks through the
+shared pipeline and schema-2 TOML, including `scripts/verify-product-platform.mjs`.
+Consumers do not copy campaign controllers or select provider/proof ports.
+
+The internal qualification mechanism binds install/build/verify commands,
+dependency edges, exact source, platform, lifecycle summaries and output roots.
+Provider publication is separate authority and is not granted by Capsule reuse.
+The following campaign invariants describe the retained internal mechanism;
+they do not claim a new hosted qualification run.
 
 The external seed retains `install` and `build` before an intentional late
 `verify` failure. A clean process reads the retained store, restores only the

package/docs/v4-tail-reseal.md

@@ -1,4 +1,27 @@
-# V4 retained-candidate tail reseal
+---
+status: active
+period: ongoing
+theme: retained-candidate-tail-reseal
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-20
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-20
+  visible_context: Internal tail-reseal contract, workflow taxonomy and shared recovery entry.
+  invisible_context_boundary: No hosted recovery or publication is claimed.
+---
+
+# Internal retained-candidate tail reseal
+
+Consumers recover through `buildchain-recover.yml` with an exact attempt and an
+optional repaired runtime. The request schema, ports and commands below describe
+internal mechanisms; they are not consumer setup or recovery inputs.
 
 Buildchain v4 can recover one narrowly defined late Alpha failure without
 rebuilding a qualified four-platform candidate. The recovery is not a cache hit
@@ -19,18 +42,14 @@ mismatch rejects reuse and requires a normal candidate build.
 - `install`, `build`, `verify`, `package`, and the ordinary platform matrix are
   skipped only when all 16 per-platform Stage Capsule decisions prove exact
   reuse. Capsule reuse has no external effects.
-- Only `macos-arm64:signing-finalization` may change payload bytes. The public
-  workflow verifies the retained macOS bytes before the effect and verifies the
+- Only `macos-arm64:signing-finalization` may change payload bytes. The internal
+  component verifies the retained macOS bytes before the effect and verifies the
   resealed bytes plus signing and release-tail readbacks afterward.
 - The signing token exists only in the macOS credential-island step. It is not
   stored in a Capsule, request, artifact, log, Passport, or receipt.
 - A successful run emits the existing
   `kungfu-buildchain-release-candidate-passport` contract. Tail reseal does not
   create a second candidate or release artifact class.
-- Durable callers use `@v4-alpha` during Alpha evaluation or `@v4` after stable
-  promotion. Exact SHAs are runtime evidence from `job.workflow_sha`, never a
-  persisted selector.
-
 ## CLI and Node API
 
 Plan locally from the deterministic data contract:
@@ -53,21 +72,16 @@ The Node exports are `@kungfu-tech/buildchain/v4-tail-reseal` for request and
 plan logic and `@kungfu-tech/buildchain/v4-tail-reseal-receipt` for terminal
 receipt creation and verification.
 
-## Reusable workflow
-
-Consumers invoke
-`kungfu-systems/buildchain/.github/workflows/public-ops-tail-reseal.yml@v4-alpha` from a
-trusted, same-repository workflow. The caller supplies the rooted request, the
-original candidate consumer-policy receipt, a reviewed macOS finalization
-command, and the explicitly named signing secret. The command must write:
+## Internal component
 
-- `.buildchain/tail-reseal/signing-provider-readback.json`
-- `.buildchain/tail-reseal/release-tail-provider-readback.json`
+`.ops-tail-reseal.yml` receives the runtime-admitted rooted request, original
+candidate policy receipt and explicitly scoped signing authority. Only its
+admitted signing-finalization tail may issue the provider effect. Its readback
+files bind the exact signing and release-tail provider roots. The component
+downloads retained material by exact authority identity and digest; a Stage
+Capsule cannot replay credentials or provider authority.
 
-Their byte digests must equal the roots fixed in the request. The workflow
-downloads the signing result by exact authority repository, run, artifact name,
-and archive digest; no credential or provider effect is replayed from a Stage
-Capsule.
+Consumers do not supply a signing command or call this component directly.
 
 The v3-to-v4 invariant mapping is recorded in
 [`architecture/tail-reseal-parity.json`](../architecture/tail-reseal-parity.json).