@kungfu-tech/buildchain 4.0.1-alpha.0 → 4.0.1-alpha.3

package/AGENTS.md

@@ -109,12 +109,20 @@ called only by the public reusable workflow and tests. `version-state`,
 `publish`, provider, signing, release, credential, AWS, and production-reuse
 effects remain excluded.
 
+Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
+`@v4-alpha` and retain matching stable and alpha contract locks.
+A source-persisted exact commit SHA, exact default, repository-variable indirection, nested
+composite indirection, missing lock, or stale selected lock fails consumer
+admission. Exact resolved SHAs remain evidence and runtime data, never a durable
+selector.
+
 If public workflow recursion prevents candidate validation, publish the exact
-candidate at `train/v4/v4.0/<capability>` and make the thin caller consume that
-fully qualified public train ref. Fix failures in the train/public contract;
-never solve recursion with an internal exception. After qualification and
-protected merge, repin the durable caller to the exact protected commit when
-the delivery plan requires it. `pnpm run check` and protected Verify run
+candidate at `train/v4/v4.0/<capability>`, keep the thin caller on `@v4-alpha`,
+and pass the train only through the trusted non-persistent runtime input. Fix
+failures in the train/public contract; never solve recursion with an internal exception.
+Never use a persisted train/SHA selector. After qualification and protected
+merge, the durable caller remains on the floating channel with refreshed dual
+contract locks. `pnpm run check` and protected Verify run
 `scripts/check-v4-public-dogfood-contract.mjs`; changing this rule, its gate, or
 the protected caller requires independent `@kungfu-origin` review.
 

package/actions/promote-buildchain-ref/README.md

@@ -156,8 +156,10 @@ trusted channel workflow:
 
 ```yaml
 - uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3
+  env:
+    BUILDCHAIN_TAG_UPDATE_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
   with:
-    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    token: ${{ github.token }}
     generated-ref-update-token: ${{ github.token }}
     sha: ${{ github.sha }}
     target-ref: release/v3/v3.0
@@ -511,11 +513,14 @@ governance semantics:
   with either the `verification-command` input or `buildchain.toml`
   `lifecycle.verify` before any tags or channel refs move.
 
-The reusable promotion workflow keeps governance reads, generated status checks,
-and generated ref updates on the run-scoped `github.token`. When branch
-protection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`
-only through `generated-pull-request-token` so the same-repository recovery PR can
-be listed or created without broadening the governance client. Protected branch
+The reusable promotion workflow keeps governance reads, provider finalization,
+generated status checks, and generated ref updates on the run-scoped
+`github.token`. It exposes `BUILDCHAIN_PROMOTION_TOKEN` only through the
+step-scoped `BUILDCHAIN_TAG_UPDATE_TOKEN` environment variable and the
+`generated-pull-request-token`: the former creates or moves public release tags,
+while the latter lists or creates the
+same-repository recovery PR when branch protection rejects generated bookkeeping.
+Protected branch
 review and check rules guard human channel merges, while the reusable build trust
 gate checks the source-lock channel HEAD and merged same-repository PR lineage
 before heavy build runners start. This action still independently rechecks PR

package/architecture/decisions/0003-two-phase-delivery-warrant.md

