@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.2

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/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",
@@ -431,6 +433,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 +467,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 +486,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 +501,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"
       ]
     }
   ]

package/architecture/maintainability-policy.json

@@ -5,12 +5,12 @@
   "enforcementRevision": "5308189b09bcb5a1314195412f2807a40d678838",
   "repositoryBudgets": {
     "baselineRevision": "c70e6ac28431888b24fefc218246cc69f8dde85a",
-    "maxHandMaintainedSourceFiles": 344,
-    "maxHandMaintainedSourceLines": 132432,
+    "maxHandMaintainedSourceFiles": 353,
+    "maxHandMaintainedSourceLines": 136936,
     "maxWorkflowFiles": 71,
-    "maxWorkflowLines": 23636,
-    "latestTransition": "The v4 architecture and Warrant-plan validators now fail closed unless production release authority, writers, and migration phases have completed the v3-to-v4 cutover.",
-    "rationale": "Sixteen validation lines close the production-authority, fallback, rollback, writer-runtime, legacy-retirement, and historical-comparison separation invariants required for the v4 release. This exact measured ceiling cannot grow implicitly."
+    "maxWorkflowLines": 24190,
+    "latestTransition": "The v4 promotion surface now admits one rooted transient exact-runtime authorization, rejects persisted selector authority, and carries fresh-attempt Stage Capsule reuse lineage into the final Release Passport.",
+    "rationale": "The existing dev queue Warrant admission, adopter compatibility port, and exact source-proof reuse remain included unchanged. Two bounded runtime-resume modules, one provider authorization adapter, rooted schema and fixtures, workflow admission gates, action and Passport plumbing, capability metadata, and negative tests account for this transition's exact growth. Exact SHAs remain transient, failed jobs are never rerun, unaffected sealed platform capsules are reused by identity, and v3 behavior remains unchanged. These exact 353-file, 136936-source-line and 24190-workflow-line ceilings cannot grow implicitly."
   },
   "sourceBudgets": {
     "newFileLines": 600,
@@ -19,6 +19,14 @@
     "existingDebtPolicy": "no-widening"
   },
   "approvedNewFileTransitions": {
+    "scripts/dev-delivery-source-proof-reuse.mjs": {
+      "maxLines": 631,
+      "rationale": "The bounded source-proof driver seals one exact PR qualification and verifies either the reviewed two-parent merge or GitHub's exact linear replay by base ancestry, commit count and every intermediate tree. Unknown, nonlinear, extra-commit or tree-drift compositions still fail closed to the full lifecycle, and this exact file ceiling cannot grow implicitly."
+    },
+    "scripts/dev-pr-prequeue-guard.mjs": {
+      "maxLines": 399,
+      "rationale": "The bounded guard keeps latest-base delta attribution, rooted source-proof reuse classification, synthetic merge composition readback, stable pre-enqueue failures, and the final base, head, queue, and Warrant compare-and-swap outside the legacy Dev PR controller; it cannot mutate the frozen source head or authorize landing by itself, and this exact file ceiling cannot grow implicitly."
+    },
     "scripts/v4-architecture.mjs": {
       "maxLines": 610,
       "rationale": "The v4 architecture validator adds only the bounded production-authority, fallback, rollback, writer-runtime, and legacy-retirement checks required for the final release cutover. This exact reviewed ceiling cannot grow implicitly."
@@ -56,12 +64,24 @@
       "maxFunctionLines": 255,
       "maxFunctionComplexity": 33,
       "rationale": "The one versioned transaction authority keeps strict declaration normalization, deterministic effect planning, atomic checkpoints, rooted observations and receipts, and bounded recovery in one independently tested audit surface; this exact preview ceiling cannot grow implicitly."
+    },
+    "packages/core/v4-runtime-ref-resume-authority.js": {
+      "maxLines": 625,
+      "rationale": "The reviewed v4 authority keeps exact-runtime authorization, source and lock binding, fresh-attempt Stage Capsule reuse, floating-ref movement, final readback, and Passport lineage verification in one bounded public module; persistence scanning is separately owned and this exact ceiling cannot grow implicitly."
+    },
+    "packages/core/v4-runtime-selector-persistence.js": {
+      "maxLines": 228,
+      "rationale": "The isolated source scanner rejects persisted exact, train, authority, variable, secret, and environment selector authority while inventorying OIDC, IAM, and external authority metadata without reading credentials; this exact ceiling cannot grow implicitly."
     }
   },
   "approvedExistingDebtTransitions": {
     "packages/core/index.js": {
-      "maxLines": 698,
-      "rationale": "The public facade forwards the reviewed declarative release-tail transaction, adapter and compatibility APIs without adding a second implementation or execution path; this exact post-integration ceiling cannot grow implicitly."
+      "maxLines": 699,
+      "rationale": "The public facade forwards the reviewed runtime-resume authority beside the existing declarative release-tail and v4 governance APIs without adding a second implementation or execution path; this exact post-integration ceiling cannot grow implicitly."
+    },
+    "actions/promote-buildchain-ref/index.js": {
+      "maxFunctionLines": 276,
+      "rationale": "The existing action entrypoint forwards one optional rooted v4 runtime-resume evidence document into the already audited durable Passport operation; this one-line terminal widening is exact and cannot grow implicitly."
     },
     "actions/promote-buildchain-ref/lib.js": {
       "maxLines": 6952,
@@ -72,8 +92,9 @@
       "rationale": "The runtime entrypoint now binds every compatibility command and alias, including the upstream paper command, through the tested command registry; this exact post-integration wiring ceiling cannot grow implicitly."
     },
     "packages/core/release-passport.js": {
-      "maxLines": 2859,
-      "rationale": "Responsibility-owned validators preserve issue ordering, byte-stable reports, and upstream release-evidence attachment verification while the terminal report constructor drops from 470 lines to at most 180. This exact post-integration ceiling cannot grow implicitly."
+      "maxLines": 2958,
+      "maxFunctionLines": 304,
+      "rationale": "Responsibility-owned validators preserve issue ordering, byte-stable reports, upstream release evidence, consumer-policy certification, and the new rooted runtime A+B resume lineage. The optional attachment is normalized and independently reverified before inclusion; these exact post-integration ceilings cannot grow implicitly."
     },
     "packages/core/buildchain-contract.js": {
       "maxLines": 1095,
@@ -85,6 +106,10 @@
       "maxLines": 1368,
       "rationale": "The publication authority now declares the alpha/v4/v4.0 and release/v4/v4.0 protected channels required for the v4 public train. This exact two-line channel transition cannot grow implicitly."
     },
+    "packages/core/buildchain-config.js": {
+      "maxLines": 1806,
+      "rationale": "Artifact signing configuration admits only the Buildchain-owned JIT profile with exact safe archive-relative target paths while rejecting credentials, entitlement files, wildcard paths, incompatible artifact kinds, and incomplete declarations; this exact wiring ceiling cannot grow implicitly."
+    },
     "scripts/check-internal-architecture.mjs": {
       "maxFunctionComplexity": 37,
       "rationale": "Ownership coverage and zero-cycle enforcement were added to the pre-existing architecture traversal; this exact guard complexity ceiling cannot grow implicitly."
@@ -136,6 +161,44 @@
     }
   },
   "approvedPublicSurfaceTransitions": {
+    "workflow:check": {
+      "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
+      "contract": {
+        "id": "check",
+        "path": ".github/workflows/check.yml",
+        "reusable": true,
+        "inputs": [
+          "buildchain-ref",
+          "buildchain-repository",
+          "mode",
+          "node-version",
+          "require-version-state",
+          "source-proof-closure-paths-json",
+          "source-proof-dependency-paths-json",
+          "source-proof-policy-paths-json",
+          "source-proof-required-contexts-json",
+          "source-proof-reuse",
+          "upload-artifacts",
+          "working-directory"
+        ],
+        "secrets": [],
+        "outputs": [
+          "controller-plan-artifact",
+          "controller-plan-digest",
+          "controller-plan-json",
+          "controller-receipt-artifact",
+          "controller-receipt-digest",
+          "controller-receipt-json",
+          "controller-receipt-status",
+          "source-proof-decision-root",
+          "source-proof-producer-run-id",
+          "source-proof-reuse-reason",
+          "source-proof-reused",
+          "source-proof-root"
+        ]
+      },
+      "rationale": "Add an opt-in merge-group fast path that accepts only an unexpired artifact from a successful same-workflow pull-request run and recomputes exact source, base, patch, runtime, plan, policy, closure, dependency, required-context, controller-receipt, and two-parent merge-group bindings. Existing callers remain on the full lifecycle by default, while any missing evidence, API failure, mismatch, grouped composition, or malformed proof also runs the full lifecycle."
+    },
     "action:promote-buildchain-ref": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
       "contract": {
@@ -210,6 +273,9 @@
           "release-passport-platform-manifest-paths",
           "release-passport-product-name",
           "release-passport-promotion-routing-json",
+          "release-passport-v4-consumer-policy-certification-json",
+          "release-passport-v4-consumer-policy-certification-root",
+          "release-passport-v4-runtime-resume-evidence-json",
           "release-tail-state-path",
           "require-governance",
           "require-publication-qualification",
@@ -226,7 +292,7 @@
         "secrets": [],
         "outputs": []
       },
-      "rationale": "The promote action opts into the reviewed declarative release-tail provider path and exposes only rooted transaction checkpoint inputs; the legacy GitHub Release path remains the default and provider failure cannot select success."
+      "rationale": "The promote action preserves the independently rooted v4 consumer-policy certification and now accepts one optional verified runtime-resume evidence document for final Release Passport construction; v3 behavior remains unchanged."
     },
     "cli:architecture": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
