@kungfu-tech/buildchain 2.4.2-alpha.0 → 2.4.2-alpha.1

package/actions/promote-buildchain-ref/README.md

@@ -125,6 +125,11 @@ contract:
 specific package publication. Direct `alpha/*` or `release/*` channel refs are
 not valid publish source locks when `require-publish-source-lock` is enabled,
 and a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.
+The reusable build workflow performs the cheaper channel-ref preflight earlier:
+after source-lock resolution and before the build matrix, it requires the target
+channel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point
+at the locked `publish-source-sha`. If not, maintainers should merge the source
+commit through the channel PR first.
 
 When enabled, the action creates or resumes a release transaction keyed by
 repository, version, source SHA, and target ref. It persists that transaction to
@@ -232,9 +237,10 @@ governance semantics:
 The promotion workflow should use `BUILDCHAIN_PROMOTION_TOKEN` for non-dry-run
 promotion. The token is the buildchain equivalent of the old ABV runner release
 authority: protected branch review and check rules guard human channel merges,
-while this action independently rechecks PR lineage, alpha/release tree
-equivalence, and generated version-state verification before moving channel
-refs and tags.
+while the reusable build trust gate now checks the source-lock channel HEAD and
+merged same-repository PR lineage before heavy build runners start. This action
+still independently rechecks PR lineage, alpha/release tree equivalence, and
+generated version-state verification before moving channel refs and tags.
 
 The tag names intentionally follow the old ABV release semantics:
 exact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating

package/bin/buildchain.mjs

