@kungfu-tech/buildchain 4.0.1-alpha.41 → 4.0.1-alpha.42

package/README.md

@@ -1,6 +1,7 @@
 # Buildchain
 
 <!-- buildchain-auditable-demo:start -->
+
 ## Buildchain beginner bootstrap
 
 [![Buildchain beginner bootstrap](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo.gif)](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/public-evidence.json)
@@ -54,12 +55,12 @@ The same mechanism releases Buildchain itself.
 
 ## Choose Your Path
 
-| You are... | Start here | You will get... |
-| --- | --- | --- |
-| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md) | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |
-| looking up a CLI command | [Generated CLI Reference](docs/cli-reference.md) | governed syntax, options, aliases, and side-effect-free help paths |
-| writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |
-| operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |
+| You are...                             | Start here                                                 | You will get...                                                                                                      |
+| -------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md)                     | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |
+| looking up a CLI command               | [Generated CLI Reference](docs/cli-reference.md)           | governed syntax, options, aliases, and side-effect-free help paths                                                   |
+| writing JavaScript automation          | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries                               |
+| operating an advanced build or release | [Documentation Map](docs/MAP.md)                           | capability-, intent-, and maturity-based navigation to normative contracts                                           |
 
 Production release operators should also read the
 [Buildchain v4 production release runbook](docs/v4-production-release.md).
@@ -290,6 +291,7 @@ direct consumer integration actions:
 - `actions/promote-buildchain-ref`
 - `actions/report-buildchain-issue`
 - `actions/release-tail`
+- `actions/v4-release-candidate-promote`
 
 Two additional release-authority components are also registered and versioned:
 
@@ -463,4 +465,5 @@ npm pack --dry-run --json --registry=https://registry.npmjs.org/
 - [Consumer issue reporting](docs/consumer-issue-reporting.md)
 - [Publish transaction](docs/publish-transaction.md)
 - [Declarative release-tail contract](docs/release-tail-contract.md)
+- [v4 declarative release-tail migration](docs/v4-declarative-release-tail-migration.md)
 - [Release governance](docs/release-governance.md)

package/actions/v4-release-candidate-promote/README.md

@@ -0,0 +1,3 @@
+# v4 release-candidate promote action
+
+This internal action validates a sealed v4 publication qualification receipt, aggregates the Buildchain Release Passport, and executes the fixed four-capability Release Tail Provider Plane. It has no command or shell extension input and is invoked by the v4 branch of the reusable `release-candidate-promote` workflow.

package/architecture/ci-lane-change-budget.json

@@ -183,5 +183,57 @@
       ".github/workflows/verify.yml#stage-capsule-checkpoints"
     ]
   },
-  "declarations": []
+  "declarations": [
+    {
+      "laneId": ".github/workflows/.release-candidate-promote.yml#legacy-promote",
+      "authorityClass": "release",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 45,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "protected release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "This is the existing v3 promotion lane under an explicit legacy identity, not an added execution path."
+      }
+    },
+    {
+      "laneId": ".github/workflows/.release-candidate-promote.yml#v4-declarative-promote",
+      "authorityClass": "release",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 30,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "protected release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The v4 provider lane replaces consumer tail execution only for release invocations and is outside merge-critical CI."
+      }
+    },
+    {
+      "laneId": ".github/workflows/v4-declarative-release-tail-dogfood.yml#publish",
+      "authorityClass": "release",
+      "triggerClass": "manual",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 35,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "manual dogfood release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The explicit dogfood run proves hosted provider publication and checkpoint resume without joining pull-request checks."
+      }
+    }
+  ]
 }

package/architecture/decisions/0004-v4-declarative-release-tail.md

