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

package/docs/dev-delivery-warrant.md

@@ -7,17 +7,21 @@ source_level: local-files
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-09-11
+review_state: unreviewed
+last_reviewed: 2026-09-20
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-11
+  generated_at: 2026-09-20
   invisible_context: not asserted
 ---
 
 # Dev Delivery Warrant Queue
 
+Warrant, lease, proof and provider fields on this page are internal authority
+contracts. Consumers use the shared normal pipeline and recover by exact attempt;
+none of these fields or helper workflows belongs in consumer YAML or TOML.
+
 Buildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a
 durable, non-preemptive delivery turn without replacing GitHub Merge Queue as
 the final protected-ref authority.
@@ -321,7 +325,7 @@ The reader rejects an empty run conclusion, nonterminal run or job state,
 unsupported job conclusion, or pull-request state outside `open|closed` before
 it can seal product-owned cleanup evidence.
 
-The public two-phase workflow keeps heartbeat authority in a fourth,
+The internal two-phase workflow keeps heartbeat authority in a fourth,
 GitHub-hosted job on a runner domain distinct from admission, native execution,
 evidence sealing, and finalization. Each successful heartbeat records the exact
 expected-old and next authority state roots plus its receipt root. The
@@ -340,13 +344,10 @@ write-normalize-observe-remutate cycle: `transferRoot`,
 `providerAttempt`, and, when expiry cleanup was required, the independent
 `providerTerminalReadbackRoot`.
 
-Buildchain's tracked self-delivery caller invokes
-`kungfu-systems/buildchain/.github/workflows/public-ops-dev-auto-merge.yml@v4-alpha`.
-The durable selector remains the floating alpha channel, the repository keeps
-matching `.buildchain/contract-lock.json` (`v4`) and
-`.buildchain/alpha-contract-lock.json` (`v4-alpha`), and a train runtime may be
-selected only through the trusted, non-persistent `workflow_dispatch` input.
-No candidate SHA or train ref is persisted in the caller.
+Buildchain's self entry is the same generated `buildchain.yml` used by other
+consumers. Internal `.ops-dev-auto-merge.yml` execution retains its authority
+boundaries. The optional repaired runtime belongs only to exact-attempt recovery;
+no candidate SHA or train ref is persisted in the consumer caller.
 
 Only complete `verified-native-qualification` evidence can mint a new Landing
 Warrant. Migrated `legacy-compatibility-only` evidence may preserve an exact
@@ -402,7 +403,7 @@ native proof or reuse authority. Phase-less native candidates remain invalid.
 
 ## Workflow rollout and rollback
 
-The reusable `public-ops-dev-auto-merge.yml` supports three explicit rollout modes:
+The internal `.ops-dev-auto-merge.yml` component retains three rollout modes for implementation qualification:
 
 - `off` preserves the previous exact-head admission controller;
 - `shadow` qualifies the source and emits a read-only queue submission plan;
@@ -423,12 +424,12 @@ The reusable `public-ops-dev-auto-merge.yml` supports three explicit rollout mod
   timestamped proof bytes, but it retains the immutable active Warrant and its
   originally selected proof instead of rewriting or rejecting that attempt.
   Each candidate also retains the exact successful source workflow run. If a
-  controller discovers that another candidate owns the active Warrant, a
-  configured consumer workflow is dispatched immediately for that exact PR,
+  controller discovers that another candidate owns the active Warrant, an
+  admitted internal continuation is dispatched immediately for that exact PR,
   head, source run, Assignment and Initiative, source identity and patch,
   plan, closure, dependency, toolchain, environment, affected paths, delivery
   class, and priority; the candidate is not left waiting for a patrol cron.
-  The shipped Buildchain caller and native template configure this handoff path
+  The internal workflow and native fixture configure this handoff path
   and accept the same complete input contract. A historical phase-less owner
   uses the distinct `legacy-phase-less-active-owner` command path. That path
   carries the exact queue state root observed before its duplicate submission,

