@kungfu-tech/buildchain 4.0.1-alpha.9 → 4.0.2-alpha.0

package/docs/publish-transaction.md

@@ -97,6 +97,13 @@ state for `vX.Y.Z-alpha.N` and cannot resume it with the same transaction
 identity, alpha version selection must advance to the next prerelease instead
 of reusing or overwriting that failed transaction slot.
 
+The immutable `publish-gate/{alpha,release}/.../<version>` source lock also
+reserves its exact version when a failure happens before durable transaction
+state can be created. A later candidate with a different source SHA advances to
+the next version; it never rebinds or overwrites the earlier source lock. The
+same source SHA reuses its own lock so authority planning and mutation stay on
+one exact version.
+
 `release-candidate-promote.yml` can establish or restore this state from an
 older successful candidate run through the documented fresh-event recovery
 inputs. The recovery receipt and sealed bundle are verified before the action
@@ -251,10 +258,10 @@ Example reused OCI evidence entry (the pre-publish requirement may omit
 
 Buildchain distinguishes two npm release modes:
 
-| Mode | Use | Auth | npm operation |
-| --- | --- | --- | --- |
-| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|vX.Y-alpha|latest>` |
-| `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token` | `npm dist-tag add <pkg>@<version> latest` |
+| Mode                       | Use                                   | Auth                 | npm operation                                   |
+| -------------------------- | ------------------------------------- | -------------------- | ----------------------------------------------- |
+| `publish-final-version`    | normal alpha or stable publication    | `trusted-publishing` | `npm publish --tag <alpha\|vX.Y-alpha\|latest>` |
+| `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token`          | `npm dist-tag add <pkg>@<version> latest`       |
 
 The normal libnode path is `publish-final-version`: publish an alpha package set
 such as `22.22.3-kf.3-alpha.0` with the `alpha` dist-tag, then publish a

package/docs/release-candidate.md

@@ -234,6 +234,13 @@ restored sealed bundle, and a conflicting payload digest fails closed. Ordinary
 duplicate publication without a complete recovery receipt retains the stricter
 same-name/same-digest rule for all assets.
 
+If that explicit complete recovery finds that the public Release Passport is
+absent, it may restore the complete locally verified evidence closure. Before
+the first upload, Buildchain rejects undeclared remote assets and compares every
+same-name remote asset byte-for-byte; any unknown name or digest conflict fails
+closed without mutation. Ordinary duplicate publication cannot enter this
+repair path.
+
 After a transaction finalizes, the target branch can legitimately advance from
 the original promotion SHA. Repeating explicit recovery accepts that movement
 only when the caller supplies the exact durable transaction identity, the

package/docs/v4-adopter-delivery.md

@@ -1,6 +1,6 @@
 ---
 status: preview
-period: 2026-08-16
+period: 2026-08-27
 theme: buildchain-v4-adopter-delivery
 doc_type: product-manual
 source_level: local-files
@@ -8,12 +8,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-16
+last_reviewed: 2026-08-27
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-16
-  visible_context: Exact protected v3 adopter-delivery cut, v4 pure contract core, published npm archive bytes, and public consumer policy.
+  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.
 ---
 
@@ -124,6 +124,25 @@ committed byte roots, semantic identity, and authority readback root. It has
 only `contents: read`; no provider credential or production writer is accepted
 or synthesized.
 
+## Cross-platform capability qualification
+
+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.
+
+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/v4-cross-platform-adopter-qualification` aggregator.
+The report and aggregate explicitly grant no production, provider, release, or
+stable-publication authority.
+
 ## Offline vectors
 
 [`offline-vectors.json`](../contracts/fixtures/v4-adopter-delivery-v1/offline-vectors.json)

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

@@ -0,0 +1,43 @@
+---
+status: active
+period: ongoing
+theme: buildchain-v4-declarative-release-tail
+doc_type: migration-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-26
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-26
+  invisible_context: unavailable
+---
+
+# Migrate a release-candidate promotion to the v4 Provider Plane
+
+Persist the public workflow call at the floating major ref and keep the matching contract lock in the consumer repository:
+
+```yaml
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4
+    with:
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
+      declarative-release-tail: true
+```
+
+The Build/Verify workflow now uploads these candidate-owned inputs together:
+
+- `release-candidate-passport.json`
+- `release-candidate-stage-capsules.json`
+- `release-candidate-publication-qualification.json`
+- the typed payload and manifest artifacts bound by those documents
+
+Remove all v4 values for `publish-command`, `publication-gate-command`, `publication-consumer-qualification-command`, `publication-commit-command`, `release-activation-command`, `release-passport-evidence-command`, KFD/invariant command inputs, and every other `command`, `cmd`, `script`, `shell`, or `run` field. v4 admission rejects them before publication planning. Do not replace them with a wrapper script or a standalone workflow; declare provider evidence and let the reusable workflow execute the fixed Provider Plane.
+
+On interruption, rerun with the same candidate and transaction state. Buildchain verifies the candidate/source/artifact/policy roots and continues from the first missing standardized receipt. Never delete the state file to make a failed capability replay from the beginning.
+
+v3 workflow calls retain their existing command-compatible behavior. Migrating a v3 consumer is an explicit contract change, not an automatic reinterpretation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.1-alpha.9",
+  "version": "4.0.2-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -48,6 +48,9 @@
     "./v4-tail-reseal": "./packages/core/v4-tail-reseal.js",
     "./v4-tail-reseal-receipt": "./packages/core/v4-tail-reseal-receipt.js",
     "./v4-publication-rehearsal": "./packages/core/v4-publication-rehearsal.js",
+    "./publication-rehearsal-runtime": "./packages/core/publication-rehearsal-runtime.js",
+    "./publication-rehearsal-projection": "./packages/core/publication-rehearsal-projection.js",
+    "./v4-publication-qualification": "./packages/core/v4-publication-qualification.js",
     "./adopter-delivery-gate": "./packages/core/adopter-delivery-gate.js",
     "./kfd-adopter-category-driver": "./packages/core/kfd-adopter-category-driver.js",
     "./buildchain-delivery-infrastructure": "./packages/core/buildchain-delivery-infrastructure.js",
@@ -58,6 +61,7 @@
     "./adopter-delivery-passport": "./packages/core/adopter-delivery-passport.js",
     "./adopter-delivery-vectors": "./packages/core/adopter-delivery-vectors.js",
     "./v4-adopter-delivery": "./packages/core/v4-adopter-delivery.js",
+    "./v4-cross-platform-adopter-qualification": "./packages/core/v4-cross-platform-adopter-qualification.js",
     "./logging": "./packages/core/logging.js",
     "./portable-dev-cache": "./packages/core/portable-dev-cache.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
@@ -114,6 +118,7 @@
     "./site/schemas/v4-publication-rehearsal-capsule-v1.schema.json": "./dist/site/schemas/v4-publication-rehearsal-capsule-v1.schema.json",
     "./site/schemas/v4-adopter-delivery-v1.schema.json": "./dist/site/schemas/v4-adopter-delivery-v1.schema.json",
     "./site/schemas/release-tail-capabilities-v1.schema.json": "./dist/site/schemas/release-tail-capabilities-v1.schema.json",
+    "./site/schemas/v4-publication-qualification-v1.schema.json": "./dist/site/schemas/v4-publication-qualification-v1.schema.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",
@@ -151,8 +156,8 @@
   "scripts": {
     "precheck:static": "prettier --check architecture/decisions/0003-two-phase-delivery-warrant.md architecture/v4-delivery-authority-parity.json contracts/dev-delivery-authority-v2.schema.json dist/site/schemas/dev-delivery-authority-v2.schema.json docs/dev-delivery-qualification-landing-adr.md packages/core/dev-delivery-authority-candidate.js packages/core/dev-delivery-authority-evidence.js packages/core/dev-delivery-authority-landing.js packages/core/dev-delivery-authority-observation.js packages/core/dev-delivery-authority-qualification.js packages/core/dev-delivery-authority-settlement.js packages/core/dev-delivery-authority-state.js packages/core/dev-delivery-execution-failure.js packages/core/dev-delivery-execution-transfer.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-native-execution.js packages/core/dev-delivery-native-proof.js packages/core/dev-delivery-process-boundary.js packages/core/dev-delivery-warrant-qualification.js packages/core/dev-delivery-warrant-state.js scripts/dev-delivery-authority-command-adapters.mjs scripts/dev-delivery-authority-provider.mjs scripts/dev-delivery-authority.mjs scripts/dev-delivery-native-run.mjs scripts/dev-delivery-process-boundary.mjs scripts/dev-delivery-two-phase-resume.mjs scripts/dev-delivery-two-phase.mjs scripts/dev-delivery-warrant-options.mjs scripts/dev-delivery-warrant-store.mjs templates/native-dev-delivery.yml",
     "operator:windows-jit": "bash scripts/aws-windows-jit-operator.sh",
-    "check": "pnpm run check:static && node scripts/check-ci-lane-change-budget.mjs && node scripts/check-v4-public-dogfood-contract.mjs && node scripts/check-v4-floating-consumer-policy-contract.mjs && pnpm run check:v4-bridge && pnpm run check:v4-contracts && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-publication-rehearsal-fixture.mjs --check && node scripts/v4-architecture.mjs validate && node scripts/v4-warrant-shadow-plan.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
-    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-provider-bindings-v1.schema.json contracts/v4-canonical-contracts-v1.schema.json contracts/v4-compatibility-facts-v1.schema.json contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json contracts/v4-delivery-warrant-trace-v1.schema.json contracts/v4-floating-consumer-policy-receipt-v1.schema.json contracts/v4-runtime-ref-resume-authority-v1.schema.json contracts/v4-tail-reseal-v1.schema.json contracts/v4-host-contract-v1.schema.json contracts/v4-provider-operation-journal-v1.schema.json contracts/v4-release-activation-shadow-v1.schema.json contracts/v4-stable-publication-fence-v1.schema.json contracts/v4-partial-mutation-recovery-v1.schema.json contracts/v4-stage-capsule-v1.schema.json contracts/v4-stage-capsule-store-v1.schema.json contracts/v4-stage-capsule-resume-v1.schema.json contracts/release-tail-capabilities-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json contracts/fixtures/v4-delivery-warrant-trace-v1/*.json contracts/fixtures/v4-floating-consumer-policy-v1/*.json contracts/fixtures/v4-runtime-ref-resume-authority-v1/*.json contracts/fixtures/v4-tail-reseal-v1/*.json contracts/fixtures/v4-compatibility-facts-v1/*.json contracts/fixtures/v4-provider-operation-journal-v1/*.json contracts/fixtures/v4-provider-readback-idempotency-v1/*.json contracts/fixtures/v4-release-activation-shadow-v1/*.json contracts/fixtures/v4-stable-publication-fence-v1/*.json contracts/fixtures/v4-partial-mutation-recovery-v1/*.json contracts/fixtures/v4-stage-capsule-v1/*.json contracts/fixtures/v4-stage-capsule-store-v1/*.json contracts/fixtures/v4-stage-capsule-resume-v1/*.json bin/internal/command-registry.mjs bin/internal/compatibility-facts-cli.mjs packages/core/v4-canonical-contracts.js packages/core/kungfu-temporal-fact.js packages/core/buildchain-compatibility-fact.js packages/core/buildchain-compatibility-authority.js packages/core/buildchain-compatibility-proof.js packages/core/v4-floating-consumer-evidence.js packages/core/v4-floating-consumer-policy.js packages/core/v4-floating-consumer-release-passport.js packages/core/v4-runtime-ref-resume-authority.js packages/core/v4-tail-reseal-contract.js packages/core/v4-tail-reseal-github.js packages/core/v4-tail-reseal-receipt.js packages/core/v4-tail-reseal.js packages/core/v4-runtime-selector-persistence.js packages/core/v4-provider-operation-journal.js packages/core/v4-provider-readback-idempotency.js packages/core/v4-release-activation-shadow.js packages/core/v4-stable-publication-fence.js packages/core/v4-partial-mutation-recovery-qualification.js packages/core/v4-stage-capsule.js packages/core/v4-stage-capsule-store.js packages/core/v4-stage-capsule-local-store.js packages/core/v4-platform-stage-checkpoints.js packages/core/v4-stage-capsule-resume-planner.js packages/core/v4-stage-capsule-qualification.js packages/core/v4-stage-capsule-qualification-campaign.js packages/core/v4-delivery-warrant-fixture-runner.js packages/core/v4-delivery-warrant-read-candidate.js packages/core/v4-delivery-warrant-semantic-diff-gate.js packages/core/v4-delivery-warrant-shadow-adapter.js scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/dev-pr-prequeue-guard.mjs scripts/check-v4-public-dogfood-contract.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/v4-bridge-bootstrap.mjs scripts/v4-bridge-evidence.mjs scripts/v4-consumer-policy.mjs scripts/v4-host-adapter.mjs scripts/v4-platform-stage-checkpoint-rehearsal.mjs scripts/v4-stage-capsule-resume-rehearsal.mjs scripts/v4-stage-capsule-qualification.mjs scripts/v4-tail-reseal-macos-rehearsal.mjs scripts/v4-tail-reseal.mjs scripts/v4-warrant-shadow-plan.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-warrant-shadow-plan.test.mjs",
+    "check": "pnpm run check:static && node scripts/check-ci-lane-change-budget.mjs && node scripts/check-v4-public-dogfood-contract.mjs && node scripts/check-v4-floating-consumer-policy-contract.mjs && pnpm run check:v4-bridge && pnpm run check:v4-contracts && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/generate-agent-change-map.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-v4-runtime-semantic-closure.mjs && node scripts/check-v3-v4-capability-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-publication-rehearsal-fixture.mjs --check && node scripts/v4-architecture.mjs validate && node scripts/v4-warrant-shadow-plan.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-provider-bindings-v1.schema.json contracts/v4-canonical-contracts-v1.schema.json contracts/v4-compatibility-facts-v1.schema.json contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json contracts/v4-delivery-warrant-trace-v1.schema.json contracts/v4-floating-consumer-policy-receipt-v1.schema.json contracts/v4-runtime-ref-resume-authority-v1.schema.json contracts/v4-tail-reseal-v1.schema.json contracts/v4-host-contract-v1.schema.json contracts/v4-provider-operation-journal-v1.schema.json contracts/v4-release-activation-shadow-v1.schema.json contracts/v4-stable-publication-fence-v1.schema.json contracts/v4-partial-mutation-recovery-v1.schema.json contracts/v4-stage-capsule-v1.schema.json contracts/v4-stage-capsule-store-v1.schema.json contracts/v4-stage-capsule-resume-v1.schema.json contracts/release-tail-capabilities-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json contracts/fixtures/v4-delivery-warrant-trace-v1/*.json contracts/fixtures/v4-floating-consumer-policy-v1/*.json contracts/fixtures/v4-runtime-ref-resume-authority-v1/*.json contracts/fixtures/v4-tail-reseal-v1/*.json contracts/fixtures/v4-compatibility-facts-v1/*.json contracts/fixtures/v4-provider-operation-journal-v1/*.json contracts/fixtures/v4-provider-readback-idempotency-v1/*.json contracts/fixtures/v4-release-activation-shadow-v1/*.json contracts/fixtures/v4-stable-publication-fence-v1/*.json contracts/fixtures/v4-partial-mutation-recovery-v1/*.json contracts/fixtures/v4-stage-capsule-v1/*.json contracts/fixtures/v4-stage-capsule-store-v1/*.json contracts/fixtures/v4-stage-capsule-resume-v1/*.json bin/internal/command-registry.mjs bin/internal/compatibility-facts-cli.mjs packages/core/v4-canonical-contracts.js packages/core/kungfu-temporal-fact.js packages/core/buildchain-compatibility-fact.js packages/core/buildchain-compatibility-authority.js packages/core/buildchain-compatibility-proof.js packages/core/v4-floating-consumer-evidence.js packages/core/v4-floating-consumer-policy.js packages/core/v4-floating-consumer-release-passport.js packages/core/v4-runtime-ref-resume-authority.js packages/core/v4-tail-reseal-contract.js packages/core/v4-tail-reseal-github.js packages/core/v4-tail-reseal-receipt.js packages/core/v4-tail-reseal.js packages/core/v4-runtime-selector-persistence.js packages/core/v4-provider-operation-journal.js packages/core/v4-provider-readback-idempotency.js packages/core/v4-release-activation-shadow.js packages/core/v4-stable-publication-fence.js packages/core/v4-partial-mutation-recovery-qualification.js packages/core/v4-stage-capsule.js packages/core/v4-stage-capsule-store.js packages/core/v4-stage-capsule-local-store.js packages/core/v4-platform-stage-checkpoints.js packages/core/v4-stage-capsule-resume-planner.js packages/core/v4-stage-capsule-qualification.js packages/core/v4-stage-capsule-qualification-campaign.js packages/core/v4-delivery-warrant-fixture-runner.js packages/core/v4-delivery-warrant-read-candidate.js packages/core/v4-delivery-warrant-semantic-diff-gate.js packages/core/v4-delivery-warrant-shadow-adapter.js scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-v4-runtime-semantic-closure.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/dev-pr-prequeue-guard.mjs scripts/check-v4-public-dogfood-contract.mjs scripts/maintainability-metrics.mjs scripts/maintainability-domain-metrics.mjs scripts/maintainability-governance.mjs scripts/generate-agent-change-map.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/v4-bridge-bootstrap.mjs scripts/v4-bridge-evidence.mjs scripts/v4-consumer-policy.mjs scripts/v4-host-adapter.mjs scripts/v4-platform-stage-checkpoint-rehearsal.mjs scripts/v4-stage-capsule-resume-rehearsal.mjs scripts/v4-stage-capsule-qualification.mjs scripts/v4-tail-reseal-macos-rehearsal.mjs scripts/v4-tail-reseal.mjs scripts/v4-warrant-shadow-plan.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/maintainability-governance.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-runtime-semantic-closure.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-warrant-shadow-plan.test.mjs",
     "check:v4-bridge": "cargo fmt --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml",
     "check:v4-contracts": "cargo fmt --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml && node --test tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy-contract.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-publication-rehearsal.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",

package/packages/core/adopter-delivery-passport.js

@@ -7,6 +7,42 @@ export const ADOPTER_DELIVERY_PASSPORT_BINDING_CONTRACT =
   "kungfu-buildchain-adopter-delivery-passport-binding";
 
 const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const EXACT_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+
+export function releasePassportKfdAdopterSourceSha({
+  passportSourceSha = "",
+  release = undefined,
+} = {}) {
+  const exactSha = (value) =>
+    EXACT_SHA_PATTERN.test(String(value || "").trim());
+  const candidateSourceSha = String(release?.candidateSourceSha || "").trim();
+  const builtSourceSha = String(release?.builtSourceSha || "").trim();
+  const promotionChannelSha = String(release?.promotionChannelSha || "").trim();
+  const candidateSourceTreeSha = String(
+    release?.candidateSourceTreeSha || "",
+  ).trim();
+  const builtSourceTreeSha = String(release?.builtSourceTreeSha || "").trim();
+  const promotionChannelTreeSha = String(
+    release?.promotionChannelTreeSha || "",
+  ).trim();
+  if (
+    release?.treeEquivalent !== true ||
+    !exactSha(passportSourceSha) ||
+    !exactSha(candidateSourceSha) ||
+    !exactSha(builtSourceSha) ||
+    !exactSha(promotionChannelSha) ||
+    candidateSourceSha !== builtSourceSha ||
+    promotionChannelSha !== passportSourceSha ||
+    !exactSha(candidateSourceTreeSha) ||
+    !exactSha(builtSourceTreeSha) ||
+    !exactSha(promotionChannelTreeSha) ||
+    candidateSourceTreeSha !== builtSourceTreeSha ||
+    candidateSourceTreeSha !== promotionChannelTreeSha
+  ) {
+    return passportSourceSha;
+  }
+  return candidateSourceSha;
+}
 
 function issue(code, message, details = {}) {
   return { code, message, details };

package/packages/core/buildchain-contract.js

@@ -166,6 +166,36 @@ function declarativeAuditableDemoSurface(root, pkg, majorLine) {
   });
 }
 
+function v4ReleaseCandidatePromoteSurface(root, majorLine) {
+  return surface(root, {
+    id: "v4-release-candidate-promote-action",
+    kind: "action",
+    path: "actions/v4-release-candidate-promote/action.yml",
+    publicRef: `kungfu-systems/buildchain/actions/v4-release-candidate-promote@${majorLine}`,
+    requiredInputs: [
+      "token", "repository", "source-sha", "version", "tag", "channel",
+      "candidate-passport-path", "stage-capsules-path",
+      "publication-qualification-path",
+    ],
+    requiredOutputs: [
+      "release-passport-path", "release-passport-root", "transaction-state",
+      "declaration-root", "transaction-root", "state-root",
+      "receipt-roots-json",
+    ],
+    breakingDefaults: {
+      statePath: ".buildchain/release-tail/state.json",
+      executionBoundary: "built-in-provider-plane-only",
+    },
+    optionalInputs: ["artifact-paths", "state-path", "failure-after-capability"],
+    guarantees: [
+      "v4 promotion consumes only sealed candidate, Stage Capsule, qualification, and artifact evidence",
+      "GitHub Release, signed-channel commit, activation, readback, and released-evidence synthesis use built-in provider adapters",
+      "durable provider checkpoints resume completed capabilities without replay",
+      "no consumer command, script, shell, checkout, or executable tail hook is accepted",
+    ],
+  });
+}
+
 export function createBuildchainContractWorld({
   root = process.cwd(),
   packageJson = undefined,
@@ -484,7 +514,7 @@ export function createBuildchainContractWorld({
         "Build Images owns encoding, Buildchain owns qualification and receipts, and site repositories own browser loading and accessibility behavior",
         "media qualification does not claim browser playback, responsive layout, reduced-motion behavior, accessibility, or production deployment",
       ],
-    }), declarativeAuditableDemoSurface(root, pkg, majorLine),
+    }), declarativeAuditableDemoSurface(root, pkg, majorLine), v4ReleaseCandidatePromoteSurface(root, majorLine),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",

package/packages/core/buildchain-publication-authority.js

@@ -58,6 +58,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/release-tail.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "caller-bound", "caller-bound", "fixed"],
   [".github/workflows/release-verify.yml", "governance-write"],
   [".github/workflows/stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/v4-declarative-release-tail-dogfood.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "none", "fixed", "fixed"],
 ]);
 
 export function buildchainPublicationAuthorityDescriptors() {

package/packages/core/dev-delivery-warrant-legacy-recovery.js

@@ -0,0 +1,246 @@
+import {
+  devDeliveryClone as clone,
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryPositiveInteger as positiveInteger,
+  devDeliveryText as text,
+  devDeliveryTimestamp as timestamp,
+} from "./dev-delivery-common.js";
+import {
+  TERMINAL_STATES,
+  normalizeDevDeliveryQueue,
+} from "./dev-delivery-warrant-state.js";
+
+export const LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-request/v1";
+export const LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA =
+  "kungfu.buildchain.legacy-hosted-terminal-evidence/v1";
+export const LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-receipt/v1";
+
+function legacyLiveNativeCandidate(candidate) {
+  return (
+    !TERMINAL_STATES.has(candidate.status) &&
+    candidate.deliveryClass !== "non-native-fast" &&
+    (!candidate.environmentRoot || !candidate.nativeCommandContract)
+  );
+}
+
+function normalizeProviderJob(input, runAttempt) {
+  const job = {
+    id: positiveInteger(input?.id, "provider job id"),
+    name: text(input?.name),
+    runAttempt: positiveInteger(input?.runAttempt, "provider job runAttempt"),
+    status: text(input?.status).toLowerCase(),
+    conclusion: text(input?.conclusion).toLowerCase(),
+    completedAt: timestamp(input?.completedAt, "provider job completedAt"),
+  };
+  if (job.runAttempt !== runAttempt) {
+    throw new Error("legacy provider job run attempt mismatch");
+  }
+  if (job.status !== "completed" || !job.conclusion) {
+    throw new Error(
+      "legacy recovery requires every provider job to be terminal",
+    );
+  }
+  return job;
+}
+
+function normalizeEvidence(input) {
+  const runAttempt = positiveInteger(input?.runAttempt, "runAttempt");
+  if (!Array.isArray(input?.jobs) || input.jobs.length === 0) {
+    throw new Error("legacy terminal evidence requires provider jobs");
+  }
+  const jobs = input.jobs
+    .map((job) => normalizeProviderJob(job, runAttempt))
+    .sort((left, right) => left.id - right.id);
+  if (new Set(jobs.map((job) => job.id)).size !== jobs.length) {
+    throw new Error(
+      "legacy terminal evidence contains duplicate provider jobs",
+    );
+  }
+  if (!jobs.some((job) => job.conclusion === "failure")) {
+    throw new Error(
+      "legacy failed run evidence requires a failed provider job",
+    );
+  }
+  const runUpdatedAt = timestamp(input?.runUpdatedAt, "runUpdatedAt");
+  if (
+    jobs.some((job) => Date.parse(job.completedAt) > Date.parse(runUpdatedAt))
+  ) {
+    throw new Error("legacy provider job completion follows the run readback");
+  }
+  const body = {
+    schema: text(input?.schema),
+    candidateId: exactRoot(input?.candidateId, "candidateId"),
+    pullRequestNumber: positiveInteger(
+      input?.pullRequestNumber,
+      "pullRequestNumber",
+    ),
+    sourceHead: exactSha(input?.sourceHead, "sourceHead"),
+    sourceWorkflowRunId: positiveInteger(
+      input?.sourceWorkflowRunId,
+      "sourceWorkflowRunId",
+    ),
+    runAttempt,
+    runStatus: text(input?.runStatus).toLowerCase(),
+    runConclusion: text(input?.runConclusion).toLowerCase(),
+    runUpdatedAt,
+    totalJobCount: jobs.length,
+    nonterminalJobCount: 0,
+    workerTerminationProven: true,
+    jobs,
+    reason: text(input?.reason),
+  };
+  if (body.schema !== LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA) {
+    throw new Error(
+      `legacy terminal evidence must use ${LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA}`,
+    );
+  }
+  if (
+    body.runStatus !== "completed" ||
+    body.runConclusion !== "failure" ||
+    !body.reason
+  ) {
+    throw new Error(
+      "legacy terminal evidence requires one completed failed run with zero nonterminal jobs and proven worker termination",
+    );
+  }
+  const evidenceRoot = devDeliveryContentRoot(body);
+  if (exactRoot(input?.evidenceRoot, "evidenceRoot") !== evidenceRoot) {
+    throw new Error("legacy terminal evidence root mismatch");
+  }
+  return { ...body, evidenceRoot };
+}
+
+function assertExactCoverage(candidates, evidence) {
+  const expected = candidates.map((candidate) => candidate.candidateId).sort();
+  const observed = evidence.map((entry) => entry.candidateId).sort();
+  if (
+    expected.length !== observed.length ||
+    expected.some((candidateId, index) => candidateId !== observed[index])
+  ) {
+    throw new Error(
+      "legacy terminal recovery must cover every live legacy native candidate exactly once",
+    );
+  }
+}
+
+export function recoverLegacyTerminalDevDeliveryQueue(
+  queueInput,
+  requestInput,
+  { now = new Date().toISOString() } = {},
+) {
+  const currentTime = timestamp(now, "now");
+  const request = requestInput || {};
+  if (request.schema !== LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA) {
+    throw new Error(
+      `legacy terminal recovery must use ${LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA}`,
+    );
+  }
+  const before = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback: true,
+  });
+  const expectedOldStateRoot = exactRoot(
+    request.expectedOldStateRoot,
+    "expectedOldStateRoot",
+  );
+  if (expectedOldStateRoot !== before.stateRoot) {
+    throw new Error("legacy terminal recovery expected-old state drift");
+  }
+  const legacyCandidates = before.candidates.filter(legacyLiveNativeCandidate);
+  if (legacyCandidates.length === 0) {
+    throw new Error("legacy terminal recovery found no live legacy candidate");
+  }
+  if (!Array.isArray(request.evidence)) {
+    throw new Error("legacy terminal recovery evidence must be an array");
+  }
+  const evidence = request.evidence.map(normalizeEvidence);
+  if (
+    new Set(evidence.map((entry) => entry.candidateId)).size !== evidence.length
+  ) {
+    throw new Error(
+      "legacy terminal recovery evidence contains duplicate candidates",
+    );
+  }
+  assertExactCoverage(legacyCandidates, evidence);
+
+  const queue = clone(before);
+  delete queue.stateRoot;
+  const transitions = [];
+  for (const entry of evidence) {
+    const candidate = queue.candidates.find(
+      (row) => row.candidateId === entry.candidateId,
+    );
+    if (
+      !candidate ||
+      candidate.pullRequestNumber !== entry.pullRequestNumber ||
+      candidate.sourceHead !== entry.sourceHead ||
+      candidate.sourceWorkflowRunId !== entry.sourceWorkflowRunId
+    ) {
+      throw new Error(
+        "legacy terminal evidence does not match candidate identity",
+      );
+    }
+    const active = queue.activeWarrant?.candidateId === candidate.candidateId;
+    if (!active && candidate.status !== "queued") {
+      throw new Error(
+        `legacy candidate status ${candidate.status} requires the exact active Warrant`,
+      );
+    }
+    const priorStatus = candidate.status;
+    candidate.status = "terminal-failure";
+    candidate.updatedAt = currentTime;
+    candidate.terminal = {
+      outcome: "terminal-failure",
+      reason: entry.reason,
+      evidenceRoot: entry.evidenceRoot,
+      authority: "legacy-hosted-native-terminal-recovery",
+      sourceWorkflowRunId: entry.sourceWorkflowRunId,
+      runAttempt: entry.runAttempt,
+      workerTerminationProven: true,
+      closedAt: currentTime,
+      ...(active
+        ? {
+            fencingToken: queue.activeWarrant.fencingToken,
+            leaseGeneration: queue.activeWarrant.generation,
+          }
+        : {}),
+    };
+    transitions.push({
+      candidateId: candidate.candidateId,
+      pullRequestNumber: candidate.pullRequestNumber,
+      sourceHead: candidate.sourceHead,
+      priorStatus,
+      activeWarrant: active,
+      outcome: "terminal-failure",
+      evidenceRoot: entry.evidenceRoot,
+    });
+  }
+  queue.activeWarrant = null;
+  queue.generation += 1;
+  queue.updatedAt = currentTime;
+  queue.stateRoot = devDeliveryContentRoot(queue);
+  const after = normalizeDevDeliveryQueue(queue);
+  const requestBody = {
+    schema: LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA,
+    expectedOldStateRoot,
+    evidence,
+  };
+  const requestRoot = devDeliveryContentRoot(requestBody);
+  const receipt = {
+    schema: LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA,
+    action: "legacy-terminal-recovery",
+    expectedOldStateRoot,
+    nextStateRoot: after.stateRoot,
+    requestRoot,
+    transitions,
+    nextAction: "Select the next strictly valid queued candidate, if any.",
+  };
+  return {
+    queue: after,
+    receipt,
+    receiptRoot: devDeliveryContentRoot(receipt),
+  };
+}