@@ -339,6 +405,7 @@
         "path": ".github/workflows/dev-pr-auto-merge.yml",
         "reusable": true,
         "inputs": [
+          "active-lease-context",
           "affected-paths-json",
           "allowed-head-prefixes",
           "assignment-root",
@@ -389,7 +456,7 @@
           "warrant-state-root"
         ]
       },
-      "rationale": "Extend targeted exact-head admission with an optional rooted Project Cut replay proof for the exact current base and immutable Warrant state-commit readback while independent approval, required checks, native queue admission, and exact integration proof remain authoritative."
+      "rationale": "Extend targeted exact-head admission with an optional rooted Project Cut replay proof and the exact active-lease status context needed to read back the same fenced Warrant before enqueue, while independent approval, required checks, native queue admission, and exact integration proof remain authoritative."
     },
     "workflow:stable-candidate-patrol": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
@@ -435,6 +502,59 @@
       },
       "rationale": "The existing release-propagation command adds one policy-reporting Site upstream entry and exact non-force Work branch executor while preserving plan, lock, pickup, and Work Control compatibility."
     },
+    "workflow:publication-artifact": {
+      "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
+      "contract": {
+        "id": "publication-artifact",
+        "path": ".github/workflows/publication-artifact.yml",
+        "reusable": true,
+        "inputs": [
+          "artifact-name",
+          "artifact-paths",
+          "artifact-retention-days",
+          "build-command",
+          "buildchain-alpha-contract-lock-path",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "buildchain-stable-contract-lock-path",
+          "node-version",
+          "package-name",
+          "prepare-paper-package",
+          "publish-dist-tag",
+          "setup-node",
+          "target-ref",
+          "toolchain-command",
+          "toolchain-digest",
+          "toolchain-image",
+          "toolchain-type",
+          "verify-command",
+          "working-directory"
+        ],
+        "secrets": [],
+        "outputs": [
+          "controller-plan-artifact",
+          "controller-plan-digest",
+          "controller-plan-json",
+          "controller-receipt-artifact",
+          "controller-receipt-digest",
+          "controller-receipt-json",
+          "controller-receipt-status",
+          "package-name",
+          "package-version",
+          "publication-artifact-name",
+          "publication-manifest-json",
+          "publication-manifest-path",
+          "publication-passport-path",
+          "publication-registry-path",
+          "publish-dist-tag",
+          "runtime-sha"
+        ]
+      },
+      "rationale": "The publication workflow adds consumer-owned stable and alpha lock inputs so its earliest semantic v4 admission gate can bind the persisted floating selector before controller or package execution; its outputs and v3 behavior remain unchanged."
+    },
     "workflow:.build": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
       "contract": {
@@ -469,6 +589,7 @@
           "buildchain-expected-major",
           "buildchain-ref",
           "buildchain-repository",
+          "buildchain-visible-workflow",
           "cache-dependency-lock-root",
           "cache-policy-root",
           "cache-toolchain-root",
@@ -587,10 +708,12 @@
           "release-manifest-json",
           "runner-preset",
           "runner-routing-json",
-          "trusted-event"
+          "trusted-event",
+          "v4-consumer-policy-receipt-json",
+          "v4-consumer-policy-receipt-root"
         ]
       },
