@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/packages/core/artifact-signing.js

@@ -9,7 +9,6 @@ export const ARTIFACT_SIGNING_AUTHORITY_CONTRACT =
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const SOURCE_SHA_PATTERN = /^[0-9a-f]{40}$/u;
-const ENTITLEMENTS_PROFILES = new Set(["none", "jit-executable-v1"]);
 const FORBIDDEN_CREDENTIAL_KEYS =
   /(?:certificate|password|private.?key|secret|token|notary|issuer|team.?id|environment)/iu;
 
@@ -89,64 +88,6 @@ function exactSourceSha(value, label) {
   return normalized;
 }
 
-function entitlementsPaths(value) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) {
-    throw new Error("signing entitlements paths must be an array");
-  }
-  const paths = value.map((entry, index) => {
-    const normalized = nonEmptyString(
-      entry,
-      `signing entitlements paths[${index}]`,
-    );
-    const parts = normalized.split("/");
-    if (
-      normalized.startsWith("/") ||
-      normalized.includes("\\") ||
-      normalized.includes(",") ||
-      parts.some((part) => part === "" || part === "." || part === "..")
-    ) {
-      throw new Error(
-        `signing entitlements paths[${index}] must be a safe archive-relative path`,
-      );
-    }
-    return normalized;
-  });
-  if (new Set(paths).size !== paths.length) {
-    throw new Error("signing entitlements paths must not contain duplicates");
-  }
-  return paths;
-}
-
-function signingEntitlements(profileId, kind, signature) {
-  const profile = String(signature.entitlementsProfile || "none").trim();
-  const paths = entitlementsPaths(signature.entitlementsPaths);
-  if (!ENTITLEMENTS_PROFILES.has(profile)) {
-    throw new Error(
-      `unsupported signing entitlements profile: ${profile || "<empty>"}`,
-    );
-  }
-  if (
-    profile !== "none" &&
-    (profileId !== "apple-developer-id" || kind !== "archive")
-  ) {
-    throw new Error(
-      `signing entitlements profile ${profile} requires an Apple archive`,
-    );
-  }
-  if (
-    (profile === "none" && paths.length !== 0) ||
-    (profile !== "none" && paths.length === 0)
-  ) {
-    throw new Error(
-      "signing entitlements paths must be non-empty exactly when an entitlements profile is enabled",
-    );
-  }
-  return profile === "none"
-    ? {}
-    : { entitlementsProfile: profile, entitlementsPaths: paths };
-}
-
 function assertNoCredentialMaterial(value, path = "request") {
   if (!value || typeof value !== "object") return;
   for (const [key, child] of Object.entries(value)) {
@@ -250,7 +191,6 @@ export function createArtifactSigningRequest({
     platform,
     artifactKind: kind,
   });
-  const entitlementIntent = signingEntitlements(profile.id, kind, signature);
   const request = {
     schemaVersion: 1,
     contract: ARTIFACT_SIGNING_REQUEST_CONTRACT,
@@ -313,7 +253,6 @@ export function createArtifactSigningRequest({
       profile: profile.id,
       provider: profile.provider,
       semantics: profile.semantics,
-      ...entitlementIntent,
     },
     delivery: {
       mode: nonEmptyString(

package/packages/core/artifact-verification-envelope.js

@@ -417,7 +417,7 @@ function kfdBindingBody({ manifest, manifestGate, legacyProjection, paths }) {
       gatePath: paths.gate,
       gateRoot: manifestGate.gateRoot,
     },
-    adopter: jsonClone(manifestGate.adopter), source: jsonClone(manifestGate.source),
+    source: jsonClone(manifestGate.source),
     standardPackage: jsonClone(manifestGate.standardPackage),
     witness: {
       decisionRoot: manifestGate.decisionWitness.root,
@@ -445,10 +445,10 @@ export function createKfdAdopterReleaseBinding({
   manifestPath = "kfd-adopter-manifest.json",
   gatePath = "kfd-adopter-manifest-gate.json",
   legacyProjectionPath = "kfd-support.json",
-  expectedAdopterId = "kungfu-systems/buildchain", expectedSourceRepository = "", expectedSourceSha = "",
+  expectedSourceSha = "",
 } = {}) {
   const gate = validateKfdAdopterManifestGate(manifestGate, {
-    expectedAdopterId, expectedSourceRepository, expectedSourceSha,
+    expectedSourceSha,
     checkedAt: manifestGate?.checkedAt,
   });
   const legacy = validateKfdLegacySupportMatrixProjection(legacyProjection, { manifest, manifestGate });
@@ -468,7 +468,7 @@ export function validateKfdAdopterReleaseBinding(binding, {
   manifest,
   manifestGate,
   legacyProjection,
-  expectedAdopterId = "kungfu-systems/buildchain", expectedSourceRepository = "", expectedSourceSha = "",
+  expectedSourceSha = "",
 } = {}) {
   const issues = [];
   if (!binding || binding.schemaVersion !== 1 || binding.contract !== KFD_ADOPTER_RELEASE_BINDING_CONTRACT) {
@@ -488,7 +488,7 @@ export function validateKfdAdopterReleaseBinding(binding, {
       manifestPath: binding.authority?.manifestPath,
       gatePath: binding.authority?.gatePath,
       legacyProjectionPath: binding.legacyProjection?.path,
-      expectedAdopterId, expectedSourceRepository, expectedSourceSha,
+      expectedSourceSha,
     });
     if (stableJson(binding) !== stableJson(expected)) {
       issues.push({ code: "adopter-release-binding-drift", path: "", message: "release binding differs from the exact manifest, gate, or legacy projection closure" });

package/packages/core/build-facts.js

@@ -81,10 +81,18 @@ function repositorySlug(cwd) {
 function readTrackedFiles(cwd, root = ".") {
   const repoRoot = fs.realpathSync(path.resolve(cwd));
   const requestedRoot = fs.realpathSync(path.resolve(cwd, root));
-  const relativeRoot = posixPath(path.relative(repoRoot, requestedRoot) || ".");
-  const args = relativeRoot === "." ? ["ls-files", "-z"] : ["ls-files", "-z", "--", relativeRoot];
-  return parseZeroSeparated(git(repoRoot, args))
-    .filter((entry) => entry && !entry.startsWith(".git/"))
+  const relativeRoot = posixPath(
+    git(requestedRoot, ["rev-parse", "--show-prefix"]),
+  ).replace(/\/+$/u, "") || ".";
+  return parseZeroSeparated(git(repoRoot, ["ls-files", "-z"]))
+    .filter((entry) =>
+      entry
+      && !entry.startsWith(".git/")
+      && (
+        relativeRoot === "."
+        || entry === relativeRoot
+        || entry.startsWith(`${relativeRoot}/`)
+      ))
     .sort();
 }
 

package/packages/core/buildchain-agent-manuals.js

@@ -10,7 +10,6 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-train", title: "Release Train and Release Cut", path: "docs/release-train.md", plane: "verify" },
-  { id: "next-development-transition", title: "Next-development transition", path: "docs/next-development-transition.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
   { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
@@ -33,7 +32,6 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
   { id: "release-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
   { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },
-  { id: "publication-rehearsal", title: "Publication rehearsal", path: "docs/publication-rehearsal.md", plane: "use" },
   { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
   { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
   { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },

package/packages/core/buildchain-config.js

@@ -1,4 +1,3 @@
-import { execSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -8,6 +7,7 @@ import {
   BUILDCHAIN_CONFIG_PATH,
   resolveBuildchainConfigPath,
 } from "./buildchain-layout.js";
+import { runShellCommandSync } from "./spawn-command.js";
 
 const CONFIG_FILE = BUILDCHAIN_CONFIG_PATH;
 const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
@@ -61,10 +61,6 @@ const SUPPORTED_SIGNING_PROFILES = new Set([
   "windows-authenticode",
   "detached-signature-v1",
 ]);
-const SUPPORTED_SIGNING_ENTITLEMENTS_PROFILES = new Set([
-  "none",
-  "jit-executable-v1",
-]);
 const SUPPORTED_SIGNING_ARTIFACT_KINDS = new Set([
   "auto", "binary", "archive", "blob", "directory", "mach-o", "app-bundle",
   "framework-bundle", "plugin-bundle", "xpc-bundle", "dylib", "pkg", "dmg",
@@ -103,27 +99,6 @@ function normalizeStringArray(value, label) {
   return value.map((entry, index) => assertString(entry, `${label}[${index}]`));
 }
 
-function normalizeSigningEntitlementsPaths(value, label) {
-  const paths = normalizeStringArray(value, label);
-  for (const [index, entry] of paths.entries()) {
-    const parts = entry.split("/");
-    if (
-      entry.startsWith("/") ||
-      entry.includes("\\") ||
-      entry.includes(",") ||
-      parts.some((part) => part === "" || part === "." || part === "..")
-    ) {
-      throw new Error(
-        `${label}[${index}] must be a safe archive-relative path`,
-      );
-    }
-  }
-  if (new Set(paths).size !== paths.length) {
-    throw new Error(`${label} must not contain duplicate paths`);
-  }
-  return paths;
-}
-
 function getByDottedKey(target, key) {
   return String(key)
     .split(".")
@@ -387,16 +362,7 @@ function normalizeSigningSection(signing) {
   const artifacts = signing.artifacts.map((artifact, index) => {
     const label = `signing.artifacts[${index}]`;
     assertPlainObject(artifact, label);
-    const allowedKeys = new Set([
-      "id",
-      "path",
-      "profile",
-      "entitlements_profile",
-      "entitlements_paths",
-      "kind",
-      "platforms",
-      "required",
-    ]);
+    const allowedKeys = new Set(["id", "path", "profile", "kind", "platforms", "required"]);
     for (const key of Object.keys(artifact)) {
       if (!allowedKeys.has(key)) {
         throw new Error(`${label}.${key} is not supported; declare desired signature state only`);
@@ -411,41 +377,10 @@ function normalizeSigningSection(signing) {
     if (!SUPPORTED_SIGNING_ARTIFACT_KINDS.has(kind)) {
       throw new Error(`${label}.kind is not a supported signing artifact kind`);
     }
-    const entitlementsProfile =
-      artifact.entitlements_profile === undefined
-        ? "none"
-        : assertString(
-            artifact.entitlements_profile,
-            `${label}.entitlements_profile`,
-          );
-    if (!SUPPORTED_SIGNING_ENTITLEMENTS_PROFILES.has(entitlementsProfile)) {
-      throw new Error(
-        `${label}.entitlements_profile must be one of none or jit-executable-v1`,
-      );
-    }
-    if (entitlementsProfile !== "none" && kind !== "archive") {
-      throw new Error(
-        `${label}.entitlements_profile ${entitlementsProfile} requires kind = "archive"`,
-      );
-    }
-    const entitlementsPaths = normalizeSigningEntitlementsPaths(
-      artifact.entitlements_paths,
-      `${label}.entitlements_paths`,
-    );
-    if (
-      (entitlementsProfile === "none" && entitlementsPaths.length !== 0) ||
-      (entitlementsProfile !== "none" && entitlementsPaths.length === 0)
-    ) {
-      throw new Error(
-        `${label}.entitlements_paths must be non-empty exactly when entitlements_profile is enabled`,
-      );
-    }
     return {
       id: artifact.id === undefined ? artifactPath : assertString(artifact.id, `${label}.id`),
       path: artifactPath,
       profile,
-      entitlementsProfile,
-      entitlementsPaths,
       kind,
       platforms: normalizeStringArray(artifact.platforms, `${label}.platforms`),
       required: optionalBoolean(artifact.required, true),
@@ -1463,11 +1398,11 @@ export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, sta
   };
   const runOnce = () => {
     if (selected.mode === "script") {
-      execSync(selected.script, execOptions);
+      runShellCommandSync(selected.script, execOptions);
       return;
     }
     for (const command of selected.commands) {
-      execSync(command, execOptions);
+      runShellCommandSync(command, execOptions);
     }
   };
   let lastError;

package/packages/core/buildchain-contract.js

@@ -2,10 +2,11 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
-  assertBuildchainCompatibilityProjection,
-  createBuildchainCompatibilityProofRegistry,
-  createHistoricalBuildchainCompatibilityProofs,
-} from "./buildchain-compatibility-proof.js";
+  BUILDCHAIN_CHANNELS,
+  evaluateBuildchainChannelBinding,
+  normalizeBuildchainRef,
+  parseBuildchainRefIdentity,
+} from "./buildchain-channel-identity.js";
 import { createControllerRegistry } from "./controller-evidence.js";
 import { enumerateWorkflowInputs } from "./public-surface-audit.js";
 
@@ -14,28 +15,13 @@ export {
   evaluateBuildchainChannelBinding,
   normalizeBuildchainRef,
   parseBuildchainRefIdentity,
-} from "./buildchain-channel-identity.js";
-
-export {
-  BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
-  BUILDCHAIN_COMPATIBILITY_PROOF_SCHEMA,
-  BUILDCHAIN_COMPATIBILITY_VERIFICATION_RECEIPT_SCHEMA,
-  assertBuildchainCompatibilityProjection,
-  contractSummary,
-  createBuildchainCompatibilityProof,
-  createBuildchainCompatibilityProofRegistry,
-  createBuildchainCompatibilityVerificationReceipt,
-  createHistoricalBuildchainCompatibilityProofs,
-  evaluateBuildchainContractLock,
-  renderBuildchainContractDriftIssueBody,
-  verifyBuildchainCompatibilityProof,
-  verifyBuildchainCompatibilityVerificationReceipt,
-} from "./buildchain-compatibility-proof.js";
+};
 
 export const BUILDCHAIN_RUNTIME_CONTRACT_WORLD = "kungfu-buildchain-runtime-contract-world";
 export const BUILDCHAIN_CONTRACT_LOCK = "kungfu-buildchain-contract-lock";
 
 const DEFAULT_POLICY = "major-compatible";
+const FLOATING_CLASSES = new Set(["stable", "alpha"]);
 
 function optionalString(value) {
   return value === undefined || value === null ? "" : String(value);
@@ -311,6 +297,9 @@ export function createBuildchainContractWorld({
         "publish-gate source locks are created by the wrapper and enforced by promote-buildchain-ref before publish side effects",
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes",
       ],
+      compatibleBreakingDigests: [
+        "sha256:acd401cfc46450115a3763fd4b679d85f185e8757ebd52510d6262e1533df4cf",
+      ],
     }),
     surface(root, {
       id: "advanced-release-candidate-promote",
@@ -325,6 +314,8 @@ export function createBuildchainContractWorld({
       },
       optionalInputs: [
         "buildchain-ref",
+        "buildchain-expected-channel",
+        "buildchain-expected-major",
         "buildchain-contract-lock-path",
         "promotion-router-ref",
         "promotion-router-sha",
@@ -352,6 +343,9 @@ export function createBuildchainContractWorld({
         "promotion reuses PR-stage release-candidate artifacts and does not run the heavy native build matrix",
         "resume-from-candidate-run is fail-closed and uses a fresh caller event instead of rerunning a frozen startup graph",
       ],
+      compatibleBreakingDigests: [
+        "sha256:aa30f22e3af0a89841310bdbdc900844dd95a66974db173fa140a71bbd7e82c0",
+      ],
     }),
     surface(root, {
       id: "web-surface",
@@ -498,6 +492,9 @@ export function createBuildchainContractWorld({
         "publish transactions can require a resolved publish-gate source lock to prevent floating-ref drift",
         "semver GitHub Releases are created or updated only after transaction completion, with prerelease/latest metadata bound to the authoritative publication channel and tag syntax retained as the fallback for ordinary callers",
       ],
+      compatibleBreakingDigests: [
+        "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874",
+      ],
     }),
     surface(root, {
       id: "macos-credential-island-action",
@@ -773,6 +770,14 @@ export function createBuildchainContractWorld({
         registryDigest: resolvedControllerRegistry.digest,
         inputClassifications: descriptor.inputs,
       },
+      ...(descriptor.id === "build-lifecycle"
+        ? {
+            compatibleBreakingDigests: [
+              "sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
+              "sha256:30745921541e9b0f70475bb2178c2559f6aef248f6680670ccd44d8c5a69a6b1",
+            ],
+          }
+        : {}),
       guarantees: [
         "plans bind exact consumer source SHA, exact Buildchain runtime SHA, and the runtime contract digest",
         "receipts bind the plan digest and preserve pass, fail, skip, and partial stage outcomes",
@@ -792,45 +797,24 @@ export function createBuildchainContractWorld({
     },
     majorLine,
     compatibilityPolicy: DEFAULT_POLICY,
-    compatibilityProofs: createHistoricalBuildchainCompatibilityProofs(),
     surfaces,
   };
   return finalizeBuildchainContractWorld(base);
 }
 
 export function finalizeBuildchainContractWorld(contractWorld) {
-  const sourceSurfaces = (contractWorld.surfaces || []).map((entry) => ({ ...entry }));
-  const proofRegistry = createBuildchainCompatibilityProofRegistry({
-    proofs: contractWorld.compatibilityProofs || createHistoricalBuildchainCompatibilityProofs(),
-    surfaces: sourceSurfaces,
-    majorLine: contractWorld.majorLine,
-  });
   const world = {
     ...contractWorld,
-    compatibilityProofs: proofRegistry.proofs,
-    compatibilityProofRegistryRoot: proofRegistry.registryRoot,
-    surfaces: sourceSurfaces.map((entry) => {
-      const surfaceEntry = { ...entry };
-      delete surfaceEntry.compatibleBreakingDigests;
-      delete surfaceEntry.compatibilityProofRoots;
-      const projection = proofRegistry.projections[entry.id] || [];
-      if (projection.length > 0) {
-        surfaceEntry.compatibleBreakingDigests = projection.map((item) => item.breakingDigest);
-        surfaceEntry.compatibilityProofRoots = projection.map((item) => item.proofRoot);
-      }
-      return surfaceEntry;
-    }),
+    surfaces: (contractWorld.surfaces || []).map((entry) => ({ ...entry })),
   };
   const compatibilityModel = {
     schemaVersion: world.schemaVersion,
     contract: world.contract,
     majorLine: world.majorLine,
-    compatibilityProofRegistryRoot: world.compatibilityProofRegistryRoot,
     surfaces: world.surfaces.map((entry) => ({
       id: entry.id,
       kind: entry.kind,
       breakingDigest: entry.breakingDigest,
-      compatibilityProofRoots: entry.compatibilityProofRoots || [],
     })),
   };
   const digestModel = {
@@ -862,7 +846,6 @@ export function createBuildchainContractLock({
       contract: contractWorld.contract,
       contractDigest: contractWorld.contractDigest,
       compatibilityDigest: contractWorld.compatibilityDigest,
-      compatibilityProofRegistryRoot: contractWorld.compatibilityProofRegistryRoot,
       majorLine: contractWorld.majorLine,
       compatibilityPolicy,
       acceptedAt,
@@ -870,7 +853,6 @@ export function createBuildchainContractLock({
         id: entry.id,
         kind: entry.kind,
         breakingDigest: entry.breakingDigest,
-        compatibilityProofRoots: entry.compatibilityProofRoots || [],
       })),
     },
   };
@@ -881,7 +863,6 @@ export function readBuildchainContractWorld(filePath) {
   if (!value || value.contract !== BUILDCHAIN_RUNTIME_CONTRACT_WORLD) {
     throw new Error(`Buildchain contract world is missing or invalid: ${filePath}`);
   }
-  assertBuildchainCompatibilityProjection(value);
   const computed = finalizeBuildchainContractWorld(value);
   for (const digestName of ["compatibilityDigest", "contractDigest"]) {
     const published = String(value[digestName] || "").trim();
@@ -907,3 +888,208 @@ export function readBuildchainContractLock(filePath) {
   }
   return value;
 }
+
+function surfaceMap(surfaces = []) {
+  return new Map(surfaces.map((entry) => [entry.id, entry]));
+}
+
+function evaluateChannelBinding({
+  lock,
+  workflowShellRef,
+  runtimeRef,
+  expectedChannel,
+  expectedMajor,
+  allowOpaqueRuntime,
+}) {
+  if (!workflowShellRef && !expectedChannel && !expectedMajor) return null;
+  return evaluateBuildchainChannelBinding({
+    workflowShellRef,
+    runtimeRef,
+    lockRef: lock?.buildchain?.ref || "",
+    lockMajorLine: lock?.buildchain?.majorLine || "",
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
+  });
+}
+
+export function evaluateBuildchainContractLock({
+  lock,
+  current,
+  runtimeRef = "",
+  runtimeSha = "",
+  runtimeClass = "",
+  compatibilityPolicy = "",
+  workflowShellRef = "",
+  expectedChannel = "",
+  expectedMajor = "",
+  allowOpaqueRuntime = false,
+} = {}) {
+  if (!current || current.contract !== BUILDCHAIN_RUNTIME_CONTRACT_WORLD) {
+    throw new Error("current must be a Buildchain runtime contract world");
+  }
+  const binding = evaluateChannelBinding({
+    lock,
+    workflowShellRef,
+    runtimeRef,
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
+  });
+  if (binding?.ok === false) {
+    return {
+      ok: false,
+      status: binding.status,
+      drift: false,
+      compatible: false,
+      issueRecommended: false,
+      reasons: binding.reasons,
+      channelBinding: binding,
+    };
+  }
+  const floatingRuntime = FLOATING_CLASSES.has(runtimeClass);
+  if (!floatingRuntime) {
+    return {
+      ok: true,
+      status: "non-floating-runtime",
+      drift: false,
+      compatible: true,
+      issueRecommended: false,
+      reason: `runtime class ${runtimeClass || "unknown"} is not a stable floating ref`,
+    };
+  }
+  if (!lock) {
+    return {
+      ok: true,
+      status: "missing-lock",
+      drift: false,
+      compatible: true,
+      issueRecommended: false,
+      reason: "consumer repository has no Buildchain contract lock",
+    };
+  }
+  const accepted = lock.buildchain || {};
+  const policy = compatibilityPolicy || accepted.compatibilityPolicy || DEFAULT_POLICY;
+  const shaDrift = !!accepted.resolvedSha && !!runtimeSha && accepted.resolvedSha !== runtimeSha;
+  const contractDrift = !!accepted.contractDigest && accepted.contractDigest !== current.contractDigest;
+  if (!shaDrift && !contractDrift) {
+    return {
+      ok: true,
+      status: "unchanged",
+      drift: false,
+      compatible: true,
+      issueRecommended: false,
+      policy,
+      accepted,
+      current: contractSummary(current, runtimeRef, runtimeSha),
+    };
+  }
+  const reasons = [];
+  if (accepted.contract !== current.contract) {
+    reasons.push(`contract changed from ${accepted.contract || "(unknown)"} to ${current.contract}`);
+  }
+  if (accepted.majorLine && accepted.majorLine !== current.majorLine) {
+    reasons.push(`major line changed from ${accepted.majorLine} to ${current.majorLine}`);
+  }
+  if (policy === "exact" && accepted.contractDigest !== current.contractDigest) {
+    reasons.push("exact policy requires the contract digest to remain unchanged");
+  }
+  if (!["major-compatible", "allow-additive", "exact"].includes(policy)) {
+    reasons.push(`unsupported compatibility policy: ${policy}`);
+  }
+  const currentSurfaces = surfaceMap(current.surfaces);
+  for (const oldSurface of accepted.surfaces || []) {
+    const nextSurface = currentSurfaces.get(oldSurface.id);
+    if (!nextSurface) {
+      reasons.push(`surface removed: ${oldSurface.id}`);
+      continue;
+    }
+    const compatibleBreakingDigests = new Set(nextSurface.compatibleBreakingDigests || []);
+    if (
+      nextSurface.breakingDigest !== oldSurface.breakingDigest
+      && !compatibleBreakingDigests.has(oldSurface.breakingDigest)
+    ) {
+      reasons.push(`surface breaking digest changed: ${oldSurface.id}`);
+    }
+  }
+  const compatible = reasons.length === 0;
+  return {
+    ok: compatible,
+    status: compatible ? "compatible-drift" : "breaking-drift",
+    drift: shaDrift || contractDrift,
+    shaDrift,
+    contractDrift,
+    compatible,
+    issueRecommended: true,
+    policy,
+    reasons,
+    accepted,
+    current: contractSummary(current, runtimeRef, runtimeSha),
+  };
+}
+
+export function contractSummary(contractWorld, runtimeRef = "", runtimeSha = "") {
+  return {
+    ref: runtimeRef,
+    resolvedSha: runtimeSha,
+    contract: contractWorld.contract,
+    contractDigest: contractWorld.contractDigest,
+    compatibilityDigest: contractWorld.compatibilityDigest,
+    majorLine: contractWorld.majorLine,
+    surfaceCount: Array.isArray(contractWorld.surfaces) ? contractWorld.surfaces.length : 0,
+  };
+}
+
+export function renderBuildchainContractDriftIssueBody({
+  repository = "",
+  workflow = "",
+  runUrl = "",
+  lockPath = "",
+  evaluation,
+} = {}) {
+  const accepted = evaluation.accepted || {};
+  const current = evaluation.current || {};
+  const severity = evaluation.compatible ? "compatible" : "breaking";
+  return [
+    "# Buildchain contract drift",
+    "",
+    "## Summary",
+    "",
+    `Buildchain detected ${severity} contract drift for a floating runtime ref before expensive Buildchain work continued.`,
+    "",
+    "## Consumer",
+    "",
+    `- Repository: ${repository || "(unknown)"}`,
+    `- Workflow: ${workflow || "(unknown)"}`,
+    `- Run: ${runUrl || "(unknown)"}`,
+    `- Lock path: ${lockPath || "(unknown)"}`,
+    "",
+    "## Accepted Buildchain contract",
+    "",
+    `- Ref: ${accepted.ref || "(unknown)"}`,
+    `- SHA: ${accepted.resolvedSha || "(unknown)"}`,
+    `- Contract digest: ${accepted.contractDigest || "(unknown)"}`,
+    `- Compatibility digest: ${accepted.compatibilityDigest || "(unknown)"}`,
+    `- Policy: ${evaluation.policy || accepted.compatibilityPolicy || "(unknown)"}`,
+    "",
+    "## Current Buildchain contract",
+    "",
+    `- Ref: ${current.ref || "(unknown)"}`,
+    `- SHA: ${current.resolvedSha || "(unknown)"}`,
+    `- Contract digest: ${current.contractDigest || "(unknown)"}`,
+    `- Compatibility digest: ${current.compatibilityDigest || "(unknown)"}`,
+    `- Major line: ${current.majorLine || "(unknown)"}`,
+    "",
+    "## Compatibility",
+    "",
+    `- Status: ${evaluation.status || "(unknown)"}`,
+    `- Compatible: ${evaluation.compatible ? "yes" : "no"}`,
+    evaluation.reasons?.length ? evaluation.reasons.map((reason) => `- ${reason}`).join("\n") : "- No breaking drift detected.",
+    "",
+    "## Suggested next action",
+    "",
+    evaluation.compatible
+      ? "Review the Buildchain release notes, then update the consumer contract lock to the current SHA and contract digest."
+      : "Failing before heavy build is intentional. Review the Buildchain contract change, update the consumer workflow/configuration, or pin the previous Buildchain SHA.",
+  ].join("\n");
+}

package/packages/core/buildchain-kfd-claims.js

@@ -138,7 +138,7 @@ function immediateReadmes(root, dir) {
 
 function publicDocumentationFiles(root) {
   return uniquePaths([
-    ...(readJson(root, "dist/site/manual-registry.json").manuals || BUILDCHAIN_AGENT_MANUALS).map((entry) => entry.path),
+    ...BUILDCHAIN_AGENT_MANUALS.map((entry) => entry.path),
     "README.md",
     "packages/core/README.md",
     ...immediateReadmes(root, "actions"),