@kungfu-tech/buildchain 2.13.0-alpha.2 → 2.13.0

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.13.0-alpha.2",
+    "version": "2.13.0",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -2704,5 +2704,5 @@
     }
   ],
   "compatibilityDigest": "sha256:af162b86ab4506e9b5f1d3c59b41f3fd57fbad79ff4d749a7f12ff16460517f8",
-  "contractDigest": "sha256:63f9ef6dd9ce1f312c8e975479134e3be2dfb51ead80a73f0ed1c3d32781f516"
+  "contractDigest": "sha256:96593e211e995724701c04826ecf885e3a1fa0c49ab38948b5e481d44b3eba6b"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-16T02:29:49.950Z",
-  "publishedAt": "2026-07-16T02:29:49.950Z",
+  "generatedAt": "2026-07-16T07:45:10.422Z",
+  "publishedAt": "2026-07-16T07:45:10.422Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "87491685ffc7b6522176f8e7519f6c595e9bf5a7",
+  "sourceRevision": "eeac02686f845b4f496b2cbaa78713e6d4b2532b",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.13.0-alpha.2",
+    "version": "2.13.0",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -1855,7 +1855,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/stable-candidate-patrol.md",
-      "digest": "sha256:3af06c896769f5b71e1e0658035e8b4393b7f4ba263f77921cb9f9b8483518c7",
+      "digest": "sha256:87111303392ee9af59506e0d2b82fc1c4432d3953ca1efcd65b6c181a93d5385",
       "headings": [
         {
           "level": 1,
@@ -1888,7 +1888,7 @@
           "anchor": "durable-recovery"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-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-11\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to an exact 40-character commit in the\nconsumer repository whose canary workflow pins the candidate's exact Buildchain\nSHA. The qualification producer still dispatches and observes the authoritative\nconsumer workflow before writing the normal candidate-bound status. Floating\nconsumer branches are rejected, and the automatic path continues to use the\nconsumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v2/v2.12/2.12.0-alpha.4\n```\n\nand opens it against `release/v2/v2.12`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v2.12-alpha`\nor `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v2/v2.12\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-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-11\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to a dispatchable consumer branch or\ntag and `canary-sha` set to the exact 40-character commit that ref must resolve\nto. That consumer workflow pins the candidate's exact Buildchain SHA. The\nqualification producer verifies the ref binding before dispatch, accepts only a\nrun whose source SHA matches, and writes the normal candidate-bound status only\nafter success. The automatic path continues to use the consumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v2/v2.12/2.12.0-alpha.4\n```\n\nand opens it against `release/v2/v2.12`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v2.12-alpha`\nor `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v2/v2.12\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
     },
     {
       "id": "manual:toolkit-observability",

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": "c96852b69afe7c6f8a42824d03d877d988a4bf5908aafc4f07ec5e79193daf3f",
+    "sha256": "e6103b9ce8a24475e86b4347c0828052d5b112355ce9ff77c4d5dc2141ff64a4",
     "summary": {
       "cliCommandCount": 81,
       "workflowCount": 47,
@@ -225,7 +225,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "c96852b69afe7c6f8a42824d03d877d988a4bf5908aafc4f07ec5e79193daf3f",
+      "sha256": "e6103b9ce8a24475e86b4347c0828052d5b112355ce9ff77c4d5dc2141ff64a4",
       "summary": {
         "cliCommandCount": 81,
         "workflowCount": 47,

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

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

package/dist/site/page-registry.json

@@ -1789,7 +1789,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/stable-candidate-patrol.md",
-      "digest": "sha256:3af06c896769f5b71e1e0658035e8b4393b7f4ba263f77921cb9f9b8483518c7",
+      "digest": "sha256:87111303392ee9af59506e0d2b82fc1c4432d3953ca1efcd65b6c181a93d5385",
       "headings": [
         {
           "level": 1,
@@ -1822,7 +1822,7 @@
           "anchor": "durable-recovery"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-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-11\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to an exact 40-character commit in the\nconsumer repository whose canary workflow pins the candidate's exact Buildchain\nSHA. The qualification producer still dispatches and observes the authoritative\nconsumer workflow before writing the normal candidate-bound status. Floating\nconsumer branches are rejected, and the automatic path continues to use the\nconsumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v2/v2.12/2.12.0-alpha.4\n```\n\nand opens it against `release/v2/v2.12`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v2.12-alpha`\nor `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v2/v2.12\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-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-11\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to a dispatchable consumer branch or\ntag and `canary-sha` set to the exact 40-character commit that ref must resolve\nto. That consumer workflow pins the candidate's exact Buildchain SHA. The\nqualification producer verifies the ref binding before dispatch, accepts only a\nrun whose source SHA matches, and writes the normal candidate-bound status only\nafter success. The automatic path continues to use the consumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v2/v2.12/2.12.0-alpha.4\n```\n\nand opens it against `release/v2/v2.12`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v2.12-alpha`\nor `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v2/v2.12\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
     },
     {
       "id": "manual:toolkit-observability",

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

@@ -3442,7 +3442,7 @@
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "ff1772371ec74271c21b6723dad0745a080347be8feef36a37e3948ebd19993d",
     "workflowRegistryDigest": "f4dc70cba95a30b79eadbffc3a4ba5f8d382aae220a7bc13965365c2bbd5e674",
-    "pageRegistryDigest": "5df8fd620c13f894a00ecc7159b7a53f518692d3d2ab3ad0b78687582efa406a"
+    "pageRegistryDigest": "32a749f66f77ed976da58b16564ae2b27dfd16125ad3b47d49e261c09ec82f58"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-16T02:29:49.950Z",
-  "publishedAt": "2026-07-16T02:29:49.950Z",
+  "generatedAt": "2026-07-16T07:45:10.422Z",
+  "publishedAt": "2026-07-16T07:45:10.422Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "87491685ffc7b6522176f8e7519f6c595e9bf5a7",
+  "sourceRevision": "eeac02686f845b4f496b2cbaa78713e6d4b2532b",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.13.0-alpha.2",
+    "version": "2.13.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-16T02:29:49.950Z",
-  "publishedAt": "2026-07-16T02:29:49.950Z",
+  "generatedAt": "2026-07-16T07:45:10.422Z",
+  "publishedAt": "2026-07-16T07:45:10.422Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "87491685ffc7b6522176f8e7519f6c595e9bf5a7",
+  "sourceRevision": "eeac02686f845b4f496b2cbaa78713e6d4b2532b",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.13.0-alpha.2",
+    "version": "2.13.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/docs/stable-candidate-patrol.md

@@ -61,12 +61,12 @@ and allowed attestor before accepting that status.
 
 When a candidate changes the outer reusable-workflow YAML itself, the stable
 shell cannot exercise that change through a runtime override. A maintainer may
-manually qualify it with `canary-ref` set to an exact 40-character commit in the
-consumer repository whose canary workflow pins the candidate's exact Buildchain
-SHA. The qualification producer still dispatches and observes the authoritative
-consumer workflow before writing the normal candidate-bound status. Floating
-consumer branches are rejected, and the automatic path continues to use the
-consumer default branch.
+manually qualify it with `canary-ref` set to a dispatchable consumer branch or
+tag and `canary-sha` set to the exact 40-character commit that ref must resolve
+to. That consumer workflow pins the candidate's exact Buildchain SHA. The
+qualification producer verifies the ref binding before dispatch, accepts only a
+run whose source SHA matches, and writes the normal candidate-bound status only
+after success. The automatic path continues to use the consumer default branch.
 
 ## Repository policy
 

package/package.json

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

package/scripts/stable-candidate-qualification.mjs

@@ -41,11 +41,27 @@ function optionalSha(value, label) {
   return normalized;
 }
 
+function optionalRef(value, label) {
+  const normalized = text(value);
+  if (
+    normalized &&
+    (!/^[A-Za-z0-9._/-]+$/.test(normalized) || normalized.includes("..") || normalized.startsWith("/") || normalized.endsWith("/"))
+  ) {
+    throw new Error(`${label} must be a safe branch or tag ref, got ${normalized}`);
+  }
+  return normalized;
+}
+
 export function normalizeStableCandidateQualificationOptions(options = {}) {
   const candidateSha = text(options.candidateSha ?? process.env.BUILDCHAIN_QUALIFICATION_CANDIDATE_SHA);
   if (!/^[0-9a-f]{40}$/i.test(candidateSha)) {
     throw new Error(`candidate SHA must be 40 hexadecimal characters, got ${candidateSha || "<empty>"}`);
   }
+  const canaryRef = optionalRef(options.canaryRef ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_REF, "canary ref");
+  const canarySha = optionalSha(options.canarySha ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_SHA, "canary SHA");
+  if (Boolean(canaryRef) !== Boolean(canarySha)) {
+    throw new Error("canary ref and canary SHA must be provided together");
+  }
   return {
     repository: repository(options.repository ?? process.env.BUILDCHAIN_QUALIFICATION_REPOSITORY ?? process.env.GITHUB_REPOSITORY),
     candidateSha,
@@ -55,7 +71,8 @@ export function normalizeStableCandidateQualificationOptions(options = {}) {
     canaryWorkflowFile: text(options.canaryWorkflowFile ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_WORKFLOW_FILE) || DEFAULTS.canaryWorkflowFile,
     canaryWorkflowName: text(options.canaryWorkflowName ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_WORKFLOW_NAME) || DEFAULTS.canaryWorkflowName,
     canaryStatusContext: text(options.canaryStatusContext ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_STATUS_CONTEXT) || DEFAULTS.canaryStatusContext,
-    canaryRef: optionalSha(options.canaryRef ?? process.env.BUILDCHAIN_QUALIFICATION_CANARY_REF, "canary ref"),
+    canaryRef,
+    canarySha,
     pollAttempts: integer(options.pollAttempts ?? process.env.BUILDCHAIN_QUALIFICATION_POLL_ATTEMPTS, DEFAULTS.pollAttempts),
     pollIntervalMs: integer(options.pollIntervalMs ?? process.env.BUILDCHAIN_QUALIFICATION_POLL_INTERVAL_MS, DEFAULTS.pollIntervalMs),
     dryRun: bool(options.dryRun ?? process.env.BUILDCHAIN_QUALIFICATION_DRY_RUN, false),
@@ -70,8 +87,8 @@ function active(run) {
   return run && run.status !== "completed";
 }
 
-async function ensureWorkflowEvidence({ client, repository, workflowFile, workflowName, ref, headSha, runName, options }) {
-  let run = await client.findWorkflowRun({ repository, workflowFile, workflowName, headSha, runName });
+async function ensureWorkflowEvidence({ client, repository, workflowFile, workflowName, ref, headSha, runName, sourceSha = "", options }) {
+  let run = await client.findWorkflowRun({ repository, workflowFile, workflowName, headSha, runName, sourceSha });
   if (successful(run)) return { state: "existing", run };
 
   if (!active(run)) {
@@ -86,6 +103,7 @@ async function ensureWorkflowEvidence({ client, repository, workflowFile, workfl
     workflowName,
     headSha,
     runName,
+    sourceSha,
     attempts: options.pollAttempts,
     intervalMs: options.pollIntervalMs,
   });
@@ -118,6 +136,12 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
   let canary = { state: status?.state === "success" ? "existing" : "pending", run: undefined };
   if (status?.state !== "success") {
     const canaryRef = options.canaryRef || await client.defaultBranch(options.canaryRepository);
+    if (options.canaryRef) {
+      const resolvedCanarySha = await client.resolveCommitSha(options.canaryRepository, canaryRef);
+      if (resolvedCanarySha !== options.canarySha) {
+        throw new Error(`canary ref ${canaryRef} resolved to ${resolvedCanarySha || "<missing>"}, expected ${options.canarySha}`);
+      }
+    }
     canary = await ensureWorkflowEvidence({
       client,
       repository: options.canaryRepository,
@@ -126,6 +150,7 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
       ref: canaryRef,
       headSha: options.candidateSha,
       runName: `${options.canaryWorkflowName} / ${options.candidateSha}`,
+      sourceSha: options.canarySha,
       options,
     });
     if (!options.dryRun) {
@@ -146,7 +171,12 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
     dryRun: options.dryRun,
     candidate,
     build: { state: build.state, url: build.run?.html_url || "" },
-    canary: { state: canary.state, ref: options.canaryRef || "default-branch", url: canary.run?.html_url || status?.target_url || "" },
+    canary: {
+      state: canary.state,
+      ref: options.canaryRef || "default-branch",
+      sha: options.canarySha,
+      url: canary.run?.html_url || status?.target_url || "",
+    },
     attestation: { context: options.canaryStatusContext, state: options.dryRun ? "planned" : status?.state || "" },
   };
 }
@@ -185,8 +215,11 @@ export function createGitHubQualificationClient({
     const payload = await api(`/repos/${query.repository}/actions/workflows/${encodeURIComponent(query.workflowFile)}/runs?per_page=100`);
     return (payload.workflow_runs || [])
       .filter((run) => (
-        (!query.runName && (!query.headSha || run.head_sha === query.headSha))
-        || (query.runName && (run.display_title === query.runName || run.name === query.runName))
+        (
+          (!query.runName && (!query.headSha || run.head_sha === query.headSha))
+          || (query.runName && (run.display_title === query.runName || run.name === query.runName))
+        )
+        && (!query.sourceSha || run.head_sha === query.sourceSha)
       ))
       .sort((left, right) => String(right.created_at).localeCompare(String(left.created_at)))[0];
   }
@@ -203,6 +236,9 @@ export function createGitHubQualificationClient({
     async defaultBranch(repositoryName) {
       return (await api(`/repos/${repositoryName}`)).default_branch;
     },
+    async resolveCommitSha(repositoryName, ref) {
+      return (await api(`/repos/${repositoryName}/commits/${encodeURIComponent(ref)}`)).sha || "";
+    },
     findWorkflowRun: matchingRun,
     async dispatchWorkflow({ repository: repositoryName, workflowFile, ref, inputs }) {
       await api(`/repos/${repositoryName}/actions/workflows/${encodeURIComponent(workflowFile)}/dispatches`, { method: "POST", body: { ref, inputs } });