@kungfu-tech/buildchain 2.5.5-alpha.3 → 2.5.5-alpha.5

package/docs/cli.md

@@ -276,10 +276,14 @@ platform packages with version, dist-tag, and digest evidence. Verification
 fails closed if supplied sections are internally incomplete or point to
 artifacts without matching evidence.
 
-`--impact-json` supplies the surface-aware impact ledger. When it includes
-`surfaceImpacts[]`, the verifier requires `versionImpact.final` to match the
-highest declared surface impact and copies `versionImpact` plus
-`surfaceImpacts` into `buildchain.release.json`. This lets
+`--impact-json` supplies the surface-aware impact ledger. Production release
+passports (`release/*`) and major publish-gate passports require
+`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it
+optional. When `surfaceImpacts[]` is required or supplied, the verifier requires
+each entry to include an id, impact, and rationale, and requires
+`versionImpact.final` to match the highest declared surface impact. The
+collector copies `versionImpact` plus `surfaceImpacts` into
+`buildchain.release.json`. This lets
 `buildchain explain release --for agent --json` state why a release is patch,
 minor, or major instead of relying on file-path memory.
 

package/docs/release-passport.md

@@ -106,11 +106,15 @@ dist-tag, registry, role, platform, and digest, so agents do not need to stitch
 npm facts back together from the lower-level evidence files.
 `buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the
 build and npm dist-tag evidence chain in the same passport.