-      "rationale": "The reusable build surface adds an opt-in final-byte verification command and trusted platform-native finalization mode. Existing consumers preserve control-runner behavior when both inputs are absent; platform-native mode rejects self-hosted runners and reseals artifacts only after consumer policy succeeds."
+      "rationale": "The reusable build surface carries one internal visible-workflow coordinate into the earliest semantic v4 consumer admission gate and emits the source/runtime/dual-lock-bound receipt; build, install, and release authority remain downstream of that gate."
     },
     "workflow:build": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
@@ -629,6 +752,7 @@
           "buildchain-ref",
           "buildchain-repository",
           "buildchain-stable-contract-lock-path",
+          "buildchain-visible-workflow",
           "cache-dependency-lock-root",
           "cache-policy-root",
           "cache-toolchain-root",
@@ -750,10 +874,12 @@
           "release-manifest-json",
           "runner-preset",
           "runner-routing-json",
-          "trusted-event"
+          "trusted-event",
+          "v4-consumer-policy-receipt-json",
+          "v4-consumer-policy-receipt-root"
         ]
       },
-      "rationale": "The generated channel router forwards the opt-in final-byte verification command and trusted platform-native finalization mode unchanged to the reusable build surface. Existing callers retain the control-runner default; the advanced workflow owns the hosted-runner guard and final artifact reseal."
+      "rationale": "The generated channel router forwards the visible-workflow coordinate and semantic v4 policy receipt while retaining floating v4 or v4-alpha selectors, dual consumer locks, and trusted nonpersistent runtime override routing."
     },
 
     "workflow:paper-release-sealed": {
@@ -927,6 +1053,7 @@
           "branch-protection-bypass-apps",
           "branch-protection-bypass-teams",
           "branch-protection-bypass-users",
+          "buildchain-alpha-contract-lock-path",
           "buildchain-contract-compatibility-policy",
           "buildchain-contract-drift-issue-mode",
           "buildchain-contract-lock-path",
@@ -934,6 +1061,7 @@
           "buildchain-expected-major",
           "buildchain-ref",
           "buildchain-repository",
+          "buildchain-stable-contract-lock-path",
           "channel",
           "declarative-release-tail",
           "dry-run",
@@ -952,6 +1080,8 @@
           "promotion-publication-channel",
           "promotion-router-ref",
           "promotion-router-sha",
+          "promotion-runtime-authorization-json",
+          "promotion-runtime-authorization-root",
           "promotion-runtime-ref",
           "promotion-runtime-sha",
           "promotion-shell-ref",
@@ -1017,6 +1147,7 @@
           "release-passport-output-dir",
           "release-passport-platform-manifest-paths",
           "release-passport-product-name",
+          "release-passport-v4-runtime-resume-evidence-json",
           "release-propagation-config-path",
           "required-artifact-count",
           "required-status-check",
@@ -1078,7 +1209,7 @@
           "release-tail-transaction-state"
         ]
       },
