@kungfu-tech/buildchain 2.14.3 → 2.14.4-alpha.0

package/packages/core/anchored-version-material.js

@@ -0,0 +1,281 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  discoverConfiguredDerivedVersionMaterial,
+  discoverConfiguredVersionStateFiles,
+  getLifecycleStage,
+  getVersionStrategy,
+  loadBuildchainConfig,
+  loadConfiguredAnchorManifest,
+  runLifecycleStage,
+} from "./buildchain-config.js";
+
+export const ANCHORED_VERSION_MATERIAL_CONTRACT =
+  "kungfu-buildchain-anchored-version-material/v1";
+
+function git(cwd, args, { buffer = false } = {}) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: buffer ? undefined : "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function sha256(content) {
+  return `sha256:${crypto.createHash("sha256").update(content).digest("hex")}`;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function normalizeTargetChannel(targetChannel, targetRef) {
+  if (targetChannel) {
+    return targetChannel;
+  }
+  if (String(targetRef || "").startsWith("release/")) {
+    return "release";
+  }
+  if (String(targetRef || "").startsWith("alpha/")) {
+    return "alpha";
+  }
+  return "";
+}
+
+function resolveLatestAlphaRef(cwd, targetRef) {
+  const match = String(targetRef || "").match(/^release\/v(\d+)\/v\1\.(\d+)$/);
+  if (!match) {
+    throw new Error(
+      `anchored derived material preflight requires release/vN/vN.M target ref, got ${targetRef || "<empty>"}`,
+    );
+  }
+  const prefix = `v${match[1]}.${match[2]}.`;
+  const tags = git(cwd, [
+    "tag",
+    "--list",
+    `${prefix}*-alpha.*`,
+    "--sort=-version:refname",
+  ])
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean);
+  if (tags.length === 0) {
+    throw new Error(
+      `anchored derived material preflight found no exact alpha tag matching ${prefix}*-alpha.*`,
+    );
+  }
+  return tags[0];
+}
+
+function gitStatus(cwd) {
+  return git(cwd, ["status", "--porcelain", "--untracked-files=all"]).trim();
+}
+
+function fileAtRef(cwd, ref, filePath) {
+  try {
+    const content = git(cwd, ["show", `${ref}:${filePath}`], { buffer: true });
+    return {
+      present: true,
+      sha256: sha256(content),
+      bytes: content.length,
+    };
+  } catch {
+    return {
+      present: false,
+      sha256: "",
+      bytes: 0,
+    };
+  }
+}
+
+function pathEvidence(cwd, ref, paths) {
+  return paths.map((filePath) => ({
+    path: filePath,
+    ...fileAtRef(cwd, ref, filePath),
+  }));
+}
+
+function readPackageVersion(cwd) {
+  const packagePath = path.join(cwd, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return "";
+  }
+  const value = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return typeof value.version === "string" ? value.version : "";
+}
+
+export function createAnchoredVersionMaterialEvidence({
+  cwd = process.cwd(),
+  targetChannel = "",
+  targetRef = "",
+  alphaRef = "",
+  releaseRef = "HEAD",
+  runLifecycle = true,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const loadedConfig = loadBuildchainConfig(resolvedCwd);
+  const versionStrategy = getVersionStrategy(loadedConfig);
+  const derivedFiles = loadedConfig
+    ? discoverConfiguredDerivedVersionMaterial(resolvedCwd, loadedConfig)
+    : [];
+  const channel = normalizeTargetChannel(targetChannel, targetRef);
+  const base = {
+    schemaVersion: 1,
+    contract: ANCHORED_VERSION_MATERIAL_CONTRACT,
+    applicable: false,
+    targetChannel: channel,
+    targetRef,
+    versionStrategy,
+  };
+  if (
+    !loadedConfig ||
+    versionStrategy.strategy !== "anchored" ||
+    versionStrategy.next !== "manual" ||
+    derivedFiles.length === 0
+  ) {
+    return {
+      ...base,
+      reason: "anchored-derived-version-material-not-configured",
+    };
+  }
+  if (channel !== "release") {
+    return {
+      ...base,
+      reason: "target-channel-is-not-release",
+    };
+  }
+
+  const initialStatus = gitStatus(resolvedCwd);
+  if (initialStatus) {
+    throw new Error(
+      `anchored derived material preflight requires a clean checkout: ${initialStatus}`,
+    );
+  }
+
+  const anchorManifest = loadConfiguredAnchorManifest(resolvedCwd, loadedConfig);
+  const version = anchorManifest?.fields?.npmVersion || readPackageVersion(resolvedCwd);
+  const lifecycleEnv = {
+    BUILDCHAIN_VERSION: version,
+    BUILDCHAIN_VERSION_STRATEGY: versionStrategy.strategy,
+    BUILDCHAIN_VERSION_NEXT: versionStrategy.next,
+    ...(anchorManifest
+      ? {
+          BUILDCHAIN_ANCHOR_MANIFEST: anchorManifest.path,
+          BUILDCHAIN_ANCHOR_MANIFEST_JSON: JSON.stringify(anchorManifest.fields),
+        }
+      : {}),
+  };
+  if (runLifecycle) {
+    const installStage = getLifecycleStage(loadedConfig, "install");
+    if (installStage) {
+      runLifecycleStage({
+        cwd: resolvedCwd,
+        loadedConfig,
+        name: "install",
+        stage: installStage,
+        env: lifecycleEnv,
+      });
+    }
+    const versionStateStage =
+      getLifecycleStage(loadedConfig, "version-state") ||
+      getLifecycleStage(loadedConfig, "version_state");
+    runLifecycleStage({
+      cwd: resolvedCwd,
+      loadedConfig,
+      name: "version-state",
+      stage: versionStateStage,
+      env: lifecycleEnv,
+    });
+    runLifecycleStage({
+      cwd: resolvedCwd,
+      loadedConfig,
+      name: "verify",
+      stage: getLifecycleStage(loadedConfig, "verify"),
+      env: lifecycleEnv,
+    });
+  }
+  const derivedStatus = gitStatus(resolvedCwd);
+  if (derivedStatus) {
+    throw new Error(
+      `anchored derived version material is stale or hand-edited; derivation changed the committed tree: ${derivedStatus}`,
+    );
+  }
+
+  const resolvedAlphaRef = alphaRef || resolveLatestAlphaRef(resolvedCwd, targetRef);
+  const versionFiles = discoverConfiguredVersionStateFiles(resolvedCwd, loadedConfig)
+    .map((file) => file.path);
+  const derivedPaths = derivedFiles.map((file) => file.path);
+  const allowedPaths = [
+    ...new Set([
+      ...versionFiles,
+      ...(anchorManifest?.path ? [anchorManifest.path] : []),
+      ...derivedPaths,
+    ]),
+  ].sort();
+  const changedPaths = git(resolvedCwd, [
+    "diff",
+    "--name-only",
+    resolvedAlphaRef,
+    releaseRef,
+    "--",
+  ])
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .sort();
+  const allowed = new Set(allowedPaths);
+  const unexpectedPaths = changedPaths.filter((filePath) => !allowed.has(filePath));
+  if (unexpectedPaths.length > 0) {
+    throw new Error(
+      `anchored release tree changed undeclared paths: ${unexpectedPaths.join(", ")}`,
+    );
+  }
+
+  const alphaCommit = git(resolvedCwd, ["rev-parse", resolvedAlphaRef]).trim();
+  const alphaTree = git(resolvedCwd, ["rev-parse", `${resolvedAlphaRef}^{tree}`]).trim();
+  const releaseCommit = git(resolvedCwd, ["rev-parse", releaseRef]).trim();
+  const releaseTree = git(resolvedCwd, ["rev-parse", `${releaseRef}^{tree}`]).trim();
+  const evidence = {
+    ...base,
+    applicable: true,
+    reason: "verified",
+    version,
+    alpha: {
+      ref: resolvedAlphaRef,
+      commit: alphaCommit,
+      tree: alphaTree,
+      material: pathEvidence(resolvedCwd, resolvedAlphaRef, allowedPaths),
+    },
+    release: {
+      ref: releaseRef,
+      commit: releaseCommit,
+      tree: releaseTree,
+      material: pathEvidence(resolvedCwd, releaseRef, allowedPaths),
+    },
+    allowedPaths,
+    versionFiles,
+    manifest: anchorManifest?.path || "",
+    derivedPaths,
+    changedPaths,
+    lifecycle: {
+      install: Boolean(getLifecycleStage(loadedConfig, "install")),
+      derivation: "version-state",
+      verification: "verify",
+    },
+  };
+  return {
+    ...evidence,
+    digest: sha256(stableJson(evidence)),
+  };
+}

package/packages/core/buildchain-config.js

@@ -220,6 +220,7 @@ export function normalizeBuildchainConfig(config) {
   }
   validateWebSurfaceConfig(normalized);
   validateInfraContractConfig(normalized);
+  validateAnchoredDerivedVersionMaterialConfig(normalized);
   return normalized;
 }
 
