@kungfu-tech/buildchain 3.0.2-alpha.2 → 3.0.2-alpha.3

package/docs/reusable-build-surface.md

@@ -94,9 +94,10 @@ jobs:
 
 | Preset                  | Platforms                                                                |
 | ----------------------- | ------------------------------------------------------------------------ |
-| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                           |
-| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels |
-| `custom`                | Requires `platforms-json`                                                |
+| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                              |
+| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                    |
+| `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |
+| `custom`                | Requires `platforms-json`                                                                                   |
 
 Callers can still provide a custom matrix with `platforms-json`. Each platform
 object has:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.2-alpha.2",
+  "version": "3.0.2-alpha.3",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -20,6 +20,7 @@
     "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./candidate-timeline": "./packages/core/candidate-timeline.js",
+    "./channel-candidate": "./packages/core/channel-candidate.js",
     "./cache-evidence": "./packages/core/cache-evidence.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",

package/packages/core/buildchain-publication-authority.js

@@ -27,6 +27,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-patrol.yml", "governance-write"],
   [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/dev-alpha-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
   [".github/workflows/github-governance-audit.yml", "governance-write"],

package/packages/core/channel-candidate.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import crypto from "node:crypto";
+
+export const CHANNEL_CANDIDATE_DECISION_SCHEMA =
+  "kungfu-buildchain-channel-candidate-decision/v1";
+
+const SHA = /^[0-9a-f]{40}$/;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function root(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function required(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+function sha(value, name) {
+  const normalized = required(value, name).toLowerCase();
+  if (!SHA.test(normalized)) throw new Error(`${name} must be an exact 40-character SHA`);
+  return normalized;
+}
+
+function qualifyWorkflow(row, { sourceSha, now, maxAgeSeconds }) {
+  if (!row || typeof row !== "object") throw new Error("workflow evidence is required");
+  const workflowPath = required(row.workflowPath, "workflowPath");
+  if (sha(row.headSha, `${workflowPath} headSha`) !== sourceSha) {
+    throw new Error(`${workflowPath} evidence does not bind source SHA ${sourceSha}`);
+  }
+  if (row.status !== "completed" || row.conclusion !== "success") {
+    throw new Error(`${workflowPath} is not a completed successful run`);
+  }
+  const completedAt = required(row.completedAt, `${workflowPath} completedAt`);
+  const ageSeconds = (Date.parse(now) - Date.parse(completedAt)) / 1000;
+  if (!Number.isFinite(ageSeconds) || ageSeconds < 0 || ageSeconds > maxAgeSeconds) {
+    throw new Error(`${workflowPath} evidence is stale or has an invalid completion time`);
+  }
+  const runId = Number(row.runId);
+  const runAttempt = Number(row.runAttempt || 1);
+  if (!Number.isSafeInteger(runId) || runId <= 0) throw new Error(`${workflowPath} runId is invalid`);
+  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0) throw new Error(`${workflowPath} runAttempt is invalid`);
+  return {
+    workflowPath,
+    workflowName: required(row.workflowName, `${workflowPath} workflowName`),
+    runId,
+    runAttempt,
+    headSha: sourceSha,
+    status: "completed",
+    conclusion: "success",
+    completedAt,
+    url: required(row.url, `${workflowPath} url`),
+  };
+}
+
+export function channelCandidateSourceLockRef(targetBranch, sourceSha) {
+  const target = required(targetBranch, "targetBranch");
+  const exactSha = sha(sourceSha, "sourceSha");
+  return `buildchain/candidate/${target.replace(/[^A-Za-z0-9._-]+/g, "-")}/${exactSha.slice(0, 12)}`;
+}
+
+export function decideChannelCandidate(input) {
+  const repository = required(input.repository, "repository");
+  const sourceBranch = required(input.sourceBranch, "sourceBranch");
+  const targetBranch = required(input.targetBranch, "targetBranch");
+  if (sourceBranch === targetBranch) throw new Error("sourceBranch and targetBranch must differ");
+  const sourceSha = sha(input.sourceSha, "sourceSha");
+  const targetSha = sha(input.targetSha, "targetSha");
+  const now = required(input.now || new Date().toISOString(), "now");
+  const maxAgeSeconds = Number(input.maxAgeSeconds ?? 7 * 24 * 60 * 60);
+  if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds <= 0) {
+    throw new Error("maxAgeSeconds must be a positive integer");
+  }
+  const comparison = input.comparison || {};
+  if (comparison.status !== "ahead" || Number(comparison.aheadBy) <= 0) {
+    const reason = comparison.status === "identical" ? "target-already-current" : "source-does-not-lead-target";
+    return {
+      schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
+      eligible: false,
+      reason,
+      repository,
+      source: { branch: sourceBranch, sha: sourceSha },
+      target: { branch: targetBranch, sha: targetSha },
+      comparison: { status: String(comparison.status || "unknown"), aheadBy: Number(comparison.aheadBy || 0) },
+      decidedAt: now,
+    };
+  }
+  const rows = Array.isArray(input.workflowEvidence) ? input.workflowEvidence : [];
+  const expectedPaths = [...new Set((input.requiredWorkflowPaths || []).map(String))];
+  if (expectedPaths.length === 0) throw new Error("requiredWorkflowPaths must not be empty");
+  if (rows.length !== expectedPaths.length) {
+    throw new Error(`expected exactly ${expectedPaths.length} workflow evidence rows, got ${rows.length}`);
+  }
+  const byPath = new Map();
+  for (const row of rows) {
+    const qualified = qualifyWorkflow(row, { sourceSha, now, maxAgeSeconds });
+    if (byPath.has(qualified.workflowPath)) {
+      throw new Error(`duplicate workflow evidence: ${qualified.workflowPath}`);
+    }
+    byPath.set(qualified.workflowPath, qualified);
+  }
+  for (const workflowPath of expectedPaths) {
+    if (!byPath.has(workflowPath)) throw new Error(`missing workflow evidence: ${workflowPath}`);
+  }
+  const body = {
+    schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
+    eligible: true,
+    reason: "same-source-qualified",
+    repository,
+    source: { branch: sourceBranch, sha: sourceSha },
+    target: { branch: targetBranch, sha: targetSha },
+    comparison: { status: "ahead", aheadBy: Number(comparison.aheadBy) },
+    sourceLockRef: channelCandidateSourceLockRef(targetBranch, sourceSha),
+    workflowEvidence: expectedPaths.map((workflowPath) => byPath.get(workflowPath)),
+    policy: { maxAgeSeconds, requiredWorkflowPaths: expectedPaths },
+    decidedAt: now,
+  };
+  return { ...body, decisionRoot: root(body) };
+}

package/packages/core/index.js

@@ -100,6 +100,12 @@ export {
   normalizeCandidateTimelineEvent,
 } from "./candidate-timeline.js";
 
+export {
+  CHANNEL_CANDIDATE_DECISION_SCHEMA,
+  channelCandidateSourceLockRef,
+  decideChannelCandidate,
+} from "./channel-candidate.js";
+
 export {
   BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT,
   BUILDCHAIN_DIAGNOSTICS_CONTRACT,

package/scripts/build-contract-core.mjs

@@ -31,6 +31,36 @@ export const RUNNER_PRESETS = Object.freeze({
       capabilities: ["node", "native-toolchain", "product-artifacts", "rust"],
     },
   ],
+  "kungfu-v4-native": [
+    {
+      id: "linux-x64",
+      name: "Linux x64",
+      platform: "linux",
+      runner: '["self-hosted","Linux","X64","kungfu-build-v4-linux-x64"]',
+      capabilities: ["node", "native-toolchain", "product-artifacts", "rust"],
+    },
+    {
+      id: "linux-arm64",
+      name: "Linux ARM64",
+      platform: "linux",
+      runner: '["ubuntu-24.04-arm"]',
+      capabilities: ["node", "native-toolchain", "product-artifacts", "rust"],
+    },
+    {
+      id: "macos-arm64",
+      name: "macOS ARM64",
+      platform: "macos",
+      runner: '["self-hosted","macOS","ARM64","kungfu-build-v4-macos-arm64"]',
+      capabilities: ["node", "native-toolchain", "product-artifacts", "rust"],
+    },
+    {
+      id: "windows-x64",
+      name: "Windows x64",
+      platform: "windows",
+      runner: '["self-hosted","Windows","X64","kungfu-build-v4-windows-x64"]',
+      capabilities: ["node", "native-toolchain", "product-artifacts", "rust"],
+    },
+  ],
 });
 
 export const LINUX_CONTAINER_PRESETS = Object.freeze({
@@ -46,6 +76,7 @@ const RUNNER_PRESET_ALIASES = Object.freeze({
   kungfu: "kungfu-v4-self-hosted",
   "kungfu-self-hosted": "kungfu-v4-self-hosted",
   "kungfu-v4": "kungfu-v4-self-hosted",
+  "kungfu-v4-four-platform": "kungfu-v4-native",
 });
 
 const LINUX_CONTAINER_PRESET_ALIASES = Object.freeze({

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+import path from "node:path";
+import { decideChannelCandidate } from "../packages/core/channel-candidate.js";
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function bool(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  return ["1", "true", "yes", "on"].includes(text(value).toLowerCase());
+}
+
+function repository(value) {
+  const normalized = text(value);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) throw new Error(`repository must be owner/repo, got ${value || "<empty>"}`);
+  return normalized;
+}
+
+function branch(value, name) {
+  const normalized = text(value).replace(/^refs\/heads\//, "");
+  if (!normalized || normalized.startsWith("-") || /[\s~^:?*[\\]/.test(normalized)) {
+    throw new Error(`${name} is not a valid branch name`);
+  }
+  return normalized;
+}
+
+function workflowPath(value, name) {
+  const normalized = text(value);
+  if (!/^\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml$/.test(normalized)) {
+    throw new Error(`${name} must be a repository workflow path`);
+  }
+  return normalized;
+}
+
+function integer(value, fallback) {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function normalizeDevAlphaPatrolOptions(options = {}) {
+  return {
+    repository: repository(options.repository ?? process.env.BUILDCHAIN_CHANNEL_PATROL_REPOSITORY ?? process.env.GITHUB_REPOSITORY),
+    sourceBranch: branch(options.sourceBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH ?? "dev/v4/v4.0", "sourceBranch"),
+    targetBranch: branch(options.targetBranch ?? process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH ?? "alpha/v4/v4.0", "targetBranch"),
+    devWorkflowPath: workflowPath(options.devWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DEV_WORKFLOW ?? ".github/workflows/dev-verify-patrol.yml", "devWorkflowPath"),
+    alphaWorkflowPath: workflowPath(options.alphaWorkflowPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_ALPHA_WORKFLOW ?? ".github/workflows/alpha-promotion-preflight.yml", "alphaWorkflowPath"),
+    maxAgeSeconds: integer(options.maxAgeSeconds ?? process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS, 7 * 24 * 60 * 60),
+    createPullRequest: bool(options.createPullRequest ?? process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR, false),
+    dryRun: bool(options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN, true),
+    now: text(options.now ?? process.env.BUILDCHAIN_CHANNEL_PATROL_NOW) || new Date().toISOString(),
+    outputPath: text(options.outputPath ?? process.env.BUILDCHAIN_CHANNEL_PATROL_OUTPUT_PATH) || ".buildchain/patrol/dev-alpha-candidate.json",
+  };
+}
+
+function latestWorkflowEvidence(runs, workflowPathValue, sourceSha) {
+  const matching = runs
+    .filter((run) => run.path === workflowPathValue && run.head_sha === sourceSha)
+    .sort((left, right) => Number(right.id) - Number(left.id));
+  if (matching.length === 0) throw new Error(`missing completed same-SHA workflow run: ${workflowPathValue}`);
+  const run = matching[0];
+  return {
+    workflowPath: workflowPathValue,
+    workflowName: run.name,
+    runId: run.id,
+    runAttempt: run.run_attempt,
+    headSha: run.head_sha,
+    status: run.status,
+    conclusion: run.conclusion,
+    completedAt: run.updated_at,
+    url: run.html_url,
+  };
+}
+
+export async function runDevAlphaCandidatePatrol(optionsInput = {}, clientInput) {
+  const options = normalizeDevAlphaPatrolOptions(optionsInput);
+  if (options.sourceBranch === options.targetBranch) throw new Error("source and target branches must differ");
+  const client = clientInput || createGitHubChannelCandidateClient({
+    repository: options.repository,
+    token: process.env.GITHUB_TOKEN,
+  });
+  const [sourceSha, targetSha] = await Promise.all([
+    client.resolveBranch(options.sourceBranch),
+    client.resolveBranch(options.targetBranch),
+  ]);
+  const comparison = await client.compare(targetSha, sourceSha);
+  const requiredWorkflowPaths = [options.devWorkflowPath, options.alphaWorkflowPath];
+  let workflowEvidence = [];
+  if (comparison.status === "ahead" && Number(comparison.ahead_by) > 0) {
+    const runs = await client.listCompletedRuns(sourceSha);
+    workflowEvidence = requiredWorkflowPaths.map((workflow) =>
+      latestWorkflowEvidence(runs, workflow, sourceSha),
+    );
+  }
+  const decision = decideChannelCandidate({
+    repository: options.repository,
+    sourceBranch: options.sourceBranch,
+    targetBranch: options.targetBranch,
+    sourceSha,
+    targetSha,
+    comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
+    workflowEvidence,
+    requiredWorkflowPaths,
+    maxAgeSeconds: options.maxAgeSeconds,
+    now: options.now,
+  });
+  let pullRequest;
+  if (decision.eligible && options.createPullRequest && !options.dryRun) {
+    await client.ensureImmutableBranch(decision.sourceLockRef, sourceSha);
+    pullRequest = await client.ensurePullRequest({
+      head: decision.sourceLockRef,
+      base: options.targetBranch,
+      title: `Promote qualified ${options.sourceBranch} candidate ${sourceSha.slice(0, 12)} to ${options.targetBranch}`,
+      body: [
+        "Buildchain exact-source channel candidate.",
+        "",
+        `- Source branch: \`${options.sourceBranch}\``,
+        `- Source SHA: \`${sourceSha}\``,
+        `- Target branch/head: \`${options.targetBranch}\` / \`${targetSha}\``,
+        `- Decision root: \`${decision.decisionRoot}\``,
+        ...decision.workflowEvidence.map(
+          (row) => `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
+        ),
+        "",
+        "The source-lock branch must continue to point at the exact source SHA. This patrol never merges the PR, publishes a package, creates a tag, or creates a release.",
+      ].join("\n"),
+    });
+  }
+  return {
+    schema: "kungfu-buildchain-dev-alpha-candidate-patrol/v1",
+    dryRun: options.dryRun,
+    createPullRequest: options.createPullRequest,
+    decision,
+    pullRequest: pullRequest || null,
+  };
+}
+
+function encodeRef(value) {
+  return value.split("/").map(encodeURIComponent).join("/");
+}
+
+export function createGitHubChannelCandidateClient({ repository: repositoryInput, token, fetchImpl = globalThis.fetch }) {
+  const [owner, repo] = repository(repositoryInput).split("/");
+  const headers = {
+    accept: "application/vnd.github+json",
+    authorization: token ? `Bearer ${token}` : undefined,
+    "user-agent": "buildchain-dev-alpha-candidate-patrol",
+    "x-github-api-version": "2022-11-28",
+  };
+  async function api(requestPath, { method = "GET", body, allow404 = false } = {}) {
+    const response = await fetchImpl(`https://api.github.com${requestPath}`, {
+      method,
+      headers: Object.fromEntries(Object.entries(headers).filter(([, value]) => value)),
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const raw = await response.text();
+    const payload = raw ? JSON.parse(raw) : undefined;
+    if (allow404 && response.status === 404) return undefined;
+    if (!response.ok) throw new Error(`GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`);
+    return payload;
+  }
+  return {
+    async resolveBranch(ref) {
+      const payload = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`);
+      return text(payload.object?.sha);
+    },
+    async compare(baseSha, headSha) {
+      return api(`/repos/${owner}/${repo}/compare/${baseSha}...${headSha}`);
+    },
+    async listCompletedRuns(headSha) {
+      const payload = await api(`/repos/${owner}/${repo}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=completed&per_page=100`);
+      return payload.workflow_runs || [];
+    },
+    async ensureImmutableBranch(ref, sourceSha) {
+      const current = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`, { allow404: true });
+      if (current && current.object?.sha !== sourceSha) {
+        throw new Error(`source-lock branch ${ref} points to ${current.object?.sha}, not ${sourceSha}`);
+      }
+      if (current) return current;
+      return api(`/repos/${owner}/${repo}/git/refs`, {
+        method: "POST",
+        body: { ref: `refs/heads/${ref}`, sha: sourceSha },
+      });
+    },
+    async ensurePullRequest({ head, base, title, body }) {
+      const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);
+      return open[0] || api(`/repos/${owner}/${repo}/pulls`, {
+        method: "POST",
+        body: { head, base, title, body },
+      });
+    },
+  };
+}
+
+function markdown(result) {
+  return [
+    "## Buildchain Dev to Alpha candidate patrol",
+    "",
+    `Eligible: \`${result.decision.eligible}\` (${result.decision.reason})`,
+    `Source: \`${result.decision.source.branch}@${result.decision.source.sha}\``,
+    `Target: \`${result.decision.target.branch}@${result.decision.target.sha}\``,
+    `Dry run: \`${result.dryRun}\``,
+    `Pull request: ${result.pullRequest?.html_url || "not created"}`,
+    "",
+  ].join("\n");
+}
+
+async function main() {
+  const options = normalizeDevAlphaPatrolOptions();
+  const result = await runDevAlphaCandidatePatrol(options);
+  fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
+  fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
+  const summary = markdown(result);
+  if (process.env.GITHUB_STEP_SUMMARY) fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+  else process.stdout.write(summary);
+  if (process.env.GITHUB_OUTPUT) {
+    const outputs = {
+      "result-path": options.outputPath,
+      eligible: String(result.decision.eligible),
+      "selected-sha": result.decision.source.sha,
+      "source-lock-ref": result.decision.sourceLockRef || "",
+      "promotion-pr": result.pullRequest?.html_url || "",
+    };
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${Object.entries(outputs).map(([key, value]) => `${key}=${value}`).join("\n")}\n`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/scripts/generate-site-bundle.mjs

@@ -337,6 +337,7 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
+  "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
@@ -516,6 +517,7 @@ function nodeApiMeta(exportName) {
     "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
+    "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
     "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
@@ -814,6 +816,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/stable-candidate-patrol.md",
+      "docs/dev-alpha-candidate-patrol.md",
       "docs/observed-evidence-patrol.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
@@ -900,6 +903,7 @@ function buildSiteBundle() {
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
         ["stable-candidate-patrol", "repository-patrol"],
+        ["dev-alpha-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-qualification", "repository-patrol"],
         ["patrol-daily", "repository-patrol"],