@kungfu-tech/buildchain 4.0.1-alpha.4 → 4.0.1-alpha.40

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-alpha-candidate-selection.js

@@ -82,7 +82,9 @@ export function selectLatestQualifiedSource({
   requiredWorkflowPaths,
   now,
   maxAgeSeconds,
+  ignoredSourceShas = [],
 }) {
+  const ignored = new Set(ignoredSourceShas);
   const latestByPath = new Map(
     requiredWorkflowPaths.map((workflow) => [
       workflow,
@@ -90,7 +92,11 @@ export function selectLatestQualifiedSource({
     ]),
   );
   for (let index = 0; index < sourceHistory.length; index += 1) {
-    const sourceSha = sourceHistory[index];
+    const sourceSha =
+      typeof sourceHistory[index] === "string"
+        ? sourceHistory[index]
+        : sourceHistory[index]?.sha;
+    if (ignored.has(sourceSha)) continue;
     const rows = requiredWorkflowPaths.map((workflow) =>
       latestByPath.get(workflow).get(sourceSha),
     );
@@ -115,7 +121,9 @@ export function selectLatestQualifiedSource({
       };
     }
   }
-  const staleSuccessfulPair = sourceHistory.some((sourceSha) => {
+  const staleSuccessfulPair = sourceHistory.some((entry) => {
+    const sourceSha = typeof entry === "string" ? entry : entry?.sha;
+    if (ignored.has(sourceSha)) return false;
     const rows = requiredWorkflowPaths.map((workflow) =>
       latestByPath.get(workflow).get(sourceSha),
     );

package/packages/core/dev-delivery-execution-transfer.js

@@ -13,6 +13,7 @@ import {
   devDeliveryText as text,
   devDeliveryTimestamp as timestamp,
 } from "./dev-delivery-common.js";
+import { verifyNativeProofReuseDecision } from "./dev-delivery-native-proof.js";
 import { verifyNativeQualificationProof } from "./dev-delivery-native-proof.js";
 import { verifyNativeExecutionFailureOutcome } from "./dev-delivery-execution-failure.js";
 
@@ -408,8 +409,28 @@ function verifySuccessOutcome(transfer, directory, warrant) {
     "native proof reuse decision root",
   );
   delete decisionBody.decisionRoot;
+  const reuseVerification = verifyNativeProofReuseDecision(decision, {
+    proof,
+    current: {
+      sourceHead: warrant.sourceHead,
+      sourceIdentityRoot: warrant.sourceIdentityRoot,
+      sourcePatchRoot: warrant.sourcePatchRoot,
+      planRoot: warrant.planRoot,
+      closureRoot: warrant.closureRoot,
+      dependencyRoot: warrant.dependencyRoot,
+      toolchainRoot: warrant.toolchainRoot,
+      environmentRoot: warrant.environmentRoot,
+      nativeCommandRoot: warrant.nativeCommandContract?.commandRoot,
+      currentBase: decision.currentBase,
+      graphKnown: decision.graphKnown,
+      attributionComplete: decision.attributionComplete,
+      changedPaths: decision.changedPaths,
+      renames: decision.renames,
+    },
+  });
   if (
     !proofVerification.ok ||
+    !reuseVerification.ok ||
     result.nativeProofRoot !== transfer.nativeProofRoot ||
     proof.proofRoot !== transfer.nativeProofRoot ||
     result.nativeReuseDecisionRoot !== transfer.nativeReuseDecisionRoot ||
@@ -420,7 +441,6 @@ function verifySuccessOutcome(transfer, directory, warrant) {
     proof.repository !== transfer.warrant.repository ||
     proof.protectedBase !== transfer.warrant.protectedBase ||
     proof.sourceHead !== transfer.warrant.sourceHead ||
-    proof.qualifiedBase !== warrant.qualifiedBase ||
     proof.sourceIdentityRoot !== warrant.sourceIdentityRoot ||
     proof.sourcePatchRoot !== warrant.sourcePatchRoot ||
     proof.planRoot !== warrant.planRoot ||

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-process-boundary.js

@@ -30,7 +30,7 @@ const PROVIDER_CREDENTIAL_NAME =
   /(?:^(?:ACTIONS_ID_TOKEN_REQUEST_TOKEN|ACTIONS_RUNTIME_TOKEN|AWS_SESSION_TOKEN|AWS_WEB_IDENTITY_TOKEN_FILE|AZURE_FEDERATED_TOKEN_FILE|GH_TOKEN|GITHUB_TOKEN|GOOGLE_GHA_CREDS_PATH|KUNGFU_GITHUB_TOKEN|NPM_TOKEN|SSH_AUTH_SOCK)$|(?:^|_)(?:(?:api|access|auth|publish|release|provider|promotion|governance|approval|mutation|write)_?(?:key|token)|authorization|credentials?|password|secret|private_key|client_secret|signing_key)(?:_|$))/iu;
 const HOSTED_RUNNER_BOUNDARY = "github-actions-runner-worker/v1";
 const GITHUB_HOSTED_LINUX_WORKER =
-  /^\/home\/runner\/runners\/(\d+\.\d+\.\d+)\/bin\/Runner\.Worker$/u;
+  /^\/home\/runner\/(?:runners|actions-runner\/cached)\/(\d+\.\d+\.\d+)\/bin\/Runner\.Worker$/u;
 function text(value, label) {
   const normalized = normalizedText(value);
   if (!normalized) throw new Error(`${label} is required`);
@@ -61,10 +61,16 @@ function processCredentialNames(procRoot, pid, readFileSync) {
     .split("\0")
     .filter((entry) => {
       const separator = entry.indexOf("=");
+      const name = entry.slice(0, separator);
+      const value = entry.slice(separator + 1);
       return (
         separator > 0 &&
-        Boolean(entry.slice(separator + 1)) &&
-        isCredentialVariableName(entry.slice(0, separator))
+        Boolean(value) &&
+        !(
+          name === "BUILDCHAIN_CREDENTIAL_ANCESTRY_BOUNDARY" &&
+          value === HOSTED_RUNNER_BOUNDARY
+        ) &&
+        isCredentialVariableName(name)
       );
     })
     .map((entry) => entry.slice(0, entry.indexOf("=")));
@@ -108,9 +114,11 @@ function hostedBoundary(procRoot, pid, command, readlinkSync) {
   const executable = ancestryRead(readlinkSync, link);
   if (
     !GITHUB_HOSTED_LINUX_WORKER.test(executable) ||
-    !new Set([executable, path.posix.basename(executable)]).has(command[0])
+    path.posix.basename(command[0]) !== path.posix.basename(executable)
   ) {
-    throw new Error("credential ancestry found an untrusted Runner.Worker");
+    throw new Error(
+      `credential ancestry found an untrusted Runner.Worker: executable=${JSON.stringify(executable)} argv0=${JSON.stringify(command[0])}`,
+    );
   }
   return { pid, kind: HOSTED_RUNNER_BOUNDARY, executable };
 }
@@ -163,7 +171,11 @@ export function assertCredentiallessProcessAncestry(options = {}) {
   return inspection;
 }
 
-export function devDeliveryProviderJobByName(jobs, expectedName) {
+export function devDeliveryProviderJobByName(
+  jobs,
+  expectedName,
+  { allowMissing = false } = {},
+) {
   const exactName = text(expectedName, "provider job name");
   const suffix = ` / ${exactName}`;
   const matches = jobs.filter((job) => {
@@ -173,6 +185,7 @@ export function devDeliveryProviderJobByName(jobs, expectedName) {
       (actualName.endsWith(suffix) && actualName.length > suffix.length)
     );
   });
+  if (matches.length === 0 && allowMissing) return null;
   if (matches.length !== 1) {
     throw new Error(`expected exactly one provider job named ${exactName}`);
   }

package/packages/core/dev-delivery-provider-heartbeat.js

@@ -13,7 +13,7 @@ export const DEV_DELIVERY_PROVIDER_HEARTBEAT_SCHEMA =
   "kungfu.buildchain.provider-heartbeat-receipt/v1";
 
 function selectedWarrant(result = {}) {
-  return result.observation?.activeWarrant || result.warrant || null;
+  return result.warrant || result.observation?.activeWarrant || null;
 }
 
 function exactWarrant(input = {}) {
@@ -40,8 +40,9 @@ function exactWarrant(input = {}) {
   };
 }
 
-function job(entries, name) {
-  const entry = devDeliveryProviderJobByName(entries, name);
+function job(entries, name, options) {
+  const entry = devDeliveryProviderJobByName(entries, name, options);
+  if (!entry) return null;
   const providerJob = {
     id: positiveInteger(entry.id, `${name} job id`),
     name,
@@ -66,13 +67,16 @@ function job(entries, name) {
   return providerJob;
 }
 
-function providerJobs(input, expected) {
+function providerJobs(input, expected, { allowMissingSeal = false } = {}) {
   const entries = Array.isArray(input) ? input : input?.jobs;
   if (!Array.isArray(entries)) {
     throw new Error("provider heartbeat jobs readback must contain jobs");
   }
   const native = job(entries, expected.nativeJobName);
-  const seal = job(entries, expected.sealJobName);
+  const seal = job(entries, expected.sealJobName, {
+    allowMissing: allowMissingSeal,
+  });
+  if (!seal) return null;
   if (native.id === seal.id) {
     throw new Error("provider heartbeat native and seal jobs must be distinct");
   }
@@ -206,7 +210,15 @@ export async function runDevDeliveryProviderHeartbeat(
       const entry = heartbeatEntry(result, previousStateRoot);
       heartbeats.push(entry);
       previousStateRoot = entry.nextStateRoot;
-      jobs = providerJobs(await readJobs(), { nativeJobName, sealJobName });
+      jobs = providerJobs(
+        await readJobs(),
+        { nativeJobName, sealJobName },
+        { allowMissingSeal: true },
+      );
+      if (!jobs) {
+        await wait(cadence * 1000);
+        continue;
+      }
       if (terminal(jobs.native) && terminal(jobs.seal)) break;
       await wait(cadence * 1000);
     }