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

package/scripts/dev-delivery-warrant.mjs

@@ -10,6 +10,7 @@ import {
   observeDevDeliveryQueue,
   qualifyDevDeliveryWarrant,
   recoverExpiredDevDeliveryWarrant,
+  reconcileDevDeliveryTerminalEvidence,
   selectDevDeliveryWarrant,
   settleDevDeliveryTerminalEvent,
   submitDevDeliveryCandidate,
@@ -52,6 +53,43 @@ function exactSha(value, label) {
   return normalized;
 }
 
+function terminalSourceHead(options) {
+  return exactSha(
+    options.expectedSourceHead || options.sourceHead,
+    "sourceHead",
+  );
+}
+
+function reconcileTerminalEvidenceCommand(queue, options) {
+  return reconcileDevDeliveryTerminalEvidence(
+    queue,
+    {
+      candidateId: exactRoot(options.candidateId, "candidateId"),
+      expectedPriorEvidenceRoot: exactRoot(
+        options.expectedPriorEvidenceRoot,
+        "expectedPriorEvidenceRoot",
+      ),
+      integrationProof:
+        options.integrationProof ||
+        jsonFile(options.integrationProofPath, "integration proof"),
+      reason: options.reason,
+    },
+    { now: options.now },
+  );
+}
+
+function requireTerminalEvidenceCas(options) {
+  if (
+    options.command === "reconcile-terminal-evidence" &&
+    options.execute &&
+    !options.expectedOldStateRoot
+  ) {
+    throw new Error(
+      "terminal evidence reconciliation execute requires expected-old CAS",
+    );
+  }
+}
+
 function normalizeRepository(value) {
   const normalized = text(value);
   const match = normalized.match(/^([^/\s]+)\/([^/\s]+)$/);
@@ -245,10 +283,7 @@ function transitionFor(command, queue, options) {
           options.pullRequestNumber,
           "pullRequestNumber",
         ),
-        sourceHead: exactSha(
-          options.expectedSourceHead || options.sourceHead,
-          "sourceHead",
-        ),
+        sourceHead: terminalSourceHead(options),
         fencingToken: options.fencingToken,
         leaseGeneration: options.leaseGeneration,
         outcome: options.outcome,
@@ -263,6 +298,9 @@ function transitionFor(command, queue, options) {
       { now: options.now },
     );
   }
+  if (command === "reconcile-terminal-evidence") {
+    return reconcileTerminalEvidenceCommand(queue, options);
+  }
   if (command === "cancel-queued") {
     return cancelQueuedDevDeliveryCandidate(
       queue,
@@ -295,7 +333,10 @@ async function observeQueue(loaded, options) {
   const readMode = text(options.readMode || "v3").toLowerCase();
   if (!["v3", "v4"].includes(readMode))
     throw new Error("readMode must be v3 or v4");
-  let observation = observeDevDeliveryQueue(loaded.queue, { now: options.now });
+  let observation = observeDevDeliveryQueue(loaded.queue, {
+    now: options.now,
+    allowLegacyV3Readback: true,
+  });
   let readCandidate;
   if (readMode === "v4") {
     const qualification =
@@ -353,6 +394,7 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
     now: new Date(optionsInput.now || Date.now()).toISOString(),
     execute: bool(optionsInput.execute, false),
   };
+  requireTerminalEvidenceCas(options);
   if (
     options.command === "submit" &&
     options.execute &&
@@ -374,6 +416,7 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
     stateRef: options.stateRef,
     protectedBase: options.branch,
     now: options.now,
+    allowLegacyV3Readback: options.command === "observe",
   });
   if (
     options.expectedOldStateRoot &&
@@ -453,7 +496,7 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
 }
 
 function usage() {
-  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|settle|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
+  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|settle|reconcile-terminal-evidence|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
 }
 
 async function main() {
@@ -472,6 +515,7 @@ async function main() {
       "recover",
       "close",
       "settle",
+      "reconcile-terminal-evidence",
       "cancel-queued",
       "observe",
     ].includes(options.command)

package/scripts/dev-pr-auto-merge.mjs

@@ -3,7 +3,7 @@ import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { admitExistingQueueEntry, createDevPrAdmissionReceipt, qualifyAtomicQueueAdmission, readDeliveryWarrantResult, runSourceQualification, runTargetedQueueAdmission, setActiveLeaseStatus, verifyCurrentDeliveryWarrant } from "./dev-pr-delivery-warrant.mjs";
+import { admitExistingQueueEntry, createDevPrAdmissionReceipt, createPreReadinessQueueFence, qualifyAtomicQueueAdmission, readDeliveryWarrantResult, runSourceQualification, runTargetedQueueAdmission, setActiveLeaseStatus, setQueueAdmissionStatus, verifyCurrentDeliveryWarrant } from "./dev-pr-delivery-warrant.mjs";
 import { projectCutQualification } from "./dev-pr-prequeue-guard.mjs";
 const DEFAULT_BLOCK_LABELS = ["blocked", "do-not-merge", "work-in-progress"];
 const DEFAULT_ALLOWED_HEAD_PREFIXES = ["feature/", "fix/", "chore/", "docs/", "ci/", "refactor/"];
@@ -197,12 +197,6 @@ function mergeableAccepted(pr, landingMode = "direct", projectCutQualified = fal
 function rejectBaseMoveBeforeAtomicReplay(options, initialBaseSha, observedBaseSha) {
   return observedBaseSha !== initialBaseSha && options.warrantMode !== "required";
 }
-async function setQueueAdmissionStatus(client, repository, sha, context, state) {
-  if (!context) return null;
-  await client.request("POST", `/repos/${repository.owner}/${repository.repo}/statuses/${sha}`, { body: { state, context, description: state === "success" ? "Buildchain admitted this exact PR head to the merge queue" : "Buildchain rejected merge queue admission for this exact PR head" } });
-  return { context, state, sha };
-}
-
 function skip(reason, details = {}) {
   return { action: "skip", reason, ...details };
 }
@@ -790,8 +784,10 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
     return targetedFailure({ options, pr: {}, state: "missing", reason: "pull-request-not-found" });
   }
 
+  const readinessFence = createPreReadinessQueueFence({ client, options, sleep: delay });
   const reject = async (state, reason, readiness = { observed: hasReadyLabel(pr, options.readyLabel), established: false }) => {
     const result = targetedFailure({ options, pr, state, reason, readiness });
+    await readinessFence.finish(result);
     if (!options.dryRun) result.diagnostic = await publishAdmissionDiagnostic(client, options, result.receipt, result.receiptRoot);
     return result;
   };
@@ -803,6 +799,12 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   if (pr.draft) return reject("blocked", "draft");
   if (!headPrefixAllowed(pr, options.allowedHeadPrefixes)) return reject("blocked", "head-prefix-not-allowed");
 
+  try {
+    await readinessFence.establish();
+  } catch (error) {
+    return reject("blocked", error.code || "pre-readiness-queue-fence-failed");
+  }
+
   let readiness = { observed: hasReadyLabel(pr, options.readyLabel), established: false };
   if (!readiness.observed) {
     if (options.dryRun) return reject("rejected", "missing-ready-label", readiness);
@@ -825,7 +827,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   }
 
   if (options.qualificationOnly) {
-    return runSourceQualification({
+    const result = await runSourceQualification({
       options, pullRequest: pr, readiness, client, reject,
       evaluate: evaluatePullRequest,
       admissionState: admissionStateFor,
@@ -833,6 +835,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
       root: contentRoot,
       publishDiagnostic: publishAdmissionDiagnostic,
     });
+    return readinessFence.finish(result);
   }
 
   const initialQueue = await client.getMergeQueueState(options.targetBranch);
@@ -844,6 +847,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   }
   const matchingEntry = initialQueue.entries.find((entry) =>
     entry.pullRequestNumber === pr.number && entry.pullRequestHeadSha === options.expectedHeadSha);
+  await readinessFence.qualifyExisting(matchingEntry);
   const existing = await admitExistingQueueEntry({
     options, pullRequest: pr, readiness, client, entry: matchingEntry, warrant,
     createReceipt: createAdmissionReceipt,
@@ -852,7 +856,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   });
   if (existing) return existing;
 
-  return runTargetedQueueAdmission({
+  const result = await runTargetedQueueAdmission({
     options, pullRequest: pr, readiness, client, warrant,
     runController: runDevPrAutoMerge,
     admissionState: admissionStateFor,
@@ -860,6 +864,7 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
     root: contentRoot,
     publishDiagnostic: publishAdmissionDiagnostic,
   });
+  return readinessFence.finish(result);
 }
 
 function finalizePatrolResult(result) {
@@ -1132,6 +1137,11 @@ function cliFlag(args, name) {
 
 export function cliOptions(args = [], environment = process.env) {
   const targetPullRequestNumber = cliValue(args, "pull-request", environment.BUILDCHAIN_DEV_PR_EXPECTED_PR_NUMBER);
+  const warrantMode = cliValue(
+    args,
+    "warrant-mode",
+    environment.BUILDCHAIN_DEV_PR_WARRANT_MODE || environment.WARRANT_MODE,
+  );
   return {
     repository: cliValue(args, "repository", environment.BUILDCHAIN_DEV_PR_REPOSITORY || environment.GITHUB_REPOSITORY),
     targetBranch: cliValue(args, "branch", environment.BUILDCHAIN_DEV_PR_TARGET_BRANCH || environment.GITHUB_REF_NAME),
@@ -1141,10 +1151,14 @@ export function cliOptions(args = [], environment = process.env) {
     blockLabels: cliValue(args, "block-labels", environment.BUILDCHAIN_DEV_PR_BLOCK_LABELS),
     allowedHeadPrefixes: cliValue(args, "allowed-head-prefixes", environment.BUILDCHAIN_DEV_PR_ALLOWED_HEAD_PREFIXES),
     requiredChecks: cliValue(args, "required-checks", environment.BUILDCHAIN_DEV_PR_REQUIRED_CHECKS),
-    queueAdmissionContext: cliValue(args, "queue-admission-context", environment.BUILDCHAIN_DEV_PR_QUEUE_ADMISSION_CONTEXT),
+    queueAdmissionContext: cliValue(
+      args,
+      "queue-admission-context",
+      environment.BUILDCHAIN_DEV_PR_QUEUE_ADMISSION_CONTEXT || (warrantMode === "required" ? "Queue admission lease" : ""),
+    ),
     activeLeaseContext: cliValue(args, "active-lease-context", environment.BUILDCHAIN_DEV_PR_ACTIVE_LEASE_CONTEXT),
     diagnosticContext: cliValue(args, "diagnostic-context", environment.BUILDCHAIN_DEV_PR_DIAGNOSTIC_CONTEXT),
-    warrantMode: cliValue(args, "warrant-mode", environment.BUILDCHAIN_DEV_PR_WARRANT_MODE),
+    warrantMode,
     warrantResultPath: cliValue(args, "warrant-result", environment.BUILDCHAIN_DEV_PR_WARRANT_RESULT_PATH),
     projectCutProofPath: cliValue(args, "project-cut-proof", environment.BUILDCHAIN_DEV_PR_PROJECT_CUT_PROOF_PATH),
     sourceProofPath: cliValue(args, "source-proof", environment.BUILDCHAIN_DEV_PR_SOURCE_PROOF_PATH),

package/scripts/dev-pr-delivery-warrant.mjs

@@ -143,6 +143,7 @@ export async function readCurrentDeliveryQueueState(client, repository, targetBr
   const { queue } = await store.read({
     stateRef: defaultDevDeliveryStateRef(targetBranch),
     protectedBase: targetBranch,
+    allowLegacyV3Readback: true,
   });
   return queue;
 }
@@ -205,6 +206,50 @@ export async function setActiveLeaseStatus(client, repository, sha, context, sta
   return { context, state, sha };
 }
 
+export async function setQueueAdmissionStatus(client, repository, sha, context, state) {
+  if (!context) return null;
+  const descriptions = {
+    pending: "Buildchain is awaiting a qualified Warrant for this exact PR head",
+    success: "Buildchain admitted this exact PR head to the merge queue",
+    failure: "Buildchain rejected merge queue admission for this exact PR head",
+  };
+  await client.request("POST", `/repos/${repository.owner}/${repository.repo}/statuses/${sha}`, {
+    body: { state, context, description: descriptions[state] || descriptions.failure },
+  });
+  return { context, state, sha };
+}
+
+export function createPreReadinessQueueFence({ client, options, sleep }) {
+  let status = null;
+  const write = async (state) => {
+    status = await setQueueAdmissionStatus(client, options.repository, options.expectedHeadSha, options.queueAdmissionContext, state);
+    return status;
+  };
+  return {
+    async establish() {
+      if (options.dryRun || options.warrantMode !== "required") return null;
+      if (!options.queueAdmissionContext) mismatch("queue-admission-context-required-before-readiness");
+      await write("pending");
+      for (let attempt = 1; attempt <= Math.max(1, options.pollMergeableAttempts); attempt += 1) {
+        const checks = await client.listCommitChecks(options.expectedHeadSha);
+        const readback = (checks?.statuses || []).find((entry) => entry.context === options.queueAdmissionContext);
+        if (readback?.state === "pending") return { ...status, readbackAttempts: attempt };
+        if (attempt < options.pollMergeableAttempts) await sleep(options.pollMergeableDelayMs);
+      }
+      await write("failure");
+      mismatch("pre-readiness-queue-fence-readback-mismatch");
+    },
+    async qualifyExisting(entry) {
+      if (entry && status?.state === "pending") await write("success");
+    },
+    async finish(result) {
+      const controllerFailed = result.controller?.evaluated?.some((entry) => entry.queueAdmissionStatus?.state === "failure");
+      if (!result.ok && status?.state === "pending" && !controllerFailed) await write("failure");
+      return result;
+    },
+  };
+}
+
 async function readBackAdmissionStatuses(client, options, expectedHeadSha, sleep) {
   let last = { queueAdmission: null, activeLease: null };
   const attempts = Math.max(1, options.pollMergeableAttempts);

package/scripts/dev-pr-prequeue-guard.mjs

@@ -164,15 +164,6 @@ async function qualifyProjectCut({
 
   let reuseDecision = null;
   if (currentBaseSha !== previousBaseSha) {
-    const observedPullRequestBase = String(
-      observedPullRequest.base?.sha || "",
-    ).toLowerCase();
-    if (observedPullRequestBase !== currentBaseSha) {
-      mismatch("pre-enqueue-project-cut-base-stale", {
-        observedPullRequestBase,
-        currentBaseSha,
-      });
-    }
     const proof = readOptionalJson(options.sourceProofPath);
     if (!proof) mismatch("pre-enqueue-base-attribution-unknown");
     if (
@@ -342,15 +333,6 @@ export async function qualifyPreEnqueueReadback({
   ) {
     mismatch("head-sha-drift-after-project-cut");
   }
-  const casPullRequestBase = String(
-    casPullRequest.base?.sha || "",
-  ).toLowerCase();
-  if (casPullRequestBase && casPullRequestBase !== casBaseSha) {
-    mismatch("pre-enqueue-project-cut-base-stale", {
-      observedPullRequestBase: casPullRequestBase,
-      currentBaseSha: casBaseSha,
-    });
-  }
   if (casPullRequest.mergeable === false) {
     mismatch("pre-enqueue-merge-conflict-after-project-cut");
   }

package/scripts/dev-qualification-patrol.mjs

@@ -501,16 +501,16 @@ export function createGitHubDevQualificationClient({
       sourceBranch,
       { activeOnly = false } = {},
     ) {
-      const query = sourceBranch
-        ? `?branch=${encodeURIComponent(sourceBranch)}`
-        : "";
-      const runs = await paged(
-        `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflow)}/runs${query}`,
-        "workflow_runs",
+      const query = sourceBranch ? `branch=${encodeRef(sourceBranch)}&` : "";
+      const runs = await Promise.all(
+        [...(activeOnly ? ACTIVE_STATUSES : [""])].map((status) =>
+          paged(
+            `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflow)}/runs?${query}${status ? `status=${status}` : ""}`,
+            "workflow_runs",
+          ),
+        ),
       );
-      return activeOnly
-        ? runs.filter((run) => ACTIVE_STATUSES.has(text(run.status)))
-        : runs;
+      return runs.flat();
     },
     async listRunJobs(runId, runAttempt) {
       return paged(

package/scripts/dispatch-artifact-signing-authority.mjs

@@ -24,7 +24,7 @@ const AUTHORITY_WORKFLOW = "artifact-signing-authority.yml";
 
 export function resolveAuthorityDispatchRef(value) {
   const ref = required(value, "authority ref");
-  return /^[0-9a-f]{40}$/u.test(ref)
+  return /^[0-9a-f]{40}$/u.test(ref) || /^v\d+(?:\.\d+)?(?:-alpha)?$/u.test(ref)
     ? DEFAULT_ARTIFACT_SIGNING_AUTHORITY_REF
     : ref;
 }

package/scripts/generate-agent-change-map.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const indexPath = "architecture/internal-capabilities.json";
+const debtPath = "architecture/maintainability-debt.json";
+const outputPath = "architecture/agent-change-map.md";
+
+function list(values) {
+  if (!values?.length) return "- None.";
+  return values.map((value) => `- \`${value}\``).join("\n");
+}
+
+function debtRouteSection(debt) {
+  if (!debt?.surfaces) return "";
+  const defaults = debt.defaults;
+  const governedPaths = Object.entries(debt.surfaces).flatMap(
+    ([domain, entries]) =>
+      Object.keys(entries).map((entry) => `${domain}: \`${entry}\``),
+  );
+  return `## Governed complexity debt routes
+
+Owner: ${defaults.owner}
+
+Capability: \`${defaults.capability}\`
+
+Invariant: ${defaults.invariant}
+
+Tests: ${defaults.tests.map((entry) => `\`${entry}\``).join(", ")}
+
+Safe change route: ${defaults.safeChangeRoute}
+
+### Oversized surfaces
+
+${governedPaths.map((entry) => `- ${entry}`).join("\n")}
+
+### Current top twenty maintenance hotspots
+
+${debt.hotspots.map((entry) => `- \`${entry}\``).join("\n")}`;
+}
+
+function generateAgentChangeMap(index, debt = null) {
+  const capabilities = [...index.capabilities].sort((left, right) =>
+    left.id.localeCompare(right.id),
+  );
+  const sections = capabilities.map(
+    (capability) => `## ${capability.id}
+
+Owner: ${capability.owner}
+
+### Implementation
+
+${list(capability.implementation)}
+
+### Contracts
+
+${list(capability.contracts)}
+
+### Tests
+
+${list(capability.tests)}
+
+### Generated outputs
+
+${list(capability.generatedOutputs)}
+
+### Minimal validation
+
+${list(capability.validationCommands)}`,
+  );
+  return `<!-- Generated by scripts/generate-agent-change-map.mjs. Do not edit directly. -->
+# Agent Change Map
+
+Use this index to identify the smallest implementation, contract, test, generated-output, and validation surface for a capability change. The machine-readable source of truth is \`${indexPath}\`.
+
+${debtRouteSection(debt)}
+
+${sections.join("\n\n")}
+`;
+}
+
+function run({ root = process.cwd(), mode = "check" } = {}) {
+  const index = JSON.parse(fs.readFileSync(path.join(root, indexPath), "utf8"));
+  const debt = JSON.parse(fs.readFileSync(path.join(root, debtPath), "utf8"));
+  const generated = generateAgentChangeMap(index, debt);
+  const target = path.join(root, outputPath);
+  if (mode === "write") {
+    fs.writeFileSync(target, generated);
+    return { outputPath, updated: true };
+  }
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (current !== generated) {
+    throw new Error(
+      `${outputPath} is stale; run node scripts/generate-agent-change-map.mjs --write`,
+    );
+  }
+  return { outputPath, updated: false };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    const mode = process.argv.includes("--write") ? "write" : "check";
+    const report = run({ mode });
+    console.log(
+      `${report.outputPath} ${report.updated ? "generated" : "is current"}`,
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+export { generateAgentChangeMap, run };

package/scripts/generate-channel-promotion-workflow.mjs

@@ -159,8 +159,8 @@ function validateWorkflowRoute(name, route, expectedLogicalRef) {
   if (!/^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/.test(route.workflowPath || "")) {
     throw new Error(`promotion shell ${name} workflowPath must name a reusable workflow`);
   }
-  if (!/^(?:v[0-9]+(?:-alpha)?|train\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
-    throw new Error(`promotion shell ${name} callRef must be an official channel ref, trusted train, or exact SHA`);
+  if (!/^(?:v[0-9]+(?:-alpha)?|(?:train|alpha|release)\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
+    throw new Error(`promotion shell ${name} callRef must be an official tag, protected channel ref, trusted train, or exact SHA`);
   }
   if (typeof route.forwardInternalInputs !== "boolean") {
     throw new Error(`promotion shell ${name} forwardInternalInputs must be boolean`);