-      "rationale": "The advanced promotion workflow preserves explicit expected channel and major bindings for opaque exact-runtime contract-lock checks while adding one opt-in declarative release-tail input and five rooted transaction outputs. Existing callers preserve legacy GitHub Release behavior by default; candidate, target tree, controller, command, authority workflow and provider transaction identities remain independently bound, and incomplete or mismatched evidence still fails closed without a hidden rebuild."
+      "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."
     },
     "workflow:release-candidate-promote": {
       "fromRevision": "5308189b09bcb5a1314195412f2807a40d678838",
@@ -1172,6 +1303,7 @@
           "release-passport-output-dir",
           "release-passport-platform-manifest-paths",
           "release-passport-product-name",
+          "release-passport-v4-runtime-resume-evidence-json",
           "release-propagation-config-path",
           "required-artifact-count",
           "required-status-check",
@@ -1245,7 +1377,7 @@
           "release-tail-transaction-state"
         ]
       },
-      "rationale": "The generated v4 promotion router forwards the opt-in declarative release-tail contract and its rooted outputs through both existing channel jobs while preserving v4-alpha and v4 shell selection, exact contract-lock routing, candidate identity and default legacy publication behavior."
+      "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."
     }
   },
   "approvedExtractedDebt": {

package/architecture/v4-floating-consumer-policy.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-floating-consumer-policy/v1",
+  "policyVersion": "2026-08-14",
+  "scope": {
+    "repository": "kungfu-systems/buildchain",
+    "majorLine": "v4",
+    "persistedSelectors": ["v4", "v4-alpha"],
+    "publicWorkflowEntrypoints": [
+      ".github/workflows/.build.yml",
+      ".github/workflows/publication-artifact.yml",
+      ".github/workflows/release-candidate-promote.yml",
+      ".github/workflows/v4-stage-capsule-canary.yml"
+    ]
+  },
+  "contractLocks": {
+    "stable": {
+      "selector": "v4",
+      "path": ".buildchain/contract-lock.json"
+    },
+    "alpha": {
+      "selector": "v4-alpha",
+      "path": ".buildchain/alpha-contract-lock.json"
+    },
+    "selectedLockMustBindResolvedWorkflowShell": true,
+    "bothRootsRequiredInReceipt": true
+  },
+  "sourcePolicy": {
+    "directExactSha": "deny",
+    "exactDefault": "deny",
+    "repositoryVariableIndirection": "deny",
+    "inputOrEnvironmentIndirection": "deny",
+    "nestedCompositeIndirection": "deny",
+    "unknownSyntax": "deny",
+    "missingCallerCheckout": "deny"
+  },
+  "runtimeEscapeBoundary": {
+    "persistedSelectorOverride": false,
+    "trustedNonPersistentInput": true,
+    "requiresSeparateAuthority": true,
+    "requiresReadback": true,
+    "receiptReuse": false
+  },
+  "receipt": {
+    "schema": "contracts/v4-floating-consumer-policy-receipt-v1.schema.json",
+    "bindings": [
+      "caller-repository",
+      "caller-source-sha",
+      "invoked-workflow",
+      "visible-selector-class",
+      "channel",
+      "stable-contract-lock-root",
+      "alpha-contract-lock-root",
+      "resolved-workflow-shell-sha",
+      "resolved-runtime-sha",
+      "policy-version",
+      "policy-root",
+      "scanner-root",
+      "source-scan-root"
+    ]
+  },
+  "enforcement": {
+    "earliestConsumerAdmissionRequired": true,
+    "heavyJobsTransitivelyGated": true,
+    "externalCertificationRequired": true,
+    "releasePassportRequired": true,
+    "oldRuntimeSelfAuthorization": false
+  },
+  "authority": {
+    "v3BehaviorChange": false,
+    "providerEffects": false,
+    "credentials": false,
+    "productionMutation": false
+  }
+}