@@ -97,7 +97,7 @@ function usage() {
                   [--path <jsonl>] -- <command> [args...]
   buildchain web-surface ...
   buildchain infra-contract ...
-  buildchain publish-source <lock|manifest|verify-lock|validate-anchored-release> ...
+  buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
   buildchain build-contract ...
 
 Examples:
@@ -823,6 +823,10 @@ async function main(argv = process.argv.slice(2)) {
       runScript("verify-publish-source-lock.mjs", publishArgs);
       return;
     }
+    if (mode === "verify-channel-ref") {
+      runScript("verify-publish-channel-ref.mjs", publishArgs);
+      return;
+    }
     if (mode === "validate-anchored-release") {
       const report = validateAnchoredPackageRelease({
         cwd: readFlag(publishArgs, "cwd", process.cwd()),

package/docs/binary-distribution.md

@@ -16,6 +16,12 @@ The release lane does not upload loose top-level `buildchain` or
 inside their archives, so top-level loose assets would collide when matrix
 artifacts are merged.
 
+Release asset upload is gated before the matrix starts. Manual
+`workflow_dispatch` runs are binary dry-runs only and must keep
+`upload-release=false`; real GitHub Release uploads must come from a true
+`v*` tag-triggered run so an invalid manual upload request cannot spend the
+three-platform build matrix and then fail at `gh release upload`.
+
 Each archive is accompanied by:
 
 - a platform manifest from the standalone binary builder;
@@ -67,4 +73,3 @@ node scripts/create-release-bundle.mjs \
   --output-dir .buildchain/release-passport \
   --tag v0.0.0-local
 ```
-

package/docs/reusable-build-surface.md

@@ -308,6 +308,17 @@ that SHA in every build job, and uses the same SHA in artifact names, manifests,
 and aggregate summaries. Reruns therefore rebuild the same source tree even if a
 gate branch moves later.
 
+Before any heavy build matrix is scheduled, the workflow also verifies that the
+target channel ref implied by the source lock already points at
+`publish-source-sha` and that the target channel HEAD came from the required
+merged same-repository channel PR. `publish-gate/alpha/<line>/<version>` must
+match `alpha/<line>` and have PR lineage `dev/<line> -> alpha/<line>`;
+`publish-gate/release/<line>/<version>` must match `release/<line>` and have PR
+lineage `alpha/<line> -> release/<line>`. If either check fails, the run fails
+fast with a diagnostic telling maintainers to merge the source commit through
+the channel PR first. This keeps verify from spending runner time on a source
+tree that cannot legally enter the requested publish channel.
+
 The resolved release manifest is uploaded as an artifact and emitted as
 `release-manifest-json`. It records:
 
@@ -335,6 +346,18 @@ If the branch tip no longer matches the manifest SHA, the publish job must fail
 closed. Moving a gate branch creates a new publish decision and should produce a
 new build run.
 
+Custom publish jobs can also repeat the channel-ref preflight:
+
+```yaml
+- name: Verify publish channel ref still matches
+  run: node .buildchain/runtime/scripts/verify-publish-channel-ref.mjs
+  env:
+    BUILDCHAIN_PUBLISH_SOURCE_REF: ${{ needs.build.outputs.publish-source-ref }}
+    BUILDCHAIN_PUBLISH_SOURCE_SHA: ${{ needs.build.outputs.publish-source-sha }}
+    BUILDCHAIN_SOURCE_REPOSITORY: ${{ github.repository }}
+    GITHUB_TOKEN: ${{ github.token }}
+```
+
 Anchored/manual package release jobs should also make the Buildchain promotion
 action validate that publication is entering through the same
 `publish-gate/{alpha,release,major}` source-lock contract before any package

package/docs/web-surface-deployments.md

@@ -368,6 +368,7 @@ The reusable workflow maps GitHub events to Buildchain web-surface semantics:
 | `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |
 | `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |
 | `push` to `main` | validate, build, verify, and plan `staging` from the merged `main` SHA |
+| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |
 | `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |
 
 The optional `buildchain-ref` input is empty by default. Empty keeps the
@@ -427,6 +428,7 @@ jobs:
       staging-apply: true
       staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions
       production-apply: false
+      production-release-on-main: false
       production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
       production-environment: production
 ```
@@ -439,9 +441,41 @@ When enabled, Buildchain owns the full release apply state machine:
   only.
 - Pushes to `main` run staging `deploy-apply --dry-run false` with the staging
   role.
-- Production runs only on `workflow_dispatch` when both `production-approved`
-  and `production-apply` are true, and the job is gated by the configured GitHub
-  Environment.
+- Production runs when `production-apply` is true and either:
+  - a trusted `workflow_dispatch` passes `production-approved=true`; or
+  - `production-release-on-main=true` and the `main` push commit is associated
+    with exactly one same-repository, merged release pull request matching
+    `production-release-label` and `production-release-head-prefix`.
+  The production job is then gated by the configured GitHub Environment.
+
+For release-PR publishing, callers opt in explicitly:
+
+```yaml
+jobs:
+  web-surface:
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    with:
+      build-command: npm run build
+      verify-command: npm run check
+      artifact-path: dist
+      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
+      production-release-on-main: true
+      production-release-label: buildchain-release
+      production-release-head-prefix: feature/release-
+      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
+      production-environment: production
+```
+
+The merge button becomes the production approval only for a PR that carries the
+release label and comes from the configured source-branch prefix. Ordinary
+pull requests merged into `main` keep the staging plan behavior and do not
+publish production.
+
+Apply-only inputs are validated before the caller build or verification command
+runs. If the current event would run preview, staging, or production apply,
+missing role inputs or a production apply without `production-approved=true`
+on manual dispatch fail immediately instead of spending the build and plan jobs
+first.
 
 Callers must grant `id-token: write` for OIDC role assumption. Preview comments
 also need `pull-requests: write`. The AWS roles remain caller-owned and should

package/package.json

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

package/scripts/build-contract-core.mjs

@@ -348,6 +348,162 @@ export function verifyPublishSourceLock({
   };
 }
 
+export function resolvePublishChannelTargetRef({
+  sourceRef = "",
+  targetRef = "",
+} = {}) {
+  const requestedTarget = normalizeGitRefName(targetRef);
+  if (requestedTarget) {
+    return requestedTarget;
+  }
+  const parsed = parsePublishSourceRef(sourceRef);
+  if (!parsed.enabled || parsed.anchor) {
+    return "";
+  }
+  if (parsed.channel === "alpha" || parsed.channel === "release") {
+    return `${parsed.channel}/${parsed.line}`;
+  }
+  if (parsed.channel === "major") {
+    return parsed.legacyAlias ? "major-gate" : "publish-gate/major";
+  }
+  return "";
+}
+
+function expectedPublishChannelHeadRef(targetRef) {
+  const ref = normalizeGitRefName(targetRef);
+  if (ref === "publish-gate/major" || ref === "major-gate") {
+    return "release/vN/vN.M";
+  }
+  const match = ref.match(/^(alpha|release)\/v(\d+)\/v(\d+)\.(\d+)$/);
+  if (!match) {
+    throw new Error(
+      `publish target channel ref must be alpha/vN/vN.M, release/vN/vN.M, publish-gate/major, or major-gate; got ${ref || "<empty>"}`,
+    );
+  }
+  const [, channel, major, lineMajor, minor] = match;
+  if (major !== lineMajor) {
+    throw new Error(`publish target channel ref major mismatch: ${ref}`);
+  }
+  return channel === "alpha"
+    ? `dev/v${major}/v${major}.${minor}`
+    : `alpha/v${major}/v${major}.${minor}`;
+}
+
+function isReleaseLineRef(ref = "") {
+  const match = String(ref || "").match(/^release\/v(\d+)\/v(\d+)\.(\d+)$/);
+  return !!match && match[1] === match[2];
+}
+
+export function verifyPublishChannelPrLineage({
+  sourceRef = "",
+  sourceSha = "",
+  targetRef = "",
+  repository = "",
+  pullRequests = [],
+} = {}) {
+  const parsed = parsePublishSourceRef(sourceRef);
+  const resolvedTargetRef = resolvePublishChannelTargetRef({
+    sourceRef,
+    targetRef,
+  });
+  if (!parsed.enabled || parsed.anchor || !resolvedTargetRef) {
+    return {
+      ok: true,
+      skipped: true,
+      sourceRef: parsed.sourceRef || normalizeGitRefName(sourceRef),
+      targetRef: resolvedTargetRef,
+      reason: !parsed.enabled
+        ? "publish source ref is not configured"
+        : parsed.anchor
+          ? "publish-gate/anchor has no channel target ref"
+          : "publish target channel ref is not configured",
+    };
+  }
+  const sha = assertSha(sourceSha, "sourceSha");
+  const expectedHeadRef = expectedPublishChannelHeadRef(resolvedTargetRef);
+  const expectedRepository = String(repository || "").trim();
+  if (!expectedRepository) {
+    throw new Error("repository is required to verify publish channel PR lineage");
+  }
+  const matchingPullRequest = (pullRequests || []).find((pullRequest) => {
+    const baseRef = pullRequest?.base?.ref || "";
+    const headRef = pullRequest?.head?.ref || "";
+    const headRepo = pullRequest?.head?.repo?.full_name || "";
+    if (!pullRequest?.merged_at || baseRef !== resolvedTargetRef || headRepo !== expectedRepository) {
+      return false;
+    }
+    if (resolvedTargetRef === "publish-gate/major" || resolvedTargetRef === "major-gate") {
+      return isReleaseLineRef(headRef);
+    }
+    return headRef === expectedHeadRef;
+  });
+  if (!matchingPullRequest) {
+    throw new Error(
+      `publish source-lock PR lineage mismatch: ${parsed.sourceRef} is locked at ${sha}, but target channel ref ${resolvedTargetRef} must come from a merged same-repository PR ${expectedHeadRef} -> ${resolvedTargetRef}. Merge the source commit through that channel PR before running publish verification.`,
+    );
+  }
+  return {
+    ok: true,
+    skipped: false,
+    sourceRef: parsed.sourceRef,
+    sourceSha: sha,
+    targetRef: resolvedTargetRef,
+    expectedHeadRef,
+    pullRequest: {
+      number: matchingPullRequest.number,
+      url: matchingPullRequest.html_url || matchingPullRequest.url || "",
+      headRef: matchingPullRequest.head?.ref || "",
+      baseRef: matchingPullRequest.base?.ref || "",
+      mergedAt: matchingPullRequest.merged_at || "",
+    },
+  };
+}
+
+export function verifyPublishChannelRef({
+  sourceRef = "",
+  sourceSha = "",
+  targetRef = "",
+  targetSha = "",
+} = {}) {
+  const parsed = parsePublishSourceRef(sourceRef);
+  const resolvedTargetRef = resolvePublishChannelTargetRef({
+    sourceRef,
+    targetRef,
+  });
+  if (!parsed.enabled || parsed.anchor || !resolvedTargetRef) {
+    return {
+      ok: true,
+      skipped: true,
+      sourceRef: parsed.sourceRef || normalizeGitRefName(sourceRef),
+      targetRef: resolvedTargetRef,
+      reason: !parsed.enabled
+        ? "publish source ref is not configured"
+        : parsed.anchor
+          ? "publish-gate/anchor has no channel target ref"
+          : "publish target channel ref is not configured",
+    };
+  }
+  const expected = assertSha(sourceSha, "sourceSha");
+  const current = assertSha(targetSha, "targetSha");
+  if (expected !== current) {
+    const channelHint =
+      parsed.channel === "alpha" || parsed.channel === "release"
+        ? `Merge the source commit through the channel PR into ${resolvedTargetRef} before running publish verification.`
+        : `Move ${resolvedTargetRef} to the reviewed source commit before running publish verification.`;
+    throw new Error(
+      `publish source-lock target mismatch: ${parsed.sourceRef} is locked at ${expected}, but target channel ref ${resolvedTargetRef} points at ${current}. ${channelHint}`,
+    );
+  }
+  return {
+    ok: true,
+    skipped: false,
+    sourceRef: parsed.sourceRef,
+    sourceSha: expected,
+    targetRef: resolvedTargetRef,
+    targetSha: current,
+  };
+}
+
 function normalizePackageSet(packages) {
   if (!Array.isArray(packages) || packages.length === 0) {
     throw new Error("package set must include at least one package");

package/scripts/verify-publish-channel-ref.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import {
+  resolvePublishChannelTargetRef,
+  verifyPublishChannelPrLineage,
+  verifyPublishChannelRef,
+} from "./build-contract-core.mjs";
+import {
+  normalizeSourceRef,
+  resolvePublishSourceRefSha,
+} from "./publish-source-ref-resolver.mjs";
+
+function readEnv(env, name, fallback = "") {
+  return env[name] || fallback;
+}
+
+function splitRepository(repository) {
+  const value = String(repository || "").trim();
+  const match = value.match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`BUILDCHAIN_SOURCE_REPOSITORY must be owner/repo, got: ${value || "<empty>"}`);
+  }
+  return { owner: match[1], repo: match[2] };
+}
+
+async function resolveAssociatedPullRequests({
+  repository,
+  sha,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch is required to verify publish channel PR lineage through GitHub REST API");
+  }
+  const { owner, repo } = splitRepository(repository);
+  const apiBase = String(readEnv(env, "GITHUB_API_URL", "https://api.github.com")).replace(/\/+$/, "");
+  const url = `${apiBase}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/commits/${encodeURIComponent(sha)}/pulls`;
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "buildchain-publish-channel-verifier",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  const token = readEnv(env, "GITHUB_TOKEN");
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  const response = await fetchImpl(url, { headers });
+  if (!response?.ok) {
+    let detail = "";
+    try {
+      const body = await response.json();
+      detail = body?.message ? `: ${body.message}` : "";
+    } catch {
+      detail = "";
+    }
+    throw new Error(`publish channel PR lineage could not be read for ${sha} (GitHub API ${response?.status || "unknown"}${detail})`);
+  }
+  const body = await response.json();
+  if (!Array.isArray(body)) {
+    throw new Error("publish channel PR lineage response must be an array");
+  }
+  return body;
+}
+
+export async function verifyPublishChannelRefCli({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const sourceRef = normalizeSourceRef(readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_REF"));
+  const sourceSha = readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_SHA");
+  const targetRef = resolvePublishChannelTargetRef({
+    sourceRef,
+    targetRef: readEnv(env, "BUILDCHAIN_PUBLISH_TARGET_REF"),
+  });
+  if (!targetRef) {
+    return verifyPublishChannelRef({ sourceRef, sourceSha, targetRef });
+  }
+  const repository = readEnv(env, "BUILDCHAIN_SOURCE_REPOSITORY", readEnv(env, "GITHUB_REPOSITORY"));
+  const targetSha = readEnv(env, "BUILDCHAIN_CURRENT_TARGET_SHA")
+    || await resolvePublishSourceRefSha({
+      repository,
+      sourceRef: targetRef,
+      env,
+      fetchImpl,
+    });
+  const refResult = verifyPublishChannelRef({
+    sourceRef,
+    sourceSha,
+    targetRef,
+    targetSha,
+  });
+  if (refResult.skipped) {
+    return refResult;
+  }
+  const pullRequestsJson = readEnv(env, "BUILDCHAIN_CURRENT_TARGET_PULLS_JSON");
+  const pullRequests = pullRequestsJson
+    ? JSON.parse(pullRequestsJson)
+    : await resolveAssociatedPullRequests({
+        repository,
+        sha: sourceSha,
+        env,
+        fetchImpl,
+      });
+  const lineageResult = verifyPublishChannelPrLineage({
+    sourceRef,
+    sourceSha,
+    targetRef,
+    repository,
+    pullRequests,
+  });
+  return {
+    ...refResult,
+    prLineage: lineageResult,
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await verifyPublishChannelRefCli();
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}