@@ -0,0 +1,152 @@
+---
+status: accepted
+period: 2026-08-11
+theme: two-phase-delivery-warrant
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-15
+---
+
+# ADR 0003: Delivery Order Is Reserved Before Native Qualification
+
+## Status
+
+Accepted. This decision is normative for the v3 Delivery Warrant state machine,
+reusable delivery workflows, and generated native consumer workflows.
+
+## Context
+
+A slow native pull request can pass source acceptance, obtain approval, and then
+spend long enough in platform qualification for the protected dev base to move
+many times. Requiring all native shards to finish before the pull request owns
+a delivery turn permits a stream of later fast candidates to overtake it.
+Freezing dev or disabling protection would avoid the race only by stopping
+unrelated work or removing the authority that must be proven.
+
+Native evidence also has two identities that must not be conflated. Semantic
+source, affected closure, dependency graph, and toolchain determine whether a
+native result remains valid. The current dev commit and replay tree determine
+the final integration composition. A dev-only documentation change should not
+invalidate semantic native evidence, while a change inside the affected closure
+must never be silently reused.
+
+## Decision
+
+Delivery Warrant ownership has two phases:
+
+```text
+queued -> provisional --native proof accepted--> qualified -> GitHub merge queue
+              |                  |
+              +--failure--------+--> terminal release -> wake next candidate
+              +--expiry------------> recovered queue entry with a new fence
+```
+
+Source acceptance, the ready label, current approval, and required source checks
+are established before selection. Selection issues a `provisional` Warrant with
+one TTL, heartbeat protocol, lease generation, and fencing token. It reserves
+the next protected-dev delivery turn but is not merge-queue authority. Later
+pull requests may run source and CI work and remain visible in the durable FIFO
+plus aging queue; none may enter the protected merge queue while another exact
+candidate owns the active Warrant.
+
+Native success upgrades the same fenced generation atomically to `qualified`.
+The transition binds a Native Qualification Proof and a rooted reuse decision.
+Only a qualified Warrant may authorize enqueue. The upgrade does not mint a new
+fence and cannot change the PR head or semantic source roots.
+
+Native Qualification Proof v3 binds semantic source identity, semantic patch,
+qualification plan, affected closure, dependency graph, toolchain, execution
+environment contract, covered paths, exact shard evidence roots, the dev base
+used for qualification, and the exact native execution receipt. That receipt
+contains the normalized repository, protected base, source head, qualified
+base, toolchain root, and environment root binding established before the
+native process starts. The proof repeats and roots that binding, and includes
+the receipt root in its shard evidence. Its
+timestamp is observational rather than part of proof identity. Reuse on another
+base requires an attributed base delta. Identical base is accepted directly; a
+descendant base with no overlap against the affected closure reuses the proof;
+overlap requires affected or full native revalidation; unknown ancestry,
+truncated attribution, semantic change, closure change, dependency change, or
+toolchain change requires full revalidation.
+
+The reusable controller composes the exact PR head with the observed protected
+base before running native work, heartbeats while the command is active, and
+checks base drift after completion. It may perform one automatic revalidation
+on the latest base. Continued overlapping drift fails closed. Native failure,
+cancel, semantic head movement, unrecoverable composition conflict, or exhausted
+revalidation closes only the current fence. The controller then emits a rooted
+`buildchain-dev-delivery-wake` repository event for the next queued candidate.
+Cancellation that prevents cleanup is covered by TTL recovery; the stale worker
+cannot renew or qualify after a new fence is minted.
+
+PR-controlled native execution is a credentialless candidate job on a
+GitHub-hosted runner. Its child process and complete `/proc` ancestry receive no
+controller or provider write credential. The ancestry sentinel treats unreadable
+process state as failure and detects generic auth, credential, key, password,
+secret, and token variable names. Only a dependent credentialed finalizer on a
+provider-readback-proven distinct GitHub-hosted job and runner may independently
+verify the content-addressed proof/state transfer, reread the same live fence,
+PR head, and protected base, and qualify or settle the attempt. A successful
+candidate exit is evidence input, not authority to mutate provider state or a
+completion signal by itself. Persistent self-hosted runners are unsupported
+because job ordering alone cannot prove detached-descendant cleanup.
+
+GitHub `merge_group` checks and the protected dev ref remain final integration
+authority. No transition disables a check, changes branch protection, force
+updates the Warrant ref, or freezes dev.
+
+Required native delivery validates the environment root before candidate
+submission, Warrant selection, checkout/composition, or native process spawn.
+An empty or malformed root is therefore an admission failure, not a terminal
+failure after native capacity has been spent. `off`, `shadow`, and
+`non-native-fast` compatibility does not turn the reusable workflow input into
+an unconditional requirement.
+
+## Compatibility
+
+Existing v1 queue documents remain readable. An historical active Warrant that
+does not contain `phase` is interpreted as the former already-qualified shape
+without rewriting its state root. Newly selected Warrants always contain
+`phase: provisional`. Existing `off` and `shadow` workflow modes remain
+available; `required` now enforces the two-phase upgrade. Native Qualification
+Proof v1 and v2 documents remain verifiable as historical evidence, but their
+execution receipts do not bind the environment root. They cannot gain v3 exact
+reuse authority and must be replaced by an explicit native revalidation.
+
+In bounded authority mode, every newly issued Landing Warrant requires the
+complete verified-native qualification shape, including the qualification
+contract, execution binding, execution receipt, command, source proof, and native
+proof roots. A migrated `legacy-compatibility-only` qualification may preserve
+the exact already-active historical Landing fence for safe handoff, but it can
+never mint a new Landing Warrant or acquire native proof authority.
+
+Elapsed lease time is not provider-stop evidence. Cleanup of an expired Landing
+fence requires a separate independent provider terminal verifier whose rooted
+readback matches the exact state root, candidate, source head, fencing token,
+generation, provider run, and provider job and is fresh for that Warrant
+generation. Caller-asserted, forged, mismatched, nonterminal, or stale readback
+cannot release the exclusive slot.
+
+## Consequences
+
+- Slow approved candidates stop starving without serializing development or CI.
+- A provisional receipt is intentionally insufficient for merge admission.
+- Base-only replay churn can reuse native evidence when closure attribution is
+  complete and disjoint.
+- Overlap and uncertainty spend more native compute but cannot create an
+  unproven protected-dev landing.
+- Consumers need a promotion token that can advance the Warrant state ref and
+  emit the wake event, plus a native command or an exact reusable proof.
+- Invalid required-native environment inputs fail before they can allocate a
+  Warrant or native runner time.
+- Legacy unbound native evidence remains readable but intentionally spends a
+  new validation run before qualification.
+- Candidate execution remains credentialless; credentialed readback,
+  qualification, and settlement happen only in a distinct, live-evidenced fresh
+  GitHub-hosted finalizer job after candidate job completion.
+- Expired Landing cleanup is rooted in exact independent provider readback, not
+  a timeout or the controller's own assertion.

package/architecture/internal-capabilities.json

@@ -48,6 +48,8 @@
     "scripts/v4-bridge-evidence.mjs",
     "scripts/v4-host-adapter.mjs",
     "crates/buildchain-v4-bridge/src/main.rs",
+    "packages/core/v4-runtime-ref-resume-authority.js",
+    "packages/core/v4-runtime-selector-persistence.js",
     "packages/core/v4-provider-operation-journal.js",
     "packages/core/v4-stage-capsule.js",
     "packages/core/v4-stage-capsule-store.js",
@@ -57,6 +59,38 @@
     "packages/core/v4-stage-capsule-qualification.js",
     "packages/core/v4-stage-capsule-qualification-campaign.js",
     "scripts/v4-stage-capsule-qualification.mjs",
+    "packages/core/dev-delivery-warrant.js",
+    "packages/core/dev-delivery-warrant-state.js",
+    "packages/core/dev-delivery-warrant-qualification.js",
+    "packages/core/dev-delivery-native-proof.js",
+    "packages/core/dev-delivery-native-execution.js",
+    "packages/core/dev-delivery-execution-failure.js",
+    "packages/core/dev-delivery-execution-transfer.js",
+    "packages/core/dev-delivery-process-boundary.js",
+    "packages/core/dev-delivery-contract-surface.js",
+    "packages/core/dev-delivery-authority-candidate.js",
+    "packages/core/dev-delivery-authority-evidence.js",
+    "packages/core/dev-delivery-authority-state.js",
+    "packages/core/dev-delivery-authority-qualification.js",
+    "packages/core/dev-delivery-authority-landing.js",
+    "packages/core/dev-delivery-landing-admission-core.js",
+    "packages/core/dev-delivery-authority-settlement.js",
+    "packages/core/dev-delivery-landing-readback.js",
+    "packages/core/dev-delivery-landing-terminal-evidence.js",
+    "packages/core/dev-delivery-landing-testing-port.js",
+    "packages/core/dev-delivery-provider-attempt.js",
+    "packages/core/dev-delivery-provider-heartbeat.js",
+    "scripts/dev-delivery-warrant.mjs",
+    "scripts/dev-delivery-warrant-options.mjs",
+    "scripts/dev-delivery-warrant-store.mjs",
+    "scripts/dev-delivery-authority.mjs",
+    "scripts/dev-delivery-authority-command-adapters.mjs",
+    "scripts/dev-delivery-authority-provider.mjs",
+    "scripts/dev-delivery-native-run.mjs",
+    "scripts/dev-delivery-process-boundary.mjs",
+    "scripts/dev-delivery-provider-heartbeat.mjs",
+    "scripts/dev-delivery-two-phase-resume.mjs",
+    "scripts/dev-delivery-two-phase.mjs",
     "crates/buildchain-v4-contracts/src/stage_capsule.rs",
     "crates/buildchain-v4-contracts/src/stage_capsule_store.rs",
     "crates/buildchain-v4-contracts/src/provider_operation_journal.rs",
@@ -416,6 +450,68 @@
         "docs/release-tail-provider-plane.md"
       ]
     },
