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

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) };
+}

package/packages/core/dev-delivery-native-proof.js

@@ -43,7 +43,39 @@ export const DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA =
 export const NATIVE_PROOF_BASE_DELTA_SCHEMA =
   "kungfu.buildchain.native-proof-base-delta/v1";
 const NATIVE_QUALIFICATION_ROOT_SEMANTICS = "semantic-native-identity-v1";
-export function validateActiveDevDeliveryWarrant(queue) {
+
+function normalizeQualifiedWarrant(warrant, candidate, allowLegacyV3Readback) {
+  const qualifiedV3Readback =
+    allowLegacyV3Readback &&
+    !warrant.nativeCommandContract &&
+    !candidate.nativeCommandContract &&
+    !warrant.nativeExecutionReceiptRoot &&
+    !warrant.qualificationReceiptRoot;
+  warrant.nativeProofRoot = exactRoot(
+    warrant.nativeProofRoot,
+    "Warrant nativeProofRoot",
+  );
+  warrant.nativeProofReuseRoot = exactRoot(
+    warrant.nativeProofReuseRoot,
+    "Warrant nativeProofReuseRoot",
+  );
+  if (!qualifiedV3Readback) {
+    warrant.nativeExecutionReceiptRoot = exactRoot(
+      warrant.nativeExecutionReceiptRoot,
+      "Warrant nativeExecutionReceiptRoot",
+    );
+    warrant.qualificationReceiptRoot = exactRoot(
+      warrant.qualificationReceiptRoot,
+      "Warrant qualificationReceiptRoot",
+    );
+  }
+  warrant.qualifiedAt = timestamp(warrant.qualifiedAt, "Warrant qualifiedAt");
+}
+
+export function validateActiveDevDeliveryWarrant(
+  queue,
+  { allowLegacyV3Readback = false } = {},
+) {
   const warrant = queue.activeWarrant;
   if (warrant.schema !== "kungfu.buildchain.dev-delivery-warrant/v1")
     throw new Error("active Warrant schema is unsupported");
@@ -68,24 +100,17 @@ export function validateActiveDevDeliveryWarrant(queue) {
   const phase = historicalPhaseLess ? "legacy-active" : warrant.phase;
   if (!["legacy-active", "provisional", "qualified"].includes(phase))
     throw new Error("active Warrant phase is unsupported");
-  if (warrant.phase === "qualified") {
-    warrant.nativeProofRoot = exactRoot(
-      warrant.nativeProofRoot,
-      "Warrant nativeProofRoot",
-    );
-    warrant.nativeProofReuseRoot = exactRoot(
-      warrant.nativeProofReuseRoot,
-      "Warrant nativeProofReuseRoot",
-    );
-    warrant.nativeExecutionReceiptRoot = exactRoot(
-      warrant.nativeExecutionReceiptRoot,
-      "Warrant nativeExecutionReceiptRoot",
-    );
-    warrant.qualificationReceiptRoot = exactRoot(
-      warrant.qualificationReceiptRoot,
-      "Warrant qualificationReceiptRoot",
+  const active = queue.candidates.filter((candidate) =>
+    ["selected", "proving", "waiting", "blocked", "qualified"].includes(
+      candidate.status,
+    ),
+  );
+  if (active.length !== 1 || active[0].candidateId !== warrant.candidateId)
+    throw new Error(
+      "exactly one active candidate must match the active Warrant",
     );
-    warrant.qualifiedAt = timestamp(warrant.qualifiedAt, "Warrant qualifiedAt");
+  if (warrant.phase === "qualified") {
+    normalizeQualifiedWarrant(warrant, active[0], allowLegacyV3Readback);
   } else if (
     warrant.phase === "provisional" &&
     (warrant.nativeProofRoot ||
@@ -98,15 +123,6 @@ export function validateActiveDevDeliveryWarrant(queue) {
       "provisional Warrant cannot carry qualified native evidence",
     );
   }
-  const active = queue.candidates.filter((candidate) =>
-    ["selected", "proving", "waiting", "blocked", "qualified"].includes(
-      candidate.status,
-    ),
-  );
-  if (active.length !== 1 || active[0].candidateId !== warrant.candidateId)
-    throw new Error(
-      "exactly one active candidate must match the active Warrant",
-    );
   if (
     historicalPhaseLess &&
     (active[0].environmentRoot ||

package/packages/core/dev-delivery-warrant-state.js

@@ -51,8 +51,8 @@ export const TERMINAL_STATES = new Set([
   "terminal-failure",
   "dequeued",
   "cancelled",
+  "superseded",
 ]);
-
 export function issueDevDeliveryWarrant(
   queue,
   before,
@@ -158,6 +158,21 @@ function normalizePolicy(policy = {}) {
     emergencyPolicy: text(policy.emergencyPolicy || "reviewed-explicit-only"),
   };
 }
+
+function lacksLiveNativeProof(candidate, status, allowLegacyV3Readback) {
+  const { environmentRoot, nativeCommandContract } = candidate;
+  const native =
+    candidate.deliveryClass !== "non-native-fast" ||
+    environmentRoot ||
+    nativeCommandContract;
+  return (
+    native &&
+    (!environmentRoot ||
+      (!nativeCommandContract && allowLegacyV3Readback !== true)) &&
+    !TERMINAL_STATES.has(status)
+  );
+}
+
 function normalizeCandidate(input, expected) {
   const identity = createDevDeliveryCandidateIdentity(
     input,
@@ -246,9 +261,7 @@ function normalizeCandidate(input, expected) {
       "candidate shardEvidenceRoots",
     );
   }
-  const { environmentRoot: env, nativeCommandContract: cmd } = candidate;
-  const native = candidate.deliveryClass !== "non-native-fast" || env || cmd;
-  if (native && (!env || !cmd) && !TERMINAL_STATES.has(status))
+  if (lacksLiveNativeProof(candidate, status, expected.allowLegacyV3Readback))
     throw new Error("live native candidate requires exact native proof");
   if (Object.hasOwn(input, "releaseBlockerPriority"))
     candidate.releaseBlockerPriority = normalizeReleaseBlockerPriorityClaim(
@@ -318,13 +331,21 @@ export function normalizeDevDeliveryQueue(input, expected = {}) {
     "queue fencingCounter",
   );
   queue.policy = normalizePolicy(queue.policy);
+  const allowLegacyV3Readback =
+    expected.allowLegacyV3Readback === true &&
+    !(queue.candidates || []).some(
+      (candidate) => candidate?.nativeCommandContract,
+    ) &&
+    !queue.activeWarrant?.nativeCommandContract &&
+    !queue.activeWarrant?.nativeExecutionReceiptRoot &&
+    !queue.activeWarrant?.qualificationReceiptRoot;
   queue.candidates = (queue.candidates || []).map((candidate) =>
-    normalizeCandidate(candidate, queue),
+    normalizeCandidate(candidate, { ...queue, allowLegacyV3Readback }),
   );
   validateDevDeliveryCandidateChain(queue.candidates, TERMINAL_STATES);
   queue.updatedAt = timestamp(queue.updatedAt, "queue updatedAt");
   if (queue.activeWarrant) {
-    validateActiveDevDeliveryWarrant(queue);
+    validateActiveDevDeliveryWarrant(queue, { allowLegacyV3Readback });
   } else if (
     queue.candidates.some((candidate) =>
       ["selected", "proving", "waiting", "blocked", "qualified"].includes(
@@ -544,9 +565,11 @@ function effectivePriority(candidate, policy, now) {
 }
 export function rankDevDeliveryCandidates(
   queueInput,
-  { now = new Date().toISOString() } = {},
+  { now = new Date().toISOString(), allowLegacyV3Readback = false } = {},
 ) {
-  const queue = normalizeDevDeliveryQueue(queueInput);
+  const queue = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback,
+  });
   const currentTime = timestamp(now, "now");
   return queue.candidates
     .filter((candidate) => candidate.status === "queued")

package/packages/core/dev-delivery-warrant.js

@@ -516,14 +516,19 @@ export const settleDevDeliveryTerminalEvent = createDevDeliveryTerminalSettler({
 });
 export function observeDevDeliveryQueue(
   queueInput,
-  { now = new Date().toISOString() } = {},
+  { now = new Date().toISOString(), allowLegacyV3Readback = false } = {},
 ) {
-  const queue = normalizeDevDeliveryQueue(queueInput);
+  const queue = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback,
+  });
   const currentTime = timestamp(now, "now");
   const states = {};
   for (const candidate of queue.candidates)
     states[candidate.status] = (states[candidate.status] || 0) + 1;
-  const queued = rankDevDeliveryCandidates(queue, { now: currentTime });
+  const queued = rankDevDeliveryCandidates(queue, {
+    now: currentTime,
+    allowLegacyV3Readback,
+  });
   return {
     schema: "kungfu.buildchain.dev-delivery-queue-observation/v1",
     repository: queue.repository,

package/packages/core/github-governance-authority.js

@@ -116,6 +116,7 @@ const PROTECTED_AUTHORITY_PATHS = Object.freeze([
   ".github/CODEOWNERS",
   ".github/workflows/.publication-authority.yml",
   ".github/workflows/.release-candidate-promote.yml",
+  ".github/workflows/buildchain-ref-promotion-recovery.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
   ".github/workflows/github-governance-audit.yml",
   ".github/workflows/paper-release-sealed.yml",

package/packages/core/index.js

@@ -139,6 +139,11 @@ export {
   normalizeCandidateTimelineEvent,
 } from "./candidate-timeline.js";
 
+export {
+  CI_LANE_CHANGE_BUDGET_CONTRACT,
+  evaluateCiLaneChangeBudget,
+} from "./ci-lane-change-budget.js";
+
 export {
   CHANNEL_CANDIDATE_DECISION_SCHEMA,
   channelCandidateSourceLockRef,

package/packages/core/legacy-kfd-adopter-driver.js

@@ -0,0 +1,167 @@
+import {
+  ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+  adopterDeliveryGateDigest,
+  defineAdopterProtocolDriver,
+} from "./adopter-delivery-gate.js";
+import {
+  KFD_LEGACY_SUPPORT_MATRIX_CONTRACT,
+  validateKfdAdopterManifestGate,
+  validateKfdLegacySupportMatrixProjection,
+} from "./kfd-adopter-manifest.js";
+
+export const LEGACY_KFD_ADOPTER_PROTOCOL_ID =
+  "buildchain.kfd-adopter/legacy-support-matrix";
+export const LEGACY_KFD_ADOPTER_PROTOCOL_VERSION = "1.0.0";
+export const LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT =
+  "kungfu-buildchain-legacy-kfd-adopter-driver-report";
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function normalizedIssues(entries) {
+  return (entries ?? []).map(({ code, path, message }) => ({
+    code,
+    path: path ? `/${path.replaceAll(".", "/")}` : "/declaration",
+    message,
+  }));
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+function bindingIssues(request, manifest) {
+  const issues = [];
+  if (
+    request.project.instanceId !== manifest?.manifestId ||
+    request.project.adopterId !== manifest?.adopter?.id
+  ) {
+    issues.push(
+      issue(
+        "delivery-legacy-project-binding-mismatch",
+        "/project",
+        "Delivery project identity must match the standard adopter manifest.",
+      ),
+    );
+  }
+  if (!sameJson(request.artifact, manifest?.adopter?.artifact)) {
+    issues.push(
+      issue(
+        "delivery-legacy-artifact-binding-mismatch",
+        "/artifact",
+        "Delivery artifact must match the standard adopter manifest artifact.",
+      ),
+    );
+  }
+  return issues;
+}
+
+function invalidContextResult(issues) {
+  const report = {
+    schemaVersion: 1,
+    contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+    valid: false,
+    qualifying: false,
+    selfCertified: false,
+    independentlyCertified: false,
+    manifestRoot: null,
+    manifestGateRoot: null,
+    legacyProjectionRoot: null,
+    legacyProjection: null,
+    adapterIssues: issues,
+    nonClaims: [
+      "The legacy support matrix is a one-way projection, not declaration authority.",
+      "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+    ],
+  };
+  return {
+    valid: false,
+    report,
+    reportRoot: adopterDeliveryGateDigest(report),
+    issues,
+  };
+}
+
+export function createLegacyKfdAdopterProtocolDriver() {
+  return defineAdopterProtocolDriver({
+    interface: ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+    id: LEGACY_KFD_ADOPTER_PROTOCOL_ID,
+    version: LEGACY_KFD_ADOPTER_PROTOCOL_VERSION,
+    verify({ request, context }) {
+      const manifest = context?.adopterManifest;
+      const manifestGate = context?.adopterManifestGate;
+      if (!manifest || !manifestGate) {
+        return invalidContextResult([
+          issue(
+            "delivery-legacy-verification-context-invalid",
+            "/protocol",
+            "The exact standard adopter manifest and manifest gate are required.",
+          ),
+        ]);
+      }
+
+      const source = manifest?.adopter?.artifact?.coordinate?.match(
+        /^([^@\s]+)@([0-9a-f]{40})$/,
+      );
+      const gateValidation = validateKfdAdopterManifestGate(manifestGate, {
+        expectedAdopterId: manifest?.adopter?.id,
+        expectedSourceRepository: source?.[1] ?? "",
+        expectedSourceSha: source?.[2] ?? "",
+        checkedAt: manifestGate?.checkedAt,
+      });
+      const projectionValidation = validateKfdLegacySupportMatrixProjection(
+        request.declaration,
+        { manifest, manifestGate },
+      );
+      const adapterIssues = [
+        ...bindingIssues(request, manifest),
+        ...normalizedIssues(gateValidation.issues),
+        ...normalizedIssues(projectionValidation.issues),
+      ];
+      if (
+        request.declaration?.contract !== KFD_LEGACY_SUPPORT_MATRIX_CONTRACT
+      ) {
+        adapterIssues.push(
+          issue(
+            "delivery-legacy-contract-invalid",
+            "/declaration/contract",
+            `Legacy declaration must use ${KFD_LEGACY_SUPPORT_MATRIX_CONTRACT}.`,
+          ),
+        );
+      }
+
+      const valid =
+        gateValidation.valid &&
+        projectionValidation.valid &&
+        adapterIssues.length === 0;
+      const report = {
+        schemaVersion: 1,
+        contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+        valid,
+        qualifying: false,
+        selfCertified: false,
+        independentlyCertified: false,
+        manifestRoot: manifestGate?.authority?.manifestRoot ?? null,
+        manifestGateRoot: manifestGate?.gateRoot ?? null,
+        legacyProjectionRoot: adopterDeliveryGateDigest(request.declaration),
+        legacyProjection: structuredClone(request.declaration),
+        adapterIssues,
+        nonClaims: [
+          "The legacy support matrix is a one-way projection, not declaration authority.",
+          "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+        ],
+      };
+      return {
+        valid,
+        report,
+        reportRoot: adopterDeliveryGateDigest(report),
+        issues: adapterIssues,
+      };
+    },
+  });
+}