@@ -0,0 +1,47 @@
+---
+status: accepted
+period: ongoing
+theme: buildchain-v4-declarative-release-tail
+doc_type: decision
+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
+---
+
+# ADR 0004: v4 release tails are sealed provider transactions
+
+## Decision
+
+Buildchain v4 release candidates carry a `kungfu.buildchain.v4-publication-qualification/v1` receipt. Build/Verify creates it from the candidate root, source root, typed artifact and manifest roots, floating-consumer policy digest, and a bounded freshness interval. The receipt root is written into every release-candidate Stage Capsule.
+
+`release-candidate-promote` validates that evidence before publication. It does not check out the consumer repository and does not evaluate product-owned qualification, KFD, invariant, publication, activation, or evidence commands. The v4 path accepts no non-empty `command`, `cmd`, `script`, `shell`, or `run` input. The v3 path remains available with its existing inputs and behavior.
+
+One Buildchain-owned provider transaction executes these ordered capabilities:
+
+1. `artifact.publish` creates and reads back immutable GitHub Release assets.
+2. `signed-channel.commit` commits the rooted channel document through the built-in GitHub document provider.
+3. `release.activate` commits and reads back the rooted activation document.
+4. `released-evidence.synthesize` writes receipt-only evidence from the sealed roots.
+
+Buildchain aggregates the Release Passport before the first provider mutation. All four capabilities share one transaction root and use the existing Release Tail Provider Plane envelope, idempotency, retry, observation, and receipt contracts.
+
+## Failure and resume semantics
+
+The transaction state is checkpointed after every observation and effect. A retry reads the same state, verifies its declaration and plan roots, and starts at the first capability without a settled receipt. A provider result lost after mutation is recovered by readback. Conflicting or partially matching public state enters `repair-required` without another mutation.
+
+The dogfood-only `provider-failure-after-capability` input interrupts after a durable capability checkpoint. The workflow immediately invokes the same built-in provider action against the same state path, proving local tail-only continuation and retaining the state, receipts, candidate evidence, and Release Passport as workflow artifacts.
+
+## Consequences
+
+- Consumers declare evidence and provider targets; they do not inject release-tail programs.
+- Candidate, source, artifact, and policy mismatch, tampering, missing evidence, and stale evidence fail before provider mutation.
+- Adding a new provider capability requires changing Buildchain's fixed capability registry and schema; arbitrary executable extension points are not a compatibility mechanism.
+- v3 consumers are not forced onto the v4 evidence contract.

package/architecture/maintainability-policy.json

