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

package/README.md

@@ -150,6 +150,9 @@ The active reusable workflow surfaces are:
 
 - `.github/workflows/.build.yml` for deterministic multi-platform build and
   artifact contracts;
+- `.github/workflows/release-candidate-promote.yml` for post-merge
+  promote-only publication from a PR-stage release candidate, without a second
+  heavy build;
 - `.github/workflows/.web-surface.yml` for preview, staging, production, and
   cleanup plans for site/app repositories;
 - `.github/workflows/buildchain-ref-promotion.yml` for protected release
@@ -168,6 +171,10 @@ uses: kungfu-systems/buildchain/actions/validate-config@v2
 uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
 ```
 
+```yaml
+uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
+```
+
 ## Release Model
 
 Buildchain treats a reviewed branch merge as release intent:

package/docs/reusable-build-surface.md

@@ -359,6 +359,45 @@ 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.
 
+## Release Candidate Promote-Only
+
+For native package sets, the PR build is the only heavy build. When a PR targets
+`alpha/<line>` or `release/<line>`, `.build.yml` uploads a release-candidate
+bundle next to the platform artifacts. The bundle contains:
+
+- `release-candidate.passport.json`;
+- the aggregate `build-summary.json`;
+- copied platform manifest evidence for the built platforms.
+
+The passport records two separate source identities:
+
+- `builtSourceSha` / `builtSourceTreeSha`: the PR-stage source that produced the
+  artifacts, usually the PR merge ref;
+- `promotionChannelSha` / `promotionChannelTreeSha`: the post-merge channel
+  commit used for publish authority.
+
+The reusable promote wrapper resolves the merged PR, finds exactly one matching
+PR-stage release-candidate artifact, downloads it, compares the built tree with
+the promotion channel tree, locks `publish-gate/{alpha,release,major}` to the
+promotion channel commit, and then calls `actions/promote-buildchain-ref` with
+`promote-only-release-candidate: "true"`. It does not call `.build.yml`, does
+not create a matrix, and must fail before publish if the RC evidence is missing
+or ambiguous.
+
+```yaml
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
+    with:
+      channel: alpha
+      target-ref: alpha/v22/v22.22
+      artifact-name: libnode
+      package-manager: npm
+      publish-target: npm
+      runner-preset: github-hosted
+      trusted-publishing: true
+```
+
 Custom publish jobs can also repeat the channel-ref preflight:
 
 ```yaml

package/package.json

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

package/packages/core/release-candidate.js

@@ -80,6 +80,26 @@ function normalizePlatformEntry(platform = {}, index = 0) {
   };
 }
 