package/architecture/v4-floating-consumer-policy.md

@@ -0,0 +1,32 @@
+# Architecture Decision: v4 Floating Consumer Admission
+
+Status: accepted for the v4 shadow and protected-delivery line on 2026-08-14.
+
+Buildchain v4 consumers persist only the public `v4` and `v4-alpha` selectors.
+They commit both `.buildchain/contract-lock.json` and
+`.buildchain/alpha-contract-lock.json`; the selected lock binds the exact commit
+behind the visible workflow selector. An exact SHA remains evidence, not a
+source selector.
+
+Every declared public v4 entrypoint runs consumer admission after immutable
+source/runtime checkout and before package setup, matrix expansion, build, or
+publication work. Downstream jobs depend on that admission. The scanner uses
+the shared workflow YAML semantic layer and follows local composite action
+manifests, so block scalar text is not mistaken for a `uses` node and nested
+indirection cannot hide a selector.
+
+The rooted receipt binds the caller repository and source SHA, invoked workflow,
+selector class and channel, visible workflow-shell SHA, actual runtime SHA, both
+contract-lock roots, and the policy/scanner/source-scan roots. A trusted manual
+train or SHA may replace only the actual runtime coordinate; it does not rewrite
+the tracked selector or the lock-to-shell binding.
+
+Release-candidate Passport construction requires the receipt for v4 runtimes.
+Promotion independently certifies it, and final Release Passport construction
+requires that certification to match the caller source and actual runtime.
+Missing, rejected, stale, root-mismatched, or old-runtime evidence fails closed.
+
+The normative machine declaration is
+[`v4-floating-consumer-policy.json`](v4-floating-consumer-policy.json). v3
+behavior, provider effects, credentials, and production mutation authority are
+outside this decision.

