@kungfu-tech/buildchain 2.11.14-alpha.7 → 2.12.0-alpha.0

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

@@ -4,7 +4,7 @@
   "status": "passed",
   "summary": {
     "cliCommandCount": 75,
-    "workflowCount": 38,
+    "workflowCount": 39,
     "actionCount": 4,
     "sitePageCount": 45,
     "docCommandRefCount": 237,
@@ -684,6 +684,66 @@
         ],
         "inputCount": 1
       },
+      {
+        "id": "build",
+        "path": ".github/workflows/build.yml",
+        "inputs": [
+          "artifact-name",
+          "artifact-name-template",
+          "artifact-paths",
+          "artifact-relay-s3-bucket",
+          "artifact-relay-s3-download-role-arn",
+          "artifact-relay-s3-oidc-audience",
+          "artifact-relay-s3-prefix",
+          "artifact-relay-s3-region",
+          "artifact-relay-s3-role-arn",
+          "artifact-relay-s3-upload-role-arn",
+          "artifact-retention-days",
+          "artifact-transfer-mode",
+          "build-command",
+          "buildchain-alpha-contract-lock-path",
+          "buildchain-channel",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "buildchain-stable-contract-lock-path",
+          "checkout-cache-fallback",
+          "checkout-cache-fetch-attempts",
+          "checkout-cache-github-timeout-seconds",
+          "checkout-cache-mirror-url-template",
+          "checkout-cache-mode",
+          "checkout-cache-reference-repository-template",
+          "checkout-cache-timeout-seconds",
+          "expected-artifacts-json",
+          "install-command",
+          "linux-container-image",
+          "linux-container-preset",
+          "node-version",
+          "platforms-json",
+          "process-sample-interval-ms",
+          "process-summary-path",
+          "publish-anchor-request-json",
+          "publish-channel",
+          "publish-refs-json",
+          "publish-registry",
+          "publish-source-ref",
+          "release-candidate",
+          "requested-parallelism",
+          "require-build",
+          "require-install",
+          "require-trusted-event",
+          "require-verify",
+          "runner-preset",
+          "sample-process-tree",
+          "setup-node",
+          "untrusted-policy",
+          "verify-command",
+          "working-directory"
+        ],
+        "inputCount": 53
+      },
       {
         "id": "buildchain-alpha-self-dogfood",
         "path": ".github/workflows/buildchain-alpha-self-dogfood.yml",
@@ -2546,8 +2606,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "3c0729f5351eb82fe26625fa5aabf30903f45f68af2431e02860f85ada468ac9",
-    "workflowRegistryDigest": "5875dd6440e9585dc8ce86fc61af8546a60ae1140ed25789199adead2846d4fe",
-    "pageRegistryDigest": "de7377d68eb8b3069b83a2096de8ea24153090e746649015388224b9997e2340"
+    "workflowRegistryDigest": "2bd177fe6e3cbcd382ba30d90c96f35865ef17fc29e451715696cb076d7da933",
+    "pageRegistryDigest": "e496f039ccd56f2be611433c075b5150a4ede2b04682bb7af0ee4716b1f5eb6a"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-11T00:08:19.877Z",
-  "publishedAt": "2026-07-11T00:08:19.877Z",
+  "generatedAt": "2026-07-11T01:35:09.048Z",
+  "publishedAt": "2026-07-11T01:35:09.048Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7d3f049ffc8b567c3afad9fa9f8e974b50fd3b90",
+  "sourceRevision": "3dde1345af4880782c221385158a8a9f3674fcad",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.7",
+    "version": "2.12.0-alpha.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-11T00:08:19.877Z",
-  "publishedAt": "2026-07-11T00:08:19.877Z",
+  "generatedAt": "2026-07-11T01:35:09.048Z",
+  "publishedAt": "2026-07-11T01:35:09.048Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7d3f049ffc8b567c3afad9fa9f8e974b50fd3b90",
+  "sourceRevision": "3dde1345af4880782c221385158a8a9f3674fcad",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.7",
+    "version": "2.12.0-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:02987c6bf99441eddc630fa4050fd109c15923047a4591e26d54a714c124539a"
+      "digest": "sha256:bad18d05d3d03b77bf64d8697fc351d58b1372a355a4f25c6719bf08984a79a2"
     },
     {
       "id": "install",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4611e4ae47091687f50b489ccc6caba911f13bb1f73b27a5d44581d8a6450d06"
+      "digest": "sha256:670528f1710001a488b2c544db7c104a4770c0ce7d62afa6c6017e473677fd03"
     },
     {
       "id": "publish-transaction",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:69c4146640626bc03b93ac178e250745e45939ba9443f3ba27207a35522036c4"
+      "digest": "sha256:db9077f3748954dee3d28cd1e418dd537fec498df31155c560f7929b622888cb"
     },
     {
       "id": "release-flow",
@@ -245,7 +245,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:2c79f7d1a072a40c75d889beac38ae843b2170587fc570ce40722d3968b6506e"
+      "digest": "sha256:400027d5e34d5c22752f7664bb9ca9ce99c04e7be298183d0303f3fb04fa7747"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -59,7 +59,7 @@
         "working-directory"
       ],
       "inputCount": 50,
