@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.10

package/packages/core/buildchain-config.js

@@ -61,6 +61,10 @@ 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",
@@ -99,6 +103,27 @@ 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(".")
@@ -211,6 +236,16 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.publication !== undefined) {
     normalized.publication = normalizePublicationSection(normalized.publication);
   }
+  if (normalized.publication_rehearsal !== undefined) {
+    normalized.publication_rehearsal = normalizePublicationRehearsalSection(
+      normalized.publication_rehearsal,
+    );
+  }
+  if (normalized.adopter_delivery !== undefined) {
+    normalized.adopter_delivery = normalizeAdopterDeliverySection(
+      normalized.adopter_delivery,
+    );
+  }
   if (normalized.consumers !== undefined) {
     normalized.consumers = normalizeConsumersSection(normalized.consumers);
   }
@@ -362,7 +397,16 @@ 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", "kind", "platforms", "required"]);
+    const allowedKeys = new Set([
+      "id",
+      "path",
+      "profile",
+      "entitlements_profile",
+      "entitlements_paths",
+      "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`);
@@ -377,10 +421,41 @@ 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),
@@ -635,6 +710,80 @@ function normalizePublicationSection(publication) {
   };
 }
 
+function normalizePublicationRehearsalSection(rehearsal) {
+  assertPlainObject(rehearsal, "publication_rehearsal");
+  const allowed = ["contract", "capsule_path", "candidate_root", "state_path", "evidence_path", "effect_default"];
+  const unknown = Object.keys(rehearsal).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`publication_rehearsal contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(rehearsal.contract, "publication_rehearsal.contract"),
+    capsulePath: posixPath(assertString(rehearsal.capsule_path, "publication_rehearsal.capsule_path")),
+    candidateRoot: posixPath(assertString(rehearsal.candidate_root, "publication_rehearsal.candidate_root")),
+    statePath: posixPath(assertString(rehearsal.state_path, "publication_rehearsal.state_path")),
+    evidencePath: posixPath(assertString(rehearsal.evidence_path, "publication_rehearsal.evidence_path")),
+    effectDefault: assertString(rehearsal.effect_default, "publication_rehearsal.effect_default"),
+  };
+  if (
+    normalized.contract !== "buildchain-v4-publication-rehearsal-capsule/v1" ||
+    normalized.effectDefault !== "disabled"
+  ) {
+    throw new Error("publication_rehearsal must use the v4 capsule contract with effect_default = disabled");
+  }
+  for (const [key, value] of Object.entries({
+    capsule_path: normalized.capsulePath,
+    candidate_root: normalized.candidateRoot,
+    state_path: normalized.statePath,
+    evidence_path: normalized.evidencePath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`publication_rehearsal.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeAdopterDeliverySection(delivery) {
+  assertPlainObject(delivery, "adopter_delivery");
+  const allowed = ["contract", "input_path", "readback_path", "bootstrap_path", "archive_path", "result_path", "driver_selector", "artifact_profile_selector"];
+  const unknown = Object.keys(delivery).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`adopter_delivery contains unsupported fields: ${unknown.join(", ")}`);
+  }
+  const normalized = {
+    contract: assertString(delivery.contract, "adopter_delivery.contract"),
+    inputPath: posixPath(assertString(delivery.input_path, "adopter_delivery.input_path")),
+    readbackPath: posixPath(assertString(delivery.readback_path, "adopter_delivery.readback_path")),
+    bootstrapPath: posixPath(assertString(delivery.bootstrap_path, "adopter_delivery.bootstrap_path")),
+    archivePath: posixPath(assertString(delivery.archive_path, "adopter_delivery.archive_path")),
+    resultPath: posixPath(assertString(delivery.result_path, "adopter_delivery.result_path")),
+    driverSelector: assertString(delivery.driver_selector, "adopter_delivery.driver_selector"),
+    artifactProfileSelector: assertString(delivery.artifact_profile_selector, "adopter_delivery.artifact_profile_selector"),
+  };
+  if (normalized.contract !== "kungfu-buildchain-v4-adopter-delivery/v1") {
+    throw new Error("adopter_delivery contract is unsupported");
+  }
+  if (
+    !["json-assertion", "kfd-category", "legacy-kfd"].includes(normalized.driverSelector) ||
+    !["git-commit", "package"].includes(normalized.artifactProfileSelector)
+  ) {
+    throw new Error("adopter_delivery selector is unsupported");
+  }
+  for (const [key, value] of Object.entries({
+    input_path: normalized.inputPath,
+    readback_path: normalized.readbackPath,
+    bootstrap_path: normalized.bootstrapPath,
+    archive_path: normalized.archivePath,
+    result_path: normalized.resultPath,
+  })) {
+    if (value.startsWith("/") || value.includes("\\") || value.split("/").includes("..")) {
+      throw new Error(`adopter_delivery.${key} must be repository-relative`);
+    }
+  }
+  return normalized;
+}
+
 function normalizePublicationArchive(archive = undefined) {
   if (archive === undefined) {
     return undefined;

package/packages/core/buildchain-contract.js

@@ -7,8 +7,18 @@ import {
   normalizeBuildchainRef,
   parseBuildchainRefIdentity,
 } from "./buildchain-channel-identity.js";
+import {
+  createHistoricalBuildchainCompatibilityFacts,
+  createHistoricalBuildchainCompatibilityProofs,
+} from "./buildchain-compatibility-fact.js";
+import {
+  assertBuildchainCompatibilityProjection,
+  createBuildchainCompatibilityProofRegistry,
+} from "./buildchain-compatibility-authority.js";
+import { evaluateBuildchainContractLock as evaluateFactBackedBuildchainContractLock } from "./buildchain-compatibility-proof.js";
 import { createControllerRegistry } from "./controller-evidence.js";
 import { enumerateWorkflowInputs } from "./public-surface-audit.js";
+import { devDeliveryWorkflowContractSurface } from "./dev-delivery-contract-surface.js";
 
 export {
   BUILDCHAIN_CHANNELS,
@@ -17,11 +27,47 @@ export {
   parseBuildchainRefIdentity,
 };
 
+export {
+  BUILDCHAIN_COMPATIBILITY_FACT_REGISTRY_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_FACT_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_PROOF_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_RELEASE_EVIDENCE_SCHEMA,
+  createBuildchainCompatibilityFact,
+  createBuildchainCompatibilityFactRegistry,
+  createBuildchainCompatibilityProof,
+  createHistoricalBuildchainCompatibilityFacts,
+  createHistoricalBuildchainCompatibilityProofs,
+  verifyBuildchainCompatibilityFact,
+  verifyBuildchainCompatibilityFactRegistry,
+  verifyBuildchainCompatibilityProof,
+} from "./buildchain-compatibility-fact.js";
+export {
+  assertBuildchainCompatibilityProjection,
+  createBuildchainCompatibilityPathQuery,
+  createBuildchainCompatibilityProofRegistry,
+  createBuildchainCompatibilityReleaseEvidence,
+  resolveBuildchainCompatibilityProof,
+  verifyBuildchainCompatibilityPath,
+} from "./buildchain-compatibility-authority.js";
+export {
+  BUILDCHAIN_COMPATIBILITY_VERIFICATION_RECEIPT_SCHEMA,
+  BUILDCHAIN_LEGACY_COMPATIBILITY_VERIFICATION_RECEIPT_SCHEMA,
+  createBuildchainCompatibilityVerificationReceipt,
+  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 compatibilityAuthority() {
+  return {
+    compatibilityFacts: createHistoricalBuildchainCompatibilityFacts(),
+    compatibilityProofs: createHistoricalBuildchainCompatibilityProofs(),
+  };
+}
 
 function optionalString(value) {
   return value === undefined || value === null ? "" : String(value);
@@ -125,8 +171,7 @@ export function createBuildchainContractWorld({
   packageJson = undefined,
   controllerRegistry = undefined,
 } = {}) {
-  const pkg = packageJson || readJson(path.join(root, "package.json"), {});
-  const majorLine = majorLineFromPackageVersion(pkg.version);
+  const pkg = packageJson || readJson(path.join(root, "package.json"), {}), majorLine = majorLineFromPackageVersion(pkg.version);
   const workflowDescriptors = controllerRegistry ? [] : enumerateWorkflowInputs({ root });
   const controllerWorkflowIds = new Set([
     "check",
@@ -217,6 +262,7 @@ export function createBuildchainContractWorld({
         "alpha and stable channel selections use separate consumer contract locks by default",
       ],
     }),
+    surface(root, devDeliveryWorkflowContractSurface(pkg, majorLine)),
     surface(root, {
       id: "release-candidate-promote",
       kind: "workflow",
@@ -795,26 +841,60 @@ export function createBuildchainContractWorld({
       version: pkg.version || "",
       repository: pkg.repository?.url || pkg.repository || "https://github.com/kungfu-systems/buildchain",
     },
-    majorLine,
-    compatibilityPolicy: DEFAULT_POLICY,
+    majorLine, compatibilityPolicy: DEFAULT_POLICY,
+    ...compatibilityAuthority(),
     surfaces,
   };
   return finalizeBuildchainContractWorld(base);
 }
 
 export function finalizeBuildchainContractWorld(contractWorld) {
+  if (!Array.isArray(contractWorld?.compatibilityFacts) || !Array.isArray(contractWorld?.compatibilityProofs)) {
+    throw new Error("contract world requires compatibility Facts and their proof projection");
+  }
+  const sourceSurfaces = (contractWorld.surfaces || []).map((entry) => ({ ...entry }));
+  const proofRegistry = createBuildchainCompatibilityProofRegistry({
+    proofs: contractWorld.compatibilityProofs,
+    surfaces: sourceSurfaces,
+    majorLine: contractWorld.majorLine,
+  });
+  if (JSON.stringify(contractWorld.compatibilityFacts) !== JSON.stringify(proofRegistry.facts)) {
+    throw new Error("contract world compatibility Facts drift from the verified registry");
+  }
   const world = {
     ...contractWorld,
-    surfaces: (contractWorld.surfaces || []).map((entry) => ({ ...entry })),
+    compatibilityFacts: proofRegistry.facts,
+    compatibilityFactRegistryRoot: proofRegistry.factRegistryRoot,
+    compatibilityFactCutRoot: proofRegistry.factCutRoot,
+    compatibilityProofs: proofRegistry.proofs,
+    compatibilityProofRegistryRoot: proofRegistry.registryRoot,
+    surfaces: sourceSurfaces.map((entry) => {
+      const surfaceEntry = { ...entry };
+      delete surfaceEntry.compatibleBreakingDigests;
+      delete surfaceEntry.compatibilityProofRoots;
+      delete surfaceEntry.compatibilityFactRoots;
+      const projection = proofRegistry.projections[entry.id] || [];
+      if (projection.length > 0) {
+        surfaceEntry.compatibleBreakingDigests = projection.map((item) => item.breakingDigest);
+        surfaceEntry.compatibilityProofRoots = projection.map((item) => item.proofRoot);
+        surfaceEntry.compatibilityFactRoots = projection.map((item) => item.factRoot);
+      }
+      return surfaceEntry;
+    }),
   };
   const compatibilityModel = {
     schemaVersion: world.schemaVersion,
     contract: world.contract,
     majorLine: world.majorLine,
+    compatibilityFactRegistryRoot: world.compatibilityFactRegistryRoot,
+    compatibilityFactCutRoot: world.compatibilityFactCutRoot,
+    compatibilityProofRegistryRoot: world.compatibilityProofRegistryRoot,
     surfaces: world.surfaces.map((entry) => ({
       id: entry.id,
       kind: entry.kind,
       breakingDigest: entry.breakingDigest,
+      compatibilityProofRoots: entry.compatibilityProofRoots || [],
+      compatibilityFactRoots: entry.compatibilityFactRoots || [],
     })),
   };
   const digestModel = {
@@ -846,6 +926,9 @@ export function createBuildchainContractLock({
       contract: contractWorld.contract,
       contractDigest: contractWorld.contractDigest,
       compatibilityDigest: contractWorld.compatibilityDigest,
+      compatibilityFactRegistryRoot: contractWorld.compatibilityFactRegistryRoot,
+      compatibilityFactCutRoot: contractWorld.compatibilityFactCutRoot,
+      compatibilityProofRegistryRoot: contractWorld.compatibilityProofRegistryRoot,
       majorLine: contractWorld.majorLine,
       compatibilityPolicy,
       acceptedAt,
@@ -853,6 +936,8 @@ export function createBuildchainContractLock({
         id: entry.id,
         kind: entry.kind,
         breakingDigest: entry.breakingDigest,
+        compatibilityProofRoots: entry.compatibilityProofRoots || [],
+        compatibilityFactRoots: entry.compatibilityFactRoots || [],
       })),
     },
   };
@@ -889,143 +974,8 @@ 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 evaluateBuildchainContractLock(options = {}) {
+  return evaluateFactBackedBuildchainContractLock(options);
 }
 
 export function contractSummary(contractWorld, runtimeRef = "", runtimeSha = "") {
@@ -1035,6 +985,9 @@ export function contractSummary(contractWorld, runtimeRef = "", runtimeSha = "")
     contract: contractWorld.contract,
     contractDigest: contractWorld.contractDigest,
     compatibilityDigest: contractWorld.compatibilityDigest,
+    compatibilityFactRegistryRoot: contractWorld.compatibilityFactRegistryRoot,
+    compatibilityFactCutRoot: contractWorld.compatibilityFactCutRoot,
+    compatibilityProofRegistryRoot: contractWorld.compatibilityProofRegistryRoot,
     majorLine: contractWorld.majorLine,
     surfaceCount: Array.isArray(contractWorld.surfaces) ? contractWorld.surfaces.length : 0,
   };