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

package/docs/release-tail-contract.md

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

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

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

package/docs/reusable-build-surface.md

@@ -24,10 +24,11 @@ single-project calls have no inputs:
 
 ```yaml
 permissions:
+  issues: write
   actions: read
   contents: read
-  issues: write
   id-token: write
+  attestations: write
 jobs:
   build:
     uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
@@ -117,7 +118,7 @@ Other optional project sections are:
 | `build.evidence` | Repository files containing gate and candidate-family evidence |
 
 Declarative signing targets continue to belong to `[signing.artifacts]`.
-The formal signing authority remains `authority/v3/v3.0/artifact-signing`
+The 4.1 formal signing contract requires `authority/v4/v4.1/artifact-signing`
 with the protected `buildchain-artifact-signing` environment.
 Credentials, authority profiles and signer identities cannot be supplied through
 that declaration. See [Release Candidate](release-candidate.md)
@@ -148,14 +149,16 @@ steps. Their shared behavior is owned by these composite actions:
 
 | Action | Owner responsibility |
 | --- | --- |
-| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |
-| `build-signing-request` | Unsigned requests and detached signing control inputs |
-| `build-verification-evidence` | Independent substage verification and failure evidence |
-| `build-attestation-policy` | Source-bound artifact attestation policy |
-| `build-agent-hub-evidence` | Agent Hub conformance evidence |
-| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |
-
-The backbone still owns install → build → verify order, job dependencies,
+| `resolve-build-plan` | Admission and complete plan |
+| `prepare-build-environment` | Source and toolchains |
+| `run-build-stage` | Ordered lifecycle and diagnostics |
+| `transfer-build-artifact` | Exact artifact coordinates and transport |
+| `sign-build-artifact` | Isolated signing and final bytes |
+| `attest-build-artifact` | Provider identity and final-byte attestation |
+| `finalize-build-result` | Complete coverage and final result |
+
+The backbone has six jobs: `plan`, `build-native`, `build-container`, `sign`,
+`attest` and `deliver`. It owns install → build → verify order, job dependencies,
 permissions, signing control, credential-island placement and final aggregation.
 A composite's internal receipt inputs transport already resolved facts; they
 are not additional reusable-workflow configuration inputs.
@@ -181,22 +184,25 @@ must verify the source, artifacts and receipts independently.
 
 ## Evidence and failure behavior
 
-The workflow retains runtime/source identity, build and diagnostics summaries,
-Release Candidate Passport, signing/finalization and controller receipt outputs.
-The public facade forwards those outputs from the single backbone execution.
+The backbone returns one rooted `result` containing source/runtime identity and
+exact provider references for payloads, diagnostics, summary, signing, attestation
+and candidate evidence. The public facade exposes that result plus the candidate
+and controller artifact names for direct `download-artifact` calls.
 Platform manifests include deterministic payload hashes; transport preserves
 hidden artifacts and provenance. Substage failure evidence is collected even
 when verify fails. Untrusted events cannot reach build runners.
 
-Signing authority and credential-island jobs remain separate from ordinary
-build execution. Imported signed bytes undergo consumer verification before
+The `sign` matrix uses separate ordinary artifact and protected macOS credential
+instances. The credential instance never checks out or executes consumer source.
+A hosted artifact instance may use its platform when final-byte verification
+requires that operating system; it receives no certificate or notary inputs. Imported signed bytes undergo consumer verification before
 manifests are recomputed. Release builds produce candidates; registry publishing
 belongs to the protected release path.
 
 ## Maintaining the contract
 
 Update the TOML parser and plan resolver, owner contracts, affected consumers
-and tests together. Run `node scripts/generate-channel-build-workflow.mjs`,
+and tests together. Run
 `pnpm run generate:workflows`, generated reference/site checks and the full
 `pnpm run check`. Breaking input removal is intentional: migrate old `with`
 settings to TOML and remove them from calls; no compatibility forwarding exists.

package/docs/shifu-gate-profiles.md

@@ -21,7 +21,7 @@ ai_provenance:
 Buildchain can schedule and aggregate a project-owned Shifu Gate profile without
 owning that project's gate ids, commands, dependencies, or dev/alpha/release
 policy. The reusable workflow is
-`.github/workflows/.gate-profile.yml`.
+`.github/workflows/.build-gate-profile.yml`.
 
 ## Ownership boundary
 
@@ -30,7 +30,7 @@ policy. The reusable workflow is
 | Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |
 | Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |
 | Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |
-| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |
+| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.build-gate-profile.yml` and `shifu-gate-profile.mjs`                             |
 | Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |
 
 Buildchain treats the Shifu plan and receipt as versioned input contracts. It