-      "surface": "reusable-workflow",
+      "surface": "reusable-build",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
@@ -343,6 +343,69 @@
       "capabilityGroup": "api-cli-reference",
       "status": "repository-internal"
     },
+    {
+      "id": "build",
+      "path": ".github/workflows/build.yml",
+      "inputs": [
+        "artifact-name",
+        "artifact-name-template",
+        "artifact-paths",
+        "artifact-relay-s3-bucket",
+        "artifact-relay-s3-download-role-arn",
+        "artifact-relay-s3-oidc-audience",
+        "artifact-relay-s3-prefix",
+        "artifact-relay-s3-region",
+        "artifact-relay-s3-role-arn",
+        "artifact-relay-s3-upload-role-arn",
+        "artifact-retention-days",
+        "artifact-transfer-mode",
+        "build-command",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-channel",
+        "buildchain-contract-compatibility-policy",
+        "buildchain-contract-drift-issue-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "buildchain-stable-contract-lock-path",
+        "checkout-cache-fallback",
+        "checkout-cache-fetch-attempts",
+        "checkout-cache-github-timeout-seconds",
+        "checkout-cache-mirror-url-template",
+        "checkout-cache-mode",
+        "checkout-cache-reference-repository-template",
+        "checkout-cache-timeout-seconds",
+        "expected-artifacts-json",
+        "install-command",
+        "linux-container-image",
+        "linux-container-preset",
+        "node-version",
+        "platforms-json",
+        "process-sample-interval-ms",
+        "process-summary-path",
+        "publish-anchor-request-json",
+        "publish-channel",
+        "publish-refs-json",
+        "publish-registry",
+        "publish-source-ref",
+        "release-candidate",
+        "requested-parallelism",
+        "require-build",
+        "require-install",
+        "require-trusted-event",
+        "require-verify",
+        "runner-preset",
+        "sample-process-tree",
+        "setup-node",
+        "untrusted-policy",
+        "verify-command",
+        "working-directory"
+      ],
+      "inputCount": 53,
+      "surface": "channel-build-router",
+      "capabilityGroup": "reusable-build",
+      "status": "active"
+    },
     {
       "id": "buildchain-alpha-self-dogfood",
       "path": ".github/workflows/buildchain-alpha-self-dogfood.yml",

package/docs/MAP.md

@@ -95,6 +95,7 @@ replace them.
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
 | What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
+| How do I use one build job that follows alpha during development and stable for releases? | [`reusable-build-surface.md`](reusable-build-surface.md#automatic-channel-router) | use | preview |
 | 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 |

package/docs/release-governance.md

@@ -170,21 +170,24 @@ while exact tags and SHAs remain the reproducible audit choice.
 ### Buildchain Alpha Self-Dogfood
 
 Buildchain continuously consumes its own current major alpha through
-`.github/workflows/buildchain-alpha-self-dogfood.yml`. The workflow calls the
-released outer reusable workflow at `@v2-alpha` without a runtime override, so
-both the workflow shell and its default runtime must resolve through the same
-floating alpha channel. A parallel stable lane checks out `v2` and runs the
-same declared install, build, and verify lifecycle directly. The direct stable
-lane is intentional: it preserves stable-runtime compatibility without
-requiring the previous stable outer workflow to understand a self-call identity
-fix that has not reached stable yet. Both lanes use a single GitHub-hosted Linux
-fixture to keep the recurring check bounded.
+`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
+released channel router at `build.yml@v2-alpha`. The auto lane must resolve
+`v2-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
+declared install, build, and verify fixture, proving that a single consumer
+surface routes to distinct released runtimes without duplicating lifecycle
+configuration in the consumer.
 
 The reusable build trust gate reads `job.workflow_ref`, which identifies the
 called workflow and its selected ref. It does not infer the runtime from
 `github.workflow_ref`, because GitHub defines that context as the caller
 workflow identity during a reusable call.
 
+The router selects `.buildchain/alpha-contract-lock.json` for alpha and
+`.buildchain/contract-lock.json` for stable. The alpha lock records the exact
+reviewed alpha SHA and compatibility digest; it does not replace the stable
+consumer lock. A later alpha with only compatible additive drift continues,
+while a changed breaking digest fails until the new alpha contract is reviewed.
+
 The evidence job resolves `v2-alpha` and `v2` through the GitHub refs API,
 compares those immutable SHAs with the reusable workflow outputs, verifies the
 `alpha` and `stable` classifications, and uploads a JSON evidence artifact.

package/docs/reusable-build-surface.md

@@ -5,9 +5,69 @@ Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
 
-## Workflow
+## Automatic Channel Router
 
-Stable consumers call:
+The preferred consumer surface is one reusable workflow call. After v2.12
+reaches the stable major ref, consumers keep this configuration for both alpha
+development and stable release work:
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    with:
+      working-directory: .
+      artifact-name: libnode
+      runner-preset: kungfu-v4-self-hosted
+      publish-channel: none
+    secrets: inherit
+```
+
+`buildchain-channel` defaults to `auto`. Selection uses this precedence:
+
+1. an explicit `buildchain-ref` train, SHA, or official channel;
+2. an explicit `buildchain-channel: alpha|stable`;
+3. `publish-channel: alpha|release|major`;
+4. GitHub release prerelease metadata;
+5. a canonical semver tag;
+6. non-release PR, push, dispatch, schedule, and workflow-run events default to
+   alpha.
+
+The resolved runtime is `vN-alpha` for development and prerelease intent and
+`vN` for stable release intent. Unknown custom publish channels, malformed
+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`.
+
+Only repositories changing the default policy need extra routing input:
+
+```yaml
+with:
+  buildchain-channel: stable
+```
+
+During the v2.12 prerelease evaluation window, canaries use
+`build.yml@v2-alpha`. The same router then selects `v2-alpha` or stable `v2` as
+the runtime. Production consumers should adopt `build.yml@v2` after the router
+has reached stable; this keeps the routing shell itself on a stable ref.
+
+The router is generated from `.build.yml`'s input/output surface. Run
+`node scripts/generate-channel-build-workflow.mjs` after changing the advanced
+build workflow; inventory and unit tests reject a stale generated router.
+
+## Advanced Workflow
+
+Consumers that need direct workflow-shell or runtime control call the advanced
+surface:
 
 ```yaml
 jobs:
@@ -214,7 +274,7 @@ The lock is intentionally small. It does not copy the full contract. The full
 contract remains in the Buildchain ref and package; the consumer records only
 what it accepted and the policy used to compare future floating-ref movement.
 
-Alpha-channel consumers select the matching workflow shell:
+Advanced alpha-channel consumers select the matching workflow shell:
 
 ```yaml
 jobs:

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |
 | 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
 | 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |
 | 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |

package/package.json

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

package/packages/core/buildchain-contract.js

@@ -111,6 +111,36 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "retryable GitHub fallback fetches use a bounded attempt budget before exact source SHA and tree verification",
       ],
     }),
