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

package/bin/buildchain.mjs

@@ -67,6 +67,7 @@ function usage() {
                                     [--trusted-publishing-json <json-or-path>]
                                     [--transaction-json <json-or-path>]
                                     [--anchor-manifest-json <json-or-path>]
+                                    [--impact-json <json-or-path>]
                                     [--build-summary-json <json-or-path>]
                                     [--platform-manifest-json <json-or-path>]...
                                     [--dist-tag-evidence-json <json-or-path>]
@@ -716,6 +717,7 @@ async function main(argv = process.argv.slice(2)) {
       trustedPublishingJson: readFlag(collectArgs, "trusted-publishing-json", ""),
       transactionJson: readFlag(collectArgs, "transaction-json", ""),
       anchorManifestJson: readFlag(collectArgs, "anchor-manifest-json", ""),
+      impactJson: readFlag(collectArgs, "impact-json", ""),
       buildSummaryJson: readFlag(collectArgs, "build-summary-json", ""),
       platformManifestJsons: readRepeatedFlag(collectArgs, "platform-manifest-json"),
       distTagEvidenceJson: readFlag(collectArgs, "dist-tag-evidence-json", ""),

package/docs/cli.md

@@ -252,6 +252,7 @@ buildchain collect github-release \
   --publish-evidence-json .buildchain/release-evidence/v2.3.2/evidence.json \
   --transaction-json .buildchain/release-state/v2.3.2/state.json \
   --package-set-json package-set.json \
+  --impact-json impact.json \
   --trusted-publishing-json trusted-publishing.json \
   --anchor-manifest-json libnode.release.json \
   --build-summary-json .buildchain/artifacts/build-summary.json \
@@ -275,6 +276,13 @@ 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
+`buildchain explain release --for agent --json` state why a release is patch,
+minor, or major instead of relying on file-path memory.
+
 Buildchain dogfoods its observability toolkit in this lane. The standalone
 builder writes API-generated events, while the workflow uses `buildchain mark`,
 `buildchain span`, `buildchain verify observability-log`, and `buildchain log

package/docs/release-passport.md

@@ -36,6 +36,10 @@ Additive passport sections:
 
 - `release`: exact tag, line, channel, source SHA, target ref, release SHA,
   release material SHA, publish tooling SHA, and durable release-state ref.
+- `versionImpact`: final patch/minor/major classification, source, and
+  rationale.
+- `surfaceImpacts`: per registered surface classification. The final impact is
+  the highest entry in this list.
 - `packageSet`: main package, platform packages, package-set order, registry,
   versions, dist-tags, and package digests.
 - `anchorManifest`: anchored/manual version manifest path, digest, and fields.
@@ -102,6 +106,11 @@ 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.
 
 Verify a release passport:
 

package/docs/versioning.md

@@ -20,7 +20,8 @@ latest stable production patch for that minor line.
 
 ## Welded Surfaces
 
-These surfaces require at least a minor bump when first introduced:
+These surfaces are classified independently; the final release impact is the
+highest impact across the affected registered surfaces:
 
 - reusable workflow inputs, outputs, and artifact contracts;
 - public CLI command families and their machine-readable JSON shapes;
@@ -31,20 +32,35 @@ These surfaces require at least a minor bump when first introduced:
   ledger, and agent index files;
 - binary distribution shapes that users can install or automate against.
 
-Additive fields inside an existing welded surface can be patch releases when
-old consumers continue to work and validation remains stricter, not looser.
-Removing fields, changing meanings, weakening trust gates, or changing the
-expected ref flow requires a major bump.
+For each surface:
+
+- content, documentation, or implementation-only work that does not touch a
+  registered surface is patch;
+- additive fields, new commands, new exports, new evidence sections, or new
+  registered surfaces are minor;
+- removals, incompatible renames, changed meanings, newly required fields,
+  weakened trust gates, or changed ref flow are major.
+
+The release passport records this as `surfaceImpacts[]` plus
+`versionImpact.final`. The final impact must equal the highest surface impact,
+so an agent cannot silently label a release patch when one machine surface needs
+minor review.
+
+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
+review. This avoids both false shortcuts: "new KFD means minor" and "all KFD
+repository changes are patch".
 
 ## Decision Log
 
-| Date | Decision | Line | Reason |
-| --- | --- | --- | --- |
-| 2026-07-02 | Buildchain toolkit observability is a minor surface. | `v2.1` | It adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. |
-| 2026-07-02 | Release passport and binary distribution are a minor surface. | `v2.2` | They add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. |
-| 2026-07-02 | Web surface host mapping is a minor surface. | `v2.3` | It adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. |
-| 2026-07-03 | Infra contract lifecycle is a minor surface. | `v2.4` | It adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. |
-| 2026-07-04 | Scheduled integration governance is a minor surface. | `v2.5` | It adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. |
+| Date | Action | Line | Faces | Class | Rationale | PR |
+| --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |
+| 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |
+| 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |
+| 2026-07-02 | open-minor | `v2.2` | release-passport, binary-distribution | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. | |
+| 2026-07-02 | open-minor | `v2.1` | logging-sdk, cli-observability, package-subpaths | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. | |
 
 ## Runner Policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.5.5-alpha.2",
+  "version": "2.5.5-alpha.3",
   "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

@@ -36,6 +36,29 @@ function optionalString(value) {
   return value === undefined || value === null ? "" : String(value);
 }
 
+const VERSION_IMPACT_ORDER = new Map([
+  ["unknown", 0],
+  ["patch", 1],
+  ["minor", 2],
+  ["major", 3],
+]);
+
+function normalizeImpactLevel(value, fallback = "unknown") {
+  const normalized = optionalString(value || fallback).toLowerCase();
+  return VERSION_IMPACT_ORDER.has(normalized) ? normalized : optionalString(value || fallback);
+}
+
+function highestImpactLevel(levels = []) {
+  let highest = "unknown";
+  for (const level of levels) {
+    const normalized = normalizeImpactLevel(level);
+    if ((VERSION_IMPACT_ORDER.get(normalized) ?? -1) > (VERSION_IMPACT_ORDER.get(highest) ?? -1)) {
+      highest = normalized;
+    }
+  }
+  return highest;
+}
+
 function stableJson(value) {
   if (Array.isArray(value)) {
     return `[${value.map(stableJson).join(",")}]`;
@@ -123,14 +146,21 @@ function defaultProductMechanism({ repository = "", productName = "Buildchain" }
 }
 
 function defaultImpact({ tag = "", line = "", decision = "unknown" } = {}) {
+  const finalImpact = normalizeImpactLevel(decision);
   return {
     schemaVersion: 1,
     contract: IMPACT_LEDGER_CONTRACT,
     release: { tag, line },
-    classification: decision,
-    breaking: false,
+    versionImpact: {
+      final: finalImpact,
+      source: "default",
+      rationale: "No surface impact classification was supplied.",
+    },
+    surfaceImpacts: [],
+    classification: finalImpact,
+    breaking: finalImpact === "major",
     security: false,
-    migrationRequired: false,
+    migrationRequired: finalImpact === "major",
     summary: "No release impact summary was supplied.",
     recovery: {
       rollback: "Use the previous exact release tag or previous floating channel ref.",
@@ -339,6 +369,55 @@ function normalizePublishEvidence(value = undefined) {
   };
 }
 
+function normalizeSurfaceImpact(entry = {}, index = 0) {
+  const id = nonEmptyString(entry.id || entry.surface || entry.surfaceId, `surfaceImpacts[${index}].id`);
+  const impact = normalizeImpactLevel(entry.impact || entry.classification || entry.versionImpact);
+  return {
+    id,
+    impact,
+    class: optionalString(entry.class || entry.changeClass || entry.change_class),
+    rationale: optionalString(entry.rationale || entry.reason),
+    source: optionalString(entry.source),
+  };
+}
+
+function normalizeImpactLedger(value = undefined, { tag = "", line = "", decision = "unknown" } = {}) {
+  if (!value) {
+    return defaultImpact({ tag, line, decision });
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("impact must be a JSON object");
+  }
+  const surfaceImpacts = Array.isArray(value.surfaceImpacts)
+    ? value.surfaceImpacts.map((entry, index) => normalizeSurfaceImpact(entry, index))
+    : [];
+  const finalImpact = normalizeImpactLevel(
+    value.versionImpact?.final ||
+    value.versionImpact ||
+    value.classification ||
+    decision,
+  );
+  return {
+    ...value,
+    schemaVersion: Number(value.schemaVersion || 1),
+    contract: value.contract || IMPACT_LEDGER_CONTRACT,
+    release: {
+      tag: optionalString(value.release?.tag || tag),
+      line: optionalString(value.release?.line || line),
+      ...(value.release && typeof value.release === "object" && !Array.isArray(value.release) ? value.release : {}),
+    },
+    versionImpact: {
+      final: finalImpact,
+      source: optionalString(value.versionImpact?.source || value.impactSource || "declared"),
+      rationale: optionalString(value.versionImpact?.rationale || value.rationale || value.summary),
+    },
+    surfaceImpacts,
+    classification: normalizeImpactLevel(value.classification || finalImpact),
+    breaking: value.breaking === undefined ? finalImpact === "major" : Boolean(value.breaking),
+    migrationRequired: value.migrationRequired === undefined ? finalImpact === "major" : Boolean(value.migrationRequired),
+  };
+}
+
 function packageSetEntries(packageSet = undefined) {
   if (!packageSet) {
     return [];
@@ -503,6 +582,7 @@ export function createReleasePassport({
   distTagPromotionEvidence = undefined,
   release = {},
   publish = {},
+  impact = undefined,
   workflow = {},
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
@@ -518,6 +598,7 @@ export function createReleasePassport({
   const normalizedDistTagPromotionEvidence = distTagPromotionEvidence
     ? normalizeEvidenceDocument(distTagPromotionEvidence, "distTagPromotionEvidence")
     : undefined;
+  const normalizedImpact = normalizeImpactLedger(impact, { tag: normalizedTag, line });
   const publishArtifacts = normalizedPublishEvidence?.artifacts || [];
   const normalizedPublishSummary = normalizePublishSummary({
     packageSet: normalizedPackageSet,
@@ -618,6 +699,8 @@ export function createReleasePassport({
     ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
     ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),
     ...(normalizedDistTagPromotionEvidence ? { distTagPromotion: normalizedDistTagPromotionEvidence } : {}),
+    versionImpact: normalizedImpact.versionImpact,
+    surfaceImpacts: normalizedImpact.surfaceImpacts,
     artifacts: [
       ...artifactEvidence.artifacts.map((asset) => ({
         group: "release",
@@ -680,6 +763,7 @@ export function collectGitHubReleasePassport({
   trustedPublishingJson = "",
   transactionJson = "",
   anchorManifestJson = "",
+  impactJson = "",
   buildSummaryJson = "",
   platformManifestJsons = [],
   distTagEvidenceJson = "",
@@ -695,6 +779,7 @@ export function collectGitHubReleasePassport({
   const trustedPublishing = parseJsonInput(trustedPublishingJson, undefined);
   const transactionMeta = parseJsonInputWithMeta(transactionJson, undefined);
   const anchorManifest = normalizeAnchorManifest(parseJsonInputWithMeta(anchorManifestJson, undefined));
+  const impactMeta = parseJsonInputWithMeta(impactJson, undefined);
   const buildSummaryMeta = parseJsonInputWithMeta(buildSummaryJson, undefined);
   const platformManifestMetas = (platformManifestJsons || [])
     .filter(Boolean)
@@ -710,7 +795,7 @@ export function collectGitHubReleasePassport({
   const resolvedOutputDir = path.resolve(cwd, outputDir);
   const productMechanism = defaultProductMechanism({ repository, productName });
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: resolvedTag, sourceSha, workflow });
-  const impact = defaultImpact({ tag: resolvedTag, line, decision: "unknown" });
+  const impact = normalizeImpactLedger(impactMeta.value, { tag: resolvedTag, line, decision: "unknown" });
   const agentIndex = defaultAgentIndex({ tag: resolvedTag });
   const passport = createReleasePassport({
     cwd,
@@ -747,6 +832,7 @@ export function collectGitHubReleasePassport({
       : undefined,
     release: releaseExtra,
     publish,
+    impact,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
@@ -1042,6 +1128,38 @@ export function createReleaseCheckReport({
   if (!passport?.runnerPolicy?.productionDefault) {
     issues.push(issue("warning", "runnerPolicy.productionDefault", "runner policy should record the production default"));
   }
+  const surfaceImpacts = Array.isArray(impact?.surfaceImpacts) ? impact.surfaceImpacts : [];
+  const passportSurfaceImpacts = Array.isArray(passport?.surfaceImpacts) ? passport.surfaceImpacts : [];
+  const declaredFinalImpact = normalizeImpactLevel(impact?.versionImpact?.final || impact?.classification);
+  const computedFinalImpact = highestImpactLevel(surfaceImpacts.map((entry) => entry.impact));
+  if (surfaceImpacts.length > 0) {
+    for (const [index, entry] of surfaceImpacts.entries()) {
+      if (!entry.id) {
+        issues.push(issue("error", `impact.surfaceImpacts[${index}].id`, "surface impact id is required"));
+      }
+      if (!VERSION_IMPACT_ORDER.has(entry.impact)) {
+        issues.push(issue("error", `impact.surfaceImpacts[${index}].impact`, "surface impact must be patch, minor, or major"));
+      }
+      if (!entry.rationale) {
+        issues.push(issue("error", `impact.surfaceImpacts[${index}].rationale`, "surface impact rationale is required"));
+      }
+    }
+    if (!impact?.versionImpact?.rationale) {
+      issues.push(issue("error", "impact.versionImpact.rationale", "version impact rationale is required when surface impacts are supplied"));
+    }
+    if (declaredFinalImpact !== computedFinalImpact) {
+      issues.push(issue("error", "impact.versionImpact.final", "versionImpact.final must equal the highest surface impact", {
+        declared: declaredFinalImpact,
+        computed: computedFinalImpact,
+      }));
+    }
+    if (stableJson(passportSurfaceImpacts) !== stableJson(surfaceImpacts)) {
+      issues.push(issue("error", "passport.surfaceImpacts", "passport.surfaceImpacts must mirror impact.surfaceImpacts"));
+    }
+  }
+  if (passport?.versionImpact?.final && impact?.versionImpact?.final && passport.versionImpact.final !== impact.versionImpact.final) {
+    issues.push(issue("error", "passport.versionImpact.final", "passport.versionImpact.final must match impact.versionImpact.final"));
+  }
   const ok = issues.every((entry) => entry.level !== "error");
   return {
     schemaVersion: 1,
@@ -1064,6 +1182,8 @@ export function createReleaseCheckReport({
       impactPresent: Boolean(impact),
       agentIndexPresent: Boolean(agentIndex),
       productMechanismPresent: Boolean(productMechanism),
+      surfaceImpactCount: surfaceImpacts.length,
+      versionImpact: impact?.versionImpact?.final || "",
     },
     issues,
   };
@@ -1156,8 +1276,11 @@ export async function explainReleasePassport({ passportLocation, forAudience = "
     artifactCount: report.completeness.artifactCount,
     runnerPolicy: passport.runnerPolicy,
     impact: {
-      breaking: false,
-      migrationRequired: false,
+      versionImpact: passport.versionImpact || {},
+      surfaceImpacts: Array.isArray(passport.surfaceImpacts) ? passport.surfaceImpacts : [],
+      breaking: Boolean(passport.versionImpact?.final === "major"),
+      migrationRequired: Boolean(passport.versionImpact?.final === "major"),
+      summary: passport.versionImpact?.rationale || "",
     },
     recovery: passport.recovery,
     nextAction,

package/scripts/check-inventory.mjs

@@ -130,7 +130,9 @@ if (!coreIndexSource.includes("reportBuildchainIssue")) {
   throw new Error("packages/core/index.js must export reportBuildchainIssue");
 }
 for (const requiredSnippet of [
-  "Release passport and binary distribution are a minor surface.",
+  "surfaceImpacts[]",
+  "versionImpact.final",
+  "kfd-registry-schema",
   "`v2.2`",
   "GitHub-hosted runners for production",
   "Self-hosted runners remain compatibility fixtures",