@@ -1087,6 +1088,42 @@ function validateInfraContractConfig(config) {
   }
 }
 
+function validateAnchoredDerivedVersionMaterialConfig(config) {
+  const derivedFiles = config.version?.derivedFiles || [];
+  if (derivedFiles.length === 0) {
+    return;
+  }
+  if (config.version.strategy !== "anchored" || config.version.next !== "manual") {
+    throw new Error(
+      "version.derived_files requires version.strategy = \"anchored\" and version.next = \"manual\"",
+    );
+  }
+  const versionState =
+    config.lifecycle?.["version-state"] ||
+    config.lifecycle?.version_state;
+  if (!versionState) {
+    throw new Error(
+      "version.derived_files requires lifecycle.version-state to regenerate declared material",
+    );
+  }
+  if (!config.lifecycle?.verify) {
+    throw new Error(
+      "version.derived_files requires lifecycle.verify to validate regenerated material",
+    );
+  }
+  const versionPaths = new Set((config.version.files || []).map((file) => file.path));
+  if (config.version.manifest) {
+    versionPaths.add(config.version.manifest);
+  }
+  for (const filePath of derivedFiles) {
+    if (versionPaths.has(filePath)) {
+      throw new Error(
+        `version.derived_files must not repeat version.files or version.manifest: ${filePath}`,
+      );
+    }
+  }
+}
+
 function validateWebSurfaceSurfaces(config) {
   const surfaces = config.surfaces || {};
   for (const [name, surface] of Object.entries(surfaces)) {
@@ -1129,6 +1166,13 @@ function normalizeVersionSection(version) {
   if (strategy === "anchored" && next !== "manual") {
     throw new Error('version.strategy = "anchored" requires version.next = "manual"');
   }
+  const derivedFiles = normalizeStringArray(
+    version.derived_files,
+    "version.derived_files",
+  ).map((filePath) => posixPath(filePath));
+  if (new Set(derivedFiles).size !== derivedFiles.length) {
+    throw new Error("version.derived_files must not contain duplicate paths");
+  }
   return {
     required: version.required === undefined ? false : Boolean(version.required),
     strategy,
@@ -1137,6 +1181,7 @@ function normalizeVersionSection(version) {
       ? undefined
       : posixPath(assertString(version.manifest, "version.manifest")),
     files: files.map((file, index) => normalizeVersionFile(file, index)),
+    derivedFiles,
   };
 }
 
@@ -1319,6 +1364,27 @@ export function discoverConfiguredVersionStateFiles(cwd = process.cwd(), loadedC
   return files;
 }
 
+export function discoverConfiguredDerivedVersionMaterial(
+  cwd = process.cwd(),
+  loadedConfig = loadBuildchainConfig(cwd),
+) {
+  const configured = loadedConfig?.config?.version?.derivedFiles || [];
+  return configured.map((filePath) => {
+    const absolutePath = path.join(cwd, filePath);
+    if (!fs.existsSync(absolutePath)) {
+      throw new Error(`Configured derived version material does not exist: ${filePath}`);
+    }
+    if (!fs.statSync(absolutePath).isFile()) {
+      throw new Error(`Configured derived version material must be a file: ${filePath}`);
+    }
+    return {
+      path: filePath,
+      filePath: absolutePath,
+      content: fs.readFileSync(absolutePath),
+    };
+  });
+}
+
 function summarizeManifestFields(content) {
   assertPlainObject(content, "version.manifest content");
   return Object.fromEntries(
@@ -1499,6 +1565,8 @@ export function validateBuildchainConfig(
       key: file.key,
       pattern: file.pattern?.source,
     })),
+    derivedVersionMaterial: discoverConfiguredDerivedVersionMaterial(cwd, loadedConfig)
+      .map((file) => ({ path: file.path })),
     lifecycleStages,
     publish: loadedConfig.config.publish,
     release: loadedConfig.config.release,

package/packages/core/buildchain-contract.js

@@ -193,6 +193,8 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-prebuild-witness-jsons",
         "release-passport-kfd-3-artifact-witness-jsons",
         "release-passport-kfd-3-artifact-verify-command",
+        "release-passport-invariant-passport-jsons",
+        "release-passport-invariant-passport-command",
         "buildchain-contract-lock-path",
         "buildchain-contract-drift-issue-mode",
         "github-release",
@@ -319,6 +321,8 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-prebuild-witness-jsons",
         "release-passport-kfd-3-artifact-witness-jsons",
         "release-passport-kfd-3-artifact-verify-command",
+        "release-passport-invariant-passport-jsons",
+        "release-passport-invariant-passport-command",
         "github-release",
         "github-release-title",
         "github-release-notes",

package/packages/core/controller-evidence.js

@@ -23,8 +23,20 @@ const CONTROLLER_SPECS = [
     workflowId: ".build",
     version: 1,
     capabilities: ["source-lock", "lifecycle-build", "lifecycle-verify", "artifact-admission"],
-    stages: ["resolve-runtime", "resolve-source", "build", "verify", "aggregate"],
-    evidence: ["platform-manifests", "build-summary", "controller-receipt"],
+    stages: [
+      "resolve-runtime",
+      "resolve-source",
+      "anchored-release-preflight",
+      "build",
+      "verify",
+      "aggregate",
+    ],
+    optionalStages: ["anchored-release-preflight"],
+    evidence: [
+      "platform-manifests",
+      "build-summary",
+      "controller-receipt",
+    ],
   },
   {
     id: "build-channel-router",
@@ -83,8 +95,22 @@ const CONTROLLER_SPECS = [
     workflowId: "release-propagation",
     version: 1,
     capabilities: ["release-propagation-plan", "downstream-lock", "pull-request-handoff"],
-    stages: ["resolve-runtime", "plan", "write-lock", "open-pr", "aggregate"],
-    optionalStages: ["open-pr"],
+    stages: [
+      "resolve-runtime",
+      "plan",
+      "write-lock",
+      "prepare-consumer",
+      "refresh-badges",
+      "verify-consumer",
+      "open-pr",
+      "aggregate",
+    ],
+    optionalStages: [
+      "prepare-consumer",
+      "refresh-badges",
+      "verify-consumer",
+      "open-pr",
+    ],
     evidence: ["propagation-plan", "propagation-lock", "controller-receipt"],
   },
 ];

package/packages/core/index.js

@@ -1,4 +1,5 @@
 export {
+  discoverConfiguredDerivedVersionMaterial,
   discoverConfiguredVersionStateFiles,
   getLifecycleStage,
   getNativeDiagnosticsProfile,
@@ -14,6 +15,11 @@ export {
   validateBuildchainConfig,
 } from "./buildchain-config.js";
 
+export {
+  ANCHORED_VERSION_MATERIAL_CONTRACT,
+  createAnchoredVersionMaterialEvidence,
+} from "./anchored-version-material.js";
+
 export {
   STABLE_CANDIDATE_LEDGER_CONTRACT,
   STABLE_CANDIDATE_STATES,

package/packages/core/release-passport-contract.js

@@ -87,6 +87,7 @@ export const RELEASE_PASSPORT_SCHEMA = {
     surfaceImpacts: { type: "array", items: OBJECT },
     packageSet: OBJECT,
     anchorManifest: OBJECT,
+    versionMaterial: OBJECT,
     trustedPublishing: OBJECT,
     transaction: OBJECT,
     surfaceTimestampPolicy: OBJECT,
@@ -111,6 +112,7 @@ const BUILDCHAIN_AGGREGATION_FIELDS = [
   "surfaceImpacts",
   "packageSet",
   "anchorManifest",
+  "versionMaterial",
   "trustedPublishing",
   "transaction",
   "surfaceTimestampPolicy",