-`impact.json` can be supplied with `--impact-json`; when it contains
-`surfaceImpacts[]`, verification fails closed unless `versionImpact.final`
-matches the highest surface impact. For example, KFD-2 content can remain patch
-while an additive `registry.kind` field on the machine-consumed KFD registry
-schema records a minor `kfd-registry-schema` surface impact.
+`impact.json` can be supplied with `--impact-json`. Production release
+passports (`release/*`) and major publish-gate passports require
+`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field
+optional. When `surfaceImpacts[]` is required or supplied, verification fails
+closed unless each entry has an id, impact, and rationale, and
+`versionImpact.final` matches the highest surface impact. For example, KFD-2
+content can remain patch while an additive `registry.kind` field on the
+machine-consumed KFD registry schema records a minor `kfd-registry-schema`
+surface impact.
 
 Verify a release passport:
 

package/docs/versioning.md

@@ -46,6 +46,11 @@ The release passport records this as `surfaceImpacts[]` plus
 so an agent cannot silently label a release patch when one machine surface needs
 minor review.
 
+`surfaceImpacts[]` is mandatory for production release passports (`release/*`)
+and major publish-gate passports. Alpha, local, and legacy passport contexts
+keep the field optional so temporary validation can proceed without pretending
+to be a production release decision.
+
 Example: a KFD document such as KFD-2 is content and remains patch, but adding a
 `kind` field to the machine-consumed KFD `registry.json` is an additive change
 to the `kfd-registry-schema` surface and therefore requires minor-impact

package/package.json

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

package/packages/core/release-passport.js

@@ -59,6 +59,43 @@ function highestImpactLevel(levels = []) {
   return highest;
 }
 
+function surfaceImpactRequirement({ passport = {}, impact = {} } = {}) {
+  const release = passport?.release && typeof passport.release === "object" ? passport.release : {};
+  const impactRelease = impact?.release && typeof impact.release === "object" ? impact.release : {};
+  const channel = optionalString(release.channel || impactRelease.channel).toLowerCase();
+  const targetRef = optionalString(
+    release.targetRef ||
+    release.target_ref ||
+    impactRelease.targetRef ||
+    impactRelease.target_ref,
+  ).toLowerCase();
+  if (channel === "release" || targetRef.startsWith("release/")) {
+    return {
+      required: true,
+      type: "production-release",
+      reason: "production release passports require surfaceImpacts[] so agents can audit the final version impact",
+      channel,
+      targetRef,
+    };
+  }
+  if (channel === "major" || targetRef === "publish-gate/major" || targetRef === "major-gate") {
+    return {
+      required: true,
+      type: "major-gate",
+      reason: "major publish gates require surfaceImpacts[] so breaking-surface rationale is explicit",
+      channel,
+      targetRef,
+    };
+  }
+  return {
+    required: false,
+    type: channel || (targetRef ? "non-production-release" : "legacy"),
+    reason: "surfaceImpacts[] is optional for alpha, local, and legacy passport contexts",
+    channel,
+    targetRef,
+  };
+}
+
 function stableJson(value) {
   if (Array.isArray(value)) {
     return `[${value.map(stableJson).join(",")}]`;
@@ -1132,6 +1169,10 @@ export function createReleaseCheckReport({
   const passportSurfaceImpacts = Array.isArray(passport?.surfaceImpacts) ? passport.surfaceImpacts : [];
   const declaredFinalImpact = normalizeImpactLevel(impact?.versionImpact?.final || impact?.classification);
   const computedFinalImpact = highestImpactLevel(surfaceImpacts.map((entry) => entry.impact));
+  const requiredSurfaceImpacts = surfaceImpactRequirement({ passport, impact });
+  if (requiredSurfaceImpacts.required && surfaceImpacts.length === 0) {
+    issues.push(issue("error", "impact.surfaceImpacts.required", "surfaceImpacts[] is required for this release passport type", requiredSurfaceImpacts));
+  }
   if (surfaceImpacts.length > 0) {
     for (const [index, entry] of surfaceImpacts.entries()) {
       if (!entry.id) {
@@ -1167,6 +1208,7 @@ export function createReleaseCheckReport({
     checkedAt,
     ok,
     trust: ok ? "pass" : "fail",
+    surfaceImpactRequirement: requiredSurfaceImpacts,
     completeness: {
       artifactCount: artifacts.length,
       evidenceArtifactCount: evidenceArtifacts.length,
@@ -1182,6 +1224,7 @@ export function createReleaseCheckReport({
       impactPresent: Boolean(impact),
       agentIndexPresent: Boolean(agentIndex),
       productMechanismPresent: Boolean(productMechanism),
+      surfaceImpactsRequired: requiredSurfaceImpacts.required,
       surfaceImpactCount: surfaceImpacts.length,
       versionImpact: impact?.versionImpact?.final || "",
     },
@@ -1278,6 +1321,7 @@ export async function explainReleasePassport({ passportLocation, forAudience = "
     impact: {
       versionImpact: passport.versionImpact || {},
       surfaceImpacts: Array.isArray(passport.surfaceImpacts) ? passport.surfaceImpacts : [],
+      surfaceImpactRequirement: report.surfaceImpactRequirement,
       breaking: Boolean(passport.versionImpact?.final === "major"),
       migrationRequired: Boolean(passport.versionImpact?.final === "major"),
       summary: passport.versionImpact?.rationale || "",

package/scripts/release-candidate-resolver.mjs

@@ -91,7 +91,7 @@ export function selectMergedChannelPullRequest({ pullRequests = [], targetRef, r
   return candidates[0];
 }
 
-export function selectReleaseCandidateRun({ runs = [], pullRequest, workflowName = "" }) {
+export function selectReleaseCandidateRuns({ runs = [], pullRequest, workflowName = "" }) {
   const prNumber = Number(pullRequest?.number || 0);
   const prHeadSha = String(pullRequest?.head?.sha || pullRequest?.headRefOid || "").trim();
   const prHeadBranch = normalizeBranch(pullRequest?.head?.ref || pullRequest?.headRefName || "");
@@ -111,7 +111,11 @@ export function selectReleaseCandidateRun({ runs = [], pullRequest, workflowName
     return matchesPr && matchesWorkflow && run.event === "pull_request" && run.status === "completed" && run.conclusion === "success";
   });
   candidates.sort((left, right) => Date.parse(right.updated_at || right.created_at || "") - Date.parse(left.updated_at || left.created_at || ""));
-  return candidates[0];
+  return candidates;
+}
+
+export function selectReleaseCandidateRun({ runs = [], pullRequest, workflowName = "" }) {
+  return selectReleaseCandidateRuns({ runs, pullRequest, workflowName })[0];
 }
 
 function outputPath(filePath) {
@@ -375,24 +379,40 @@ export async function resolveReleaseCandidateArtifacts({
     fetchImpl,
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${encodeURIComponent(workflowFile)}/runs?event=pull_request&status=success&per_page=100`,
   });
-  const run = selectReleaseCandidateRun({
+  const candidateRuns = selectReleaseCandidateRuns({
     runs: Array.isArray(runs.workflow_runs) ? runs.workflow_runs : [],
     pullRequest,
     workflowName,
   });
-  if (!run) {
+  if (!candidateRuns.length) {
     throw new Error(`no successful ${workflowName} pull_request run found for channel PR #${pullRequest.number}`);
   }
-  const artifactResponse = await githubJson({
-    apiUrl,
-    token,
-    fetchImpl,
-    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${run.id}/artifacts?per_page=100`,
-  });
-  const selected = selectReleaseCandidateArtifacts({
-    artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
-    artifactName,
-  });
+  let run;
+  let artifactResponse;
+  let selected;
+  const selectionErrors = [];
+  for (const candidateRun of candidateRuns) {
+    const candidateArtifactResponse = await githubJson({
+      apiUrl,
+      token,
+      fetchImpl,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${candidateRun.id}/artifacts?per_page=100`,
+    });
+    try {
+      selected = selectReleaseCandidateArtifacts({
+        artifacts: Array.isArray(candidateArtifactResponse.artifacts) ? candidateArtifactResponse.artifacts : [],
+        artifactName,
+      });
+      run = candidateRun;
+      artifactResponse = candidateArtifactResponse;
+      break;
+    } catch (error) {
+      selectionErrors.push(`run ${candidateRun.id}: ${error.message}`);
+    }
+  }
+  if (!run || !artifactResponse || !selected) {
+    throw new Error(`no successful ${workflowName} pull_request run for channel PR #${pullRequest.number} contained release-candidate artifacts: ${selectionErrors.join("; ")}`);
+  }
   const payloadArtifacts = selectPayloadArtifacts({
     artifacts: Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [],
     artifactName: selected.prefix,