@kungfu-tech/buildchain 3.0.8 → 3.0.9-alpha.1

package/docs/release-passport.md

@@ -313,6 +313,13 @@ fails closed if any claim is missing source bindings, machine evidence, hashes,
 artifact coordinates, verification result, audit boundary, responsibility, or
 residual risk.
 
+The same self-promotion boundary extends the Buildchain-owned KFD witness
+generator against the transaction's exact source SHA. It produces the standard
+full-cut adopter manifest, the non-qualifying KFD-4/5/7 product gates, and the
+one-way legacy projection before the final passport is collected. An explicitly
+supplied adopter manifest still takes precedence; an omitted self-release
+manifest no longer silently produces a KFD-1/2/3-only passport.
+
 ### KFD-3 collaboration-interface release gate
 
 KFD-3 asks a different release question than KFD-1. KFD-1 proves that named
@@ -399,18 +406,24 @@ instead of trusting docs or release notes.
 
 ### KFD support projection
 
-Pass `--kfd-support-matrix-json` together with three
-`--kfd-product-gate-json` arguments for KFD-4, KFD-5, and KFD-7. The collector
-verifies the product-owned KFD-1..13 matrix against the installed
-`@kungfu-tech/kfd` standards, binds each gate to the exact release source and
-fresh evidence cut, and emits `kfd-support.json`. The identical projection is
-embedded as `kfdSupport` in `buildchain.release.json`.
-
-Release verification fails closed when the sibling is missing or differs,
-when a gate expires, when matrix and gate status disagree, or when a matrix
-widens KFD-4/5 candidate, KFD-6 unsupported, KFD-8..13 draft, or any non-shipped
-state. A passed projection is release evidence only; product qualification,
-activation, certification, and support ownership remain outside Buildchain.
+Pass the standard full-cut declaration with `--kfd-adopter-manifest-json`
+together with three `--kfd-product-gate-json` arguments for KFD-4, KFD-5, and
+KFD-7. The collector invokes the verifier from the exact installed
+`@kungfu-tech/kfd` package, binds the package artifact, registry and verifier
+roots, the exact Buildchain source, the manifest/report/bundle witness roots,
+and the existing product-gate roots. It emits `kfd-adopter-manifest.json`,
+`kfd-adopter-manifest-gate.json`, and a legacy `kfd-support.json` projection.
+The release passport and `artifact-evidence.json` carry the same rooted
+`kfdAdopter` binding.
+
+The adopter manifest is the sole declaration authority. The old
+`--kfd-support-matrix-json` input is retained only as a compatibility check: if
+supplied with the manifest, it must exactly equal the generated legacy
+projection. Release verification fails closed when any sibling, package root,
+source root, witness root, gate root, passport binding, or artifact-evidence
+binding differs. A passed binding is release evidence only; product
+qualification, activation, certification, and support ownership remain outside
+Buildchain.
 
 ### Floating Buildchain contract lock
 

package/docs/release-train.md

@@ -8,12 +8,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-10
+last_reviewed: 2026-08-11
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-10
-  visible_context: Buildchain v3 release candidate, recovery, Dev to Alpha Candidate Patrol, Warrant, publication transaction, and release governance sources.
+  generated_at: 2026-08-11
+  visible_context: Buildchain v3 release candidate, recovery, Dev to Alpha Candidate Patrol, rooted blocker repair, Warrant, publication transaction, and release governance sources.
   invisible_context_boundary: Live provider state and credentials were not read.
 ---
 
@@ -38,8 +38,9 @@ own those effects and persist the rooted contract in their declared store.
 - a canonical creation timestamp.
 
 The resulting `cutRoot` covers all of those fields. A generation greater than
-one must name the prior cut root and one of four supersession causes:
+one must name the prior cut root and one of five supersession causes:
 
+- `release-blocker-repair` (reserved for the rooted repair contract below);
 - `incompatible-semantics`;
 - `alpha-base-incompatibility`;
 - `invalid-authority`; or
@@ -74,6 +75,55 @@ an invalid transition fails closed.
 changing `trainRoot`, `cutRoot`, candidate identity, generation, or state. The
 same exact observation is idempotent.
 
+## Rooted release-blocker repair
+
+`createReleaseBlockerRepair()` starts only from the active train's exact
+`repair-required` state root. It creates generation N+1 from the frozen cut,
+changing only the candidate commit and tree while preserving the original Dev
+cut, Alpha base, runtime, route, and prior cut root. The prior train receives an
+explicit `release-blocker-repair` supersession transition; later Dev movement
+alone still cannot advance a generation.
+
+The repair binds one semantic patch root to a cut landing and a Dev
+forward-port. A successful cut landing makes the successor candidate buildable
+even while the Dev forward-port is in conflict. Publication remains blocked
+until `settleReleaseBlockerDevLanding()` compare-and-swap checks the repair root
+and records a Dev landing with the same patch root. A landed but different Dev
+patch produces a rooted `cut-dev-patch-root-mismatch` gate rather than
+publication authority.
+
+Buildchain v3 Candidate Patrol resolves the open managed candidate's persisted
+train before it considers a new qualified development head. It reads back the
+candidate ref and tree, Alpha base, and exact Buildchain runtime. Matching
+coordinates resume the frozen candidate; a newer development head becomes a
+single rooted observation. Candidate, tree, base, runtime, or route drift emits
+a rooted hold and stops settlement. Only a validated train already carrying an
+enumerated `superseded` transition is reported as superseded.
+
+## Buildchain self-dogfood campaign
+
+Buildchain qualifies the complete v3 mechanism with
+`scripts/release-train-self-dogfood.mjs`. The campaign composes one frozen
+Release Cut, moving-dev observation, deterministic failed build, successor
+repair, cut/dev patch-root settlement, publication gate, and bounded Delivery
+Warrant priority. It also proves that an active Warrant is not preempted and
+that duplicate events, invalid authority, and unrelated priority claims fail
+closed.
+
+The command accepts an exact evidence input and emits a replayable rooted
+report:
+
+```sh
+node scripts/release-train-self-dogfood.mjs \
+  --input /path/to/exact-protected-delivery.json \
+  --output /tmp/buildchain-release-train-self-dogfood.json
+```
+
+A passing report requires a merged protected PR, exact-head approval,
+merge-group CI success, tree-equivalent merge readback, artifact evidence, and
+installed-product evidence. Synthetic or unit-only evidence is useful for
+negative tests but is not sufficient for release qualification.
+
 ## Readback and legacy state
 
 `validateReleaseCut()` checks the standalone immutable cut and its canonical

package/docs/reusable-build-surface.md

@@ -66,10 +66,25 @@ release events, and non-semver release-like tags fail before the build matrix;
 they never guess alpha for a stable release.
 
 The router automatically selects `.buildchain/alpha-contract-lock.json` for
-alpha and `.buildchain/contract-lock.json` for stable. A repository can override
-the common path with `buildchain-contract-lock-path`, or override one channel
-with `buildchain-alpha-contract-lock-path` /
-`buildchain-stable-contract-lock-path`.
+alpha and `.buildchain/contract-lock.json` for stable. The generated workflow
+uses two static advanced-workflow calls: `@vN-alpha` for alpha and `@vN` for
+stable. A repository can override the common path with
+`buildchain-contract-lock-path`, or override one channel with
+`buildchain-alpha-contract-lock-path` / `buildchain-stable-contract-lock-path`,
+but the path is never channel authority. The selected file's
+`buildchain.ref` must prove the same channel and major as the workflow shell and
+runtime.
+
+Channel binding is independent of the current Buildchain major. Every
+channel-bound run validates the complete triad before compatibility drift:
+
+- stable = shell `vN` + runtime `vN` + a lock whose ref is stable `vN`;
+- alpha = shell `vN-alpha` + runtime `vN-alpha` + a lock whose ref is alpha
+  `vN-alpha`.
+
+Exact release refs are classified the same way. A missing lock, an ambiguous
+identity, a major mismatch, or any stable/alpha mixture fails even when the
+contract digest is unchanged or the drift would otherwise be additive.
 
 Only repositories changing the default policy need extra routing input:
 
@@ -279,7 +294,8 @@ shell. The full train validation protocol is documented in
 [`runtime-train-validation.md`](runtime-train-validation.md).
 
 For one-off manual validation, a trusted maintainer can run the caller workflow
-with a temporary runtime override:
+with a temporary runtime override. The override inherits the caller's declared
+alpha or stable lane; trust authorizes the opaque ref, not cross-channel use:
 
 ```yaml
 on:
@@ -1092,10 +1108,11 @@ jobs:
 ```
 
 Existing callers may keep `buildchain-contract-lock-path`; a non-empty explicit
-path overrides channel-specific selection for compatibility. Migration only
-requires adding the two channel lock inputs and may retain the remaining common
-promotion declaration unchanged. Consumers must not call the dot-prefixed
-advanced workflow directly.
+path overrides channel-specific path selection only. Its lock content must
+still prove the selected channel and major. Migration only requires adding the
+two channel lock inputs and may retain the remaining common promotion
+declaration unchanged. Consumers must not call the dot-prefixed advanced
+workflow directly.
 
 `buildchain-issue-app-id` and `buildchain-issue-app-private-key` are optional
 but recommended for cross-repository consumers. They should identify a GitHub

package/docs/runtime-train-validation.md

@@ -165,6 +165,12 @@ maintain, or admin permission on the caller repository. Pull requests,
 including fork-originated pull requests, cannot use train or exact-SHA
 overrides.
 
+That permission does not create a third channel. A train, authority ref, or
+exact SHA must be bound to an alpha or stable shell lane, and the consumer lock
+must prove that same lane and major. Trusted overrides can replace the runtime
+coordinate for validation; they cannot combine a stable shell or lock with an
+alpha runtime, or the reverse.
+
 Runtime train validation covers Buildchain runtime scripts, CLI code, local
 actions, configuration parsing, and lifecycle behavior. It cannot validate
 changes that require the outer reusable workflow YAML itself to change, such as

package/docs/versioning.md

@@ -79,8 +79,9 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| 2026-08-10 | extend-minor | `v3.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                | additive | Add a provider-neutral rooted Release Cut and idempotent Release Train state contract that freezes candidate, tree, Alpha base, runtime, generation, and authority while treating later Dev movement as observation rather than implicit supersession.                                                                                 |       |
-| 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                 |       |
+| 2026-08-11 | extend-minor | `v3.0`  | release-blocker-repair-contract, release-blocker-priority-claim, release-train-node-export, dev-delivery-warrant-node-export                                                 | additive | Add rooted successor candidate generations on a frozen Release Cut, exact semantic patch identity across cut and Dev landings, publication blocking through conflict or mismatch, and a narrow non-preemptive Warrant blocker lane.                                                                                                    |       |
+| 2026-08-10 | extend-minor | `v3.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                 | additive | Add a provider-neutral rooted Release Cut and idempotent Release Train state contract that freezes candidate, tree, Alpha base, runtime, generation, and authority while treating later Dev movement as observation rather than implicit supersession.                                                                                 |       |
+| 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                  |       |
 | 2026-08-04 | extend-minor | `v3.0`  | dev-delivery-warrant-queue, source-qualification-proof, integration-delivery-proof, dev-delivery-cli, reusable-dev-delivery-workflows                                        | additive | Add durable fair and fenced protected-dev scheduling plus split source/integration proof contracts. Existing PR admission remains available through explicit `off` and `shadow` rollout modes; no existing command, export, or release flow is removed.                                                                                |       |
 | 2026-08-01 | extend-minor | `v3.0`  | cli-reference-registry, node-api-symbol-registry, golden-path-manual                                                                                                         | additive | Add generated, drift-checked CLI and Node API reference registries to the public site bundle, plus a package-tested first-user Golden Path; existing command execution and import semantics remain unchanged.                                                                                                                          |       |
 | 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                            |       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.8",
+  "version": "3.0.9-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -33,6 +33,8 @@
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./kfd": "./packages/core/kfd.js",
     "./kfd-product-gates": "./packages/core/kfd-product-gates.js",
+    "./kfd-adopter-manifest": "./packages/core/kfd-adopter-manifest.js",
+    "./kfd-adopter-release-binding": "./packages/core/artifact-verification-envelope.js",
     "./kfd-agent-hub": "./packages/core/kfd-agent-hub.js",
     "./buildchain-layout": "./packages/core/buildchain-layout.js",
     "./release-line-bootstrap": "./packages/core/release-line-bootstrap.js",
@@ -87,7 +89,6 @@
     "./site/schemas/release-passport-v1.schema.json": "./dist/site/schemas/release-passport-v1.schema.json",
     "./site/schemas/kfd-agent-hub-adoption.schema.json": "./dist/site/schemas/kfd-agent-hub-adoption.schema.json",
     "./site/schemas/kfd-product-gate-input-v1.schema.json": "./dist/site/schemas/kfd-product-gate-input-v1.schema.json",
-    "./site/schemas/kfd-support-projection-v1.schema.json": "./dist/site/schemas/kfd-support-projection-v1.schema.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",
@@ -139,7 +140,7 @@
     "typescript": "^5.9.0"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "1.0.0-alpha.53",
+    "@kungfu-tech/kfd": "1.0.0-alpha.60",
     "ajv": "8.20.0",
     "smol-toml": "1.7.0"
   }

package/packages/core/artifact-verification-envelope.js

@@ -1,4 +1,11 @@
 import crypto from "node:crypto";
+import kfdPackageJson from "@kungfu-tech/kfd/package.json" with { type: "json" };
+import kfdSelfAdopterManifest from "@kungfu-tech/kfd/adopter-conformance/adopters/kfd/manifest.json" with { type: "json" };
+import {
+  validateKfdAdopterManifestGate,
+  validateKfdLegacySupportMatrixProjection,
+} from "./kfd-adopter-manifest.js";
+import { kfdProductGateDigest } from "./kfd-product-gates.js";
 
 export const ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT =
   "kungfu-buildchain-artifact-verification-envelope";
@@ -6,6 +13,8 @@ export const ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT =
   "kungfu-buildchain-artifact-verification-envelope-check";
 export const KFX_ADMISSION_INPUTS_CONTRACT =
   "kungfu-buildchain-kfx-admission-inputs";
+export const KFD_ADOPTER_RELEASE_BINDING_CONTRACT =
+  "kungfu-buildchain-kfd-adopter-release-binding";
 
 const ARTIFACT_VERIFICATION_CONTRACT =
   "kungfu-buildchain-artifact-verification";
@@ -384,3 +393,108 @@ export function projectArtifactVerificationEnvelopeToKfx({
     kfdAssessment: jsonClone(envelope.kfdAssessment),
   };
 }
+
+export function installedKfdPackageArtifactRoot() {
+  const cut = kfdSelfAdopterManifest?.kfdCut?.package;
+  if (cut?.name !== kfdPackageJson.name || cut?.version !== kfdPackageJson.version
+    || !SHA256_PATTERN.test(String(cut?.artifactRoot || ""))) {
+    throw new Error("installed KFD package does not expose a matching rooted self-adopter package cut");
+  }
+  return cut.artifactRoot;
+}
+
+function kfdBindingBody({ manifest, manifestGate, legacyProjection, paths }) {
+  return {
+    schemaVersion: 1,
+    contract: KFD_ADOPTER_RELEASE_BINDING_CONTRACT,
+    status: "passed",
+    qualifying: false,
+    selfCertified: false,
+    authority: {
+      manifestPath: paths.manifest,
+      manifestContract: manifest.contract,
+      manifestRoot: manifestGate.authority.manifestRoot,
+      gatePath: paths.gate,
+      gateRoot: manifestGate.gateRoot,
+    },
+    source: jsonClone(manifestGate.source),
+    standardPackage: jsonClone(manifestGate.standardPackage),
+    witness: {
+      decisionRoot: manifestGate.decisionWitness.root,
+      verificationReportRoot: manifestGate.manifestVerificationReportRoot,
+      bundleRoot: manifestGate.manifestBundleRoot,
+    },
+    legacyProjection: {
+      path: paths.legacy,
+      contract: legacyProjection.contract,
+      root: kfdProductGateDigest(legacyProjection),
+      authorityRoot: legacyProjection.authority.root,
+      gateRoot: legacyProjection.authority.gateRoot,
+    },
+    nonClaims: [
+      "This binding proves exact release-envelope consumption, not KFD certification or release authorization.",
+      "The legacy support matrix remains a projection of the standard adopter manifest authority.",
+    ],
+  };
+}
+
+export function createKfdAdopterReleaseBinding({
+  manifest,
+  manifestGate,
+  legacyProjection,
+  manifestPath = "kfd-adopter-manifest.json",
+  gatePath = "kfd-adopter-manifest-gate.json",
+  legacyProjectionPath = "kfd-support.json",
+  expectedSourceSha = "",
+} = {}) {
+  const gate = validateKfdAdopterManifestGate(manifestGate, {
+    expectedSourceSha,
+    checkedAt: manifestGate?.checkedAt,
+  });
+  const legacy = validateKfdLegacySupportMatrixProjection(legacyProjection, { manifest, manifestGate });
+  if (!gate.valid || !legacy.valid) {
+    throw new Error(`KFD adopter release binding inputs are invalid: ${JSON.stringify([...gate.issues, ...legacy.issues])}`);
+  }
+  const body = kfdBindingBody({
+    manifest,
+    manifestGate,
+    legacyProjection,
+    paths: { manifest: manifestPath, gate: gatePath, legacy: legacyProjectionPath },
+  });
+  return { ...body, bindingRoot: kfdProductGateDigest(body) };
+}
+
+export function validateKfdAdopterReleaseBinding(binding, {
+  manifest,
+  manifestGate,
+  legacyProjection,
+  expectedSourceSha = "",
+} = {}) {
+  const issues = [];
+  if (!binding || binding.schemaVersion !== 1 || binding.contract !== KFD_ADOPTER_RELEASE_BINDING_CONTRACT) {
+    return { valid: false, issues: [{ code: "adopter-release-binding-contract", path: "", message: `binding must use ${KFD_ADOPTER_RELEASE_BINDING_CONTRACT} v1` }] };
+  }
+  const copy = jsonClone(binding);
+  const bindingRoot = copy.bindingRoot;
+  delete copy.bindingRoot;
+  if (bindingRoot !== kfdProductGateDigest(copy)) {
+    issues.push({ code: "adopter-release-binding-root", path: "bindingRoot", message: "release binding root does not match its content" });
+  }
+  try {
+    const expected = createKfdAdopterReleaseBinding({
+      manifest,
+      manifestGate,
+      legacyProjection,
+      manifestPath: binding.authority?.manifestPath,
+      gatePath: binding.authority?.gatePath,
+      legacyProjectionPath: binding.legacyProjection?.path,
+      expectedSourceSha,
+    });
+    if (stableJson(binding) !== stableJson(expected)) {
+      issues.push({ code: "adopter-release-binding-drift", path: "", message: "release binding differs from the exact manifest, gate, or legacy projection closure" });
+    }
+  } catch (error) {
+    issues.push({ code: "adopter-release-binding-authority", path: "", message: error.message });
+  }
+  return { valid: issues.length === 0, issues };
+}

package/packages/core/buildchain-channel-identity.js

@@ -0,0 +1,119 @@
+const EXACT_SHA_RE = /^[0-9a-f]{40}$/i;
+const OFFICIAL_REF_RE = /^v(\d+)(?:\.\d+)?(-alpha)?$/;
+const STABLE_RELEASE_RE = /^v(\d+)\.\d+\.\d+$/;
+const ALPHA_RELEASE_RE = /^v(\d+)\.\d+\.\d+-alpha\.\d+$/;
+const TRAIN_REF_RE = /^train\/v(\d+)\/v(\d+)\.\d+\/[A-Za-z0-9._/-]+$/;
+const AUTHORITY_REF_RE = /^authority\/v(\d+)\/v(\d+)\.\d+\/[A-Za-z0-9._/-]+$/;
+
+export const BUILDCHAIN_CHANNELS = new Set(["stable", "alpha"]);
+
+export function normalizeBuildchainRef(ref = "") {
+  const value = String(ref || "").trim();
+  const workflowRef = value.includes("/.github/workflows/") ? value.split("@").pop() || "" : value;
+  return workflowRef.replace(/^refs\/(?:heads|tags)\//, "");
+}
+
+export function parseBuildchainRefIdentity(ref = "") {
+  const value = normalizeBuildchainRef(ref);
+  if (!value) return { ref: value, kind: "missing", channel: null, major: null };
+  if (EXACT_SHA_RE.test(value)) return { ref: value, kind: "exact-sha", channel: null, major: null };
+
+  for (const [pattern, channel, kind] of [
+    [OFFICIAL_REF_RE, null, "official-channel"],
+    [STABLE_RELEASE_RE, "stable", "release"],
+    [ALPHA_RELEASE_RE, "alpha", "release"],
+  ]) {
+    const match = value.match(pattern);
+    if (match) {
+      return {
+        ref: value,
+        kind,
+        channel: channel || (match[2] ? "alpha" : "stable"),
+        major: Number(match[1]),
+      };
+    }
+  }
+
+  for (const [pattern, kind] of [
+    [TRAIN_REF_RE, "train"],
+    [AUTHORITY_REF_RE, "authority"],
+  ]) {
+    const match = value.match(pattern);
+    if (match) {
+      return {
+        ref: value,
+        kind,
+        channel: null,
+        major: Number(match[1]),
+        coherentMajor: match[1] === match[2],
+      };
+    }
+  }
+  return { ref: value, kind: "development", channel: null, major: null };
+}
+
+function expectedIdentity({ workflowShellRef, expectedChannel, expectedMajor }) {
+  const shell = parseBuildchainRefIdentity(workflowShellRef);
+  const channel =
+    String(expectedChannel || "")
+      .trim()
+      .toLowerCase() || shell.channel;
+  const majorText = String(expectedMajor ?? "").trim();
+  const major = majorText ? Number(majorText.replace(/^v/, "")) : shell.major;
+  return { shell, channel, major };
+}
+
+function expectedReasons(expected, { expectedChannel, expectedMajor }) {
+  const reasons = [];
+  if (!BUILDCHAIN_CHANNELS.has(expected.channel)) reasons.push("Buildchain channel is missing or ambiguous");
+  if (!Number.isInteger(expected.major) || expected.major < 1) reasons.push("Buildchain major is missing or ambiguous");
+  if (expected.shell.channel && expected.shell.channel !== expected.channel) {
+    reasons.push(`workflow shell ${expected.shell.ref} is ${expected.shell.channel}, expected ${expected.channel}`);
+  }
+  if (Number.isInteger(expected.shell.major) && expected.shell.major !== expected.major) {
+    reasons.push(`workflow shell ${expected.shell.ref} is v${expected.shell.major}, expected v${expected.major}`);
+  }
+  if (!expected.shell.channel && (!expectedChannel || !expectedMajor)) {
+    reasons.push(`workflow shell ${expected.shell.ref || "(missing)"} does not declare a stable or alpha channel`);
+  }
+  return reasons;
+}
+
+function runtimeReasons(expected, runtime, allowOpaqueRuntime) {
+  if (runtime.channel) {
+    return [runtime.channel !== expected.channel ? `runtime ${runtime.ref} is ${runtime.channel}, expected ${expected.channel}` : "", runtime.major !== expected.major ? `runtime ${runtime.ref} is v${runtime.major}, expected v${expected.major}` : ""].filter(Boolean);
+  }
+  if (new Set(["train", "authority", "exact-sha"]).has(runtime.kind) && allowOpaqueRuntime) {
+    return [runtime.coherentMajor === false ? `runtime ${runtime.ref} has inconsistent major segments` : "", Number.isInteger(runtime.major) && runtime.major !== expected.major ? `runtime ${runtime.ref} is v${runtime.major}, expected v${expected.major}` : ""].filter(Boolean);
+  }
+  return [`runtime ${runtime.ref || "(missing)"} does not prove the ${expected.channel || "selected"} channel`];
+}
+
+function lockReasons(expected, lock, lockMajor, lockMajorLine) {
+  if (!lock.ref) return ["Buildchain contract lock is required for a channel-bound run"];
+  return [lock.channel !== expected.channel ? `contract lock ref ${lock.ref} does not prove the ${expected.channel} channel` : "", lock.major !== expected.major ? `contract lock ref ${lock.ref} does not prove major v${expected.major}` : "", lockMajorLine && lockMajor.major !== expected.major ? `contract lock major line ${lockMajor.ref} does not match v${expected.major}` : ""].filter(Boolean);
+}
+
+export function evaluateBuildchainChannelBinding({ workflowShellRef = "", runtimeRef = "", lockRef = "", lockMajorLine = "", expectedChannel = "", expectedMajor = "", allowOpaqueRuntime = false } = {}) {
+  const expected = expectedIdentity({
+    workflowShellRef,
+    expectedChannel,
+    expectedMajor,
+  });
+  const runtime = parseBuildchainRefIdentity(runtimeRef);
+  const lock = parseBuildchainRefIdentity(lockRef);
+  const lockMajor = parseBuildchainRefIdentity(lockMajorLine);
+  const reasons = [...expectedReasons(expected, { expectedChannel, expectedMajor }), ...runtimeReasons(expected, runtime, allowOpaqueRuntime), ...lockReasons(expected, lock, lockMajor, lockMajorLine)];
+
+  return {
+    ok: reasons.length === 0,
+    status: reasons.length === 0 ? "channel-bound" : "channel-binding-mismatch",
+    channel: expected.channel || null,
+    major: Number.isInteger(expected.major) ? expected.major : null,
+    shell: expected.shell,
+    runtime,
+    lock,
+    lockMajor,
+    reasons,
+  };
+}

package/packages/core/buildchain-compatibility-proof.js

@@ -7,6 +7,7 @@ import {
   devDeliveryRepository as repository,
   devDeliveryText as text,
 } from "./dev-delivery-common.js";
+import { evaluateBuildchainChannelBinding } from "./buildchain-channel-identity.js";
 
 export const BUILDCHAIN_COMPATIBILITY_PROOF_SCHEMA = "kungfu.buildchain.compatibility-proof/v1";
 export const BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA = "kungfu.buildchain.compatibility-proof-registry/v1";
@@ -437,6 +438,19 @@ function evaluateSurfaceRelation({ oldSurface, nextSurface, proofRegistry, major
   };
 }
 
+function evaluateChannelBinding({ lock, workflowShellRef, runtimeRef, expectedChannel, expectedMajor, allowOpaqueRuntime }) {
+  if (!workflowShellRef && !expectedChannel && !expectedMajor) return null;
+  return evaluateBuildchainChannelBinding({
+    workflowShellRef,
+    runtimeRef,
+    lockRef: lock?.buildchain?.ref || "",
+    lockMajorLine: lock?.buildchain?.majorLine || "",
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
+  });
+}
+
 export function evaluateBuildchainContractLock({
   lock,
   current,
@@ -444,11 +458,29 @@ export function evaluateBuildchainContractLock({
   runtimeSha = "",
   runtimeClass = "",
   compatibilityPolicy = "",
+  workflowShellRef = "",
+  expectedChannel = "",
+  expectedMajor = "",
+  allowOpaqueRuntime = false,
 } = {}) {
   if (!current || current.contract !== BUILDCHAIN_CONTRACT) {
     throw new Error("current must be a Buildchain runtime contract world");
   }
   assertBuildchainCompatibilityProjection(current);
+  const binding = evaluateChannelBinding({
+    lock, workflowShellRef, runtimeRef, expectedChannel, expectedMajor, allowOpaqueRuntime,
+  });
+  if (binding?.ok === false) {
+    return {
+      ok: false,
+      status: binding.status,
+      drift: false,
+      compatible: false,
+      issueRecommended: false,
+      reasons: binding.reasons,
+      channelBinding: binding,
+    };
+  }
   if (!new Set(["stable", "alpha"]).has(runtimeClass)) {
     return {
       ok: true,

package/packages/core/buildchain-contract.js

@@ -9,6 +9,13 @@ import {
 import { createControllerRegistry } from "./controller-evidence.js";
 import { enumerateWorkflowInputs } from "./public-surface-audit.js";
 
+export {
+  BUILDCHAIN_CHANNELS,
+  evaluateBuildchainChannelBinding,
+  normalizeBuildchainRef,
+  parseBuildchainRefIdentity,
+} from "./buildchain-channel-identity.js";
+
 export {
   BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
   BUILDCHAIN_COMPATIBILITY_PROOF_SCHEMA,

package/packages/core/controller-evidence.js

@@ -53,7 +53,8 @@ const CONTROLLER_SPECS = [
     workflowId: "build",
     version: 1,
     capabilities: ["channel-selection", "runtime-selection", "build-delegation"],
-    stages: ["resolve-channel", "build", "aggregate"],
+    stages: ["resolve-channel", "alpha", "stable", "aggregate"],
+    optionalStages: ["alpha", "stable"],
     evidence: ["nested-controller-receipt", "controller-receipt"],
   },
   {