@kungfu-tech/buildchain 2.14.0 → 2.14.1-alpha.1

package/dist/site/public-surface-audit.json

@@ -3,11 +3,11 @@
   "contract": "kungfu-buildchain-public-surface-reverse-audit",
   "status": "passed",
   "summary": {
-    "cliCommandCount": 82,
+    "cliCommandCount": 83,
     "workflowCount": 47,
     "actionCount": 4,
     "sitePageCount": 50,
-    "docCommandRefCount": 253,
+    "docCommandRefCount": 256,
     "failureCount": 0
   },
   "enumerated": {
@@ -307,6 +307,11 @@
         "source": "bin/buildchain.mjs",
         "usage": "buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]"
       },
+      {
+        "id": "portable-cache",
+        "source": "bin/buildchain.mjs",
+        "usage": "buildchain portable-cache plan --manifest <file-or-json> [--output <file>]"
+      },
       {
         "id": "project",
         "source": "bin/buildchain.mjs",
@@ -1228,6 +1233,7 @@
           "cadence",
           "capabilities",
           "dry-run",
+          "landing-mode",
           "max-actions",
           "merge-method",
           "mode",
@@ -1237,7 +1243,7 @@
           "same-repository-only",
           "target-branch"
         ],
-        "inputCount": 15,
+        "inputCount": 16,
         "secrets": [
           "github-token"
         ],
@@ -1332,6 +1338,7 @@
           "buildchain-ref",
           "buildchain-repository",
           "dry-run",
+          "landing-mode",
           "max-merges",
           "merge-method",
           "ready-label",
@@ -1340,18 +1347,20 @@
           "same-repository-only",
           "target-branch"
         ],
-        "inputCount": 12,
+        "inputCount": 13,
         "secrets": [
           "github-token"
         ],
         "secretCount": 1,
         "outputs": [
+          "action-count",
+          "enqueued-count",
           "evaluated-count",
           "final-base-sha",
           "merged-count",
           "skipped-count"
         ],
-        "outputCount": 4
+        "outputCount": 6
       },
       {
         "id": "npm-publish",
@@ -1481,6 +1490,7 @@
           "buildchain-ref",
           "buildchain-repository",
           "dry-run",
+          "landing-mode",
           "max-actions",
           "merge-method",
           "ready-label",
@@ -1489,7 +1499,7 @@
           "same-repository-only",
           "target-branch"
         ],
-        "inputCount": 12,
+        "inputCount": 13,
         "secrets": [
           "github-token"
         ],
@@ -3110,6 +3120,21 @@
         "path": "docs/cli.md",
         "command": "buildchain npm dry-run"
       },
