@kungfu-tech/buildchain 2.14.1 → 2.14.2-alpha.0

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-17T00:55:24.253Z",
-  "publishedAt": "2026-07-17T00:55:24.253Z",
+  "generatedAt": "2026-07-17T02:13:15.755Z",
+  "publishedAt": "2026-07-17T02:13:15.755Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d962181c3023e587488a5276b10307007cc5a13f",
+  "sourceRevision": "dd861c4e31186a2b68ee4d624bea517757b1e2e2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.1",
+    "version": "2.14.2-alpha.0",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-17T00:55:24.253Z",
-  "publishedAt": "2026-07-17T00:55:24.253Z",
+  "generatedAt": "2026-07-17T02:13:15.755Z",
+  "publishedAt": "2026-07-17T02:13:15.755Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d962181c3023e587488a5276b10307007cc5a13f",
+  "sourceRevision": "dd861c4e31186a2b68ee4d624bea517757b1e2e2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.1",
+    "version": "2.14.2-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -229,7 +229,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:cc2f4c9d2b9988962a237bbc7e8da83385d45585e2b2dd105ff4c4334a74c05d"
+      "digest": "sha256:950ca4fb2f7ab0a7d40775593e3864f8bb1229f8543b266b00154af82c619e95"
     },
     {
       "id": "release-governance",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:5cf4bf4332119531f6aaa1c123d7f64e6af4a61611c4e4a33d40bd9fb46448cf"
+      "digest": "sha256:511d214a8d9a24125f64c5cb363aeeb3351a1236eec96f5fa6f49832d5fcba98"
     },
     {
       "id": "release-flow",
@@ -269,7 +269,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:797d8f0e81974a49125b17256bb8b4a85fc60673e06d6bbecbbf399651163437"
+      "digest": "sha256:856a7602cf1c2d3a0a540cdf0d64566914f79dde24417c92089f0466bee25df1"
     }
   ],
   "facts": [

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/publish-transaction.md

@@ -395,6 +395,20 @@ last transient error seen before a rerun.
 An exact tag at an unrelated SHA is still a material conflict and blocks
 recovery.
 
+Governed retries distinguish unrelated channel advancement from advancement
+made by their own durable transaction. An unrelated descendant remains an
+auditable `superseded-promotion` no-op. When the target ref is exactly the
+recorded `release_sha` for the requested source, target, and expected version,
+Buildchain resumes finalization, restores publish evidence, and emits the
+release-passport paths needed by downstream controller receipts.
+
+Publication authority planning applies the same occupied-version rule as the
+later mutation step. If a current alpha transaction already contains published
+material and regenerating version state would create new release material, the
+planner advances to the next alpha before sealing authority. It never seals the
+old published version and then lets the publisher discover a different version
+inside the mutation boundary.
+
 If finalization fails after an exact Git tag is created, the next run reads the
 durable `finalizing` state, verifies the exact tag points at the recorded
 release SHA, and retries the remaining floating refs. An exact tag at a

package/docs/release-governance.md

@@ -411,7 +411,8 @@ buildchain dev merge-queue \
   --repository owner/repository \
   --branch dev/v4/v4.0 \
   --workflow .github/workflows/source-acceptance.yml \
-  --workflow .github/workflows/affected-native-pr.yml
+  --workflow .github/workflows/affected-native-pr.yml \
+  --bypass-app dedicated-release-app
 ```
 
 After reviewing the plan, repeat with `--apply`. Buildchain creates or updates
@@ -423,6 +424,15 @@ protection. The ruleset uses the first merge method that the repository itself
 allows, and fails closed when the repository has no enabled merge method.
 Re-running the command is idempotent.
 
+Merge-queue rules also reject generated post-publish version-state ref updates.
+When the sealed promotion workflow uses a dedicated GitHub App, user, or team
+already declared by release governance, repeat `--bypass-app`, `--bypass-user`,
+or `--bypass-team` to project that exact actor into the ruleset. Bypass actors
+are never inferred and broad repository or organization roles are not accepted.
+This keeps ordinary feature PRs on the predecessor-aligned queue path while the
+sealed publication authority can finish its machine-verified bookkeeping. The
+dry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.
+
 Buildchain provides the reusable
 `.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a
 scheduled or manual "merge ready dev PRs" pass. The consumer repository owns
@@ -435,9 +445,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 +519,7 @@ jobs:
       ready-label: ready
       block-labels: blocked,do-not-merge
       max-merges: 1
+      landing-mode: auto
       dry-run: ${{ inputs.dry-run || false }}
 ```
 

package/docs/web-surface-deployments.md

@@ -745,7 +745,10 @@ When enabled, Buildchain owns the full release apply state machine:
   operator can verify staging from the PR page and use merge as the approval
   action. Consumers do not need to hand-write `gh pr create` or production
   release-intent glue.
-- Production runs when `production-apply` is true and either:
+- `production-apply=true` enables the production capability; it does not request
+  production for every event. Ordinary `main` pushes remain staging-only and
+  can create or update a release PR. Production runs only when the capability
+  is enabled and either:
   - a `workflow_dispatch` passes `production-approved=true` and the triggering
     actor currently has `write`, `maintain`, or `admin` permission; or
   - `production-release-on-main=true` and the `main` push commit is associated
@@ -794,7 +797,7 @@ jobs:
       build-command: npm run build
       verify-command: npm run check
       artifact-path: dist
-      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
+      production-apply: true
       production-release-on-main: true
       production-release-label: buildchain-release
       production-release-head-prefix: release/
@@ -804,6 +807,13 @@ jobs:
       production-environment: production
 ```
 
+Keep `production-apply` enabled in the caller when the repository supports
+production. Buildchain derives whether the current event may use that
+capability: an ordinary `main` push plans and applies staging, a matching
+reviewed release PR merge authorizes production, and an approved trusted manual
+dispatch authorizes production. Inputs from an untrusted event cannot turn that
+decision on.
+
 `production-release-pr-mode` controls the post-staging handoff:
 
 | Mode | Behavior |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.1",
+  "version": "2.14.2-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/scripts/buildchain-patrol.mjs

@@ -91,6 +91,7 @@ export function normalizePatrolOptions(options = {}) {
     sameRepositoryOnly: options.sameRepositoryOnly ?? process.env.BUILDCHAIN_PATROL_SAME_REPOSITORY_ONLY,
     maxActions: intOption(options.maxActions ?? process.env.BUILDCHAIN_PATROL_MAX_ACTIONS, 1),
     mergeMethod: String(options.mergeMethod || process.env.BUILDCHAIN_PATROL_MERGE_METHOD || "merge").trim(),
+    landingMode: String(options.landingMode || process.env.BUILDCHAIN_PATROL_LANDING_MODE || "auto").trim(),
     dryRun: boolOption(options.dryRun ?? process.env.BUILDCHAIN_PATROL_DRY_RUN, true),
     outputPath: String(options.outputPath || process.env.BUILDCHAIN_PATROL_OUTPUT_PATH || DEFAULT_OUTPUT_PATH),
   };
@@ -167,6 +168,7 @@ export async function runBuildchainPatrol(optionsInput = {}, clientInput) {
         sameRepositoryOnly: options.sameRepositoryOnly,
         maxMerges: options.maxActions,
         mergeMethod: options.mergeMethod,
+        landingMode: options.landingMode,
         dryRun: options.dryRun,
         outputPath: path.join(path.dirname(options.outputPath), "dev-pr-auto-merge.json"),
       },
@@ -178,7 +180,7 @@ export async function runBuildchainPatrol(optionsInput = {}, clientInput) {
       result: mergeResult,
     });
     result.summary.evaluatedCount += mergeResult.evaluated.length;
-    result.summary.actionCount += mergeResult.merged.length;
+    result.summary.actionCount += mergeResult.actions.length;
     result.summary.skippedCount += mergeResult.skipped.length;
   }
 

package/scripts/dev-merge-queue.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
 const RULESET_PREFIX = "Buildchain dev merge queue";
+const RULESET_BYPASS_TYPES = new Set(["Integration", "Team", "User"]);
 
 function positiveInteger(value, label, fallback) {
   const parsed = Number(value || fallback);
@@ -19,6 +20,53 @@ function requiredString(value, label) {
   return normalized;
 }
 
+function normalizeRulesetBypassActors(actors = []) {
+  const normalized = [];
+  const seen = new Set();
+  for (const actor of actors) {
+    const actorType = requiredString(actor?.actor_type, "ruleset bypass actor type");
+    const actorId = Number(actor?.actor_id);
+    if (!RULESET_BYPASS_TYPES.has(actorType)) {
+      throw new Error(`ruleset bypass actor type must be Integration, Team, or User, got '${actorType}'`);
+    }
+    if (!Number.isInteger(actorId) || actorId < 1) {
+      throw new Error("ruleset bypass actor id must be a positive integer");
+    }
+    const key = `${actorType}:${actorId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalized.push({ actor_id: actorId, actor_type: actorType, bypass_mode: "always" });
+  }
+  return normalized;
+}
+
+export async function resolveRulesetBypassActors({
+  api,
+  repository,
+  apps = [],
+  users = [],
+  teams = [],
+} = {}) {
+  const [owner] = requiredString(repository, "repository").split("/");
+  const actors = [];
+  for (const slug of apps) {
+    const app = await api.request("GET", `apps/${encodeURIComponent(requiredString(slug, "bypass app"))}`);
+    actors.push({ actor_id: app.id, actor_type: "Integration" });
+  }
+  for (const login of users) {
+    const user = await api.request("GET", `users/${encodeURIComponent(requiredString(login, "bypass user"))}`);
+    actors.push({ actor_id: user.id, actor_type: "User" });
+  }
+  for (const slug of teams) {
+    const team = await api.request(
+      "GET",
+      `orgs/${encodeURIComponent(owner)}/teams/${encodeURIComponent(requiredString(slug, "bypass team"))}`,
+    );
+    actors.push({ actor_id: team.id, actor_type: "Team" });
+  }
+  return normalizeRulesetBypassActors(actors);
+}
+
 export function selectMergeQueueMethod(repositorySettings = {}) {
   const candidates = [
     ["MERGE", repositorySettings.allow_merge_commit],
@@ -64,6 +112,7 @@ export function createDevMergeQueuePlan({
   protection,
   repositorySettings,
   rulesets = [],
+  bypassActors = [],
   checkResponseTimeoutMinutes = 120,
   maxEntriesToBuild = 1,
 } = {}) {
@@ -84,6 +133,7 @@ export function createDevMergeQueuePlan({
     name: rulesetName,
     target: "branch",
     enforcement: "active",
+    bypass_actors: normalizeRulesetBypassActors(bypassActors),
     conditions: {
       ref_name: {
         include: [`refs/heads/${normalizedBranch}`],
@@ -144,6 +194,9 @@ export async function reconcileDevMergeQueue({
   branch,
   workflows,
   apply = false,
+  bypassApps = [],
+  bypassUsers = [],
+  bypassTeams = [],
   checkResponseTimeoutMinutes = 120,
   maxEntriesToBuild = 1,
 } = {}) {
@@ -151,6 +204,13 @@ export async function reconcileDevMergeQueue({
   const repositorySettings = await api.request("GET", `repos/${repository}`);
   const protection = await api.request("GET", `repos/${repository}/branches/${encodedBranch}/protection`);
   const rulesets = await api.request("GET", `repos/${repository}/rulesets?includes_parents=false&per_page=100`);
+  const bypassActors = await resolveRulesetBypassActors({
+    api,
+    repository,
+    apps: bypassApps,
+    users: bypassUsers,
+    teams: bypassTeams,
+  });
   const plan = createDevMergeQueuePlan({
     repository,
     branch,
@@ -158,6 +218,7 @@ export async function reconcileDevMergeQueue({
     protection,
     repositorySettings,
     rulesets,
+    bypassActors,
     checkResponseTimeoutMinutes,
     maxEntriesToBuild,
   });
@@ -245,6 +306,9 @@ async function main(args = process.argv.slice(2)) {
     apply: args.includes("--apply"),
     checkResponseTimeoutMinutes: readFlag(args, "check-response-timeout-minutes", "120"),
     maxEntriesToBuild: readFlag(args, "max-entries-to-build", "1"),
+    bypassApps: readRepeatedFlag(args, "bypass-app"),
+    bypassUsers: readRepeatedFlag(args, "bypass-user"),
+    bypassTeams: readRepeatedFlag(args, "bypass-team"),
   });
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }