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

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-17T00:51:57.848Z",
-  "publishedAt": "2026-07-17T00:51:57.848Z",
+  "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": "5073d72855cd9136112a1866398f072ac3a065bb",
+  "sourceRevision": "dd861c4e31186a2b68ee4d624bea517757b1e2e2",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.1-alpha.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:5e0e6ef6720b51bb156da54390850688ef9a538908afb22484011364102e48eb"
+      "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/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

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-alpha.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/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`);
 }

package/scripts/dev-pr-auto-merge.mjs

@@ -48,7 +48,7 @@ function choiceOption(value, valid, fallback, field) {
 }
 
 function normalizeRepo(value) {
-  const text = String(value || "").trim();
+  const text = String(value?.fullName || value || "").trim();
   const match = text.match(/^([^/\s]+)\/([^/\s]+)$/);
   if (!match) throw new Error(`repository must be owner/repo, got: ${text || "<empty>"}`);
   return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };