@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.55

package/packages/core/buildchain-delivery-self-dogfood.js

@@ -0,0 +1,395 @@
+import { initAdopterManifest } from "@kungfu-tech/kfd/adopter-conformance/toolchain";
+
+import { adopterDeliveryGateDigest } from "./adopter-delivery-gate.js";
+import { withPublishedBuildchainDeliveryAuthority } from "./published-delivery-authority.js";
+
+export const BUILDCHAIN_DELIVERY_SELF_DOGFOOD_CONTRACT =
+  "kungfu-buildchain-delivery-infrastructure-self-dogfood/v1";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const BUILDCHAIN_PACKAGE = "@kungfu-tech/buildchain";
+const KFD_PACKAGE = "@kungfu-tech/kfd";
+const PROFILE_REQUIREMENTS = Object.freeze([
+  ["adopter-identity", ["declaration"]],
+  ["artifact-readback", ["verification"]],
+  ["claim-boundary", ["declaration"]],
+  ["delivery-policy-cut", ["declaration", "verification"]],
+  ["kfd-cut", ["verification"]],
+  ["protected-delivery", ["implementation", "review", "verification"]],
+  ["source-artifact", ["implementation"]],
+]);
+
+function exactPackage(value, { name, version = "", root = "", label }) {
+  if (
+    value?.name !== name ||
+    typeof value.version !== "string" ||
+    value.version.length === 0 ||
+    !ROOT_PATTERN.test(value.artifactRoot ?? "")
+  ) {
+    throw new TypeError(`${label} package identity is incomplete`);
+  }
+  if (version && value.version !== version) {
+    throw new TypeError(`${label} package version does not match its binding`);
+  }
+  if (root && value.artifactRoot !== root) {
+    throw new TypeError(`${label} package root does not match its binding`);
+  }
+  return structuredClone(value);
+}
+
+function authorityFunctions(authorityRuntime) {
+  const names = [
+    "createBuildchainDeliveryInfrastructureInstanceManifest",
+    "verifyBuildchainDeliveryInfrastructureInstance",
+    "createAdopterDeliveryGate",
+    "createPackageArtifactProfile",
+    "createKfdAdopterCategoryProtocolDriver",
+    "qualifyBuildchainDeliveryInfrastructureBootstrap",
+  ];
+  for (const name of names) {
+    if (typeof authorityRuntime?.[name] !== "function") {
+      throw new TypeError(`authority runtime is missing ${name}`);
+    }
+  }
+  return authorityRuntime;
+}
+
+function passed(value, label) {
+  if (value?.status !== "passed") {
+    throw new Error(
+      `${label} failed closed: ${JSON.stringify(value?.issues ?? [])}`,
+    );
+  }
+  return value;
+}
+
+function candidateWarrant(candidate) {
+  const terminal = candidate?.terminal;
+  if (
+    candidate?.status !== "merged" ||
+    !SHA_PATTERN.test(candidate?.sourceHead ?? "") ||
+    !ROOT_PATTERN.test(candidate?.sourceProofRoot ?? "") ||
+    terminal?.outcome !== "merged" ||
+    !ROOT_PATTERN.test(terminal?.nativeProofRoot ?? "") ||
+    !ROOT_PATTERN.test(terminal?.evidenceRoot ?? "")
+  ) {
+    throw new TypeError("candidate Warrant settlement is incomplete");
+  }
+  return {
+    outcome: "merged",
+    sourceHead: candidate.sourceHead,
+    sourceProofRoot: candidate.sourceProofRoot,
+    nativeProofRoot: terminal.nativeProofRoot,
+    integrationProofRoot: terminal.evidenceRoot,
+  };
+}
+
+function deliveryCut() {
+  const protocol = {
+    id: "kfd.adopter-category/instance-manifest",
+    version: "1.0.0",
+  };
+  protocol.root = adopterDeliveryGateDigest(protocol);
+  const profile = {
+    id: "kfd.adopter-category/delivery-infrastructure",
+    version: "1.0.0",
+  };
+  profile.root = adopterDeliveryGateDigest({
+    ...profile,
+    requirements: PROFILE_REQUIREMENTS,
+  });
+  return {
+    gateRoot: adopterDeliveryGateDigest({
+      protocol,
+      profile,
+      artifactProfile: {
+        id: "buildchain.artifact/package",
+        version: "1.0.0",
+      },
+    }),
+    protocol,
+    profile,
+  };
+}
+
+function candidateEvidence({
+  source,
+  artifact,
+  authority,
+  warrant,
+  kfdRoot,
+  observedAt,
+}) {
+  const roots = {
+    "adopter-identity:declaration": source.root,
+    "artifact-readback:verification": artifact.root,
+    "claim-boundary:declaration": adopterDeliveryGateDigest({
+      qualifying: false,
+      selfCertified: false,
+      releaseAuthorized: false,
+    }),
+    "delivery-policy-cut:declaration": authority.gateRoot,
+    "delivery-policy-cut:verification": warrant.integrationProofRoot,
+    "kfd-cut:verification": kfdRoot,
+    "protected-delivery:implementation": artifact.root,
+    "protected-delivery:review": warrant.sourceProofRoot,
+    "protected-delivery:verification": warrant.nativeProofRoot,
+    "source-artifact:implementation": source.root,
+  };
+  return PROFILE_REQUIREMENTS.flatMap(([requirementId, kinds]) =>
+    kinds.map((kind) => ({
+      requirementId,
+      kind,
+      coordinate: `evidence://kungfu-systems/buildchain/${requirementId}/${kind}`,
+      root: roots[`${requirementId}:${kind}`],
+      observedAt,
+    })),
+  );
+}
+
+export function createBuildchainDeliveryInfrastructureSelfDogfood(
+  {
+    authorityPackage,
+    kfdPackage,
+    authority,
+    candidate,
+    instanceId,
+    adopterManifest,
+    source,
+    artifact,
+    release,
+    evidence = [],
+    warrant,
+    transitionEvidence,
+    verifiedAt,
+    maxAgeSeconds,
+  } = {},
+  authorityRuntime,
+) {
+  const runtime = authorityFunctions(authorityRuntime);
+  const boundAuthorityPackage = exactPackage(authorityPackage, {
+    name: BUILDCHAIN_PACKAGE,
+    version: authority?.version,
+    root: authority?.packageRoot,
+    label: "Buildchain authority",
+  });
+  const boundKfdPackage = exactPackage(kfdPackage, {
+    name: KFD_PACKAGE,
+    version: adopterManifest?.kfdCut?.package?.version,
+    root: adopterManifest?.kfdCut?.package?.artifactRoot,
+    label: "KFD authority",
+  });
+  if (candidate?.authorityVersion !== boundAuthorityPackage.version) {
+    throw new TypeError(
+      "candidate does not name the exact Buildchain N-1 authority",
+    );
+  }
+
+  const instanceManifest =
+    runtime.createBuildchainDeliveryInfrastructureInstanceManifest({
+      instanceId,
+      adopterManifest,
+      source,
+      artifact,
+      release,
+      evidence,
+    });
+  const instanceReport = runtime.verifyBuildchainDeliveryInfrastructureInstance(
+    instanceManifest,
+    {
+      adopterManifest,
+      verifiedAt,
+      maxAgeSeconds,
+    },
+  );
+  if (instanceReport?.valid !== true) {
+    throw new Error(
+      `delivery-infrastructure instance failed closed: ${JSON.stringify(instanceReport?.issues ?? [])}`,
+    );
+  }
+
+  const gateResult = passed(
+    runtime
+      .createAdopterDeliveryGate({
+        drivers: [runtime.createKfdAdopterCategoryProtocolDriver()],
+        artifactProfiles: [runtime.createPackageArtifactProfile()],
+      })
+      .evaluate(
+        {
+          schemaVersion: 1,
+          contract: "kungfu-buildchain-adopter-delivery-request",
+          protocol: {
+            id: "kfd.adopter-category/instance-manifest",
+            version: "1.0.0",
+          },
+          artifactProfile: {
+            id: "buildchain.artifact/package",
+            version: "1.0.0",
+          },
+          project: {
+            instanceId,
+            adopterId: "kungfu-systems/buildchain",
+          },
+          artifact: structuredClone(artifact),
+          declaration: instanceManifest,
+        },
+        { adopterManifest, verifiedAt, maxAgeSeconds },
+      ),
+    "adopter delivery gate",
+  );
+  const bootstrap = passed(
+    runtime.qualifyBuildchainDeliveryInfrastructureBootstrap({
+      authority,
+      candidate,
+      gateResult,
+      warrant,
+      transitionEvidence,
+    }),
+    "delivery-infrastructure bootstrap",
+  );
+
+  const result = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_DELIVERY_SELF_DOGFOOD_CONTRACT,
+    status: "passed",
+    authorityRuntime: {
+      buildchainPackage: boundAuthorityPackage,
+      kfdPackage: boundKfdPackage,
+    },
+    candidate: structuredClone(candidate),
+    roots: {
+      adopterManifest: adopterDeliveryGateDigest(adopterManifest),
+      instanceManifest: adopterDeliveryGateDigest(instanceManifest),
+      instanceReport: adopterDeliveryGateDigest(instanceReport),
+      gateResult: gateResult.gateRoot,
+      bootstrap: bootstrap.bootstrapRoot,
+      warrant: adopterDeliveryGateDigest(warrant),
+    },
+    instanceManifest,
+    instanceReport,
+    gateResult,
+    bootstrap,
+    qualifying: false,
+    selfCertified: false,
+    releaseAuthorized: false,
+    finalAuthority:
+      "protected-n-minus-one-runtime-plus-exact-delivery-evidence",
+  };
+  result.selfDogfoodRoot = adopterDeliveryGateDigest(result);
+  return result;
+}
+
+export async function createPublishedBuildchainDeliveryInfrastructureSelfDogfood({
+  authorityPackages,
+  selfDogfood,
+} = {}) {
+  return withPublishedBuildchainDeliveryAuthority(
+    authorityPackages,
+    async ({ packages, authorityRuntime, authorityRoot }) => {
+      const result = createBuildchainDeliveryInfrastructureSelfDogfood(
+        {
+          ...structuredClone(selfDogfood ?? {}),
+          authorityPackage: packages.buildchain,
+          kfdPackage: packages.kfd,
+        },
+        authorityRuntime,
+      );
+      return {
+        ...result,
+        publishedAuthorityRoot: authorityRoot,
+      };
+    },
+  );
+}
+
+export async function createPublishedBuildchainDeliveryInfrastructureCandidateSelfDogfood({
+  authorityPackages,
+  authoritySourceCommit,
+  candidatePackage,
+  warrantCandidate,
+  source,
+  release,
+  verifiedAt,
+  maxAgeSeconds = 86400,
+} = {}) {
+  if (!SHA_PATTERN.test(authoritySourceCommit ?? "")) {
+    throw new TypeError("authority source commit is invalid");
+  }
+  const artifact = exactPackage(candidatePackage, {
+    name: BUILDCHAIN_PACKAGE,
+    label: "Buildchain candidate",
+  });
+  if (
+    source?.coordinate !==
+      `kungfu-systems/buildchain@${warrantCandidate?.sourceHead ?? ""}` ||
+    !ROOT_PATTERN.test(source?.root ?? "") ||
+    !ROOT_PATTERN.test(release?.root ?? "")
+  ) {
+    throw new TypeError("candidate source or release binding is incomplete");
+  }
+  const warrant = candidateWarrant(warrantCandidate);
+  const cut = deliveryCut();
+  const authority = {
+    version: authorityPackages?.buildchain?.version,
+    sourceCommit: authoritySourceCommit,
+    packageRoot: authorityPackages?.buildchain?.artifactRoot,
+    ...cut,
+    protected: true,
+    published: true,
+  };
+  const candidate = {
+    version: artifact.version,
+    sourceCommit: warrant.sourceHead,
+    packageRoot: artifact.artifactRoot,
+    ...cut,
+    authorityVersion: authority.version,
+  };
+  const adopterManifest = initAdopterManifest({
+    manifestId: `buildchain-delivery-infrastructure-${artifact.version}`,
+    adopterId: "kungfu-systems/buildchain",
+    artifactKind: "package",
+    artifactCoordinate: `${artifact.name}@${artifact.version}`,
+    artifactRoot: artifact.artifactRoot,
+    scope: "Buildchain delivery infrastructure release candidate self-dogfood",
+    packageArtifactRoot: authorityPackages?.kfd?.artifactRoot,
+    verifiedAt,
+    maxAgeSeconds,
+  });
+  adopterManifest.releaseBindings.push({
+    id: `buildchain-${artifact.version}`,
+    artifact: {
+      kind: "package",
+      coordinate: `${artifact.name}@${artifact.version}`,
+      root: artifact.artifactRoot,
+    },
+    releasePassport: structuredClone(release),
+    kfdPackageRoot: authorityPackages.kfd.artifactRoot,
+  });
+  const evidence = candidateEvidence({
+    source,
+    artifact: adopterManifest.releaseBindings[0].artifact,
+    authority,
+    warrant,
+    kfdRoot: authorityPackages.kfd.artifactRoot,
+    observedAt: verifiedAt,
+  });
+  const result =
+    await createPublishedBuildchainDeliveryInfrastructureSelfDogfood({
+      authorityPackages,
+      selfDogfood: {
+        authority,
+        candidate,
+        instanceId: `kungfu-systems/buildchain@${artifact.version}`,
+        adopterManifest,
+        source,
+        artifact: adopterManifest.releaseBindings[0].artifact,
+        release,
+        evidence,
+        warrant,
+        verifiedAt,
+        maxAgeSeconds,
+      },
+    });
+  return { ...result, adopterManifest, deliveryEvidence: evidence };
+}

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

