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

package/packages/core/artifact-signing.js

@@ -9,6 +9,7 @@ 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;
 
@@ -88,6 +89,64 @@ 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)) {
@@ -191,6 +250,7 @@ export function createArtifactSigningRequest({
     platform,
     artifactKind: kind,
   });
+  const entitlementIntent = signingEntitlements(profile.id, kind, signature);
   const request = {
     schemaVersion: 1,
     contract: ARTIFACT_SIGNING_REQUEST_CONTRACT,
@@ -253,6 +313,7 @@ export function createArtifactSigningRequest({
       profile: profile.id,
       provider: profile.provider,
       semantics: profile.semantics,
+      ...entitlementIntent,
     },
     delivery: {
       mode: nonEmptyString(

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

@@ -10,6 +10,7 @@ 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" },
@@ -29,10 +30,12 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
   { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
   { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
+  { id: "v4-adopter-delivery", title: "V4 public adopter delivery", path: "docs/v4-adopter-delivery.md", plane: "verify" },
   { 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: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
+  { id: "v4-compatibility-facts", title: "Buildchain v4 compatibility Facts", path: "docs/v4-compatibility-facts.md", plane: "verify" },
   { 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" },
   { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },

package/packages/core/buildchain-compatibility-authority.js

@@ -0,0 +1,336 @@
+import {
+  devDeliveryContentRoot as contentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryText as text,
+} from "./dev-delivery-common.js";
+import {
+  BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_RELEASE_EVIDENCE_SCHEMA,
+  createBuildchainCompatibilityFactRegistry,
+  createHistoricalBuildchainCompatibilityProofs,
+  verifyBuildchainCompatibilityProof,
+} from "./buildchain-compatibility-fact.js";
+import {
+  KUNGFU_TEMPORAL_PATH_QUERY_SCHEMA,
+  verifyKungfuTemporalPath,
+} from "./kungfu-temporal-fact.js";
+
+const COMPATIBILITY_OPERATION = "accept-contract-lock";
+const COMPATIBILITY_DIRECTION = "source-to-target";
+
+function exactText(value, label) {
+  const normalized = text(value);
+  if (!normalized) throw new Error(`${label} must not be empty`);
+  return normalized;
+}
+
+function factInputFromProof(proof) {
+  return {
+    proofId: proof.proofId,
+    surfaceId: proof.source.surfaceId,
+    surfaceKind: proof.source.surfaceKind,
+    sourceBreakingDigest: proof.source.breakingDigest,
+    targetBreakingDigest: proof.target.breakingDigest,
+    scope: proof.scope,
+    evidence: proof.evidence,
+    authority: proof.authority,
+    cut: proof.cut,
+  };
+}
+
+function projectionForSurface({ proofs, factByProofRoot, surface }) {
+  const matching = proofs.filter(
+    (proof) =>
+      proof.target.surfaceId === surface.id &&
+      proof.target.surfaceKind === surface.kind &&
+      proof.target.breakingDigest === surface.breakingDigest &&
+      proof.operation === COMPATIBILITY_OPERATION,
+  );
+  const bySource = new Map();
+  for (const proof of matching) {
+    const sourceDigest = proof.source.breakingDigest;
+    if (bySource.has(sourceDigest))
+      throw new Error(
+        `ambiguous compatibility proof for ${surface.id} ${sourceDigest}`,
+      );
+    bySource.set(sourceDigest, proof);
+  }
+  return [...bySource.values()]
+    .sort((left, right) =>
+      left.source.breakingDigest.localeCompare(right.source.breakingDigest),
+    )
+    .map((proof) => ({
+      breakingDigest: proof.source.breakingDigest,
+      proofRoot: proof.proofRoot,
+      factRoot: factByProofRoot.get(proof.proofRoot)?.factRoot || "",
+    }));
+}
+
+export function createBuildchainCompatibilityProofRegistry({
+  proofs = createHistoricalBuildchainCompatibilityProofs(),
+  surfaces = [],
+  majorLine = "",
+} = {}) {
+  const verifiedProofs = proofs
+    .map((proof) => {
+      const verification = verifyBuildchainCompatibilityProof(proof);
+      if (!verification.ok)
+        throw new Error(
+          `invalid compatibility proof: ${verification.reason}${verification.error ? `: ${verification.error}` : ""}`,
+        );
+      return verification.proof;
+    })
+    .sort((left, right) => left.proofRoot.localeCompare(right.proofRoot));
+  const factRegistry = createBuildchainCompatibilityFactRegistry({
+    factInputs: verifiedProofs.map(factInputFromProof),
+  });
+  const factByProofRoot = new Map(
+    factRegistry.facts.map((fact) => [fact.proof.proofRoot, fact]),
+  );
+  const projections = Object.fromEntries(
+    [...surfaces]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((surface) => [
+        surface.id,
+        projectionForSurface({
+          proofs: verifiedProofs,
+          factByProofRoot,
+          surface,
+        }),
+      ])
+      .filter(([, entries]) => entries.length > 0),
+  );
+  const identity = {
+    schema: BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+    proofRoots: verifiedProofs.map((proof) => proof.proofRoot),
+  };
+  return {
+    ...identity,
+    proofs: verifiedProofs,
+    facts: factRegistry.facts,
+    factRegistry,
+    factRegistryRoot: factRegistry.registryRoot,
+    factCutRoot: factRegistry.currentCutRoot,
+    projections,
+    registryRoot: contentRoot(identity),
+  };
+}
+
+export function assertBuildchainCompatibilityProjection(contractWorld) {
+  if (
+    !Array.isArray(contractWorld?.compatibilityFacts) ||
+    !Array.isArray(contractWorld?.compatibilityProofs)
+  ) {
+    throw new Error(
+      "compatibility Facts and their proof projection are required",
+    );
+  }
+  const registry = createBuildchainCompatibilityProofRegistry({
+    proofs: contractWorld.compatibilityProofs,
+    surfaces: contractWorld.surfaces || [],
+    majorLine: contractWorld.majorLine,
+  });
+  if (contractWorld.compatibilityProofRegistryRoot !== registry.registryRoot) {
+    throw new Error("compatibility proof registry root mismatch");
+  }
+  if (
+    contractWorld.compatibilityFactRegistryRoot !== registry.factRegistryRoot
+  ) {
+    throw new Error("compatibility Fact registry root mismatch");
+  }
+  if (contractWorld.compatibilityFactCutRoot !== registry.factCutRoot) {
+    throw new Error("compatibility Fact Cut root mismatch");
+  }
+  if (
+    JSON.stringify(contractWorld.compatibilityFacts) !==
+    JSON.stringify(registry.facts)
+  ) {
+    throw new Error("compatibility Facts drift from the verified registry");
+  }
+  for (const surface of contractWorld.surfaces || []) {
+    const expected = registry.projections[surface.id] || [];
+    const expectedDigests = expected.map((entry) => entry.breakingDigest);
+    const expectedRoots = expected.map((entry) => entry.proofRoot);
+    const expectedFactRoots = expected.map((entry) => entry.factRoot);
+    const actualDigests = surface.compatibleBreakingDigests || [];
+    const actualRoots = surface.compatibilityProofRoots || [];
+    const actualFactRoots = surface.compatibilityFactRoots || [];
+    if (JSON.stringify(actualDigests) !== JSON.stringify(expectedDigests)) {
+      throw new Error(
+        `compatibleBreakingDigests projection mismatch for ${surface.id}`,
+      );
+    }
+    if (JSON.stringify(actualRoots) !== JSON.stringify(expectedRoots)) {
+      throw new Error(
+        `compatibilityProofRoots projection mismatch for ${surface.id}`,
+      );
+    }
+    if (JSON.stringify(actualFactRoots) !== JSON.stringify(expectedFactRoots)) {
+      throw new Error(
+        `compatibilityFactRoots projection mismatch for ${surface.id}`,
+      );
+    }
+  }
+  return {
+    ok: true,
+    reason: "exact-Fact-backed-projection",
+    registryRoot: registry.registryRoot,
+    factRegistryRoot: registry.factRegistryRoot,
+    factCutRoot: registry.factCutRoot,
+  };
+}
+
+export function verifyBuildchainCompatibilityPath({ registry, query } = {}) {
+  if (!registry?.temporalBundle)
+    throw new Error("compatibility Fact registry is required");
+  return verifyKungfuTemporalPath(registry.temporalBundle, query);
+}
+
+export function createBuildchainCompatibilityPathQuery({
+  registry,
+  queryId,
+  sourceRoot,
+  targetRoot,
+  relationPathRoots,
+  maxDepth = 1,
+} = {}) {
+  if (!registry?.temporalBundle || registry.predicateRoots?.length !== 1) {
+    throw new Error(
+      "one exact compatibility Fact registry predicate is required",
+    );
+  }
+  const predicateRoot = registry.predicateRoots[0];
+  const predicate = registry.temporalBundle.predicates.find(
+    (entry) => entry.root === predicateRoot,
+  )?.record;
+  return {
+    schema: KUNGFU_TEMPORAL_PATH_QUERY_SCHEMA,
+    queryId: exactText(queryId, "queryId"),
+    operation: COMPATIBILITY_OPERATION,
+    predicateRoot,
+    sourceRoot: exactRoot(sourceRoot, "sourceRoot"),
+    targetRoot: exactRoot(targetRoot, "targetRoot"),
+    cutRoot: exactRoot(registry.currentCutRoot, "currentCutRoot"),
+    relationPathRoots: (relationPathRoots || []).map((entry) =>
+      exactRoot(entry, "relationPathRoot"),
+    ),
+    requiredAuthorityRoot: exactRoot(
+      predicate?.authorityRoot,
+      "requiredAuthorityRoot",
+    ),
+    maxDepth,
+  };
+}
+
+export function resolveBuildchainCompatibilityProof({
+  registry,
+  surface,
+  sourceBreakingDigest,
+  majorLine,
+} = {}) {
+  const candidates = (registry?.proofs || []).filter(
+    (proof) =>
+      proof.source.surfaceId === surface.id &&
+      proof.source.surfaceKind === surface.kind &&
+      proof.source.breakingDigest === sourceBreakingDigest &&
+      proof.target.breakingDigest === surface.breakingDigest &&
+      proof.operation === COMPATIBILITY_OPERATION,
+  );
+  if (candidates.length === 0)
+    return { ok: false, reason: "compatibility-proof-missing" };
+  if (candidates.length > 1)
+    return { ok: false, reason: "ambiguous-compatibility-proof" };
+  const verification = verifyBuildchainCompatibilityProof(candidates[0]);
+  if (!verification.ok) return verification;
+  const projection = registry.projections?.[surface.id] || [];
+  if (
+    !projection.some(
+      (entry) =>
+        entry.breakingDigest === sourceBreakingDigest &&
+        entry.proofRoot === verification.proofRoot,
+    )
+  ) {
+    return { ok: false, reason: "compatibility-proof-projection-missing" };
+  }
+  const fact = registry.factRegistry?.facts.find(
+    (entry) => entry.proof.proofRoot === verification.proofRoot,
+  );
+  if (!fact) return { ok: false, reason: "compatibility-fact-missing" };
+  const query = createBuildchainCompatibilityPathQuery({
+    registry: registry.factRegistry,
+    queryId: `buildchain:compatibility:${surface.id}:${sourceBreakingDigest}:${surface.breakingDigest}`,
+    sourceRoot: fact.sourceRoot,
+    targetRoot: fact.targetRoot,
+    relationPathRoots: [fact.factRoot],
+    maxDepth: 1,
+  });
+  const pathReceipt = verifyBuildchainCompatibilityPath({
+    registry: registry.factRegistry,
+    query,
+  });
+  if (pathReceipt.record.status !== "accepted") {
+    return {
+      ok: false,
+      reason: pathReceipt.record.failureCode,
+      pathReceipt,
+      pathReceiptRoot: pathReceipt.root,
+    };
+  }
+  return {
+    ok: true,
+    reason: "Fact-backed-compatible-relation",
+    proof: verification.proof,
+    proofRoot: verification.proofRoot,
+    fact,
+    factRoot: fact.factRoot,
+    pathReceipt,
+    pathReceiptRoot: pathReceipt.root,
+  };
+}
+
+export function createBuildchainCompatibilityReleaseEvidence({
+  contractWorld,
+  release,
+  decisions = [],
+} = {}) {
+  const projection = assertBuildchainCompatibilityProjection(contractWorld);
+  const normalizedRelease = {
+    sourceSha: exactSha(release?.sourceSha, "release.sourceSha"),
+    tag: exactText(release?.tag, "release.tag"),
+    channel: exactText(release?.channel, "release.channel"),
+  };
+  const rootSet = (field) =>
+    [...new Set(decisions.map((entry) => entry[field]).filter(Boolean))]
+      .map((entry) => exactRoot(entry, field))
+      .sort();
+  const compatibility = {
+    operation: COMPATIBILITY_OPERATION,
+    direction: COMPATIBILITY_DIRECTION,
+    authority: "Fact-registry-only",
+    grantsReleaseAuthority: false,
+    contractDigest: exactRoot(
+      contractWorld.contractDigest,
+      "contractWorld.contractDigest",
+    ),
+    compatibilityDigest: exactRoot(
+      contractWorld.compatibilityDigest,
+      "contractWorld.compatibilityDigest",
+    ),
+    factRegistryRoot: projection.factRegistryRoot,
+    factCutRoot: projection.factCutRoot,
+    proofRegistryRoot: projection.registryRoot,
+    usedFactRoots: rootSet("factRoot"),
+    usedProofRoots: rootSet("proofRoot"),
+    pathReceiptRoots: rootSet("pathReceiptRoot"),
+  };
+  const body = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_COMPATIBILITY_RELEASE_EVIDENCE_SCHEMA,
+    id: "buildchain-compatibility-facts",
+    kind: "compatibility-fact-lineage",
+    release: normalizedRelease,
+    compatibility,
+  };
+  return { ...body, evidenceRoot: contentRoot(body) };
+}