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

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
@@ -403,6 +412,13 @@ Consumers that want Buildchain to own the check wrapper can call
 `lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when
 either declaration is missing or the command exits non-zero.
 
+Development pull requests that need source acceptance without product build or
+artifact verification can opt into `mode: source`. That mode runs only
+`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while
+preserving the stable `check / check` required-check context. Existing callers
+remain on `mode: verify` by default, and callers may set
+`upload-artifacts: false` without weakening the job conclusion.
+
 Typical consumer wrapper:
 
 ```yaml
@@ -445,6 +461,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 +470,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/reusable-build-surface.md

@@ -162,6 +162,43 @@ Artifact names, manifest paths, expected artifact checks, publish-source locks,
 and aggregate summaries are the same in both jobs. The split is an execution
 detail, not a different artifact contract.
 
+## Native Rust Toolchains
+
+Native lifecycle jobs can request an isolated Rust installation instead of
+depending on a self-hosted runner user's PATH:
+
+```yaml
+with:
+  setup-rust: true
+  rust-toolchain: "1.96.0"
+  rustup-dist-server: "https://rsproxy.cn"
+  rustup-update-root: "https://rsproxy.cn/rustup"
+  cargo-registry-index: ${{ vars.BUILDCHAIN_CARGO_REGISTRY_INDEX }}
+```
+
+`setup-rust` defaults to `false`, so existing consumers are unchanged. When it
+is enabled, Buildchain installs `rust-toolchain` before the install, build, and
+verify lifecycle stages on every native matrix platform. Windows uses the
+official rustup bootstrap through `cmd.exe` and `curl.exe` into runner-temporary
+Cargo and rustup homes, so it works under a restrictive PowerShell execution
+policy and the service account does not depend on another user's PATH or mutate
+host toolchain state. Pin an exact toolchain for release builds. Linux container jobs continue
+to obtain Rust from their digest-pinned image contract; Buildchain does not
+mutate that container surface.
+
+The rustup server inputs are optional and default to Rust's official servers.
+Consumers behind a slow cross-border link may select a trusted transport mirror;
+rustup still verifies the selected toolchain's distribution metadata and
+component checksums.
+
+`cargo-registry-index` is also optional. When set, Buildchain exposes it to
+Cargo as `CARGO_REGISTRIES_CRATES_IO_INDEX` for every native lifecycle stage,
+so a self-hosted runner can use a repository or organization variable without
+committing private LAN topology to public workflow YAML. The endpoint must be a
+crates.io-compatible index whose `config.json` download contract serves the
+matching checksum-verified crate archives. An empty value preserves Cargo's
+normal crates.io behavior.
+
 The container image provides `fnm` but does not preinstall Node. Buildchain uses
 `fnm` inside the container to install the requested `node-version` before it
 runs Buildchain runtime scripts or lifecycle actions.
@@ -289,6 +326,38 @@ also pass `buildchain-ref: v2-alpha` explicitly; official floating refs are
 ordinary channel selections and are allowed on pull requests and pushes. Train
 refs and exact SHAs remain trusted manual overrides.
 
+## Shifu Cache Profile Passthrough
+
+Buildchain can carry one trusted Shifu cache-profile reference and its exact
+digest into lifecycle execution. Its contract is an opaque reference and digest
+only. This surface is deliberately opaque:
+Buildchain does not fetch the profile, parse JSON, select cache services,
+rewrite bindings, decide fallback, or emit Shifu resolution evidence. Those
+semantics remain owned by the consumer's pinned Shifu implementation.
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    with:
+      shifu-cache-profile-ref: ${{ vars.SHIFU_CACHE_PROFILE_REF }}
+      shifu-cache-profile-digest: ${{ vars.SHIFU_CACHE_PROFILE_DIGEST }}
+```
+
+The reusable workflow passes the pair as `SHIFU_CACHE_PROFILE_REF` and
+`SHIFU_CACHE_PROFILE_DIGEST` to install, build, and verify lifecycle commands.
+The consumer must invoke its Shifu cache-aware execution surface. An empty pair
+preserves existing behavior; a consumer Shifu should fail closed when exactly
+one value is present or the resolved bytes do not match the expected digest.
+
+Use trusted repository or organization variables rather than PR-controlled
+files for private/LAN references. The variables must remain secret-free; any
+credentials use a separate provider-approved secret surface and must not be
+embedded in the profile reference. This passthrough is separate from
+Buildchain's locked source checkout cache below: Buildchain owns checkout
+transport and source identity, while Shifu owns post-checkout execution cache
+bindings and receipts.
+
 ## Locked Source Checkout Cache
 
 Self-hosted runners that build large repositories can opt into a locked checkout