@@ -29,6 +29,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-patrol-monthly.yml", "governance-write"],
   [".github/workflows/buildchain-patrol-weekly.yml", "governance-write"],
   [".github/workflows/buildchain-patrol.yml", "governance-write"],
+  [".github/workflows/buildchain-ref-promotion-recovery.yml", "governance-write"],
   [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-qualification-patrol.yml", "governance-write"],
@@ -57,6 +58,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/release-tail.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "caller-bound", "caller-bound", "fixed"],
   [".github/workflows/release-verify.yml", "governance-write"],
   [".github/workflows/stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/v4-declarative-release-tail-dogfood.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "none", "fixed", "fixed"],
 ]);
 
 export function buildchainPublicationAuthorityDescriptors() {

package/packages/core/ci-lane-change-budget.js

@@ -0,0 +1,247 @@
+import crypto from "node:crypto";
+import { parseWorkflowDocument } from "./workflow-yaml-contract.js";
+
+export const CI_LANE_CHANGE_BUDGET_CONTRACT =
+  "buildchain.ci-lane-change-budget/v1";
+
+const AUTHORITY_CLASSES = new Set([
+  "merge-critical-required",
+  "merge-critical-admission",
+  "post-merge-advisory",
+  "diagnostic",
+  "evidence",
+  "release",
+]);
+const TRIGGER_CLASSES = new Set([
+  "merge-group",
+  "pull-request",
+  "push",
+  "scheduled",
+  "manual",
+  "reusable",
+  "release",
+  "mixed",
+]);
+const CONCURRENCY_MODES = new Set([
+  "none",
+  "ref-scoped",
+  "workflow-scoped",
+  "serialized",
+]);
+const CANCELLATION_BEHAVIORS = new Set([
+  "cancel-stale",
+  "finish-started",
+  "provider-default",
+  "not-applicable",
+]);
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonical(value[key])]),
+    );
+  }
+  return value;
+}
+
+function root(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function triggerClass(triggers) {
+  const classes = new Set();
+  for (const trigger of triggers) {
+    if (trigger === "merge_group") classes.add("merge-group");
+    else if (trigger.startsWith("pull_request")) classes.add("pull-request");
+    else if (trigger === "push") classes.add("push");
+    else if (trigger === "schedule") classes.add("scheduled");
+    else if (trigger === "workflow_dispatch") classes.add("manual");
+    else if (trigger === "workflow_call") classes.add("reusable");
+    else if (trigger === "release") classes.add("release");
+    else classes.add("mixed");
+  }
+  return classes.size === 1 ? [...classes][0] : "mixed";
+}
+
+function diagnostic(code, laneId, message) {
+  return { code, laneId, message };
+}
+
+function validateDeclaration(declaration, observed) {
+  const laneId = String(declaration?.laneId || "");
+  const diagnostics = [];
+  if (!AUTHORITY_CLASSES.has(declaration?.authorityClass)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-authority-class",
+        laneId,
+        "authorityClass must identify the lane's merge or non-merge authority",
+      ),
+    );
+  }
+  if (!TRIGGER_CLASSES.has(declaration?.triggerClass)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-trigger-class",
+        laneId,
+        "triggerClass must identify the workflow trigger class",
+      ),
+    );
+  } else if (observed && declaration.triggerClass !== observed.triggerClass) {
+    diagnostics.push(
+      diagnostic(
+        "trigger-class-mismatch",
+        laneId,
+        `declared ${declaration.triggerClass}, observed ${observed.triggerClass}`,
+      ),
+    );
+  }
+  const concurrency = declaration?.concurrencyPolicy;
+  if (
+    !concurrency ||
+    !CONCURRENCY_MODES.has(concurrency.mode) ||
+    typeof concurrency.cancelInProgress !== "boolean"
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-concurrency-policy",
+        laneId,
+        "concurrencyPolicy requires a known mode and boolean cancelInProgress",
+      ),
+    );
+  }
+  if (
+    !Number.isFinite(declaration?.expectedRunnerMinutes) ||
+    declaration.expectedRunnerMinutes <= 0
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-runner-budget",
+        laneId,
+        "expectedRunnerMinutes must be greater than zero",
+      ),
+    );
+  }
+  if (!CANCELLATION_BEHAVIORS.has(declaration?.cancellationBehavior)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-cancellation-behavior",
+        laneId,
+        "cancellationBehavior must describe how stale or started work settles",
+      ),
+    );
+  }
+  const impact = declaration?.sloImpact;
+  if (
+    !impact ||
+    typeof impact.mergeCritical !== "boolean" ||
+    !String(impact.metric || "").trim() ||
+    !Number.isFinite(impact.expectedContributionSeconds) ||
+    impact.expectedContributionSeconds < 0 ||
+    !String(impact.rationale || "").trim()
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-slo-impact",
+        laneId,
+        "sloImpact requires mergeCritical, metric, expectedContributionSeconds, and rationale",
+      ),
+    );
+  }
+  return diagnostics;
+}
+
+function collectLanes(workflows) {
+  const lanes = new Map();
+  for (const workflow of workflows) {
+    const workflowPath = String(workflow?.path || "").trim();
+    if (!workflowPath) throw new Error("workflow path is required");
+    const document = parseWorkflowDocument(workflow.text);
+    for (const job of document.jobs) {
+      const laneId = `${workflowPath}#${job.id}`;
+      if (lanes.has(laneId)) throw new Error(`duplicate CI lane: ${laneId}`);
+      lanes.set(laneId, {
+        laneId,
+        workflowPath,
+        jobId: job.id,
+        triggerClass: triggerClass(document.triggers),
+      });
+    }
+  }
+  return lanes;
+}
+
+export function evaluateCiLaneChangeBudget({
+  policy,
+  workflows,
+  baselineWorkflows = null,
+} = {}) {
+  if (policy?.schema !== CI_LANE_CHANGE_BUDGET_CONTRACT) {
+    throw new Error(`expected ${CI_LANE_CHANGE_BUDGET_CONTRACT}`);
+  }
+  if (!Array.isArray(workflows)) throw new Error("workflows must be an array");
+  const observed = collectLanes(workflows);
+  const baselineLaneIds = baselineWorkflows
+    ? [...collectLanes(baselineWorkflows).keys()]
+    : policy.baseline?.lanes || [];
+  const baseline = new Set(baselineLaneIds);
+  if (baseline.size !== baselineLaneIds.length) {
+    throw new Error("baseline CI lanes must be unique");
+  }
+  const declarations = new Map();
+  const diagnostics = [];
+  for (const declaration of policy.declarations || []) {
+    const laneId = String(declaration?.laneId || "").trim();
+    if (!laneId) throw new Error("CI lane declaration laneId is required");
+    if (declarations.has(laneId))
+      throw new Error(`duplicate CI lane declaration: ${laneId}`);
+    declarations.set(laneId, declaration);
+    if (!observed.has(laneId)) {
+      diagnostics.push(
+        diagnostic(
+          "stale-declaration",
+          laneId,
+          "declared CI lane is absent from the current workflow cut",
+        ),
+      );
+    }
+    diagnostics.push(
+      ...validateDeclaration(declaration, observed.get(laneId) || null),
+    );
+  }
+  const newLanes = [...observed.keys()]
+    .filter((laneId) => !baseline.has(laneId))
+    .sort();
+  for (const laneId of newLanes) {
+    if (!declarations.has(laneId)) {
+      diagnostics.push(
+        diagnostic(
+          "undeclared-new-lane",
+          laneId,
+          "new CI lane must declare authority, trigger, concurrency, runner, cancellation, and SLO budgets",
+        ),
+      );
+    }
+  }
+  const result = {
+    schema: "buildchain.ci-lane-change-budget.evaluation/v1",
+    ok: diagnostics.length === 0,
+    observedLaneCount: observed.size,
+    baselineLaneCount: baseline.size,
+    newLaneCount: newLanes.length,
+    declaredLaneCount: declarations.size,
+    newLanes,
+    diagnostics: diagnostics.sort((left, right) =>
+      `${left.laneId}:${left.code}`.localeCompare(
+        `${right.laneId}:${right.code}`,
+      ),
+    ),
+  };
+  return { ...result, evaluationRoot: root(result) };
+}