@@ -5,12 +5,12 @@
   "enforcementRevision": "5308189b09bcb5a1314195412f2807a40d678838",
   "repositoryBudgets": {
     "baselineRevision": "858dbe00b6206a8f356b4a12d2659bee7a72e71b",
-    "maxHandMaintainedSourceFiles": 429,
-    "maxHandMaintainedSourceLines": 160703,
-    "maxWorkflowFiles": 76,
-    "maxWorkflowLines": 26320,
-    "latestTransition": "Terminal Warrant evidence correction retains prior settlement and verifies exact product integration proof.",
-    "latestTransitionRationale": "The bounded correction path cannot resettle or rewrite a terminal candidate: it retains the original evidence root, accepts one exact Integration Delivery Proof only when repository, protected base, candidate, source proof, fence, generation, merge-group commit and tree all match, and requires fresh expected-old compare-and-swap before persistence. Duplicate correction and settlement are exact no-ops; any prior-root, proof, identity or second-correction drift fails closed. The existing Project Cut adapter remains the only source-lineage replay surface and still grants no merge authority. These exact 429-file, 160703-source-line, 76-workflow-file and 26320-workflow-line ceilings contain no unrelated headroom.",
+    "maxHandMaintainedSourceFiles": 433,
+    "maxHandMaintainedSourceLines": 161573,
+    "maxWorkflowFiles": 77,
+    "maxWorkflowLines": 26557,
+    "latestTransition": "V4 release-candidate promotion closes through the declarative provider plane.",
+    "latestTransitionRationale": "Four bounded source surfaces add the sealed publication qualification contract, earliest declarative admission, the dedicated v4 promotion Action, and built-in GitHub document providers. One manual-only dogfood workflow proves floating v4 contract-lock consumption and checkpoint resume. The existing v3 action and legacy lane retain their prior inputs and implementation. These exact 433-file, 161573-source-line, 77-workflow-file and 26557-workflow-line ceilings contain no unrelated headroom.",
     "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, tolerate only a not-yet-materialized seal job while retaining exact native and duplicate-job rejection, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. The hosted process boundary anchors trust in the kernel-resolved versioned Runner.Worker path while accepting an equivalent argv-zero spelling with the same basename; its public boundary marker is allowed only at the one exact non-secret value, so a forged value under the same credential-like name still fails closed. The credentialless transfer seal validates the rooted native reuse decision against the Warrant-bound source, closure, dependency, toolchain, environment and command inputs; qualifiedBase stays in the proof and decision where it is rooted and later independently rechecked, rather than being assumed on the Warrant schema. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. Next-development parity adds one versioned transition authority, one durable controller, one bounded reservation adapter, and pure public-contract recovery evidence while retaining the existing thin floating-channel callers byte-for-byte. The floating-consumer gate reuses the existing contract-world evaluator so SHA drift passes only under the selected lock's compatibility policy, breaking surface drift still fails closed, and external certification reconstructs the receipt from the observed workflow SHA rather than the lock's historical evidence SHA. Tail reseal adds no Stage Capsule effect or general rebuild authority: it verifies the exact retained four-platform bytes, admits one known macOS tail failure through live provider readback, fences signing and finalization to explicit credentials and Warrant identity, and requires standard candidate Passport plus provider and protected readback. Compatibility Facts parity isolates canonical encoding, temporal verification, lifecycle validation, fixture projection, public authority projection, and CLI adaptation into bounded modules; legacy digest and proof arrays are derived only from exact current Fact lineage. Publication Rehearsal adds no production release authority: the content-addressed capsule contract binds source, candidate, manifest, config, canonical data-only provider bindings, provider policy, observations and core version separately from filesystem, runtime and rehearsal-only provider authority; simulate, replay and explicitly authorized provider rehearsal all reuse the release-tail planner, while same-commit local dogfood resolves the new reusable contract and exact current runtime before external callers remain on floating v4-alpha. Cross-runtime candidate recovery preserves original runtime and provider roots and creates resume lineage only after exact public ref, tag, ancestry, npm version and integrity readback. Adopter Delivery restores the reviewed public v3 gate, drivers, Passport binding, N-1 bootstrap and exact archive loader through one public v4 surface while keeping provider and release authority explicit non-claims. Floating Alpha bootstrap uses only the existing exact resolver and protected Alpha private shell to move an otherwise stale floating shell, retains public v4 stable promotion, and removes itself after protected readback. CI lane change-budget enforcement adds a bounded parser, evaluator, guard, and tests without creating another merge authority."
   },
   "sourceBudgets": {
@@ -105,8 +105,8 @@
   },
   "approvedExistingDebtTransitions": {
     "packages/core/index.js": {
-      "maxLines": 704,
-      "rationale": "The public facade exposes the bounded CI lane change-budget contract beside the existing v4 governance APIs without adding a second implementation or merge authority; this exact post-integration ceiling cannot grow implicitly."
+      "maxLines": 705,
+      "rationale": "The public facade exposes the bounded v4 publication qualification contract beside the existing v4 governance APIs without adding provider effects or a second implementation; this exact post-integration ceiling cannot grow implicitly."
     },
     "actions/promote-buildchain-ref/index.js": {
       "maxFunctionLines": 280,
@@ -156,10 +156,10 @@
       "rationale": "The generated promotion router keeps the exact candidate recovery interface and the latest bounded shell-routing implementation in one deterministic generator. It now derives the advanced contract gate's expected lane and major from the selected route without exposing them as caller-controlled public inputs. This exact combined train ceiling cannot grow implicitly."
     },
     "scripts/release-candidate-resolver.mjs": {
-      "maxLines": 810,
-      "maxFunctionLines": 306,
+      "maxLines": 854,
+      "maxFunctionLines": 309,
       "maxFunctionComplexity": 63,
-      "rationale": "The shared candidate resolver selects the original Passport runtime, seals exact payloads under the existing publication bundle contract, streams GitHub archives to disk, and verifies size and sha256 with bounded-memory reads; the exact ceiling cannot grow implicitly."
+      "rationale": "The shared candidate resolver retains its bounded archive and payload validation while additionally locating and validating the candidate-bound Stage Capsule aggregate and publication qualification receipt before exposing their exact paths. The validation is extracted from the main orchestration and does not execute consumer code; these exact ceilings cannot grow implicitly."
     },
     "scripts/auditable-demo.mjs": {
       "maxLines": 1330,
@@ -1133,6 +1133,7 @@
           "promotion-shell-ref",
           "promotion-shell-sha",
           "promotion-target-ref",
+          "provider-failure-after-capability",
           "publication-admission-json",
           "publication-authority-workflow-path",
           "publication-auto-admission",
@@ -1255,7 +1256,7 @@
           "release-tail-transaction-state"
         ]
       },