@@ -103,7 +103,7 @@ per-gate evidence pointers, omissions, and issues.
 ```yaml
 jobs:
   gates:
-    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/.build-gate-profile.yml@v3
     with:
       gate-profile: alpha-pr
       runner-preset: kungfu-v4-self-hosted
@@ -180,7 +180,7 @@ registry or its direct diagnostic commands.
 Unit fixtures prove deterministic matrix generation and required/advisory,
 capability, unsupported, missing, stale, failure, and definition-drift
 propagation. Because a train ref changes runtime scripts but not the outer
-reusable workflow topology, an unreleased `.gate-profile.yml` must also be
+reusable workflow topology, an unreleased `.build-gate-profile.yml` must also be
 validated through a trusted `workflow_dispatch` canary that references the
 temporary workflow ref or exact SHA. See
 [`runtime-train-validation.md`](runtime-train-validation.md).

package/docs/site-bundle-contract.md

@@ -66,7 +66,7 @@ internal paths. `cli-registry.json` similarly retains every governed command
 path, syntax, option, alias, and side-effect-free help command projected from
 the runtime registry and usage authority.
 `kfd-claims.json` is the Buildchain-owned KFD claim registry. It is generated
-from `packages/core/buildchain-kfd-claims.js` and enumerates the public release
+from `packages/core/adoption/buildchain-kfd-claims.js` and enumerates the public release
 claims plus the KFD-3 collaboration surfaces that Buildchain self-verifies
 during release promotion.
 `public-surface-audit.json` is the reverse enumeration report for those

package/docs/stable-candidate-patrol.md

@@ -125,7 +125,7 @@ permissions:
 
 jobs:
   stable:
-    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v4
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-stable-candidate-patrol.yml@v4
     with:
       release-now: ${{ inputs.release-now }}
       dry-run: false

package/docs/v4-adopter-delivery.md

@@ -1,152 +1,81 @@
 ---
 status: preview
-period: 2026-08-27
-theme: buildchain-v4-adopter-delivery
+period: 2026-09-10
+theme: buildchain-adopter-delivery
 doc_type: product-manual
 source_level: local-files
 confidence: high
 sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-27
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-27
-  visible_context: Exact protected v3 adopter-delivery cut, v4 pure contract core, published npm archive bytes, public consumer policy, complete v3 capability inventory, and rooted cross-platform qualification reports.
-  invisible_context_boundary: No credentials, provider mutations, signing operations, publication operations, or release authority were used.
+  generated_at: 2026-09-10
+  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.
 ---
 
-# V4 Public Adopter Delivery
+# Public Adopter Delivery
 
-Buildchain v4 carries the v3 adopter-delivery capability through a public,
-protocol-neutral boundary. Consumers select an exact protocol driver and
-artifact profile, retain the rooted gate result, and independently recompute
-that readback. Buildchain does not interpret a protocol owned by another
-project and a passing result never grants runtime, provider, signing,
-publication, or release authority.
-
-The parity source is the read-only protected cut
-`dev/v3/v3.0@6b96bdad8d9f8ccf9275f27d9370a226a9c78465`. Work began from the
-minimal v4 absorption base
-`dev/v4/v4.0@e5611377efc03178f8687d99968cfdfa3ce2825b` and absorbed the
-verified protected-base advances through
-`dev/v4/v4.0@e0342713c7447960c13bd73377282b2e93f4853d` before delivery. These
-identities, the v3 vector-suite root, and the KFD package cut are committed in
-[`adopter-delivery-parity.json`](../architecture/adopter-delivery-parity.json)
-and exposed by the public Node API.
+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.
 
 ## Public contract
 
-The JSON input schema is
-[`v4-adopter-delivery-v1.schema.json`](../contracts/v4-adopter-delivery-v1.schema.json).
-An input names both selectors and the exact request identities. A selector
-whose implementation identity differs from the request fails closed. The
-public selectors are `json-assertion`, `kfd-category`, and `legacy-kfd`, with
-`git-commit` and `package` artifact profiles.
-
-Applications can also import the lower-level driver interface from
-`@kungfu-tech/buildchain/adopter-delivery-gate` and define an isolated driver.
-The v4 convenience runtime, exact source declaration, readback verification,
-N-1 lineage check, and published archive loader are exported from
-`@kungfu-tech/buildchain/v4-adopter-delivery`.
-
-## CLI
+The [input schema](../contracts/v4-adopter-delivery-v1.schema.json) requires an
+exact protocol driver and artifact profile. Built-in driver selectors are
+`json-assertion` and `kfd-category`; artifact profiles are `git-commit` and
+`package`. A selector must match the identity in the request.
 
-All four operations are offline after the declared archive bytes exist:
+Import the driver interface from `@kungfu-tech/buildchain/adopter-delivery-gate`
+and the current convenience runtime from `@kungfu-tech/buildchain/adopter-delivery`.
+The runtime evaluates declarations and independently recomputes readback. Its
+result grants no provider, signing, publication or release authority.
 
 ```sh
 buildchain adopter-delivery run \