package/architecture/v4-runtime-ref-resume-authority.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-runtime-ref-resume-authority/v1",
+  "schemaAuthority": "contracts/v4-runtime-ref-resume-authority-v1.schema.json",
+  "fixtureAuthority": "contracts/fixtures/v4-runtime-ref-resume-authority-v1/scenario.json",
+  "runtimeAuthority": "packages/core/v4-runtime-ref-resume-authority.js",
+  "mode": "v4-only",
+  "transientSelection": {
+    "trustedEvent": "workflow_dispatch",
+    "actorPermissions": ["write", "maintain", "admin"],
+    "approvedRefs": [
+      "v4",
+      "v4-alpha",
+      "train/v4/v4.N/*",
+      "authority/v4/v4.N/*"
+    ],
+    "exactShaRequiresApprovedRefReachability": true,
+    "operatorReasonRequired": true,
+    "sourceTreeBound": true,
+    "consumerPolicyReceiptBound": true,
+    "dualContractLockRootsBound": true,
+    "providerReadbackRooted": true
+  },
+  "persistence": {
+    "exactShaDefault": "deny",
+    "trainOrAuthorityDefault": "deny",
+    "repositoryVariableIndirection": "deny",
+    "secretIndirection": "deny",
+    "environmentIndirection": "deny",
+    "oidcIamAndExternalAuthorityInventory": "metadata-only"
+  },
+  "resume": {
+    "freshAttemptRequired": true,
+    "failedJobRerun": false,
+    "floatingRefMovementRequired": true,
+    "buildAndResumeRuntimeMustDiffer": true,
+    "sealedCapsuleIdentity": [
+      "source-sha",
+      "source-tree-sha",
+      "platform",
+      "build-runtime-sha",
+      "consumer-policy-receipt-root",
+      "capsule-root",
+      "identity-root",
+      "artifact-digest"
+    ],
+    "validUnaffectedPlatforms": "reuse",
+    "missingPlatforms": "rebuild",
+    "staleOrAmbiguousCapsules": "reject"
+  },
+  "passport": {
+    "section": "v4RuntimeResume",
+    "recordsRuntimeAAndB": true,
+    "authorizationRootRequired": true,
+    "lineageRootRequired": true,
+    "finalPublicReadbackRootRequired": true
+  },
+  "authority": {
+    "v3BehaviorChange": false,
+    "credentialsInEvidence": false,
+    "persistentExactSha": false,
+    "providerMutation": false
+  }
+}

package/architecture/v4-stage-capsule-qualification.json

@@ -26,7 +26,7 @@
   "publicConsumerDogfood": {
     "callerWorkflow": ".github/workflows/v4-public-consumer-dogfood.yml",
     "reusableWorkflow": "kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml",
-    "validationRef": "4178776bf635d0738cb1917e449076d64883218c",
+    "validationRef": "v4-alpha",
     "invocation": "workflow_call",
     "runtimeBinding": "job.workflow_sha",
     "consumerSourceBinding": "github.sha",
@@ -46,7 +46,7 @@
     "relativeOrSelfInvocationAllowed": false,
     "directQualificationInvocationAllowed": false,
     "candidateBranchOverrideAllowed": false,
-    "recursionRecovery": "public-train-ref-only"
+    "recursionRecovery": "floating-selector-with-trusted-runtime-input"
   },
   "faultCampaign": [
     "corrupt",

package/bin/internal/trust-release-release-handlers.mjs

@@ -262,6 +262,11 @@ async function handleCollectCommand({ args, runScript, packageVersion }) {
       collectArgs,
       "release-evidence-json",
     ),
+    v4RuntimeResumeEvidenceJson: readFlag(
+      collectArgs,
+      "v4-runtime-resume-evidence-json",
+      "",
+    ),
     githubArtifactAttestationPolicyJsons: readRepeatedFlag(
       collectArgs,
       "github-artifact-attestation-policy-json",