+    surface(root, {
+      id: "channel-build-router",
+      kind: "workflow",
+      path: ".github/workflows/build.yml",
+      publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/build.yml@${majorLine}`,
+      requiredInputs: [],
+      requiredOutputs: ["buildchain-channel", "buildchain-runtime-sha", "build-summary-artifact"],
+      breakingDefaults: {
+        channelDefault: "auto",
+        developmentDefault: "alpha",
+        prereleaseDefault: "alpha",
+        stableReleaseDefault: "stable",
+        ambiguousReleasePolicy: "fail-closed",
+      },
+      optionalInputs: [
+        "buildchain-channel",
+        "buildchain-ref",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-stable-contract-lock-path",
+        "buildchain-contract-lock-path",
+      ],
+      guarantees: [
+        "consumers declare one build job while Buildchain selects the matching generic major channel",
+        "development and prerelease intent select vN-alpha",
+        "stable release intent selects vN",
+        "ambiguous release-like intent fails before build jobs",
+        "explicit train and exact-SHA overrides retain the reusable build trust gate",
+        "alpha and stable channel selections use separate consumer contract locks by default",
+      ],
+    }),
     surface(root, {
       id: "release-candidate-promote",
       kind: "workflow",

package/scripts/buildchain-channel-router.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CHANNELS = new Set(["auto", "alpha", "stable"]);
+const STABLE_PUBLISH_CHANNELS = new Set(["release", "major"]);
+const OFFICIAL_REF = /^v(\d+)(?:\.\d+)?(?:-alpha)?$/;
+const EXACT_SHA = /^[0-9a-f]{40}$/i;
+const TRAIN_REF = /^(?:refs\/heads\/)?train\/v(\d+)\/v\d+\.\d+\/[A-Za-z0-9._/-]+$/;
+const SEMVER_TAG = /^refs\/tags\/v?\d+\.\d+\.\d+(?:-([0-9A-Za-z.-]+))?$/;
+
+function normalized(value) {
+  return String(value ?? "").trim();
+}
+
+function parseBoolean(value, name) {
+  const text = normalized(value).toLowerCase();
+  if (text === "true") return true;
+  if (text === "false") return false;
+  throw new Error(`${name} must be true or false`);
+}
+
+function readPackageVersion(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version || "";
+  } catch {
+    return "";
+  }
+}
+
+function majorFrom(value) {
+  const text = normalized(value).replace(/^refs\/(?:heads|tags)\//, "");
+  const official = text.match(OFFICIAL_REF);
+  if (official) return Number(official[1]);
+  const train = text.match(TRAIN_REF);
+  if (train) return Number(train[1]);
+  const embedded = text.match(/(?:^|\/)v(\d+)(?:$|[./-])/);
+  if (embedded) return Number(embedded[1]);
+  const version = text.match(/^(\d+)\.\d+\.\d+/);
+  return version ? Number(version[1]) : undefined;
+}
+
+function resolveMajor({ requestedRef, routerRef, packageVersion }) {
+  for (const candidate of [requestedRef, routerRef, packageVersion]) {
+    const major = majorFrom(candidate);
+    if (Number.isInteger(major)) return major;
+  }
+  throw new Error("unable to derive the Buildchain major; call the router from a vN ref or provide a vN buildchain-ref");
+}
+
+function classifyRequestedRef(value) {
+  const ref = normalized(value).replace(/^refs\/(?:heads|tags)\//, "");
+  if (!ref) return { kind: "none", ref };
+  if (EXACT_SHA.test(ref)) return { kind: "override", ref };
+  if (TRAIN_REF.test(value) || TRAIN_REF.test(ref)) {
+    return { kind: "override", ref: normalized(value).replace(/^refs\/heads\//, "") };
+  }
+  const official = ref.match(OFFICIAL_REF);
+  if (official) {
+    return {
+      kind: ref.endsWith("-alpha") ? "alpha" : "stable",
+      ref,
+      major: Number(official[1]),
+    };
+  }
+  throw new Error("buildchain-ref must be an official vN/vN.M channel, a train ref, or an exact 40-character SHA");
+}
+
+function selected(channel, major, source, reason) {
+  return {
+    channel,
+    major,
+    buildchainRef: channel === "alpha" ? `v${major}-alpha` : `v${major}`,
+    selectionSource: source,
+    reason,
+  };
+}
+
+export function resolveBuildchainChannel({
+  requestedChannel = "auto",
+  requestedRef = "",
+  publishChannel = "none",
+  eventName = "",
+  gitRef = "",
+  releasePrerelease = "",
+  routerRef = "",
+  packageVersion = "",
+} = {}) {
+  const channel = normalized(requestedChannel || "auto").toLowerCase();
+  if (!CHANNELS.has(channel)) {
+    throw new Error("buildchain-channel must be auto, alpha, or stable");
+  }
+
+  const explicitRef = classifyRequestedRef(requestedRef);
+  const major = resolveMajor({ requestedRef: explicitRef.ref, routerRef, packageVersion });
+  if (explicitRef.kind !== "none") {
+    if (channel !== "auto" && explicitRef.kind !== "override" && channel !== explicitRef.kind) {
+      throw new Error(`buildchain-channel=${channel} conflicts with buildchain-ref=${explicitRef.ref}`);
+    }
+    if (channel !== "auto" && explicitRef.kind === "override") {
+      throw new Error("train and exact-SHA buildchain-ref overrides require buildchain-channel=auto");
+    }
+    return {
+      channel: explicitRef.kind,
+      major,
+      buildchainRef: explicitRef.ref,
+      selectionSource: "explicit-buildchain-ref",
+      reason: `explicit Buildchain runtime ref ${explicitRef.ref}`,
+    };
+  }
+
+  if (channel !== "auto") {
+    return selected(channel, major, "explicit-channel", `explicit buildchain-channel=${channel}`);
+  }
+
+  const publishing = normalized(publishChannel || "none").toLowerCase();
+  if (publishing === "alpha") {
+    return selected("alpha", major, "publish-channel", "publish-channel=alpha");
+  }
+  if (STABLE_PUBLISH_CHANNELS.has(publishing)) {
+    return selected("stable", major, "publish-channel", `publish-channel=${publishing}`);
+  }
+  if (publishing !== "none") {
+    throw new Error(`custom publish-channel=${publishing} requires an explicit buildchain-channel`);
+  }
+
+  if (eventName === "release") {
+    if (normalized(releasePrerelease) === "") {
+      throw new Error("release events require github.event.release.prerelease to select a Buildchain channel");
+    }
+    const prerelease = parseBoolean(releasePrerelease, "releasePrerelease");
+    return selected(
+      prerelease ? "alpha" : "stable",
+      major,
+      "release-event",
+      prerelease ? "GitHub prerelease event" : "GitHub stable release event",
+    );
+  }
+
+  const ref = normalized(gitRef);
+  if (ref.startsWith("refs/tags/")) {
+    const tag = ref.match(SEMVER_TAG);
+    if (!tag) {
+      throw new Error(`tag ${ref} is not a canonical semver release tag; set buildchain-channel explicitly`);
+    }
+    return selected(
+      tag[1] ? "alpha" : "stable",
+      major,
+      "semver-tag",
+      tag[1] ? `prerelease tag ${ref}` : `stable tag ${ref}`,
+    );
+  }
+
+  return selected("alpha", major, "development-default", `non-release ${eventName || "unknown"} event`);
+}
+
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`missing value for --${key}`);
+    values[key] = value;
+    index += 1;
+  }
+  return values;
+}
+
+function appendOutputs(file, result) {
+  const entries = {
+    channel: result.channel,
+    major: String(result.major),
+    "buildchain-ref": result.buildchainRef,
+    "selection-source": result.selectionSource,
+    reason: result.reason,
+  };
+  fs.appendFileSync(file, Object.entries(entries).map(([key, value]) => `${key}=${value}\n`).join(""));
+}
+
+function appendSummary(file, result) {
+  fs.appendFileSync(
+    file,
+    [
+      "## Buildchain channel router",
+      "",
+      `- selected channel: \`${result.channel}\``,
+      `- selected runtime ref: \`${result.buildchainRef}\``,
+      `- selection source: \`${result.selectionSource}\``,
+      `- reason: ${result.reason}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = path.resolve(args.cwd || process.cwd());
+  const result = resolveBuildchainChannel({
+    requestedChannel: args.channel,
+    requestedRef: args["buildchain-ref"],
+    publishChannel: args["publish-channel"],
+    eventName: args["event-name"],
+    gitRef: args.ref,
+    releasePrerelease: args["release-prerelease"],
+    routerRef: args["router-ref"],
+    packageVersion: readPackageVersion(cwd),
+  });
+  if (process.env.GITHUB_OUTPUT) appendOutputs(process.env.GITHUB_OUTPUT, result);
+  if (process.env.GITHUB_STEP_SUMMARY) appendSummary(process.env.GITHUB_STEP_SUMMARY, result);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((error) => {
+    console.error(`buildchain-channel-router: ${error.message}`);
+    process.exitCode = 1;
+  });
+}