-  --input contracts/fixtures/v4-adopter-delivery-v1/gate-positive.json \
+  --input contracts/adopter-delivery/input.json \
   --output .buildchain/adopter-delivery/readback.json
 
 buildchain adopter-delivery verify \
-  --input contracts/fixtures/v4-adopter-delivery-v1/gate-positive.json \
+  --input contracts/adopter-delivery/input.json \
   --readback .buildchain/adopter-delivery/readback.json
-
-buildchain adopter-delivery bootstrap \
-  --input contracts/fixtures/v4-adopter-delivery-v1/bootstrap-positive.json
-
-buildchain adopter-delivery archive \
-  --input contracts/fixtures/v4-adopter-delivery-v1/archive-template.json
 ```
 
-`verify` requires the complete rooted readback and recomputes it. Missing or
-substituted readback, unknown selector, unknown driver, protocol-version
-mismatch, archive-byte or package-identity mismatch, and altered bootstrap
-lineage all fail closed.
-
-## N-1 and published archives
-
-N-1 bootstrap is distinct from the candidate. The lineage wrapper requires
-the exact v3 authority commit, exact v4 absorption base, and exact public
-Buildchain archive root. The retained v3 bootstrap also requires protected and
-published N-1 authority, rejects self-authorization, binds the candidate gate
-artifact, and requires merged Warrant-shaped evidence. Protocol, profile, or
-gate changes require independently reviewed transition evidence.
-
-Published authority loading verifies compressed bytes before extraction,
-rejects unsafe paths and links, verifies extracted package identity, verifies
-KFD's semantic package root, and imports only declared public delivery modules.
-The caller must supply an independently retained authority readback root. The
-fixture binds `@kungfu-tech/buildchain@3.0.9-alpha.16` and
-`@kungfu-tech/kfd@1.0.0-alpha.65`; a package version is not treated as proof of
-the Git source cut.
-
-## Config and reusable workflow
-
-Consumer configuration is closed and repository-relative:
-
-```toml
-[adopter_delivery]
-contract = "kungfu-buildchain-v4-adopter-delivery/v1"
-input_path = "contracts/adopter-delivery/input.json"
-readback_path = ".buildchain/adopter-delivery/readback.json"
-bootstrap_path = "contracts/adopter-delivery/bootstrap.json"
-archive_path = "contracts/adopter-delivery/archives.json"
-result_path = ".buildchain/adopter-delivery/result.json"
-driver_selector = "kfd-category"
-artifact_profile_selector = "package"
-```
+Unknown selectors, mismatched protocol versions, missing readback and changed
+rooted evidence fail. The API has two operations: `run` and `verify`.
 
-The public reusable workflow is
-`kungfu-systems/buildchain/.github/workflows/public-build-adopter-qualification.yml@v4` for
-stable use and `@v4-alpha` during prerelease evaluation. It resolves the exact
-called-workflow SHA, enforces floating selector plus dual-lock consumer
-admission, and runs the same CLI on Linux, macOS, and Windows. Buildchain
-dogfoods it through the thin
-[`self-build-adopter-dogfood.yml`](../.github/workflows/self-build-adopter-dogfood.yml)
-caller, which contains no steps or local orchestration and persists only the
-floating `@v4-alpha` selector.
+## Configuration
 
-The reusable workflow downloads exact public N-1 npm archives and uses the
-committed byte roots, semantic identity, and authority readback root. It has
-only `contents: read`; no provider credential or production writer is accepted
-or synthesized.
+The closed JSON input owns `driverSelector`, `artifactProfileSelector`, `request`
+and `context`. The public workflow'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.
 
-## Cross-platform capability qualification
+Paths must stay inside the consumer repository. Workflow 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
+executing policy. Conformance jobs use the admitted source SHA.
 
-The reusable workflow also produces a rooted report on `linux-x64`,
-`macos-arm64`, and `windows-x64`. Each report binds `job.workflow_sha`, the
-consumer source SHA, and the complete 4,648-row v3-to-v4 inventory. Source-only
-capabilities retain their raw category counts with an `exact-source-route`
-applicability; they are not mislabeled as operating-system executions.
+## Qualification evidence
 
-The executable boundary is exercised rather than inferred: a public run must
-pass, a substituted readback must fail, retry must reproduce the original root,
-terminal verification and N-1 bootstrap must pass, and the independent
-`ledger-specification-driver` clean-room test must pass without a KFD package.
-The workflow then reconciles one exact report from each platform. Final family
-qualification combines the Buildchain self-dogfood and `agent-hub-demo`
-matrices through the exported
-`@kungfu-tech/buildchain/cross-platform-adopter-qualification` aggregator.
-The report and aggregate explicitly grant no production, provider, release, or
-stable-publication authority.
+Each platform runs the current public CLI, rejects a tampered readback, retries
+and verifies the final readback. It also runs the independent
+`ledger-specification-driver` clean-room test. A report binds the exact runtime
+commit, consumer commit and input root to these executed scenarios.
 
-## Offline vectors
+Reconciliation requires exactly one report per declared platform. All reports
+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.
 
-[`offline-vectors.json`](../contracts/fixtures/v4-adopter-delivery-v1/offline-vectors.json)
-indexes positive driver, N-1, and archive cases plus negative selector, driver,
-archive identity, bootstrap lineage, protocol version, and tampered readback
-cases. Tests synthesize archives locally so extraction and identity failures do
-not depend on the network.
+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.

package/docs/v4-canonical-contracts.md

@@ -41,7 +41,7 @@ Event, receipt, and typed-fault objects use closed versioned shapes in [`contrac
 
 ## Implementations and proof
 