-      "rationale": "The advanced promotion workflow preserves exact contract-lock and channel bindings while adding a trusted transient runtime authorization plus expected root and an optional final Passport resume attachment. Candidate, target tree, policy, scanner, dual-lock, provider and fresh-attempt lineage remain independently bound, and incomplete or mismatched evidence fails closed before heavy work."
+      "rationale": "The advanced workflow adds an isolated v4-only declarative provider lane and one optional dogfood failure checkpoint while preserving the existing v3 promotion implementation as the legacy lane. V4 admits only sealed candidate, Stage Capsule and qualification evidence; legacy command inputs fail closed before planning and the provider resumes only incomplete capabilities."
     },
     "workflow:release-candidate-promote": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
@@ -1290,6 +1291,7 @@
           "github-release-payload-patterns",
           "github-release-title",
           "package-manager",
+          "provider-failure-after-capability",
           "publication-admission-json",
           "publication-auto-admission",
           "publication-auto-no-gate",
@@ -1423,7 +1425,7 @@
           "release-tail-transaction-state"
         ]
       },
-      "rationale": "The generated v4 promotion router preserves the opt-in declarative release-tail contract and exact contract-lock routing while forwarding one optional verified runtime-resume attachment through both existing channel jobs without changing default legacy publication behavior."
+      "rationale": "The generated router preserves exact floating v4 contract-lock routing and forwards one optional dogfood provider checkpoint into the v4-only declarative lane. Existing v3 callers retain the same defaults, public inputs and legacy implementation, while v4 rejects command-shaped tail authority before planning."
     }
   },
   "approvedExtractedDebt": {

package/contracts/fixtures/v4-tail-reseal-v1/valid.json

@@ -22,7 +22,7 @@
     "ref": "v4-alpha",
     "sha": "dddddddddddddddddddddddddddddddddddddddd",
     "contractRoot": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
-    "consumerPolicyReceiptRoot": "sha256:83e75f961e61f5a6ed3648898836076afa5561a0b25bfc07ff6d3f2d4b7405d6"
+    "consumerPolicyReceiptRoot": "sha256:c3779989554f16ea3e8cd38c270985e5168a59481596918bd57a3a0bde66de4d"
   },
   "warrant": {
     "candidateId": "candidate-alpha-2",

package/contracts/v4-publication-qualification-v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kungfu.link/schemas/buildchain/v4-publication-qualification-v1.schema.json",
+  "title": "Buildchain v4 Publication Qualification Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "repository",
+    "candidateRoot",
+    "sourceSha",
+    "sourceRoot",
+    "policyDigest",
+    "artifacts",
+    "issuedAt",
+    "expiresAt",
+    "artifactRoot",
+    "receiptRoot"
+  ],
+  "properties": {
+    "schema": { "const": "kungfu.buildchain.v4-publication-qualification/v1" },
+    "repository": { "type": "string", "pattern": "^[^/\\s]+/[^/\\s]+$" },
+    "candidateRoot": { "$ref": "#/$defs/root" },
+    "sourceSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "sourceRoot": { "$ref": "#/$defs/root" },
+    "policyDigest": { "$ref": "#/$defs/root" },
+    "artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/artifact" }
+    },
+    "issuedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "artifactRoot": { "$ref": "#/$defs/root" },
+    "receiptRoot": { "$ref": "#/$defs/root" }
+  },
+  "$defs": {
+    "root": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "platform", "artifactRoot", "manifestRoot"],
+      "properties": {
+        "role": { "type": "string", "minLength": 1 },
+        "platform": { "type": "string", "minLength": 1 },
+        "artifactRoot": { "$ref": "#/$defs/root" },
+        "manifestRoot": { "$ref": "#/$defs/root" }
+      }
+    }
+  }
+}

package/dist/site/agent-index.json

@@ -24,6 +24,7 @@
     "schemas/v4-publication-rehearsal-capsule-v1.schema.json",
     "schemas/v4-adopter-delivery-v1.schema.json",
     "schemas/release-tail-capabilities-v1.schema.json",
