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

package/packages/core/release-passport.js

@@ -26,6 +26,7 @@ export const PRODUCT_MECHANISM_CONTRACT = "kungfu-buildchain-product-mechanism";
 export const RELEASE_CHECK_REPORT_CONTRACT = "kungfu-buildchain-release-check-report";
 export const KFD2_RELEASE_TRUST_PASSPORT_CONTRACT = "kungfu-buildchain-kfd-2-release-trust-passport-audit";
 export const KFD2_TRUST_PROOF_CONTRACT = "kungfu-buildchain-kfd-2-trust-proof";
+export const INVARIANT_PASSPORT_GATE_CONTRACT = "buildchain.invariant-passport-gate/v1";
 
 const CONTRACTS = new Set([
   RELEASE_PASSPORT_CONTRACT,
@@ -128,6 +129,80 @@ export function sha256Text(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
 
+function invariantSemanticPreimage(passport) {
+  const value = structuredClone(passport);
+  delete value.passportRoot;
+  delete value.observedAt;
+  return value;
+}
+
+function normalizeInvariantPassport(meta, index = 0) {
+  const value = meta?.value;
+  const label = `invariantPassportJsons[${index}]`;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  for (const field of ["schema", "product", "canonicalization", "passportRoot", "contractRoot", "registryRoot", "verdict"]) {
+    nonEmptyString(value[field], `${label}.${field}`);
+  }
+  if (value.canonicalization !== "stable-json-sha256-v1") {
+    throw new Error(`${label}.canonicalization must be stable-json-sha256-v1`);
+  }
+  if (!/^sha256:[0-9a-f]{64}$/.test(value.passportRoot)) {
+    throw new Error(`${label}.passportRoot must be sha256:<64-lowercase-hex>`);
+  }
+  const expectedRoot = `sha256:${sha256Text(stableJson(invariantSemanticPreimage(value)))}`;
+  if (value.passportRoot !== expectedRoot) {
+    throw new Error(`${label}.passportRoot mismatch: expected ${expectedRoot}, got ${value.passportRoot}`);
+  }
+  if (value.verdict !== "verified") {
+    throw new Error(`${label}.verdict must be verified, got ${value.verdict}`);
+  }
+  if (value.coverage?.complete !== true) {
+    throw new Error(`${label}.coverage.complete must be true`);
+  }
+  if (value.source?.dirty !== false) {
+    throw new Error(`${label}.source.dirty must be false`);
+  }
+  if (!/^[0-9a-f]{40}$/.test(optionalString(value.source?.revision))) {
+    throw new Error(`${label}.source.revision must be an exact 40-hex revision`);
+  }
+  const platforms = Array.isArray(value.coverage?.platforms)
+    ? [...new Set(value.coverage.platforms.map(String))].sort()
+    : [];
+  if (platforms.length === 0) throw new Error(`${label}.coverage.platforms must be non-empty`);
+  if (!Array.isArray(value.residualRisk)) throw new Error(`${label}.residualRisk must be an array`);
+  return {
+    path: optionalString(meta.path),
+    sha256: optionalString(meta.sha256),
+    schema: value.schema,
+    product: value.product,
+    passportRoot: value.passportRoot,
+    contractRoot: value.contractRoot,
+    registryRoot: value.registryRoot,
+    verdict: value.verdict,
+    source: structuredClone(value.source),
+    coverage: structuredClone(value.coverage),
+    platforms,
+    residualRisk: structuredClone(value.residualRisk),
+  };
+}
+
+export function createInvariantPassportGate(passportMetas = []) {
+  const passports = passportMetas.filter((meta) => meta?.value).map(normalizeInvariantPassport);
+  if (passports.length === 0) return undefined;
+  return {
+    contract: INVARIANT_PASSPORT_GATE_CONTRACT,
+    result: "passed",
+    passports,
+    responsibility: {
+      invariantSemanticsOwner: "consumer",
+      passportVerificationOwner: "consumer",
+      releaseAdmissionOwner: "Buildchain",
+    },
+  };
+}
+
 export function sha256File(filePath) {
   return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
 }
@@ -411,7 +486,12 @@ function parseJsonCommandOutput({ command = "", cwd = process.cwd(), label = "co
   if (!stdout) {
     throw new Error(`${label} produced no JSON on stdout`);
   }
-  const parsed = JSON.parse(stdout);
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`${label} output must be valid JSON: ${error.message}`, { cause: error });
+  }
   return {
     value: parsed,
     path: "",
@@ -1016,6 +1096,7 @@ export function createReleasePassport({
   assets = [],
   packageSet = undefined,
   anchorManifest = undefined,
+  versionMaterial = undefined,
   publishEvidence = undefined,
   trustedPublishing = undefined,
   transaction = undefined,
@@ -1030,6 +1111,7 @@ export function createReleasePassport({
   kfd1 = undefined,
   kfd2Claims = [],
   kfd3 = undefined,
+  invariantPassports = undefined,
   controllerReceipts = [],
   controllerReceiptReferences = [],
 } = {}) {
@@ -1186,6 +1268,7 @@ export function createReleasePassport({
     ...(normalizedPackageSet ? { packageSet: normalizedPackageSet } : {}),
     ...(normalizedPublishSummary ? { publish: normalizedPublishSummary } : {}),
     ...(anchorManifest ? { anchorManifest } : {}),
+    ...(versionMaterial ? { versionMaterial } : {}),
     ...(normalizedTrustedPublishing ? { trustedPublishing: normalizedTrustedPublishing } : {}),
     ...(normalizedTransaction ? { transaction: normalizedTransaction } : {}),
     ...(normalizedPromotionRouting ? { promotionRouting: normalizedPromotionRouting } : {}),
@@ -1196,6 +1279,7 @@ export function createReleasePassport({
     ...(normalizedKfd1 ? { [normalizedKfd1.key || kfd1Metadata.key]: normalizedKfd1.passportSection } : {}),
     ...(normalizedKfd2 ? { "kfd-2": normalizedKfd2 } : {}),
     ...(normalizedKfd3 ? { [normalizedKfd3.key || "kfd-3"]: normalizedKfd3.passportSection } : {}),
+    ...(invariantPassports ? { invariantPassports } : {}),
     ...(normalizedControllerReceipts.length > 0 ? { controllerReceipts: normalizedControllerReceipts } : {}),
     versionImpact: normalizedImpact.versionImpact,
     surfaceImpacts: normalizedImpact.surfaceImpacts,
@@ -1238,6 +1322,7 @@ export function createReleasePassport({
       kfd1: normalizedKfd1 ? `${normalizedKfd1.key || kfd1Metadata.key}` : "",
       kfd2: normalizedKfd2 ? "kfd-2" : "",
       kfd3: normalizedKfd3 ? `${normalizedKfd3.key || "kfd-3"}` : "",
+      invariantPassports: invariantPassports ? "invariantPassports" : "",
       impact: impactPath,
       checkReport: checkReportPath,
       agentIndex: agentIndexPath,
@@ -1267,6 +1352,7 @@ export function collectGitHubReleasePassport({
   trustedPublishingJson = "",
   transactionJson = "",
   anchorManifestJson = "",
+  versionMaterialJson = "",
   impactJson = "",
   buildSummaryJson = "",
   buildFactsJsons = [],
@@ -1277,6 +1363,8 @@ export function collectGitHubReleasePassport({
   kfd3PrebuildWitnessJsons = [],
   kfd3ArtifactWitnessJsons = [],
   kfd3ArtifactVerifyCommand = "",
+  invariantPassportJsons = [],
+  invariantPassportCommand = "",
   controllerReceiptReferences = [],
   basePassportJson = "",
   requireBaseKfd = false,
@@ -1292,6 +1380,11 @@ export function collectGitHubReleasePassport({
   const trustedPublishing = parseJsonInput(trustedPublishingJson, undefined, { cwd, label: "trustedPublishingJson" });
   const transactionMeta = parseJsonInputWithMeta(transactionJson, undefined, { cwd, label: "transactionJson" });
   const anchorManifest = normalizeAnchorManifest(parseJsonInputWithMeta(anchorManifestJson, undefined, { cwd, label: "anchorManifestJson" }));
+  const versionMaterial = parseJsonInput(
+    versionMaterialJson,
+    undefined,
+    { cwd, label: "versionMaterialJson" },
+  );
   const impactMeta = parseJsonInputWithMeta(impactJson, undefined, { cwd, label: "impactJson" });
   const buildSummaryMeta = parseJsonInputWithMeta(buildSummaryJson, undefined, { cwd, label: "buildSummaryJson" });
   const buildFactMetas = (buildFactsJsons || [])
@@ -1324,6 +1417,17 @@ export function collectGitHubReleasePassport({
     cwd,
     label: "KFD-3 artifact verify command",
   });
+  const invariantPassportMetas = (invariantPassportJsons || [])
+    .filter(Boolean)
+    .map((passportJson) => parseJsonInputWithMeta(passportJson, undefined, { cwd, label: "invariantPassportJsons entry" }))
+    .filter((meta) => meta.value);
+  const invariantPassportCommandMeta = parseJsonCommandOutput({
+    command: invariantPassportCommand,
+    cwd,
+    label: "invariant passport command",
+  });
+  if (invariantPassportCommandMeta.value) invariantPassportMetas.push(invariantPassportCommandMeta);
+  const invariantPassports = createInvariantPassportGate(invariantPassportMetas);
   const kfd3ArtifactWitnesses = [
     ...kfd3ArtifactWitnessMetas.map((meta) => meta.value),
     ...(kfd3ArtifactCommandMeta.value ? [kfd3ArtifactCommandMeta.value] : []),
@@ -1369,6 +1473,7 @@ export function collectGitHubReleasePassport({
     assets,
     packageSet,
     anchorManifest,
+    versionMaterial,
     publishEvidence: publishEvidenceMeta.value,
     trustedPublishing,
     transaction: transactionMeta.value,
@@ -1400,6 +1505,7 @@ export function collectGitHubReleasePassport({
     kfd1,
     kfd2Claims: kfd2ClaimMetas.map((meta) => meta.value),
     kfd3,
+    invariantPassports,
     controllerReceiptReferences,
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
@@ -1881,6 +1987,56 @@ export function createReleaseCheckReport({
       issues.push(issue("error", "anchorManifest.fields", "anchorManifest.fields must be an object"));
     }
   }
+  if (passport?.versionMaterial) {
+    if (passport.versionMaterial.contract !== "kungfu-buildchain-anchored-version-material/v1") {
+      issues.push(issue(
+        "error",
+        "versionMaterial.contract",
+        "versionMaterial contract must be kungfu-buildchain-anchored-version-material/v1",
+      ));
+    }
+    if (!passport.versionMaterial.alpha?.tree || !passport.versionMaterial.release?.tree) {
+      issues.push(issue(
+        "error",
+        "versionMaterial.tree",
+        "versionMaterial must record alpha and release tree identities",
+      ));
+    }
+    const allowedPaths = Array.isArray(passport.versionMaterial.allowedPaths)
+      ? passport.versionMaterial.allowedPaths
+      : [];
+    const derivedFiles = Array.isArray(passport.versionMaterial.derivedFiles)
+      ? passport.versionMaterial.derivedFiles
+      : [];
+    for (const [index, file] of derivedFiles.entries()) {
+      if (!file?.path || !file?.sha256 || !allowedPaths.includes(file.path)) {
+        issues.push(issue(
+          "error",
+          `versionMaterial.derivedFiles[${index}]`,
+          "derived version material must have a path, digest, and matching allowed path",
+        ));
+      }
+    }
+    for (const side of ["alpha", "release"]) {
+      const material = Array.isArray(passport.versionMaterial[side]?.material)
+        ? passport.versionMaterial[side].material
+        : [];
+      for (const [index, file] of material.entries()) {
+        if (
+          !file?.path ||
+          !allowedPaths.includes(file.path) ||
+          file.present !== true ||
+          !/^sha256:[0-9a-f]{64}$/.test(file.sha256 || "")
+        ) {
+          issues.push(issue(
+            "error",
+            `versionMaterial.${side}.material[${index}]`,
+            "version material must have an allowed path, present bytes, and sha256 digest",
+          ));
+        }
+      }
+    }
+  }
   if (!passport?.runnerPolicy?.productionDefault) {
     issues.push(issue("warning", "runnerPolicy.productionDefault", "runner policy should record the production default"));
   }
@@ -1917,6 +2073,35 @@ export function createReleaseCheckReport({
       issues.push(issue("error", "kfd-3.metadata", error.message));
     }
   }
+  if (passport?.invariantPassports) {
+    const section = passport.invariantPassports;
+    if (section.contract !== INVARIANT_PASSPORT_GATE_CONTRACT) {
+      issues.push(issue("error", "invariantPassports.contract", `invariantPassports.contract must be ${INVARIANT_PASSPORT_GATE_CONTRACT}`));
+    }
+    if (section.result !== "passed") {
+      issues.push(issue("error", "invariantPassports.result", "invariantPassports.result must be passed"));
+    }
+    if (!Array.isArray(section.passports) || section.passports.length === 0) {
+      issues.push(issue("error", "invariantPassports.empty", "invariantPassports must contain at least one verified passport"));
+    }
+    const acceptedSourceShas = new Set([
+      passport?.release?.sourceSha,
+      passport?.release?.builtSourceSha,
+      passport?.release?.promotionChannelSha,
+    ].filter(Boolean));
+    for (const [index, entry] of (section.passports || []).entries()) {
+      const prefix = `invariantPassports.passports[${index}]`;
+      if (entry.verdict !== "verified") issues.push(issue("error", `${prefix}.verdict`, `${prefix}.verdict must be verified`));
+      if (entry.coverage?.complete !== true) issues.push(issue("error", `${prefix}.coverage`, `${prefix}.coverage.complete must be true`));
+      if (entry.source?.dirty !== false) issues.push(issue("error", `${prefix}.source.dirty`, `${prefix}.source.dirty must be false`));
+      if (acceptedSourceShas.size > 0 && !acceptedSourceShas.has(entry.source?.revision)) {
+        issues.push(issue("error", `${prefix}.source.revision`, `${prefix}.source.revision must match a release source identity`));
+      }
+      if (!/^sha256:[0-9a-f]{64}$/.test(optionalString(entry.passportRoot))) issues.push(issue("error", `${prefix}.passportRoot`, `${prefix}.passportRoot is invalid`));
+      if (!Array.isArray(entry.platforms) || entry.platforms.length === 0) issues.push(issue("error", `${prefix}.platforms`, `${prefix}.platforms must be non-empty`));
+      if (!Array.isArray(entry.residualRisk)) issues.push(issue("error", `${prefix}.residualRisk`, `${prefix}.residualRisk must be an array`));
+    }
+  }
   if (impactVersion) {
     if (!impactLine) {
       issues.push(issue("error", "impact.release.line", "version-bound impact requires release.line"));

package/scripts/anchored-version-material.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { createAnchoredVersionMaterialEvidence } from "../packages/core/anchored-version-material.js";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function writeOutput(name, value) {
+  if (!process.env.GITHUB_OUTPUT) {
+    return;
+  }
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${String(value)}\n`);
+}
+
+try {
+  const cwd = path.resolve(env("BUILDCHAIN_ANCHORED_SOURCE_CWD", process.cwd()));
+  const outputPath = path.resolve(
+    env(
+      "BUILDCHAIN_ANCHORED_MATERIAL_OUTPUT",
+      ".buildchain/artifacts/anchored-version-material.json",
+    ),
+  );
+  const evidence = createAnchoredVersionMaterialEvidence({
+    cwd,
+    targetChannel: env("BUILDCHAIN_ANCHORED_TARGET_CHANNEL"),
+    targetRef: env("BUILDCHAIN_ANCHORED_TARGET_REF"),
+    alphaRef: env("BUILDCHAIN_ANCHORED_ALPHA_REF"),
+    releaseRef: env("BUILDCHAIN_ANCHORED_RELEASE_REF", "HEAD"),
+    runLifecycle: env("BUILDCHAIN_ANCHORED_RUN_LIFECYCLE", "true") !== "false",
+  });
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(evidence, null, 2)}\n`);
+  writeOutput("anchored-version-material-applicable", evidence.applicable === true);
+  writeOutput("anchored-version-material-digest", evidence.digest || "");
+  writeOutput("anchored-version-material-path", outputPath);
+  process.stdout.write(`${JSON.stringify(evidence)}\n`);
+} catch (error) {
+  console.error(`anchored version material: ${error.message}`);
+  process.exitCode = 1;
+}

package/scripts/check-inventory.mjs

@@ -26,6 +26,7 @@ const requiredPaths = [
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
   "packages/core/artifact-verification-envelope.js",
+  "packages/core/anchored-version-material.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
   "packages/core/release-line-bootstrap.js",
@@ -58,6 +59,7 @@ const requiredPaths = [
   "scripts/generate-release-candidate-passport.mjs",
   "scripts/shifu-gate-profile.mjs",
   "scripts/artifact-relay-s3.mjs",
+  "scripts/anchored-version-material.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
   "scripts/publication-package.mjs",
@@ -876,6 +878,10 @@ for (const requiredSnippet of [
   "release-passport-kfd-3-artifact-witness-jsons:",
   "release-passport-kfd-3-artifact-witness-jsons: ${{ inputs.release-passport-kfd-3-artifact-witness-jsons }}",
   "release-passport-kfd-3-artifact-verify-command:",
+  "release-passport-invariant-passport-jsons:",
+  "release-passport-invariant-passport-jsons: ${{ inputs.release-passport-invariant-passport-jsons }}",
+  "release-passport-invariant-passport-command:",
+  "release-passport-invariant-passport-command: ${{ inputs.release-passport-invariant-passport-command }}",
   "release-passport-buildchain-self-kfd:",
   "release-passport-buildchain-self-kfd: ${{ inputs.release-passport-buildchain-self-kfd }}",
   "github-release:",

package/scripts/generate-site-bundle.mjs

@@ -499,6 +499,7 @@ function nodeApiMeta(exportName) {
     "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
+    "./anchored-version-material": { group: "reusable-build", summary: "Anchored/manual derived version material preflight, exact-tree binding, and digest evidence APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },

package/scripts/stable-candidate-patrol.mjs

@@ -223,7 +223,7 @@ export async function runStableCandidatePatrol(optionsInput = {}, clientInput) {
           `Buildchain Stable Candidate Patrol human release-now for ${selection.candidate.version}`,
         );
       }
-      await client.ensureBranch(refs.sourceRef, selection.candidate.sha);
+      await client.ensureBranch(refs.sourceRef, selection.candidate.sha, refs.targetRef);
       const pullRequest = await client.ensurePromotionPullRequest({
         head: refs.sourceRef,
         base: refs.targetRef,
@@ -371,15 +371,64 @@ export function createGitHubStableCandidateClient({ repository: repositoryInput,
         },
       });
     },
-    async ensureBranch(ref, candidateSha) {
+    async ensureBranch(ref, candidateSha, targetRef) {
       const current = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`, { allow404: true });
-      if (!current) {
+      if (!targetRef) {
+        if (!current) {
+          return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: candidateSha } });
+        }
+        if (current.object.sha !== candidateSha) {
+          throw new Error(`source-lock branch ${ref} already points to ${current.object.sha}, not ${candidateSha}`);
+        }
+        return current;
+      }
+
+      const candidateCommit = await api(`/repos/${owner}/${repo}/git/commits/${candidateSha}`);
+      let sourceSha = current?.object?.sha || candidateSha;
+      if (sourceSha !== candidateSha) {
+        const sourceCommit = await api(`/repos/${owner}/${repo}/git/commits/${sourceSha}`);
+        if (sourceCommit.tree?.sha !== candidateCommit.tree?.sha) {
+          throw new Error(`source-lock branch ${ref} no longer preserves candidate ${candidateSha} tree`);
+        }
+        const candidateLineage = await api(`/repos/${owner}/${repo}/compare/${candidateSha}...${sourceSha}`);
+        if (!["ahead", "identical"].includes(candidateLineage.status)) {
+          throw new Error(`source-lock branch ${ref} no longer descends from candidate ${candidateSha}`);
+        }
+      }
+
+      const target = await api(`/repos/${owner}/${repo}/git/ref/heads/${encodeRef(targetRef)}`);
+      const targetSha = target.object?.sha || "";
+      const targetLineage = await api(`/repos/${owner}/${repo}/compare/${targetSha}...${sourceSha}`);
+      if (["ahead", "identical"].includes(targetLineage.status)) {
+        if (current) return current;
         return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: candidateSha } });
       }
-      if (current.object.sha !== candidateSha) {
-        throw new Error(`source-lock branch ${ref} already points to ${current.object.sha}, not ${candidateSha}`);
+
+      const identity = { name: "Buildchain Patrol", email: "buildchain-patrol@kungfu.link" };
+      const reconciliation = await api(`/repos/${owner}/${repo}/git/commits`, {
+        method: "POST",
+        body: {
+          message: [
+            "chore(buildchain): reconcile stable source-lock ancestry",
+            "",
+            `Preserve the exact candidate tree from ${candidateSha} while admitting ${targetRef} at ${targetSha}.`,
+            "",
+            "Signed-off-by: Buildchain Patrol <buildchain-patrol@kungfu.link>",
+          ].join("\n"),
+          tree: candidateCommit.tree.sha,
+          parents: [sourceSha, targetSha],
+          author: identity,
+          committer: identity,
+        },
+      });
+      sourceSha = reconciliation.sha;
+      if (!current) {
+        return api(`/repos/${owner}/${repo}/git/refs`, { method: "POST", body: { ref: `refs/heads/${ref}`, sha: sourceSha } });
       }
-      return current;
+      return api(`/repos/${owner}/${repo}/git/refs/heads/${encodeRef(ref)}`, {
+        method: "PATCH",
+        body: { sha: sourceSha, force: false },
+      });
     },
     async ensurePromotionPullRequest({ head, base, title, body }) {
       const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);