@kungfu-tech/buildchain 2.12.0 → 2.12.1-alpha.2

package/dist/site/workflow-registry.json

@@ -489,6 +489,19 @@
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },
+    {
+      "id": "buildchain-stable-candidate-patrol",
+      "path": ".github/workflows/buildchain-stable-candidate-patrol.yml",
+      "inputs": [
+        "buildchain-ref",
+        "dry-run",
+        "release-now"
+      ],
+      "inputCount": 3,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "active"
+    },
     {
       "id": "candidate-lab",
       "path": ".github/workflows/candidate-lab.yml",
@@ -805,6 +818,31 @@
       "capabilityGroup": "api-cli-reference",
       "status": "compatibility-fixture"
     },
+    {
+      "id": "stable-candidate-patrol",
+      "path": ".github/workflows/stable-candidate-patrol.yml",
+      "inputs": [
+        "auto-approve",
+        "auto-merge",
+        "auto-promote",
+        "buildchain-ref",
+        "buildchain-repository",
+        "dry-run",
+        "hold",
+        "hold-reason",
+        "ledger-ref",
+        "minimum-soak-seconds",
+        "release-now",
+        "required-checks",
+        "revoke-reason",
+        "revoked-versions",
+        "target-branch"
+      ],
+      "inputCount": 15,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "active"
+    },
     {
       "id": "verify",
       "path": ".github/workflows/verify.yml",

package/docs/MAP.md

@@ -99,6 +99,7 @@ replace them.
 | How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |
 | How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |
 | How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
+| How do I automatically qualify alpha candidates and publish the newest non-revoked qualified candidate at a fixed window? | [`stable-candidate-patrol.md`](stable-candidate-patrol.md) | use | preview |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
 | How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
@@ -117,6 +118,8 @@ replace them.
   [`release-flow.md`](release-flow.md).
 - **Buildchain self-dogfood / released alpha canary / stable compatibility lane** ->
   [`release-governance.md`](release-governance.md#buildchain-alpha-self-dogfood).
+- **qualified alpha ledger / scheduled stable selection / hold and revoke** ->
+  [`stable-candidate-patrol.md`](stable-candidate-patrol.md).
 - **v2.1 vs v2.2 / when to open a new minor line** ->
   [`versioning.md`](versioning.md).
 - **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)

package/docs/release-governance.md

@@ -303,6 +303,15 @@ Compatible work should still be batched until a stable release has a concrete
 consumer need. Changing the interval, canary set, attestors, product path
 boundary, or soak time is a reviewed policy change.
 
+Repositories that want a predictable scheduled stable window can use
+[`Stable Candidate Patrol`](stable-candidate-patrol.md). It persists each exact
+alpha independently, qualifies it after repository-declared checks and soak,
+and selects the newest qualified non-revoked candidate. A newer soaking alpha
+does not invalidate an older qualified candidate. The selected tree enters the
+existing strict `publish-gate/release/<line>/<version> -> release/<line>` PR
+path, so scheduled selection changes release intent timing without weakening
+source locks, review, verification, publish transactions, or passports.
+
 If release finalization is resumed after generated version-state bookkeeping was
 partially applied, Buildchain applies the same recovery rule: the current
 release head may be the generated commit, or a historical merge commit that
@@ -445,6 +454,7 @@ patrol workflow family:
 | `.github/workflows/patrol-daily.yml` | daily | lightweight inspection plus ready dev PR maintenance |
 | `.github/workflows/patrol-weekly.yml` | weekly | release-state, passport, gate, and stale-state health checks as they are added |
 | `.github/workflows/patrol-monthly.yml` | monthly | governance, permission, branch-protection, and workflow drift checks as they are added |
+| `.github/workflows/stable-candidate-patrol.yml` | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR |
 
 The cadence names describe patrol intensity, not release cadence:
 
@@ -453,6 +463,12 @@ The cadence names describe patrol intensity, not release cadence:
 - monthly patrol is for structural drift checks that should not block ordinary
   development velocity.
 
+Stable Candidate Patrol is separate from those maintenance cadences because its
+caller-owned cron is a release-intent window. Its candidate ledger and selection
+remain generic; registry-specific side effects still run through the normal
+repository `lifecycle.publish` transaction. See
+[`stable-candidate-patrol.md`](stable-candidate-patrol.md).
+
 Consumers should schedule thin callers and keep their YAML declarative. For
 example:
 

package/docs/stable-candidate-patrol.md

@@ -0,0 +1,172 @@
+---
+status: preview
+period: ongoing
+theme: stable-candidate-patrol
+doc_type: architecture-and-usage
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-07-11
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-11
+  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.
+  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.
+---
+
+# Stable Candidate Patrol
+
+Buildchain can treat every exact alpha as an independent stable candidate. A
+new alpha creates a new candidate; it does not silently revoke an older alpha
+that already completed its checks and soak interval.
+
+## Candidate lifecycle
+
+The durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:
+
+```text
+registered -> soaking -> qualified -> promoted
+                       \-> revoked
+```
+
+Each entry binds an exact alpha version to one immutable commit SHA. Registering
+the same version at another SHA fails closed. Qualification records the required
+checks, their completion times, the derived soak start, and elapsed time.
+
+Scheduled selection chooses the newest `qualified` candidate that is neither
+`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not
+hide an older qualified candidate. Once a stable version is promoted, remaining
+alphas for that exact stable version are closed because that immutable stable
+version has been consumed; their later product changes continue through the
+next patch alpha prepared by the normal release transaction.
+
+## Repository policy
+
+Declare the default once in `.buildchain/buildchain.toml`:
+
+```toml
+[release.stable]
+strategy = "latest-qualified-alpha"
+timezone = "Asia/Shanghai"
+publish_at = "03:00"
+minimum_soak_seconds = 3600
+required_checks = [
+  "alpha-release",
+  "workflow:Build",
+  "status:buildchain-canary/consumer",
+]
+auto_promote = true
+auto_merge = true
+```
+
+Check identifiers use these forms:
+
+- `alpha-release`: the exact GitHub prerelease publication fact;
+- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;
+- `status:<context>`: a successful commit status on the exact candidate SHA;
+- an unprefixed value: an exact status context or check-run name.
+
+Candidate discovery uses immutable exact alpha Git tags. When a repository also
+publishes GitHub prereleases, `alpha-release` binds qualification to that public
+release fact. Repositories that intentionally disable GitHub Releases omit
+`alpha-release` and declare their own exact-SHA workflow/status evidence; tag
+commit time remains the earliest possible soak start.
+
+`publish_at` and `timezone` are the auditable policy declaration. GitHub only
+starts scheduled workflows from caller-owned cron, so the thin caller keeps the
+matching UTC trigger:
+
+```yaml
+name: Stable Candidate Patrol
+
+on:
+  schedule:
+    - cron: "0 19 * * *" # 03:00 Asia/Shanghai
+  workflow_dispatch:
+    inputs:
+      release-now:
+        description: Exact alpha selected by explicit human authority
+        required: false
+        default: ""
+
+permissions:
+  contents: write
+  pull-requests: write
+  checks: read
+  statuses: read
+
+jobs:
+  stable:
+    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v2
+    with:
+      release-now: ${{ inputs.release-now }}
+      dry-run: false
+    secrets:
+      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+```
+
+The promotion token must be repository-owned and capable of creating the
+machine ledger branch, exact source-lock branch, and pull request. Repositories
+that require an approving review can set `auto-approve: true` only when their
+GitHub Actions policy explicitly allows the caller token to approve the PR;
+otherwise a repository-owned App or review bot supplies the approval. The
+generated PR may use auto-merge, but it never bypasses the target branch checks.
+
+## Exact-source stable promotion
+
+For a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:
+
+```text
+publish-gate/release/v2/v2.12/2.12.0-alpha.4
+```
+
+and opens it against `release/v2/v2.12`. This is an existing strict Buildchain
+governance path. The PR freezes the qualified candidate even if `v2.12-alpha`
+or `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,
+release-candidate resolution, source-tree equivalence, publish transaction,
+passport, registry, tag, and floating-ref checks still run.
+
+## Hold, revoke, and immediate release
+
+Persistent repository controls can be supplied as reusable-workflow inputs or
+repository variables:
+
+```text
+BUILDCHAIN_STABLE_HOLD=true
+BUILDCHAIN_STABLE_HOLD_REASON=release freeze
+BUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7
+BUILDCHAIN_STABLE_REVOKE_REASON=consumer regression
+```
+
+Revocation is explicit evidence; publishing a newer alpha alone is not
+revocation. A manual `workflow_dispatch` `release-now` chooses one exact,
+non-revoked candidate immediately. It may bypass the scheduled soak decision,
+but cannot change candidate SHA, reuse a consumed stable version, or bypass the
+source-lock PR and publish transaction.
+
+For Buildchain's own stable gate, Patrol automatically projects that explicit
+human decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and
+reason variables. A later Patrol run removes them after it observes the public
+stable release. This is an internal compatibility projection, not a manual user
+step; the durable authority record remains the candidate ledger entry and PR.
+
+## Durable recovery
+
+The default ledger ref is derived from the release line, for example:
+
+```text
+buildchain/candidate-ledger/v2/v2.12
+```
+
+It stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized
+per repository and release line. Repeated runs reuse the same exact source-lock
+branch and PR, while later runs observe the public stable release and mark the
+candidate `promoted`.
+
+When Patrol is enabled after a stable version already exists, it reconstructs
+that consumed patch from GitHub Release truth and closes historical alpha
+candidates for the same stable version. It never attempts to republish an
+already claimed exact stable version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.0",
+  "version": "2.12.1-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -30,6 +30,7 @@
     "./publication-package": "./packages/core/publication-package.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
+    "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./release-propagation": "./packages/core/release-propagation.js",
     "./surface-manifest": "./packages/core/surface-manifest.js",

package/packages/core/buildchain-config.js

@@ -19,6 +19,7 @@ const SUPPORTED_PUBLISH_MODES = new Set(["publish-final-version", "promote-exist
 const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
 const SUPPORTED_PUBLISH_KINDS = new Set(["npm-package", "npm-paper-package"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
+const SUPPORTED_STABLE_RELEASE_STRATEGIES = new Set(["manual", "latest-qualified-alpha"]);
 const SUPPORTED_NATIVE_COMPILER_CACHE = new Set(["auto", "ccache", "sccache", "none"]);
 const WEB_SURFACE_CHANNELS = ["preview", "staging", "production"];
 const SUPPORTED_CHANNEL_VISIBILITY = new Set(["ephemeral", "protected", "public", "internal"]);
@@ -180,6 +181,9 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.publish !== undefined) {
     normalized.publish = normalizePublishSection(normalized.publish);
   }
+  if (normalized.release !== undefined) {
+    normalized.release = normalizeReleaseSection(normalized.release);
+  }
   if (normalized.channels !== undefined) {
     normalized.channels = normalizeChannelsSection(normalized.channels, normalized.project);
   }
@@ -215,6 +219,59 @@ export function normalizeBuildchainConfig(config) {
   return normalized;
 }
 
+function normalizeReleaseSection(release) {
+  assertPlainObject(release, "release");
+  const normalized = { ...release };
+  if (release.stable !== undefined) {
+    assertPlainObject(release.stable, "release.stable");
+    const strategy = release.stable.strategy === undefined
+      ? "manual"
+      : assertString(release.stable.strategy, "release.stable.strategy");
+    if (!SUPPORTED_STABLE_RELEASE_STRATEGIES.has(strategy)) {
+      throw new Error("release.stable.strategy must be one of manual or latest-qualified-alpha");
+    }
+    const minimumSoakSeconds = release.stable.minimum_soak_seconds === undefined
+      ? 3600
+      : Number(release.stable.minimum_soak_seconds);
+    if (!Number.isInteger(minimumSoakSeconds) || minimumSoakSeconds < 0) {
+      throw new Error("release.stable.minimum_soak_seconds must be a non-negative integer");
+    }
+    normalized.stable = {
+      strategy,
+      timezone: release.stable.timezone === undefined
+        ? "UTC"
+        : assertString(release.stable.timezone, "release.stable.timezone"),
+      publishAt: release.stable.publish_at === undefined
+        ? "03:00"
+        : assertString(release.stable.publish_at, "release.stable.publish_at"),
+      minimumSoakSeconds,
+      requiredChecks: normalizeStringArray(release.stable.required_checks, "release.stable.required_checks"),
+      ledgerRef: release.stable.ledger_ref === undefined
+        ? ""
+        : assertString(release.stable.ledger_ref, "release.stable.ledger_ref"),
+      autoPromote: optionalBoolean(release.stable.auto_promote, strategy === "latest-qualified-alpha"),
+      autoMerge: optionalBoolean(release.stable.auto_merge, false),
+    };
+    if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(normalized.stable.publishAt)) {
+      throw new Error("release.stable.publish_at must be HH:MM in 24-hour time");
+    }
+  }
+  return normalized;
+}
+
+export function getStableReleasePolicy(loadedConfig) {
+  return loadedConfig?.config?.release?.stable || {
+    strategy: "manual",
+    timezone: "UTC",
+    publishAt: "03:00",
+    minimumSoakSeconds: 3600,
+    requiredChecks: [],
+    ledgerRef: "",
+    autoPromote: false,
+    autoMerge: false,
+  };
+}
+
 function normalizeFactsSection(facts) {
   assertPlainObject(facts, "facts");
   return {
@@ -1389,6 +1446,7 @@ export function validateBuildchainConfig(
     })),
     lifecycleStages,
     publish: loadedConfig.config.publish,
+    release: loadedConfig.config.release,
     facts: loadedConfig.config.facts,
     publication: loadedConfig.config.publication,
   };

package/packages/core/index.js

@@ -3,6 +3,7 @@ export {
   getLifecycleStage,
   getNativeDiagnosticsProfile,
   getPublishContract,
+  getStableReleasePolicy,
   getVersionStrategy,
   loadBuildchainConfig,
   loadConfiguredAnchorManifest,
@@ -13,6 +14,20 @@ export {
   validateBuildchainConfig,
 } from "./buildchain-config.js";
 
+export {
+  STABLE_CANDIDATE_LEDGER_CONTRACT,
+  STABLE_CANDIDATE_STATES,
+  createStableCandidateLedger,
+  markStableCandidatePromoted,
+  normalizeStableCandidateLedger,
+  qualifyStableCandidate,
+  registerStableCandidate,
+  revokeStableCandidate,
+  selectStableCandidate,
+  setStableCandidateHold,
+  stableCandidatePromotionRefs,
+} from "./stable-candidate-ledger.js";
+
 export {
   assertPackageManager,
   commandForKungfuUpgrade,