+    "schemas/v4-publication-qualification-v1.schema.json",
     "buildchain-contract.json",
     "kfd-upstream-aggregate.json",
     "kfd-claims.json",

package/dist/site/artifact-schemas.json

@@ -12,6 +12,7 @@
     "schemas/v4-publication-rehearsal-capsule-v1.schema.json",
     "schemas/v4-adopter-delivery-v1.schema.json",
     "schemas/release-tail-capabilities-v1.schema.json",
+    "schemas/v4-publication-qualification-v1.schema.json",
     "kfd-support.json",
     "artifact-evidence.json",
     "product-mechanism.json",
@@ -51,6 +52,7 @@
     "schemas/v4-publication-rehearsal-capsule-v1.schema.json",
     "schemas/v4-adopter-delivery-v1.schema.json",
     "schemas/release-tail-capabilities-v1.schema.json",
+    "schemas/v4-publication-qualification-v1.schema.json",
     "buildchain-contract.json",
     "kfd-claims.json",
     "product-mechanism.json",

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.41",
+    "version": "4.0.1-alpha.42",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v4",
@@ -1591,7 +1591,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:5f10c81d3f80cb417960be682921884639c40b6d875f1a3b1ffae7e652c3f468",
-      "auditDigest": "sha256:c291fe4e40be4db76da1f8b06f697df457126da5921fe9349d41eb4dbedc2172"
+      "auditDigest": "sha256:4eebf2dfffd030f88de33622e470a6a77321b67f7e717901b11207dade542f1b"
     },
     {
       "contractVersion": 1,
@@ -1646,7 +1646,7 @@
         "resume-from-candidate-run is fail-closed and uses a fresh caller event instead of rerunning a frozen startup graph"
       ],
       "breakingDigest": "sha256:9db8dd07152855d03ff30f9c571438593c689d3e8139fa45431d000f548242f5",
-      "auditDigest": "sha256:b0136525db98a9cf66490f33a91ce14bc990b8290532953a7ba7f7bbff69019e",
+      "auditDigest": "sha256:0004ab83f8e7ef1d07ebc3de28d9cd3bbbb6ce0d95cfa7eaa41107e3656f7f20",
       "compatibleBreakingDigests": [
         "sha256:aa30f22e3af0a89841310bdbdc900844dd95a66974db173fa140a71bbd7e82c0"
       ],
@@ -1819,6 +1819,52 @@
       "breakingDigest": "sha256:0bcba689ab5060e12230db4118895242ecb48677ff581ea0360b1833bdac558c",
       "auditDigest": "sha256:da366842e8943c88a4f12520faf2d19c555b7530d8f6d44cf75a37b94200960d"
     },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "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@v4",
