@kungfu-tech/buildchain 3.0.2-alpha.3 → 3.0.2-alpha.4

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.3",
+    "version": "3.0.2-alpha.4",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v3",
@@ -170,7 +170,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:acd401cfc46450115a3763fd4b679d85f185e8757ebd52510d6262e1533df4cf",
-      "auditDigest": "sha256:26993d90db926a0e086947a28359242cdaba042f0ceacee75f680216d6143ab7"
+      "auditDigest": "sha256:366a389cde040e8c0b1cebe65587565871288941d886c775693fd87c99f42b9d"
     },
     {
       "contractVersion": 1,
@@ -713,7 +713,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:b1617817941f332dc666ca941bce82491c2324abef127e3c6e9800d86a01dd6b"
+      "auditDigest": "sha256:74b2abc26f004a55e36f0c746925255281b5df3de1ce4efb141f558919bf28fd"
     },
     {
       "contractVersion": 1,
@@ -3311,5 +3311,5 @@
     }
   ],
   "compatibilityDigest": "sha256:008b1c5a90a787cf30106829ac7aca68ab501f6d9c375e415d9c5c6b89039f46",
-  "contractDigest": "sha256:33cde8db3883afe7d7695d2c2e332a8c6753a804e14db0c8e3d2e5d2eb492271"
+  "contractDigest": "sha256:d5d86b0bfb22f11daae2e9f6ecc9444e5d3a6ee1b35115d7a9e2692f3364ab73"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-27T01:10:48.385Z",
-  "publishedAt": "2026-07-27T01:10:48.385Z",
+  "generatedAt": "2026-07-27T05:08:19.148Z",
+  "publishedAt": "2026-07-27T05:08:19.148Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "8b1b52cc9dc5eb0a89f2aae3acfd08a22dae6934",
+  "sourceRevision": "ba9a63a1960beab3660cacaca76ceed02ea9a0f1",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.3",
+    "version": "3.0.2-alpha.4",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -640,7 +640,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-alpha-candidate-patrol.md",
-      "digest": "sha256:ebaec4d54f0f66fd82ec24b34e227b20f90a4a76cf724cf94d9e912422ee89a2",
+      "digest": "sha256:ffd96da21ed6a99e01d60b6545ca4a486d6c22dbf053f717a3a2cce5c3970a28",
       "headings": [
         {
           "level": 1,
@@ -653,7 +653,7 @@
           "anchor": "reusable-workflow"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches and accepts\nthe development head only when:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact source SHA succeeded;\n- the latest completed Alpha preflight for the same SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
     },
     {
       "id": "manual:github-governance-authority",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "23b05dbcaf2e80dd05bdc0c908f16ec927bbd6d1cfd3bc5c329fe972ae868195",
+    "sha256": "ef5ce46ab398bd64e8ddaf9916d6f107baea6ddd91f21eb904470f14ff4926dd",
     "summary": {
       "cliCommandCount": 96,
       "workflowCount": 54,
@@ -228,7 +228,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "23b05dbcaf2e80dd05bdc0c908f16ec927bbd6d1cfd3bc5c329fe972ae868195",
+      "sha256": "ef5ce46ab398bd64e8ddaf9916d6f107baea6ddd91f21eb904470f14ff4926dd",
       "summary": {
         "cliCommandCount": 96,
         "workflowCount": 54,

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.3",
+    "version": "3.0.2-alpha.4",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/node-api-registry.json

@@ -125,7 +125,7 @@
       "specifier": "@kungfu-tech/buildchain/channel-candidate",
       "export": "./channel-candidate",
       "target": "./packages/core/channel-candidate.js",
-      "digest": "sha256:fe37b5319563d16d5f4f2009c2fc097fe41f0630429c5291fb3e18ae7e7b5ee5",
+      "digest": "sha256:4f667440dc1d3df1663fba13afe68358aa3fc0c9316d1393e760bd932cec8a45",
       "summary": "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs.",
       "capabilityGroup": "governance-versioning",
       "audience": [

package/dist/site/page-registry.json

@@ -574,7 +574,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-alpha-candidate-patrol.md",
-      "digest": "sha256:ebaec4d54f0f66fd82ec24b34e227b20f90a4a76cf724cf94d9e912422ee89a2",
+      "digest": "sha256:ffd96da21ed6a99e01d60b6545ca4a486d6c22dbf053f717a3a2cce5c3970a28",
       "headings": [
         {
           "level": 1,
@@ -587,7 +587,7 @@
           "anchor": "reusable-workflow"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches and accepts\nthe development head only when:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact source SHA succeeded;\n- the latest completed Alpha preflight for the same SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
     },
     {
       "id": "manual:github-governance-authority",

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

@@ -4118,7 +4118,7 @@
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "a1c10dd6977d85a7bc793054baa549108b46d6d18098de109733e01b9151a024",
     "workflowRegistryDigest": "adbf4d0f0f67aab550735fac44b544cb5eeeaa94d1604c18953d7e81d3cb0136",
-    "pageRegistryDigest": "b8b393b19ef85b18e389837a8d956f5a93050ea2e700de0a02961f6899bfef90"
+    "pageRegistryDigest": "d0af91a01b205954540fe4388cc08dcfaa9182f4eb6cfb162bb0c987fc33eef2"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-27T01:10:48.385Z",
-  "publishedAt": "2026-07-27T01:10:48.385Z",
+  "generatedAt": "2026-07-27T05:08:19.148Z",
+  "publishedAt": "2026-07-27T05:08:19.148Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "8b1b52cc9dc5eb0a89f2aae3acfd08a22dae6934",
+  "sourceRevision": "ba9a63a1960beab3660cacaca76ceed02ea9a0f1",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.3",
+    "version": "3.0.2-alpha.4",
     "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-27T01:10:48.385Z",
-  "publishedAt": "2026-07-27T01:10:48.385Z",
+  "generatedAt": "2026-07-27T05:08:19.148Z",
+  "publishedAt": "2026-07-27T05:08:19.148Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "8b1b52cc9dc5eb0a89f2aae3acfd08a22dae6934",
+  "sourceRevision": "ba9a63a1960beab3660cacaca76ceed02ea9a0f1",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.3",
+    "version": "3.0.2-alpha.4",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/docs/dev-alpha-candidate-patrol.md

@@ -21,14 +21,26 @@ ai_provenance:
 
 Buildchain provides a reusable observation and PR controller for repositories
 that promote a development branch into a protected Alpha branch. It does not
-publish Alpha. The controller reads the exact heads of both branches and accepts
-the development head only when:
+publish Alpha. The controller reads the exact heads of both branches, walks the
+bounded development history from newest to oldest (stopping early at the Alpha
+head), and selects the newest commit that satisfies all of these conditions:
 
 - the source is strictly ahead of the recorded target head;
-- the latest completed Dev Patrol for that exact source SHA succeeded;
-- the latest completed Alpha preflight for the same SHA succeeded; and
+- the latest completed Dev Patrol for that exact commit SHA succeeded;
+- the latest completed Alpha preflight for the same commit SHA succeeded; and
 - both runs are within the caller's evidence age limit.
 
+The selected commit can be behind the observed development head when newer
+commits have not completed both workflows yet. The decision binds the observed
+head, selected SHA, and count of skipped newer commits. This makes a slow native
+verification lane live under continuous development without silently treating
+an unqualified head as releasable.
+
+History discovery is bounded to the newest 1000 development commits. The
+controller then compares the selected SHA to the exact Alpha head before it can
+be eligible, so a bounded scan cannot turn a commit outside the promotion
+ancestry into a candidate.
+
 The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the
 source and target branches and SHAs, comparison distance, workflow paths, run
 identities and attempts, completion times, URLs, policy, and a canonical decision

package/package.json

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

package/packages/core/channel-candidate.js

@@ -34,28 +34,40 @@ function required(value, name) {
 
 function sha(value, name) {
   const normalized = required(value, name).toLowerCase();
-  if (!SHA.test(normalized)) throw new Error(`${name} must be an exact 40-character SHA`);
+  if (!SHA.test(normalized))
+    throw new Error(`${name} must be an exact 40-character SHA`);
   return normalized;
 }
 
 function qualifyWorkflow(row, { sourceSha, now, maxAgeSeconds }) {
-  if (!row || typeof row !== "object") throw new Error("workflow evidence is required");
+  if (!row || typeof row !== "object")
+    throw new Error("workflow evidence is required");
   const workflowPath = required(row.workflowPath, "workflowPath");
   if (sha(row.headSha, `${workflowPath} headSha`) !== sourceSha) {
-    throw new Error(`${workflowPath} evidence does not bind source SHA ${sourceSha}`);
+    throw new Error(
+      `${workflowPath} evidence does not bind source SHA ${sourceSha}`,
+    );
   }
   if (row.status !== "completed" || row.conclusion !== "success") {
     throw new Error(`${workflowPath} is not a completed successful run`);
   }
   const completedAt = required(row.completedAt, `${workflowPath} completedAt`);
   const ageSeconds = (Date.parse(now) - Date.parse(completedAt)) / 1000;
-  if (!Number.isFinite(ageSeconds) || ageSeconds < 0 || ageSeconds > maxAgeSeconds) {
-    throw new Error(`${workflowPath} evidence is stale or has an invalid completion time`);
+  if (
+    !Number.isFinite(ageSeconds) ||
+    ageSeconds < 0 ||
+    ageSeconds > maxAgeSeconds
+  ) {
+    throw new Error(
+      `${workflowPath} evidence is stale or has an invalid completion time`,
+    );
   }
   const runId = Number(row.runId);
   const runAttempt = Number(row.runAttempt || 1);
-  if (!Number.isSafeInteger(runId) || runId <= 0) throw new Error(`${workflowPath} runId is invalid`);
-  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0) throw new Error(`${workflowPath} runAttempt is invalid`);
+  if (!Number.isSafeInteger(runId) || runId <= 0)
+    throw new Error(`${workflowPath} runId is invalid`);
+  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0)
+    throw new Error(`${workflowPath} runAttempt is invalid`);
   return {
     workflowPath,
     workflowName: required(row.workflowName, `${workflowPath} workflowName`),
@@ -79,9 +91,31 @@ export function decideChannelCandidate(input) {
   const repository = required(input.repository, "repository");
   const sourceBranch = required(input.sourceBranch, "sourceBranch");
   const targetBranch = required(input.targetBranch, "targetBranch");
-  if (sourceBranch === targetBranch) throw new Error("sourceBranch and targetBranch must differ");
+  if (sourceBranch === targetBranch)
+    throw new Error("sourceBranch and targetBranch must differ");
   const sourceSha = sha(input.sourceSha, "sourceSha");
   const targetSha = sha(input.targetSha, "targetSha");
+  const selection = input.selection
+    ? {
+        mode: required(input.selection.mode, "selection.mode"),
+        observedSourceHeadSha: sha(
+          input.selection.observedSourceHeadSha,
+          "selection.observedSourceHeadSha",
+        ),
+        skippedNewerCommitCount: Number(
+          input.selection.skippedNewerCommitCount || 0,
+        ),
+      }
+    : undefined;
+  if (
+    selection &&
+    (!Number.isSafeInteger(selection.skippedNewerCommitCount) ||
+      selection.skippedNewerCommitCount < 0)
+  ) {
+    throw new Error(
+      "selection.skippedNewerCommitCount must be a non-negative integer",
+    );
+  }
   const now = required(input.now || new Date().toISOString(), "now");
   const maxAgeSeconds = Number(input.maxAgeSeconds ?? 7 * 24 * 60 * 60);
   if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds <= 0) {
@@ -89,7 +123,10 @@ export function decideChannelCandidate(input) {
   }
   const comparison = input.comparison || {};
   if (comparison.status !== "ahead" || Number(comparison.aheadBy) <= 0) {
-    const reason = comparison.status === "identical" ? "target-already-current" : "source-does-not-lead-target";
+    const reason =
+      comparison.status === "identical"
+        ? "target-already-current"
+        : "source-does-not-lead-target";
     return {
       schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
       eligible: false,
@@ -97,15 +134,25 @@ export function decideChannelCandidate(input) {
       repository,
       source: { branch: sourceBranch, sha: sourceSha },
       target: { branch: targetBranch, sha: targetSha },
-      comparison: { status: String(comparison.status || "unknown"), aheadBy: Number(comparison.aheadBy || 0) },
+      comparison: {
+        status: String(comparison.status || "unknown"),
+        aheadBy: Number(comparison.aheadBy || 0),
+      },
       decidedAt: now,
     };
   }
-  const rows = Array.isArray(input.workflowEvidence) ? input.workflowEvidence : [];
-  const expectedPaths = [...new Set((input.requiredWorkflowPaths || []).map(String))];
-  if (expectedPaths.length === 0) throw new Error("requiredWorkflowPaths must not be empty");
+  const rows = Array.isArray(input.workflowEvidence)
+    ? input.workflowEvidence
+    : [];
+  const expectedPaths = [
+    ...new Set((input.requiredWorkflowPaths || []).map(String)),
+  ];
+  if (expectedPaths.length === 0)
+    throw new Error("requiredWorkflowPaths must not be empty");
   if (rows.length !== expectedPaths.length) {
-    throw new Error(`expected exactly ${expectedPaths.length} workflow evidence rows, got ${rows.length}`);
+    throw new Error(
+      `expected exactly ${expectedPaths.length} workflow evidence rows, got ${rows.length}`,
+    );
   }
   const byPath = new Map();
   for (const row of rows) {
@@ -116,7 +163,8 @@ export function decideChannelCandidate(input) {
     byPath.set(qualified.workflowPath, qualified);
   }
   for (const workflowPath of expectedPaths) {
-    if (!byPath.has(workflowPath)) throw new Error(`missing workflow evidence: ${workflowPath}`);
+    if (!byPath.has(workflowPath))
+      throw new Error(`missing workflow evidence: ${workflowPath}`);
   }
   const body = {
     schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
@@ -126,8 +174,11 @@ export function decideChannelCandidate(input) {
     source: { branch: sourceBranch, sha: sourceSha },
     target: { branch: targetBranch, sha: targetSha },
     comparison: { status: "ahead", aheadBy: Number(comparison.aheadBy) },
+    ...(selection ? { selection } : {}),
     sourceLockRef: channelCandidateSourceLockRef(targetBranch, sourceSha),
-    workflowEvidence: expectedPaths.map((workflowPath) => byPath.get(workflowPath)),
+    workflowEvidence: expectedPaths.map((workflowPath) =>
+      byPath.get(workflowPath),
+    ),
     policy: { maxAgeSeconds, requiredWorkflowPaths: expectedPaths },
     decidedAt: now,
   };

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -16,13 +16,18 @@ function bool(value, fallback = false) {
 
 function repository(value) {
   const normalized = text(value);
-  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) throw new Error(`repository must be owner/repo, got ${value || "<empty>"}`);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized))
+    throw new Error(`repository must be owner/repo, got ${value || "<empty>"}`);
   return normalized;
 }
 
 function branch(value, name) {
   const normalized = text(value).replace(/^refs\/heads\//, "");
-  if (!normalized || normalized.startsWith("-") || /[\s~^:?*[\\]/.test(normalized)) {
+  if (
+    !normalized ||
+    normalized.startsWith("-") ||
+    /[\s~^:?*[\\]/.test(normalized)
+  ) {
     throw new Error(`${name} is not a valid branch name`);
   }
   return normalized;
@@ -43,24 +48,69 @@ function integer(value, fallback) {
 
 export function normalizeDevAlphaPatrolOptions(options = {}) {
   return {
-    repository: repository(options.repository ?? process.env.BUILDCHAIN_CHANNEL_PATROL_REPOSITORY ?? process.env.GITHUB_REPOSITORY),
-    sourceBranch: branch(options.sourceBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH ?? "dev/v4/v4.0", "sourceBranch"),
-    targetBranch: branch(options.targetBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH ?? "alpha/v4/v4.0", "targetBranch"),
-    devWorkflowPath: workflowPath(options.devWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DEV_WORKFLOW ?? ".github/workflows/dev-verify-patrol.yml", "devWorkflowPath"),
-    alphaWorkflowPath: workflowPath(options.alphaWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_ALPHA_WORKFLOW ?? ".github/workflows/alpha-promotion-preflight.yml", "alphaWorkflowPath"),
-    maxAgeSeconds: integer(options.maxAgeSeconds ?? process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS, 7 * 24 * 60 * 60),
-    createPullRequest: bool(options.createPullRequest ?? process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR, false),
-    dryRun: bool(options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN, true),
-    now: text(options.now ?? process.env.BUILDCHAIN_CHANNEL_PATROL_NOW) || new Date().toISOString(),
-    outputPath: text(options.outputPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_OUTPUT_PATH) || ".buildchain/patrol/dev-alpha-candidate.json",
+    repository: repository(
+      options.repository ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_REPOSITORY ??
+        process.env.GITHUB_REPOSITORY,
+    ),
+    sourceBranch: branch(
+      options.sourceBranch ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH ??
+        "dev/v4/v4.0",
+      "sourceBranch",
+    ),
+    targetBranch: branch(
+      options.targetBranch ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH ??
+        "alpha/v4/v4.0",
+      "targetBranch",
+    ),
+    devWorkflowPath: workflowPath(
+      options.devWorkflowPath ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_DEV_WORKFLOW ??
+        ".github/workflows/dev-verify-patrol.yml",
+      "devWorkflowPath",
+    ),
+    alphaWorkflowPath: workflowPath(
+      options.alphaWorkflowPath ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_ALPHA_WORKFLOW ??
+        ".github/workflows/alpha-promotion-preflight.yml",
+      "alphaWorkflowPath",
+    ),
+    maxAgeSeconds: integer(
+      options.maxAgeSeconds ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS,
+      7 * 24 * 60 * 60,
+    ),
+    createPullRequest: bool(
+      options.createPullRequest ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR,
+      false,
+    ),
+    dryRun: bool(
+      options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN,
+      true,
+    ),
+    now:
+      text(options.now ?? process.env.BUILDCHAIN_CHANNEL_PATROL_NOW) ||
+      new Date().toISOString(),
+    outputPath:
+      text(
+        options.outputPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_OUTPUT_PATH,
+      ) || ".buildchain/patrol/dev-alpha-candidate.json",
   };
 }
 
 function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
   const matching = runs
-    .filter((run) => run.path === workflowPathValue && run.head_sha === sourceSha)
+    .filter(
+      (run) => run.path === workflowPathValue && run.head_sha === sourceSha,
+    )
     .sort((left, right) => Number(right.id) - Number(left.id));
-  if (matching.length === 0) throw new Error(`missing completed same-SHA workflow run: ${workflowPathValue}`);
+  if (matching.length === 0)
+    throw new Error(
+      `missing completed same-SHA workflow run: ${workflowPathValue}`,
+    );
   const run = matching[0];
   return {
     workflowPath: workflowPathValue,
@@ -75,25 +125,122 @@ function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
   };
 }
 
-export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput) {
+function workflowEvidenceIsFreshAndSuccessful(run, { now, maxAgeSeconds }) {
+  const completedAt = Date.parse(run.updated_at);
+  const ageSeconds = (Date.parse(now) - completedAt) / 1000;
+  return (
+    run.status === "completed" &&
+    run.conclusion === "success" &&
+    Number.isFinite(ageSeconds) &&
+    ageSeconds >= 0 &&
+    ageSeconds <= maxAgeSeconds
+  );
+}
+
+function latestRunsBySha(runs, workflowPathValue) {
+  const latest = new Map();
+  for (const run of runs.filter((row) => row.path === workflowPathValue)) {
+    const current = latest.get(run.head_sha);
+    if (!current || Number(run.id) > Number(current.id))
+      latest.set(run.head_sha, run);
+  }
+  return latest;
+}
+
+export function selectLatestQualifiedSource({
+  sourceHistory,
+  workflowRunsByPath,
+  requiredWorkflowPaths,
+  now,
+  maxAgeSeconds,
+}) {
+  const latestByPath = new Map(
+    requiredWorkflowPaths.map((workflow) => [
+      workflow,
+      latestRunsBySha(workflowRunsByPath.get(workflow) || [], workflow),
+    ]),
+  );
+  for (let index = 0; index < sourceHistory.length; index += 1) {
+    const sourceSha = sourceHistory[index];
+    const rows = requiredWorkflowPaths.map((workflow) =>
+      latestByPath.get(workflow).get(sourceSha),
+    );
+    if (
+      rows.every((run) =>
+        workflowEvidenceIsFreshAndSuccessful(run || {}, { now, maxAgeSeconds }),
+      )
+    ) {
+      return {
+        sourceSha,
+        skippedNewerCommitCount: index,
+        workflowEvidence: requiredWorkflowPaths.map((workflow) =>
+          latestWorkflowEvidence(
+            workflowRunsByPath.get(workflow) || [],
+            workflow,
+            sourceSha,
+          ),
+        ),
+      };
+    }
+  }
+  throw new Error(
+    "no source commit ahead of target has fresh completed successful same-SHA workflow evidence",
+  );
+}
+
+export async function runDevAlphaCandidatePatrol(
+  optionsInput = {},
+  clientInput,
+) {
   const options = normalizeDevAlphaPatrolOptions(optionsInput);
-  if (options.sourceBranch === options.targetBranch) throw new Error("source and target branches must differ");
-  const client = clientInput || createGitHubChannelCandidateClient({
-    repository: options.repository,
-    token: process.env.GITHUB_TOKEN,
-  });
-  const [sourceSha, targetSha] = await Promise.all([
+  if (options.sourceBranch === options.targetBranch)
+    throw new Error("source and target branches must differ");
+  const client =
+    clientInput ||
+    createGitHubChannelCandidateClient({
+      repository: options.repository,
+      token: process.env.GITHUB_TOKEN,
+    });
+  const [observedSourceHeadSha, targetSha] = await Promise.all([
     client.resolveBranch(options.sourceBranch),
     client.resolveBranch(options.targetBranch),
   ]);
-  const comparison = await client.compare(targetSha, sourceSha);
-  const requiredWorkflowPaths = [options.devWorkflowPath, options.alphaWorkflowPath];
+  const headComparison = await client.compare(targetSha, observedSourceHeadSha);
+  const requiredWorkflowPaths = [
+    options.devWorkflowPath,
+    options.alphaWorkflowPath,
+  ];
+  let sourceSha = observedSourceHeadSha;
+  let comparison = headComparison;
   let workflowEvidence = [];
-  if (comparison.status === "ahead" && Number(comparison.ahead_by) > 0) {
-    const runs = await client.listCompletedRuns(sourceSha);
-    workflowEvidence = requiredWorkflowPaths.map((workflow) =>
-      latestWorkflowEvidence(runs, workflow, sourceSha),
-    );
+  let skippedNewerCommitCount = 0;
+  if (
+    headComparison.status === "ahead" &&
+    Number(headComparison.ahead_by) > 0
+  ) {
+    const [sourceHistory, ...workflowRunSets] = await Promise.all([
+      client.listBranchHistory(options.sourceBranch, targetSha),
+      ...requiredWorkflowPaths.map((workflow) =>
+        client.listCompletedWorkflowRuns(workflow, options.sourceBranch),
+      ),
+    ]);
+    const selected = selectLatestQualifiedSource({
+      sourceHistory,
+      workflowRunsByPath: new Map(
+        requiredWorkflowPaths.map((workflow, index) => [
+          workflow,
+          workflowRunSets[index],
+        ]),
+      ),
+      requiredWorkflowPaths,
+      now: options.now,
+      maxAgeSeconds: options.maxAgeSeconds,
+    });
+    sourceSha = selected.sourceSha;
+    skippedNewerCommitCount = selected.skippedNewerCommitCount;
+    workflowEvidence = selected.workflowEvidence;
+    if (sourceSha !== observedSourceHeadSha)
+      comparison = await client.compare(targetSha, sourceSha);
   }
   const decision = decideChannelCandidate({
     repository: options.repository,
@@ -102,6 +249,11 @@ export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput)
     sourceSha,
     targetSha,
     comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
+    selection: {
+      mode: "latest-qualified-source-ancestor",
+      observedSourceHeadSha,
+      skippedNewerCommitCount,
+    },
     workflowEvidence,
     requiredWorkflowPaths,
     maxAgeSeconds: options.maxAgeSeconds,
@@ -118,11 +270,14 @@ export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput)
         "Buildchain exact-source channel candidate.",
         "",
         `- Source branch: \`${options.sourceBranch}\``,
+        `- Observed source HEAD: \`${observedSourceHeadSha}\``,
         `- Source SHA: \`${sourceSha}\``,
+        `- Skipped newer unqualified commits: \`${skippedNewerCommitCount}\``,
         `- Target branch/head: \`${options.targetBranch}\` / \`${targetSha}\``,
         `- Decision root: \`${decision.decisionRoot}\``,
         ...decision.workflowEvidence.map(
-          (row) => `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
+          (row) =>
+            `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
         ),
         "",
         "The source-lock branch must continue to point at the exact source SHA. This patrol never merges the PR, publishes a package, creates a tag, or creates a release.",
@@ -142,7 +297,11 @@ function encodeRef(value) {
   return value.split("/").map(encodeURIComponent).join("/");
 }
 
-export function createGitHubChannelCandidateClient({ repository: repositoryInput, token, fetchImpl = globalThis.fetch }) {
+export function createGitHubChannelCandidateClient({
+  repository: repositoryInput,
+  token,
+  fetchImpl = globalThis.fetch,
+}) {
   const [owner, repo] = repository(repositoryInput).split("/");
   const headers = {
     accept: "application/vnd.github+json",
@@ -150,34 +309,74 @@ export function createGitHubChannelCandidateClient({ repository: repositoryInput
     "user-agent": "buildchain-dev-alpha-candidate-patrol",
     "x-github-api-version": "2022-11-28",
   };
-  async function api(requestPath, { method = "GET", body, allow404 = false } = {}) {
+  async function api(
+    requestPath,
+    { method = "GET", body, allow404 = false } = {},
+  ) {
     const response = await fetchImpl(`https://api.github.com${requestPath}`, {
       method,
-      headers: Object.fromEntries(Object.entries(headers).filter(([, value]) => value)),
+      headers: Object.fromEntries(
+        Object.entries(headers).filter(([, value]) => value),
+      ),
       body: body === undefined ? undefined : JSON.stringify(body),
     });
     const raw = await response.text();
     const payload = raw ? JSON.parse(raw) : undefined;
     if (allow404 && response.status === 404) return undefined;
-    if (!response.ok) throw new Error(`GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`);
+    if (!response.ok)
+      throw new Error(
+        `GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`,
+      );
     return payload;
   }
   return {
     async resolveBranch(ref) {
-      const payload = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`);
+      const payload = await api(
+        `/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`,
+      );
       return text(payload.object?.sha);
     },
     async compare(baseSha, headSha) {
       return api(`/repos/${owner}/${repo}/compare/${baseSha}...${headSha}`);
     },
-    async listCompletedRuns(headSha) {
-      const payload = await api(`/repos/${owner}/${repo}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=completed&per_page=100`);
-      return payload.workflow_runs || [];
+    async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
+      const runs = [];
+      for (let page = 1; page <= 10; page += 1) {
+        const payload = await api(
+          `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflowPathValue)}/runs?branch=${encodeURIComponent(sourceBranch)}&status=completed&per_page=100&page=${page}`,
+        );
+        const rows = payload.workflow_runs || [];
+        runs.push(...rows);
+        if (rows.length < 100) return runs;
+      }
+      throw new Error(
+        `${workflowPathValue} completed workflow history exceeds 1000 runs`,
+      );
+    },
+    async listBranchHistory(sourceBranch, targetSha) {
+      const commits = [];
+      for (let page = 1; page <= 10; page += 1) {
+        const rows = await api(
+          `/repos/${owner}/${repo}/commits?sha=${encodeURIComponent(sourceBranch)}&per_page=100&page=${page}`,
+        );
+        for (const commit of rows) {
+          const commitSha = text(commit.sha);
+          if (commitSha === targetSha) return commits;
+          commits.push(commitSha);
+        }
+        if (rows.length < 100) return commits;
+      }
+      return commits;
     },
     async ensureImmutableBranch(ref, sourceSha) {
-      const current = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`, { allow404: true });
+      const current = await api(
+        `/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`,
+        { allow404: true },
+      );
       if (current && current.object?.sha !== sourceSha) {
-        throw new Error(`source-lock branch ${ref} points to ${current.object?.sha}, not ${sourceSha}`);
+        throw new Error(
+          `source-lock branch ${ref} points to ${current.object?.sha}, not ${sourceSha}`,
+        );
       }
       if (current) return current;
       return api(`/repos/${owner}/${repo}/git/refs`, {
@@ -186,11 +385,16 @@ export function createGitHubChannelCandidateClient({ repository: repositoryInput
       });
     },
     async ensurePullRequest({ head, base, title, body }) {
-      const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);
-      return open[0] || api(`/repos/${owner}/${repo}/pulls`, {
-        method: "POST",
-        body: { head, base, title, body },
-      });
+      const open = await api(
+        `/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`,
+      );
+      return (
+        open[0] ||
+        api(`/repos/${owner}/${repo}/pulls`, {
+          method: "POST",
+          body: { head, base, title, body },
+        })
+      );
     },
   };
 }
@@ -214,7 +418,8 @@ async function main() {
   fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
   fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
   const summary = markdown(result);
-  if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+  if (process.env.GITHUB_STEP_SUMMARY)
+    fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
   else process.stdout.write(summary);
   if (process.env.GITHUB_OUTPUT) {
     const outputs = {
@@ -224,7 +429,12 @@ async function main() {
       "source-lock-ref": result.decision.sourceLockRef || "",
       "promotion-pr": result.pullRequest?.html_url || "",
     };
-    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${Object.entries(outputs).map(([key, value]) => `${key}=${value}`).join("\n")}\n`);
+    fs.appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      `${Object.entries(outputs)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("\n")}\n`,
+    );
   }
 }