package/docs/dev-qualification-patrol.md

@@ -1,26 +1,32 @@
 ---
-status: preview
+status: active
 period: ongoing
 theme: dev-qualification-patrol
-doc_type: architecture-and-usage
+doc_type: technical-reference
 source_level: local-files
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-03
+review_state: unreviewed
+last_reviewed: 2026-09-20
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-03
-  visible_context: Existing Buildchain Shifu Gate receipts, Kungfu Dev Patrol, Alpha preflight, candidate patrol, and GitHub failed-job rerun semantics.
-  invisible_context_boundary: No credentials, private logs, or private configuration were used.
+  generated_at: 2026-09-20
+  visible_context: Current workflow taxonomy, shared consumer entry contract, and retained internal qualification controller.
+  invisible_context_boundary: No new hosted qualification or external consumer migration is claimed.
 ---
 
-# Dev Qualification Patrol
+# Internal Dev Qualification Patrol
 
-Buildchain provides a reusable controller for repositories whose development
-branch advances faster than a heavy cross-platform qualification workflow can
+This document describes the internal
+[`.ops-dev-qualification-patrol.yml`](../.github/workflows/.ops-dev-qualification-patrol.yml)
+component. Consumers use the generated normal and attempt recovery callers;
+they do not add a patrol workflow, schedule, dispatch payload, or controller
+script. See the [Golden Path](getting-started.md).
+
+The retained controller handles internal qualification for a development
+branch that advances faster than a heavy cross-platform qualification workflow can
 settle. The controller keeps no external queue. On every wakeup it derives the
 only pending item from the current source-branch head and maintains these
 states:
@@ -45,14 +51,13 @@ without consuming the shared native runners.
 
 ## Exact-source and priority contract
 
-Call `.github/workflows/public-ops-dev-qualification-patrol.yml` from a thin consumer
-workflow after the lightweight preflight, Dev Patrol, and declared priority
-workflows complete. Add an offset schedule as recovery for delayed or missed
-GitHub events. Repeated wakeups are idempotent.
+Internal orchestration owns wakeups from preflight, qualification and priority
+workflow completion. Repeated wakeups are idempotent. Event recovery belongs
+to the runtime; this component does not require an extra consumer caller.
 
 The controller requires a successful preflight whose `head_sha` equals the
 current source head. It dispatches the heavy workflow on the source branch and
-adds a controller-owned `source-sha` input. The consumer must reject the run
+adds a controller-owned `source-sha` input. The internal qualification adapter must reject the run
 before qualification if that input differs from the workflow event SHA. This
 closes the race where the branch advances between observation and workflow
 startup. The heavy reusable Gate workflow then receives the exact SHA as its
@@ -97,10 +102,10 @@ is false. Before writing, it re-resolves the branch and all workflow state and
 requires the action and source SHA to match the read-only observation. A race
 fails closed and the next event recomputes from current truth.
 
-Start a consumer in dry-run mode. Its observation and mutation decisions are
-retained as exact-source artifacts with a canonical decision root. Enabling
-mutation requires a repository token that can write Actions; no contents,
-pull-request, tag, release, package, or publication permission is used.
+The internal dry-run mode retains observation and mutation decisions as
+exact-source artifacts with a canonical decision root. Its separately scoped
+mutation credential can write Actions; it does not receive contents,
+pull-request, tag, release, package, or publication authority.
 
 The controller does not merge a PR, publish an Alpha, create a tag, create a
 release, or settle a Release Passport. Once Dev and Alpha preflight evidence

package/docs/getting-started.md

@@ -6,163 +6,104 @@ doc_type: technical-guide
 source_level: local-files
 confidence: high
 sensitivity: public
-evidence_grade: A
+evidence_grade: B
 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: not asserted
+  generated_at: 2026-09-20
+  visible_context: Schema-2 initializer, shared caller generator and local validation code.
+  invisible_context_boundary: Initialization does not prove hosted publication or provider authorization.
 ---
 
 # Buildchain Golden Path
 
-This path is for a repository maintainer adopting Buildchain for the first
-time. It takes about 15–30 minutes and ends with five inspectable outcomes: an
-exact package pin, a declared project type, a valid local configuration, a thin
-reusable workflow caller, and a Release Passport inspection.
+A consumer owns its product source and one schema-2 TOML declaration.
+Buildchain generates two product-independent YAML callers: normal execution
+and exact-attempt recovery. The published runtime owns delivery and publication.
 
-Use this page for the first successful pass. Move to the advanced manuals only
-after the local checks below are green.
+## Install and initialize
 
-## 1. Create a clean consumer and install an exact version
+In an existing npm product repository with a version in `package.json`:
 
-```bash
-consumer_dir="$(mktemp -d)"
-cd "$consumer_dir"
-npm init -y
-buildchain_version="$(npm view @kungfu-tech/buildchain version)"
-pnpm add -D "@kungfu-tech/buildchain@$buildchain_version"
-pnpm exec buildchain --version
+```sh
+pnpm add -D --save-exact @kungfu-tech/buildchain
+pnpm exec buildchain init --type npm --package-manager pnpm
 ```
 
-The package manager records the exact resolved version in `package.json` and
-the lockfile. Review that version before committing it; do not leave a floating
-range in a release repository.
+Use `--type binary` for a CMake product or `--type paper` for a PDF product.
+`package`, `native`, and `publication-artifact` select the corresponding product
+kind. `anchored-package` selects an npm product whose version is changed by a
+reviewed source update rather than automatic version rewriting.
 
-## 2. Choose the project type and initialize
+Initialization writes:
 
-Start with `package` for a Node package. Other supported types are `native`,
-`web-surface`, `infra-contract`, `publication-artifact`, and
-`anchored-package`.
+- `.buildchain/buildchain.toml`: products, artifacts, publication targets,
+  version files, channel routes and protected review policy;
+- `.github/workflows/buildchain.yml`: the normal `public-ops-pipeline.yml` caller;
+- `.github/workflows/buildchain-recover.yml`: the `public-ops-recover.yml` caller;
+- a managed consumer section in `AGENTS.md`;
+- `release.json` as version source when a binary or Paper product has no package version.
 
-```bash
-pnpm exec buildchain init --type package --package-manager pnpm
-```
-
-Inspect the two generated files before continuing:
-
-```bash
-sed -n '1,220p' .buildchain/buildchain.toml
-sed -n '1,220p' .github/workflows/build.yml
-```
-
-`buildchain.toml` owns repository lifecycle declarations. The workflow is a
-thin caller of Buildchain's reusable workflow; it is not a second release
-implementation.
+Both YAML files are byte-identical across npm, binary and Paper projects.
+Edit product install, build, verification and artifact declarations in TOML to
+match your existing source. Keep the generated caller bytes unchanged. There
+are no consumer publication commands, hidden controller scripts or provider
+request payloads to maintain.
 
-## 3. Validate the local contract
+## Validate locally
 
-```bash
-pnpm exec buildchain validate \
-  --require-version-state \
-  --require-lifecycle-stages install,build,verify
+```sh
+pnpm exec buildchain validate --require-version-state
 pnpm exec buildchain doctor --json
 ```
 
-If the generated lifecycle commands do not match the repository, edit only
-`.buildchain/buildchain.toml`, then rerun both checks. See
-[Lifecycle Protocol](lifecycle-protocol.md) for the normative fields.
-
-## 4. Inspect the reusable workflow and release dry-run
-
-The generated caller contains one reusable `uses:` edge and no inputs.
-Project choices belong in `.buildchain/buildchain.toml`; `@v4` or `@v4-alpha`
-selects the runtime channel:
-
-```bash
-rg -n 'uses:' .github/workflows/build.yml
-pnpm exec buildchain release --dry-run \
-  --target-ref alpha/v4/v4.0 \
-  --json
-```
-
-The dry-run explains legal source refs, tags, version state, and publication
-effects. It does not move refs, edit files, or publish packages.
-
-## 5. Create and inspect a local Release Passport example
-
-This example creates a source-bound local Passport through the public Node API,
-then reads it through the CLI. It is learning evidence, not publication
-authority.
-
-```bash
-mkdir -p .buildchain/golden-path
-node --input-type=module <<'EOF'
-import fs from "node:fs";
-import { createReleasePassport } from "@kungfu-tech/buildchain";
-
-const passport = createReleasePassport({
-  repository: "example/consumer",
-  tag: "v0.1.0-alpha.0",
-  sourceSha: "a".repeat(40),
-  assets: [{ name: "consumer.tgz", sha256: "b".repeat(64) }],
-});
-fs.writeFileSync(
-  ".buildchain/golden-path/buildchain.release.json",
-  `${JSON.stringify(passport, null, 2)}\n`,
-);
-EOF
-
-pnpm exec buildchain inspect release \
-  --passport .buildchain/golden-path/buildchain.release.json \
-  --json
-```
-
-For a real release, the protected Buildchain workflow creates the Passport from
-the exact source, artifact, controller, and publication evidence. See
-[Release Passport](release-passport.md); do not promote this local example.
-
-## You are done when
-
-- the dependency and lockfile contain one exact Buildchain version;
-- `.buildchain/buildchain.toml` declares the intended project type and lifecycle;
-- `validate` and `doctor` succeed;
-- `.github/workflows/build.yml` remains a thin reusable-workflow caller;
-- the release dry-run and local Passport inspection both return structured output.
-
-The repository test `pnpm run check:golden-path` reproduces this path in a new
-temporary consumer using the locally packed Buildchain package.
-
-## Choose the next manual
-
-| Intent | Next page |
-| --- | --- |
-| Change lifecycle commands or version files | [Lifecycle Protocol](lifecycle-protocol.md) |
-| Configure native matrices, runners, caches, or artifacts | [Reusable Build Surface](reusable-build-surface.md) |
-| Look up a command | [Generated CLI Reference](cli-reference.md) |
-| Import the Node toolkit | [Generated Node API Reference](node-api-reference.md) |
-| Understand protected branches and tags | [Release Flow](release-flow.md) |
-| Verify published evidence | [Release Passport](release-passport.md) |
-
-## Troubleshooting
-
-- `already exists`: initialization is no-overwrite by default. Inspect the
-  existing files; use `--force` only for an intentional replacement.
-- missing lifecycle stage: add the named stage to
-  `.buildchain/buildchain.toml`; do not weaken the validation command.
-- package release-age policy: add a temporary, package-and-version-specific
-  `minimumReleaseAgeExclude`, then remove it after the normal window.
-- unsure about syntax: run `buildchain <path> --help`. Help is intercepted
-  before command dispatch and is side-effect free at every governed path.
-
-## Small glossary
-
-- **project type**: the repository shape selected by `buildchain init`.
-- **lifecycle**: repository-owned install, build, verify, and publish commands.
-- **reusable workflow**: Buildchain-owned GitHub Actions control plane called by
-  a thin consumer workflow.
-- **Release Passport**: source- and artifact-bound release evidence, not a
-  release trigger.
-- **train ref**: a temporary validation runtime; never a production dependency.
+For npm products, `--require-lifecycle-stages install,build,verify` also checks
+that every product declares those commands. Binary and Paper products can omit
+an install stage. Run your product's declared build and verification commands
+before opening the first PR.
+
+`validate` checks the schema, declared version sources and both caller files.
+`doctor` also checks the Git repository and, for npm products, package-manager
+discovery. Local success establishes configuration validity; hosted qualification
+and publication have their own source-bound results.
+
+## Use the normal release path
+
+Commit the generated files and product source. Complete repository permissions,
+branch protection, independent reviewer configuration and provider authorization
+once. When present, tool-maintained stable and Alpha contract locks select the
+published runtime. Without a lock, the published entry uses its own exact runtime
+commit; initialization does not invent a lock or require one to select that default.
+Existing npm Trusted Publishing remains in use; normal releases do not require
+an interactive npm login or a manually supplied publishing token.
+
+Open a PR along a route declared in TOML: a feature branch into development,
+development into Alpha, or Alpha into release. The same normal caller handles
+build, protected delivery, publication, provider readback and next-development.
+Follow the workflow's actual result and published Release Passport.
+
+For an interrupted attempt, run `buildchain-recover.yml` with its exact attempt.
+Supply a repaired runtime only when a runtime repair is needed. Do not supply
+replacement source, artifacts or provider-effect parameters.
+
+## Migrating old callers
+
+Schema-1 product-specific workflow callers are not generated by this initializer.
+The old `web-surface` and `infra-contract` initialization modes are outside the
+current schema-2 npm/binary/Paper pipeline; initialization rejects them before
+writing files. Their internal product modules remain available to maintainers.
+
+Existing unrelated workflows or conflicting files stop initialization before
+any write. `--force` replaces the declared generated files only; it does not
+delete other workflows or follow symlinks. Move product commands into TOML and
+remove obsolete consumer orchestration as part of an explicit migration.
+
+See the [standard examples](../templates/minimal-consumer/),
+[workflow catalog](workflow-catalog.md), [CLI reference](cli-reference.md), and
+[Release Passport](release-passport.md).
+
+`pnpm run check:golden-path` packs the local package, installs it in a temporary
+consumer, initializes and validates the shared caller pair, and executes the
+fixture product build and check. It performs no hosted publication.