-- JavaScript: [`packages/core/canonical-contracts.js`](../packages/core/canonical-contracts.js)
+- JavaScript: [`packages/core/contracts/canonical-contracts.js`](../packages/core/contracts/canonical-contracts.js)
 - Rust: [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts)
 - Shared golden and adversarial cases: [`architecture/canonical-contract-fixtures.json`](../architecture/canonical-contract-fixtures.json)
 
@@ -55,7 +55,7 @@ The check validates both implementations, compares exact UTF-8 bytes and SHA-256
 
 ## Shared Delivery Warrant fixture runner
 
-The versioned trace contract in [`contracts/v4-delivery-warrant-trace-v1.schema.json`](../contracts/v4-delivery-warrant-trace-v1.schema.json) is the language-neutral boundary for retained Delivery Warrant fixtures. The JavaScript runner in [`packages/core/delivery-warrant-fixture-runner.js`](../packages/core/delivery-warrant-fixture-runner.js) and the Rust runner in [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts) consume the same UTF-8 fixture bytes and emit the same deterministic semantic projection.
+The versioned trace contract in [`contracts/v4-delivery-warrant-trace-v1.schema.json`](../contracts/v4-delivery-warrant-trace-v1.schema.json) is the language-neutral boundary for retained Delivery Warrant fixtures. The JavaScript runner in [`packages/core/dev-delivery/delivery-warrant-fixture-runner.js`](../packages/core/dev-delivery/delivery-warrant-fixture-runner.js) and the Rust runner in [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts) consume the same UTF-8 fixture bytes and emit the same deterministic semantic projection.
 
 Each trace is closed and ordered. It binds the exact prior root, event, action or typed fault, canonical successor bytes and root, generation, fencing counter, ordered declarative effects, provider-neutral observations, and rooted receipt. The runner verifies the full root chain before returning a projection. Malformed JSON, missing or unknown fields, reordered sequences, stale roots, and unsupported contract versions fail closed.
 