+      {
+        "id": "portable-cache",
+        "path": "docs/cli.md",
+        "command": "buildchain portable-cache plan"
+      },
+      {
+        "id": "portable-cache",
+        "path": "docs/cli.md",
+        "command": "buildchain portable-cache receipt"
+      },
+      {
+        "id": "portable-cache",
+        "path": "docs/cli.md",
+        "command": "buildchain portable-cache plan"
+      },
       {
         "id": "project",
         "path": "docs/artifact-verification-envelope.md",
@@ -3461,9 +3486,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "b07ed2241d34696ad0500c3431b2106b1499a0d4372a77385a8c0e0698421d76",
-    "workflowRegistryDigest": "62b7ca87803c461e1e1436a477c3b6b70103eed84dbf14d855d383e810d7d71e",
-    "pageRegistryDigest": "1bec2a9ecc289aed2e3dd4e646989b1335d090b8445e04170c25955e638011ee"
+    "cliRegistryDigest": "b469949f77ed7777f23fe68c54daf6d2c20d3afc97f3bbd5a178a91202a068d0",
+    "workflowRegistryDigest": "283dac6adfcebb463db63545d2c00686daa317f1603f5ac13c9d5c5c3c91592f",
+    "pageRegistryDigest": "77061e79d575aa965482dad26280a0262d09aadc92c87038065a3591c7072045"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-16T23:48:23.239Z",
-  "publishedAt": "2026-07-16T23:48:23.239Z",
+  "generatedAt": "2026-07-17T00:51:57.848Z",
+  "publishedAt": "2026-07-17T00:51:57.848Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "1886767b1d8621d17dc8de5bcf94dcec12d090fe",
+  "sourceRevision": "5073d72855cd9136112a1866398f072ac3a065bb",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.0",
+    "version": "2.14.1-alpha.1",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -25,6 +25,7 @@
       "./readme-badges": "./packages/core/readme-badges.js",
       "./public-surface-audit": "./packages/core/public-surface-audit.js",
       "./logging": "./packages/core/logging.js",
+      "./portable-dev-cache": "./packages/core/portable-dev-cache.js",
       "./publication-artifact": "./packages/core/publication-artifact.js",
       "./publication-package": "./packages/core/publication-package.js",
       "./publication-authority": "./packages/core/publication-authority.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-16T23:48:23.239Z",
-  "publishedAt": "2026-07-16T23:48:23.239Z",
+  "generatedAt": "2026-07-17T00:51:57.848Z",
+  "publishedAt": "2026-07-17T00:51:57.848Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "1886767b1d8621d17dc8de5bcf94dcec12d090fe",
+  "sourceRevision": "5073d72855cd9136112a1866398f072ac3a065bb",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.0",
+    "version": "2.14.1-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a9a9594c0bd9584b145a8f41847db83e297c1c4d1b8b2d7c4bf8d10264ab1cef"
+      "digest": "sha256:308bc83b7403f407ac1be13d7c19000fa249f4bedf0c9c90b2f701e5163471a3"
     },
     {
       "id": "install",
@@ -189,7 +189,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a7a31bbec048acbc9759324c5421c7ea0734f394f8d6705b63d70654867fdfa6"
+      "digest": "sha256:9ecf8c220b5ff02ee5719cb877d4b2b159c3d683af288630eae0013d9d906373"
     },
     {
       "id": "build-facts",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:5cf4bf4332119531f6aaa1c123d7f64e6af4a61611c4e4a33d40bd9fb46448cf"
+      "digest": "sha256:5e0e6ef6720b51bb156da54390850688ef9a538908afb22484011364102e48eb"
     },
     {
       "id": "release-flow",

package/dist/site/workflow-registry.json

@@ -879,6 +879,7 @@
         "cadence",
         "capabilities",
         "dry-run",
+        "landing-mode",
         "max-actions",
         "merge-method",
         "mode",
@@ -888,7 +889,7 @@
         "same-repository-only",
         "target-branch"
       ],
-      "inputCount": 15,
+      "inputCount": 16,
       "secrets": [
         "github-token"
       ],
@@ -1001,6 +1002,7 @@
         "buildchain-ref",
         "buildchain-repository",
         "dry-run",
+        "landing-mode",
         "max-merges",
         "merge-method",
         "ready-label",
@@ -1009,18 +1011,20 @@
         "same-repository-only",
         "target-branch"
       ],
-      "inputCount": 12,
+      "inputCount": 13,
       "secrets": [
         "github-token"
       ],
       "secretCount": 1,
       "outputs": [
+        "action-count",
+        "enqueued-count",
         "evaluated-count",
         "final-base-sha",
         "merged-count",
         "skipped-count"
       ],
-      "outputCount": 4,
+      "outputCount": 6,
       "surface": "dev-governance",
       "capabilityGroup": "governance-versioning",
       "status": "active"
@@ -1162,6 +1166,7 @@
         "buildchain-ref",
         "buildchain-repository",
         "dry-run",
+        "landing-mode",
         "max-actions",
         "merge-method",
         "ready-label",
@@ -1170,7 +1175,7 @@
         "same-repository-only",
         "target-branch"
       ],
-      "inputCount": 12,
+      "inputCount": 13,
       "secrets": [
         "github-token"
       ],

package/docs/MAP.md