package/docs/github-artifact-attestation.md

@@ -1,6 +1,6 @@
 ---
 status: draft
-period: 2026-07
+period: ongoing
 theme: buildchain-linux-artifact-provenance
 doc_type: protocol
 source_level: code-and-official-docs
@@ -8,17 +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-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-24
-  visible_context: Buildchain source, tests, GitHub Actions documentation, and actions/attest documentation
-  invisible_context: Model internals and provider-side implementation details are not visible
+  generated_at: 2026-09-20
+  visible_context: Current Buildchain taxonomy and consumer contract, retained attestation implementation and protocol documentation.
+  invisible_context_boundary: No fresh provider attestation or hosted qualification is asserted by this documentation update.
 ---
 
 # GitHub-native Linux Artifact Attestation
 
+This is an internal protocol reference. Consumers use the generated normal and
+recovery callers described in the [Golden Path](getting-started.md); they do
+not add a promotion or attester workflow, prepare policy JSON, or select source
+and artifact roots. The retained internal component is
+[`.release-artifact-attestation.yml`](../.github/workflows/.release-artifact-attestation.yml).
+
 Buildchain can bind a Linux release artifact to its original compiler run, exact
 source revision, platform manifest, Release Passport, and an immutable
 Buildchain attester workflow. GitHub's OIDC identity and artifact attestation
@@ -68,7 +74,7 @@ still binding both directions.
 
 ## GitHub Permissions and Runtime Pins
 
-Both caller and reusable workflow grant only:
+The internal attester invocation and its reusable component grant only:
 
 ```yaml
 permissions:
@@ -85,9 +91,11 @@ itself must also be called at its exact signer-bootstrap commit. The signer
 commit and the later Buildchain runtime commit are separately bound so the
 first v3 integration never relies on a mutable or self-referential workflow ref.
 
-## Prepare the Release Passport
+## Internal Release Passport preparation
 
-Create one input document for each Linux artifact and seal it as a policy:
+The runtime owns policy preparation. Maintainers can inspect the retained
+policy contract with the following low-level tooling; these commands are not
+consumer lifecycle steps. One input document describes each Linux artifact:
 
 ```bash
 buildchain create github-artifact-attestation-policy \
