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

package/docs/dev-alpha-candidate-patrol.md

@@ -0,0 +1,64 @@
+---
+status: preview
+period: ongoing
+theme: dev-alpha-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-26
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-26
+  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.
+  invisible_context_boundary: No credentials, private logs, or private configuration were used.
+---
+
+# Dev to Alpha Candidate Patrol
+
+Buildchain provides a reusable observation and PR controller for repositories
+that promote a development branch into a protected Alpha branch. It does not
+publish Alpha. The controller reads the exact heads of both branches, walks the
+bounded development history from newest to oldest (stopping early at the Alpha
+head), and selects the newest commit that satisfies all of these conditions:
+
+- the source is strictly ahead of the recorded target head;
+- the latest completed Dev Patrol for that exact commit SHA succeeded;
+- the latest completed Alpha preflight for the same commit SHA succeeded; and
+- both runs are within the caller's evidence age limit.
+
+The selected commit can be behind the observed development head when newer
+commits have not completed both workflows yet. The decision binds the observed
+head, selected SHA, and count of skipped newer commits. This makes a slow native
+verification lane live under continuous development without silently treating
+an unqualified head as releasable.
+
+History discovery is bounded to the newest 1000 development commits. The
+controller then compares the selected SHA to the exact Alpha head before it can
+be eligible, so a bounded scan cannot turn a commit outside the promotion
+ancestry into a candidate.
+
+The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the
+source and target branches and SHAs, comparison distance, workflow paths, run
+identities and attempts, completion times, URLs, policy, and a canonical decision
+root. Missing, stale, failed, duplicate, or source-mismatched evidence fails
+closed.
+
+## Reusable workflow
+
+Call `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository
+workflow. Start with `dry-run: true`. Once the repository has proven that its
+two workflow names and branch topology produce exact same-SHA evidence, it may
+set `create-pull-request: true` and `dry-run: false`.
+
+Candidate mode creates one branch named from the target branch and the first 12
+characters of the full source SHA. An existing branch must point to the same
+full SHA or the run fails. The controller then creates or reuses one open pull
+request from that immutable branch to the protected Alpha branch.
+
+The workflow never moves the Alpha ref directly, merges or auto-merges the pull
+request, publishes npm, creates a Git tag or GitHub Release, or changes branch
+protection. Those remain repository-owned protected settlement actions.

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.4",
   "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,186 @@
+// 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 selection = input.selection
+    ? {
+        mode: required(input.selection.mode, "selection.mode"),
+        observedSourceHeadSha: sha(
+          input.selection.observedSourceHeadSha,
+          "selection.observedSourceHeadSha",
+        ),
+        skippedNewerCommitCount: Number(
+          input.selection.skippedNewerCommitCount || 0,
+        ),
+      }
+    : undefined;
+  if (
+    selection &&
+    (!Number.isSafeInteger(selection.skippedNewerCommitCount) ||
+      selection.skippedNewerCommitCount < 0)
+  ) {
+    throw new Error(
+      "selection.skippedNewerCommitCount must be a non-negative integer",
+    );
+  }
+  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) },
+    ...(selection ? { selection } : {}),
+    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({