@@ -103,6 +103,7 @@ replace them.
 | How do I use one build job that follows alpha during development and stable for releases? | [`reusable-build-surface.md`](reusable-build-surface.md#automatic-channel-router) | use | preview |
 | How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |
 | How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |
+| How do ephemeral GitHub-hosted runners share exact dependency or compiler caches without fixed-runner affinity? | [`cli.md`](cli.md#commands) | use/verify | preview |
 | How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
 | How do I automatically qualify alpha candidates and publish the newest non-revoked qualified candidate at a fixed window? | [`stable-candidate-patrol.md`](stable-candidate-patrol.md) | use | preview |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |

package/docs/cli.md

@@ -78,6 +78,7 @@ import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-pr
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
 import { createBuildchainLayoutDiscovery } from "@kungfu-tech/buildchain/buildchain-layout";
+import { createPortableDevCachePlan } from "@kungfu-tech/buildchain/portable-dev-cache";
 import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
 import capabilityRegistry from "@kungfu-tech/buildchain/site/capability-registry.json" with { type: "json" };
 import manualRegistry from "@kungfu-tech/buildchain/site/manual-registry.json" with { type: "json" };
@@ -110,6 +111,42 @@ not sufficient. The same contract is available through
 `buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow
 caller at `.github/workflows/build.yml`.
 
+`buildchain portable-cache plan` turns a consumer-owned, secret-free manifest
+into GitHub Actions cache inputs without letting each consumer invent key or
+restore-prefix semantics. The exact key binds source SHA and the consumer plan
+digest; the compatible restore prefix still requires the same provider schema,
+layer, roots, runner image, platform/architecture, toolchain, dependency lock,
+and build profile.
+
+```bash
+buildchain portable-cache plan \
+  --manifest .buildchain/portable-cache.json \
+  --output .buildchain/portable-cache-plan.json \
+  --github-output "$GITHUB_OUTPUT"
+```
+
+The emitted `cache-key`, `restore-keys`, and `cache-paths` values are intended
+for pinned `actions/cache/restore` and `actions/cache/save` actions. After
+restore and a consumer validation probe, seal the provider result:
+
+```bash
+buildchain portable-cache receipt \
+  --plan .buildchain/portable-cache-plan.json \
+  --matched-key "$CACHE_MATCHED_KEY" \
+  --cache-hit "$CACHE_HIT" \
+  --validation-status pass \
+  --cold-fallback-status passed \
+  --output .buildchain/portable-cache-receipt.json
+```
+
+The receipt distinguishes `exact`, `compatible`, `miss`, and `corrupt`.
+Unknown or contradictory provider evidence fails closed. A miss or corruption
+requires the consumer's audited cold path; a cache never substitutes for the
+consumer's current build or tests. Roots must be workspace-relative or under
+`~/`, and manifests cannot carry credentials, absolute host paths, or escape
+segments. `cold-fallback-status=passed` qualifies a miss only after the current
+source has completed its normal build and test path.
+
 Supported presets:
 
 - `--type package` for Node package repositories with pnpm, npm, or yarn.

package/docs/release-governance.md

@@ -435,9 +435,21 @@ The workflow defaults are conservative. A PR is skipped unless it targets the
 configured dev line, is not a draft, has the ready label, has no block label,
 comes from the same repository, uses an allowed work-branch prefix, has a
 current approval, is mergeable, and has the configured required checks passing.
-After each merge, the next PR is re-evaluated before it can move the protected
-dev branch. This prevents one merge from silently making the next candidate
-stale or conflicting.
+`landing-mode: auto` reads the target branch's native merge-queue state. When a
+queue exists, Buildchain never calls the direct merge endpoint: it admits at
+most one PR against the observed target-branch SHA and immutable PR head, then
+calls GraphQL `enqueuePullRequest` with `expectedHeadOid`. GitHub's
+`merge_group` checks remain the final authority for the projected merge.
+
+The admission receipt records the expected and observed base/head SHAs, policy
+checks, decision, reason, and active predecessor. Buildchain re-reads the base,
+head, mergeability, and native queue immediately before enqueueing. Base or
+head drift fails closed, an active queue entry blocks admission, and a rejected
+ready predecessor leaves its PR open while later PRs receive
+`blocked-by-predecessor`. Workflow concurrency serializes Buildchain-owned
+admission runs; GitHub still owns the atomic queue and protected-ref update.
+Repositories may explicitly select `landing-mode: direct` only when the target
+branch has no native queue. Queue presence always disables the direct path.
 
 The canonical consumer required check context is `check / check`, matching the
 reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
@@ -497,6 +509,7 @@ jobs:
       ready-label: ready
       block-labels: blocked,do-not-merge
       max-merges: 1
+      landing-mode: auto
       dry-run: ${{ inputs.dry-run || false }}
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.0",
+  "version": "2.14.1-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -28,6 +28,7 @@
     "./readme-badges": "./packages/core/readme-badges.js",
     "./public-surface-audit": "./packages/core/public-surface-audit.js",
     "./logging": "./packages/core/logging.js",
+    "./portable-dev-cache": "./packages/core/portable-dev-cache.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
     "./publication-package": "./packages/core/publication-package.js",
     "./publication-authority": "./packages/core/publication-authority.js",

package/packages/core/index.js

@@ -51,6 +51,12 @@ export {
   writeReleaseTransaction,
 } from "./publish-transaction.js";
 
+export {
+  createPortableDevCachePlan,
+  createPortableDevCacheReceipt,
+  verifyPortableDevCachePlan,
+} from "./portable-dev-cache.js";
+
 export {
   explainReleaseLineDryRun,
   formatReleaseLineDryRun,