+      "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"
+      ],
+      "breakingDigest": "sha256:9229eb3a000fb408feb6b8793c209c77afbf9327026467d68954470e22e4f8f4",
+      "auditDigest": "sha256:83fd394419851e6da877c50018e879b447497db52b0ac871dfd83e074f5459a8"
+    },
     {
       "contractVersion": 1,
       "stability": "stable",
@@ -2211,7 +2257,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:09e4b6c14e5f0f7173930f2e089f31e4db1f47c84c0a8ae7963f3973c0c2a4d5"
+      "auditDigest": "sha256:26db255c7250b899d1352c53010a5208f5299b03007179349730b37a11c10be3"
     },
     {
       "contractVersion": 1,
@@ -2233,7 +2279,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:47e2e7fdab45ab68e36b73d972eb1a8268f8bd4e408493cb51ad23cd632d9458"
+      "auditDigest": "sha256:a1400da39b461f070b0a8b0eced378eaf81938227b50eb6ee1d808081a483ed1"
     },
     {
       "contractVersion": 1,
@@ -2289,7 +2335,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:91aeff9ffcc598918626c24850a00063a79ddf26aa48702fa22e7dce8c761968",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "buildchain-ref": {
             "classification": "included",
@@ -2497,7 +2543,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:03677ba50080b3813a20004c41802e340368e4d225782fae194e3722c763bd01",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN": {
             "classification": "redacted",
@@ -3064,7 +3110,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:45978a572cf3ce57b48e5c3190761ad4fbeedc8e75ea0dae2e66ea5a980282df",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN": {
             "classification": "redacted",
@@ -3566,7 +3612,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:8e42956a2c10fa109500e72b97994f06b3d22a19cc63a46f66410b2e81706e9d",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -3783,7 +3829,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:c5274b37f04d0054559fdc8698c51bd0f0d8ae470baf163e9caa7699aa970575",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "artifact-path": {
             "classification": "digest-only",
@@ -4029,7 +4075,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:e48bb7719886d3949d63ec69d638264b20c7de8a70ee2db3cca78d4369f5a41e",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -4219,7 +4265,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:6d71409659fbf8543c7e520b0c493d8afe86bdf60286b860bb917f0041ebc173",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "artifact-name": {
             "classification": "included",
@@ -4477,6 +4523,7 @@
         "promotion-shell-ref",
         "promotion-shell-sha",
         "promotion-target-ref",
+        "provider-failure-after-capability",
         "publication-admission-json",
         "publication-authority-workflow-path",
         "publication-auto-admission",
@@ -4558,8 +4605,8 @@
       ],
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
-        "digest": "sha256:3c83524f650a4d04004400d3821dbbd081b8802035dc6004464cdcfd0b5cdfc3",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "digest": "sha256:665f27b24c6aaf813f071da1182c27ccf487df42cc0caee85afd9b5fc1bfab05",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "BUILDCHAIN_ISSUE_APP_ID": {
             "classification": "redacted",
@@ -4761,6 +4808,10 @@
             "classification": "included",
             "source": "workflow-call-input"
           },
+          "provider-failure-after-capability": {
+            "classification": "included",
+            "source": "workflow-call-input"
+          },
           "publication-admission-json": {
             "classification": "digest-only",
             "source": "workflow-call-input"
@@ -5082,7 +5133,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:015d8de793adbd4c539416be7d7512e18cc92097e629b0203fa06d2c183e98bd",
-      "auditDigest": "sha256:b0136525db98a9cf66490f33a91ce14bc990b8290532953a7ba7f7bbff69019e"
+      "auditDigest": "sha256:0004ab83f8e7ef1d07ebc3de28d9cd3bbbb6ce0d95cfa7eaa41107e3656f7f20"
     },
     {
       "contractVersion": 1,
@@ -5147,7 +5198,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:660579b5561e8e33375a3f3b1fefbb8a5bd8241a55ba43374d786fb772c24a12",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {
           "agent-work-context-json": {
             "classification": "digest-only",
@@ -5291,7 +5342,7 @@
       "controllerDescriptor": {
         "contract": "buildchain.controller-descriptor/v1",
         "digest": "sha256:b6f53563c0adc859bc586c05fce560a5094d7d9666438d63c5fd3e1fc4774555",
-        "registryDigest": "sha256:eb9eb918b763f303baf313e153076e9d3158ca28a2e6cc558834a06e49d9d9cf",
+        "registryDigest": "sha256:5250c4437ad5b1bac03d283d62ccbc0335a3fb7cb2ffe538dd9e42c3a192548a",
         "inputClassifications": {}
       },
       "guarantees": [
@@ -5307,6 +5358,6 @@
   "compatibilityFactRegistryRoot": "sha256:232fd556a2372b29db586bbc2acbdfce6464a68c93902797ff527f75f7816c42",
   "compatibilityFactCutRoot": "sha256:f61b975d4a96c921cc4bd37fb3ed9a0596b47004fe34dc7219979d697e3707f9",
   "compatibilityProofRegistryRoot": "sha256:b7194b811e4d3af2df4390bc4d1731e16a86215bd64ee18cb630dd5492f4fb63",
-  "compatibilityDigest": "sha256:5de1c69386510b74b17eb70141b8bdd07063d62c504f91db5e84b67c6d4b64a2",
-  "contractDigest": "sha256:174c9982f3ddee2c9e651ae2d29399d0bedaa2d53c234fea826a78cca2bf0a45"
+  "compatibilityDigest": "sha256:20411029d83211dff426fb6535a608902129844a5ccb4788db77d3f81becb839",
+  "contractDigest": "sha256:cfce04a67fbf3003bd6282de28ab9a71b5b2f188d59192cb1bbbb10204326a9d"
 }