package/docs/stable-candidate-patrol.md

@@ -0,0 +1,188 @@
+---
+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.
+
+For Buildchain's own release line, successful Alpha Self-Dogfood starts an
+idempotent qualification producer for the exact alpha SHA. It dispatches the
+existing `Build Surface Fixture` at the immutable exact tag, runs the existing
+`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared
+commit-status attestation only after that authoritative canary succeeds. The
+producer creates evidence only: Patrol still owns qualification and selection,
+and the normal source-lock PR, stable gate, transaction, and branch protections
+remain mandatory.
+
+Cross-repository dispatch and repository-local attestation use separate tokens.
+The promotion token can start the no-apply consumer workflow, while the
+repository-scoped Actions token writes the status as `github-actions[bot]` only
+after the producer has observed the successful authoritative workflow run. The
+stable gate still verifies the workflow identity, exact runtime SHA, target URL,
+and allowed attestor before accepting that status.
+
+## 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.10",
   "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",
@@ -83,6 +84,7 @@
     "check:site": "node scripts/generate-site-bundle.mjs --check",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",
+    "binary:build": "node scripts/build-standalone-binary.mjs",
     "package": "npm pack --dry-run --json --registry=https://registry.npmjs.org/",
     "pack:check": "npm pack --dry-run --json --registry=https://registry.npmjs.org/"
   },

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/buildchain-kfd-claims.js

@@ -6,6 +6,7 @@ import {
   BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT,
   collectPublicSurfaceReverseAudit,
 } from "./public-surface-audit.js";
+import { normalizeKfd3DistributionDeclaration } from "./kfd3-surface-register.js";
 
 export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-claim-registry";
 export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchain-kfd-collaboration-interface";
@@ -307,6 +308,23 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/public-surface-audit.json",
       ],
     },
+    {
+      id: "claim:buildchain-shifu-kfd-discovery",
+      claim: "Buildchain exposes a versioned repository-layout discovery contract and KFD-3 distribution declarations so Shifu can locate the registry and determine jurisdiction without copying Buildchain layout paths.",
+      sourcePaths: [
+        "packages/core/buildchain-layout.js",
+        "packages/core/buildchain-kfd-claims.js",
+        "packages/core/kfd3-surface-register.js",
+        "bin/buildchain.mjs",
+        "scripts/build-standalone-binary.mjs",
+        "docs/kfd-support.md",
+      ],
+      artifactPaths: [
+        "dist/site/kfd-claims.json",
+        "dist/site/cli-registry.json",
+        "dist/site/node-api-registry.json",
+      ],
+    },
     {
       id: "claim:buildchain-readme-badge-facts",
       claim: "Buildchain README status badges are generated from repository-owned facts and verified release-passport evidence, not hand-maintained README prose.",
@@ -431,6 +449,37 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
   ];
   const siteConsumptionContracts = SITE_CONTRACT_FILES.map((relPath) => surface(`site:${relPath}`, "site-consumption-contract", relPath));
   const controlSurfaces = WORKFLOW_AND_ACTION_FILES.map((relPath) => surface(`control:${relPath}`, relPath.includes("actions/") ? "action" : "workflow", relPath));
+  const standaloneDistribution = surface(
+    "distribution:buildchain-standalone",
+    "binary-distribution",
+    "scripts/build-standalone-binary.mjs",
+    {
+      name: "Buildchain standalone binary distribution",
+      artifactPath: "dist/binary",
+      evidencePath: ".github/workflows/binary-distribution.yml",
+      distribution: normalizeKfd3DistributionDeclaration({
+        registrar: "shifu",
+        tasks: ["binary:build"],
+        artifacts: [
+          {
+            kind: "binary",
+            platform: "linux",
+            pathGlob: "dist/binary/buildchain-x86_64-unknown-linux-gnu.tar.gz",
+          },
+          {
+            kind: "binary",
+            platform: "macos",
+            pathGlob: "dist/binary/buildchain-aarch64-apple-darwin.tar.gz",
+          },
+          {
+            kind: "binary",
+            platform: "windows",
+            pathGlob: "dist/binary/buildchain-x86_64-pc-windows-msvc.zip",
+          },
+        ],
+      }, { surfaceId: "distribution:buildchain-standalone" }),
+    },
+  );
   const reverseEnumeratedSurfaces = uniqueById([
     ...reverseAudit.enumerated.cliCommands.map((entry) => surface(`cli:${entry.id}`, "cli-command", "bin/buildchain.mjs", {
       name: entry.usage,
@@ -463,8 +512,8 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
       siteConsumptionContracts,
       reverseEnumeratedSurfaces,
     },
-    additionalSurfaces: controlSurfaces,
-    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + reverseEnumeratedSurfaces.length + controlSurfaces.length,
+    additionalSurfaces: [...controlSurfaces, standaloneDistribution],
+    publicSurfaceCount: docs.length + schemas.length + standardsMetadata.length + exports.length + siteConsumptionContracts.length + reverseEnumeratedSurfaces.length + controlSurfaces.length + 1,
   };
 }
 

package/packages/core/buildchain-layout.js

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 
 export const BUILDCHAIN_DIR = ".buildchain";
+export const BUILDCHAIN_VERSION_PIN_PATH = ".buildchain-version";
+export const BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT = "kungfu-buildchain-layout-discovery";
 export const BUILDCHAIN_CONFIG_PATH = ".buildchain/buildchain.toml";
 export const LEGACY_BUILDCHAIN_CONFIG_PATH = "buildchain.toml";
 export const BUILDCHAIN_CONTRACT_LOCK_PATH = ".buildchain/contract-lock.json";
@@ -94,6 +96,50 @@ export function resolveReleasePassportPath(cwd = process.cwd()) {
   ]);
 }
 
+export function createBuildchainLayoutDiscovery({
+  cwd = process.cwd(),
+  buildchainVersion = "",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const configPath = resolveBuildchainConfigPath(resolvedCwd);
+  const kfd3RegistryPath = resolveKfd3SurfaceRegistryPath(resolvedCwd);
+  return {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT,
+    buildchain: {
+      version: String(buildchainVersion || ""),
+      versionPinPath: BUILDCHAIN_VERSION_PIN_PATH,
+    },
+    repository: {
+      root: resolvedCwd,
+      managed: fs.existsSync(repoPath(resolvedCwd, configPath))
+        || fs.existsSync(repoPath(resolvedCwd, BUILDCHAIN_VERSION_PIN_PATH))
+        || fs.existsSync(repoPath(resolvedCwd, kfd3RegistryPath)),
+      configPath,
+    },
+    kfd: {
+      root: BUILDCHAIN_KFD_ROOT,
+      registries: {
+        "kfd-3": {
+          standard: "kfd-3",
+          schemaVersion: 1,
+          path: kfd3RegistryPath,
+          canonicalPath: BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+          exists: fs.existsSync(repoPath(resolvedCwd, kfd3RegistryPath)),
+        },
+      },
+    },
+    shifu: {
+      jurisdiction: {
+        source: "kfd-3-distribution-declaration",
+        registryStandard: "kfd-3",
+        field: "surfaces[].distribution.registrar",
+        value: "shifu",
+      },
+    },
+  };
+}
+
 export function discoverBuildchainRepoFiles(cwd = process.cwd()) {
   const files = [
     {

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,
@@ -277,6 +292,8 @@ export {
   BUILDCHAIN_CONFIG_PATH,
   BUILDCHAIN_CONTRACT_LOCK_PATH,
   BUILDCHAIN_DIR,
+  BUILDCHAIN_LAYOUT_DISCOVERY_CONTRACT,
+  BUILDCHAIN_VERSION_PIN_PATH,
   BUILDCHAIN_GENERATED_DIRS,
   BUILDCHAIN_KFD_ROOT,
   BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH,
@@ -302,6 +319,7 @@ export {
   LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATHS,
   LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH,
   discoverBuildchainRepoFiles,
+  createBuildchainLayoutDiscovery,
   migrateBuildchainLayout,
   planBuildchainLayoutMigration,
   resolveBuildchainConfigPath,
@@ -344,6 +362,7 @@ export {
   auditKfd3Surfaces,
   createKfd3SurfaceWitness,
   detectKfd3Surfaces,
+  normalizeKfd3DistributionDeclaration,
   queryKfd3Capabilities,
   readKfd3SurfaceRegistry,
   registerKfd3Surfaces,