+    {
+      "id": "v4-delivery-authority",
+      "owner": "Buildchain protected delivery maintainers",
+      "implementation": [
+        "packages/core/dev-delivery-warrant.js",
+        "packages/core/dev-delivery-warrant-state.js",
+        "packages/core/dev-delivery-warrant-qualification.js",
+        "packages/core/dev-delivery-native-proof.js",
+        "packages/core/dev-delivery-native-execution.js",
+        "packages/core/dev-delivery-execution-failure.js",
+        "packages/core/dev-delivery-execution-transfer.js",
+        "packages/core/dev-delivery-process-boundary.js",
+        "packages/core/dev-delivery-contract-surface.js",
+        "packages/core/dev-delivery-authority-candidate.js",
+        "packages/core/dev-delivery-authority-evidence.js",
+        "packages/core/dev-delivery-authority-state.js",
+        "packages/core/dev-delivery-authority-qualification.js",
+        "packages/core/dev-delivery-authority-landing.js",
+        "packages/core/dev-delivery-landing-admission-core.js",
+        "packages/core/dev-delivery-authority-settlement.js",
+        "packages/core/dev-delivery-landing-readback.js",
+        "packages/core/dev-delivery-landing-terminal-evidence.js",
+        "packages/core/dev-delivery-landing-testing-port.js",
+        "packages/core/dev-delivery-provider-attempt.js",
+        "packages/core/dev-delivery-provider-heartbeat.js",
+        "scripts/dev-delivery-warrant.mjs",
+        "scripts/dev-delivery-warrant-options.mjs",
+        "scripts/dev-delivery-warrant-store.mjs",
+        "scripts/dev-delivery-authority.mjs",
+        "scripts/dev-delivery-authority-command-adapters.mjs",
+        "scripts/dev-delivery-authority-provider.mjs",
+        "scripts/dev-delivery-native-run.mjs",
+        "scripts/dev-delivery-process-boundary.mjs",
+        "scripts/dev-delivery-provider-heartbeat.mjs",
+        "scripts/dev-delivery-two-phase-resume.mjs",
+        "scripts/dev-delivery-two-phase.mjs"
+      ],
+      "tests": [
+        "tests/dev-delivery-warrant.test.mjs",
+        "tests/dev-delivery-warrant-command.test.mjs",
+        "tests/dev-delivery-two-phase.test.mjs",
+        "tests/dev-delivery-two-phase-run.test.mjs",
+        "tests/dev-delivery-native-run.test.mjs",
+        "tests/dev-delivery-process-boundary.test.mjs",
+        "tests/dev-delivery-process-boundary-negative.test.mjs",
+        "tests/dev-delivery-provider-heartbeat.test.mjs",
+        "tests/dev-delivery-authority.test.mjs",
+        "tests/build-surface.test.mjs",
+        "tests/v4-delivery-authority-parity.test.mjs"
+      ],
+      "contracts": [
+        "architecture/v4-delivery-authority-parity.json",
+        "architecture/decisions/0003-two-phase-delivery-warrant.md",
+        "contracts/dev-delivery-authority-v2.schema.json",
+        "dist/site/schemas/dev-delivery-authority-v2.schema.json",
+        ".github/workflows/dev-pr-auto-merge.yml",
+        ".github/workflows/buildchain-dev-delivery.yml",
+        "templates/native-dev-delivery.yml",
+        "docs/dev-delivery-warrant.md",
+        "docs/dev-delivery-qualification-landing-adr.md"
+      ]
+    },
     {
       "id": "v4-architecture-governance",
       "owner": "Buildchain architecture maintainers",
@@ -431,6 +527,8 @@
         "packages/core/v4-stable-publication-fence.js",
         "packages/core/v4-partial-mutation-recovery-qualification.js",
         "packages/core/v4-adopter-delivery-parity.js",
+        "packages/core/v4-runtime-ref-resume-authority.js",
+        "packages/core/v4-runtime-selector-persistence.js",
         "packages/core/v4-stage-capsule.js",
         "packages/core/v4-stage-capsule-store.js",
         "packages/core/v4-stage-capsule-local-store.js",
@@ -463,7 +561,8 @@
         "tests/v4-stage-capsule-store.test.mjs",
         "tests/v4-platform-stage-checkpoints.test.mjs",
         "tests/v4-stage-capsule-qualification.test.mjs",
-        "tests/v4-adopter-delivery-parity.test.mjs"
+        "tests/v4-adopter-delivery-parity.test.mjs",
+        "tests/v4-runtime-ref-resume-authority.test.mjs"
       ],
       "contracts": [
         "architecture/v4-architecture-constitution.md",
@@ -481,6 +580,7 @@
         "architecture/v4-platform-stage-checkpoints.json",
         "architecture/v4-stage-capsule-qualification.json",
         "architecture/v4-adopter-delivery-parity.json",
+        "architecture/v4-runtime-ref-resume-authority.json",
         "contracts/v4-host-contract-v1.schema.json",
         "contracts/v4-provider-operation-journal-v1.schema.json",
         "contracts/v4-release-activation-shadow-v1.schema.json",
@@ -495,7 +595,10 @@
         "contracts/fixtures/v4-release-activation-shadow-v1/shared.json",
         "contracts/fixtures/v4-stable-publication-fence-v1/shared.json",
         "contracts/fixtures/v4-partial-mutation-recovery-v1/shared.json",
-        "docs/v4-stage-capsule.md"
+        "contracts/v4-runtime-ref-resume-authority-v1.schema.json",
+        "contracts/fixtures/v4-runtime-ref-resume-authority-v1/scenario.json",
+        "docs/v4-stage-capsule.md",
+        "docs/v4-runtime-ref-resume-authority.md"
       ]
     }
   ]