@@ -68,7 +68,7 @@ The runner is not a state-machine implementation and does not sample time, execu
 
 ## TypeScript shadow adapter
 
-The adapter in [`packages/core/delivery-warrant-shadow-adapter.js`](../packages/core/delivery-warrant-shadow-adapter.js) runs the existing TypeScript v3 fixture projection first and preserves that exact result as the only authoritative output. When explicitly enabled, it sends the same canonical input bytes to the replaceable Rust host command, requires the effect-disabled host capability, and captures the returned semantic projection only as a non-authoritative observation. Rust never receives effect authority, and success, failure, timeout, cancellation, malformed output, or an unsupported host cannot change the v3 result.
+The adapter in [`packages/core/dev-delivery/delivery-warrant-shadow-adapter.js`](../packages/core/dev-delivery/delivery-warrant-shadow-adapter.js) runs the existing TypeScript v3 fixture projection first and preserves that exact result as the only authoritative output. When explicitly enabled, it sends the same canonical input bytes to the replaceable Rust host command, requires the effect-disabled host capability, and captures the returned semantic projection only as a non-authoritative observation. Rust never receives effect authority, and success, failure, timeout, cancellation, malformed output, or an unsupported host cannot change the v3 result.
 
 Shadow retention accepts only checked-in fixtures or captured replays explicitly marked public-safe. Each returned observation binds the input root, exact TypeScript and Rust source revisions, validator version, capture time, fixed retention deadline, both projections, and sanitized diagnostics. It contains no comparison verdict or cutover signal. The adapter is disabled unless the caller opts in or sets `BUILDCHAIN_V4_WARRANT_SHADOW=enabled`; even then, invalid source bindings or an unsafe retention class skip Rust invocation.
 

package/docs/v4-compatibility-facts.md

@@ -27,7 +27,7 @@ verified path receipt.
 ## Authority chain
 
 The package source is
-`packages/core/buildchain-compatibility-facts.json`, retained from v3 exact head
+`packages/core/governance/buildchain-compatibility-facts.json`, retained from v3 exact head
 `6b96bdad8d9f8ccf9275f27d9370a226a9c78465`. Each declaration becomes a KFR2
 predicate and relation, then enters an append-only temporal bundle. The
 registry identity binds all Fact, proof, Cut, supersession, revocation, and