@@ -110,74 +118,17 @@ buildchain collect github-release \
   # ...the existing release inputs
 ```
 
-The build, Passport, and attestation jobs must stay in the same workflow run.
-The release-candidate build declares both the subject and the already-merged
-signer bootstrap commit. The Buildchain runtime remains the exact runtime ref
-used by the build workflow and may be a later commit:
-
-```yaml
-with:
-  github-artifact-attestation-subject-path: dist/kungfu-linux-x64.tar.gz
-  github-artifact-attestation-signer-sha: <exact-signer-bootstrap-sha>
-  github-artifact-attestation-platform-id: linux-x64
-```
-
-For release promotion, prefer the integrated v3 route. The policy must already
-be present in the downloaded release-candidate payload:
-
-```yaml
-permissions:
-  actions: write
-  artifact-metadata: write
-  attestations: write
-  checks: write
-  contents: write
-  id-token: write
-  issues: write
-
-jobs:
-  promote:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
-    with:
-      github-release: true
-      release-passport: true
-      github-artifact-attestation-policy-json: .buildchain/release-candidate/payload/<artifact>/policy.json
-      github-artifact-attestation-environment: buildchain-artifact-attestation
-```
-
-Promotion binds the policy into the Passport, stages only digest-matching data,
-calls the public signer entry, verifies the provider identity a second time, and
-publishes immutable bundle, predicate, verification, evidence, and receipt
-assets beside the release artifact. A same-name Release asset with different
-bytes is rejected instead of overwritten.
-
-Low-level callers may call the reusable attester directly after their Passport
-job. The public entry selects the execution runtime through the same contract as
-build and release. Provider signer identity and subject digests remain mandatory:
+The retained attestation mechanism binds the original compiler execution,
+sealed candidate payload, platform manifest and Passport. Internal promotion
+stages only digest-matching data, invokes the internal signer, verifies provider
+identity, and retains the bundle, predicate, verification evidence and receipt.
+A same-name published asset with different bytes is rejected.
 
-```yaml
-jobs:
-  attest-linux:
-    needs: [build-linux, release-passport]
-    permissions:
-      actions: read
-      artifact-metadata: write
-      attestations: write
-      contents: read
-      id-token: write
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-artifact-attestation.yml@v4
-    with:
-      evidence-run-id: ${{ github.run_id }}
-      source-sha: ${{ github.sha }}
-      subject-artifact-name: linux-release
-      subject-relative-path: libnode-linux-x64.tar.gz
-      platform-manifest-artifact-name: linux-platform-manifest
-      platform-manifest-relative-path: manifest.json
-      release-passport-artifact-name: release-passport
-      release-passport-relative-path: buildchain.release.json
-      policy-json: ${{ needs.release-passport.outputs.github-attestation-policy-json }}
-      evidence-artifact-name: linux-attestation-evidence
-```
+Signer bootstrap identity and the runtime used to build the product remain
+separate immutable facts. These fields are derived and checked inside the
+runtime. Neither `public-release-promote.yml` nor
+`public-release-artifact-attestation.yml` is a current consumer API; new wiring
+must not copy the former v3 input sets into an extra workflow.
 
 ## Verify Online and Offline
 
@@ -209,8 +160,7 @@ expected statement, or GitHub reports a self-hosted signer.
 
 ## Qualification Policy
 
-New protocol work qualifies on the Buildchain v3 alpha line first. The v2
-development branch is not a supported landing target. Production
-adoption waits for the exact v3 implementation commit to pass the repository
-suite and a real GitHub OIDC/Sigstore qualification run, including the negative
-cases above. A successful local fixture is necessary but not sufficient.
+Protocol changes land through the protected `dev/v4/v4.1` workflow and require
+qualification of the exact published runtime before consumer adoption. Local
+fixtures validate the protocol's negative cases; they do not substitute for a
+real GitHub OIDC/Sigstore qualification run or prove provider publication.