+function inferVersionFromReleaseManifest(buildSummary = {}) {
+  const raw = buildSummary.publishSource?.releaseManifest || "";
+  if (!raw) {
+    return "";
+  }
+  try {
+    const manifest = JSON.parse(raw);
+    const versions = [
+      ...new Set(
+        (manifest.versionFiles || [])
+          .map((file) => optionalString(file.version).trim())
+          .filter(Boolean),
+      ),
+    ];
+    return versions.length === 1 ? versions[0] : "";
+  } catch {
+    return "";
+  }
+}
+
 export function createReleaseCandidatePassport({
   repository = "",
   pullRequest = {},
@@ -96,10 +116,12 @@ export function createReleaseCandidatePassport({
 } = {}) {
   const normalizedSummary = buildSummary && typeof buildSummary === "object" ? buildSummary : {};
   const sourceSha = sourceHeadSha || normalizedSummary.publishSource?.sha || normalizedSummary.git?.sha || "";
+  const resolvedTreeHash = optionalString(sourceTreeHash || normalizedSummary.git?.treeSha);
   const channel = normalizeTargetChannel(targetChannel)
     || normalizeTargetChannel(normalizedSummary.publishSource?.channel)
     || normalizeTargetChannel(normalizedSummary.publishGate?.channel)
     || normalizeTargetChannel(pullRequest.baseRef);
+  const resolvedVersion = version || normalizedSummary.publishSource?.consumerVersion || inferVersionFromReleaseManifest(normalizedSummary);
   const candidate = {
     schemaVersion: 1,
     contract: RELEASE_CANDIDATE_PASSPORT_CONTRACT,
@@ -114,13 +136,15 @@ export function createReleaseCandidatePassport({
     target: {
       channel: nonEmptyString(channel, "targetChannel"),
       ref: optionalString(normalizedSummary.publishSource?.ref || normalizedSummary.git?.ref),
-      version: nonEmptyString(version || normalizedSummary.publishSource?.consumerVersion, "version"),
+      version: nonEmptyString(resolvedVersion, "version"),
     },
     source: {
       headSha: nonEmptyString(sourceSha, "sourceHeadSha"),
       baseSha: optionalString(baseSha),
       mergeRefSha: optionalString(mergeRefSha || sourceSha),
-      treeHash: optionalString(sourceTreeHash || normalizedSummary.git?.treeSha),
+      treeHash: resolvedTreeHash,
+      builtSourceSha: nonEmptyString(mergeRefSha || sourceSha, "builtSourceSha"),
+      builtSourceTreeSha: resolvedTreeHash,
     },
     buildchain: {
       ref: optionalString(buildchain.ref || normalizedSummary.runtime?.ref),

package/packages/core/release-passport.js

@@ -576,6 +576,11 @@ export function createReleasePassport({
       targetRef,
       releaseSha,
       releaseMaterialSha,
+      builtSourceSha: optionalString(release.builtSourceSha || release.built_source_sha),
+      builtSourceTreeSha: optionalString(release.builtSourceTreeSha || release.built_source_tree_sha),
+      promotionChannelSha: optionalString(release.promotionChannelSha || release.promotion_channel_sha),
+      promotionChannelTreeSha: optionalString(release.promotionChannelTreeSha || release.promotion_channel_tree_sha),
+      treeEquivalent: release.treeEquivalent === undefined ? undefined : Boolean(release.treeEquivalent),
       publishToolingSha: optionalString(
         release.publishToolingSha ||
         release.publish_tooling_sha ||

package/scripts/check-inventory.mjs

@@ -28,8 +28,11 @@ const requiredPaths = [
   "scripts/build-standalone-binary.mjs",
   "scripts/create-release-bundle.mjs",
   "scripts/generate-site-bundle.mjs",
+  "scripts/generate-release-candidate-passport.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
+  "scripts/release-candidate-resolver.mjs",
+  "scripts/workflow-friction-report.mjs",
   "docs/migration-inventory.md",
   "docs/lifecycle-protocol.md",
   "docs/ownership.md",
@@ -38,6 +41,7 @@ const requiredPaths = [
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/npm-publish.yml",
   ".github/workflows/binary-distribution.yml",
   ".github/workflows/verify.yml",

package/scripts/generate-release-candidate-passport.mjs

@@ -23,7 +23,7 @@ export function generateReleaseCandidatePassportCli() {
   const sourceSha = env("BUILDCHAIN_RC_SOURCE_HEAD_SHA", buildSummary.publishSource?.sha || buildSummary.git?.sha || "");
   const version = env(
     "BUILDCHAIN_RC_VERSION",
-    buildSummary.publishSource?.consumerVersion || `source-${String(sourceSha).slice(0, 12)}`,
+    buildSummary.publishSource?.consumerVersion || "",
   );
   const passport = createReleaseCandidatePassport({
     repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),

package/scripts/release-candidate-resolver.mjs

@@ -294,6 +294,7 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "release-candidate-passport-path": result.paths?.passport || "",
     "release-candidate-build-summary-path": result.paths?.buildSummary || "",
     "release-candidate-version": result.version || "",
+    "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",
     "release-candidate-build-summary-artifact": result.artifacts?.summary || "",
     "release-candidate-run-id": result.run?.id || "",