@kungfu-tech/buildchain 4.0.2-alpha.5 → 4.0.2-alpha.50

package/scripts/dev-delivery-warrant.mjs

@@ -10,16 +10,17 @@ import {
   heartbeatDevDeliveryWarrant,
   observeDevDeliveryQueue,
   qualifyDevDeliveryWarrant,
-  recoverExpiredDevDeliveryWarrant,
   reconcileDevDeliveryTerminalEvidence,
   selectDevDeliveryWarrant,
   settleDevDeliveryTerminalEvent,
   submitDevDeliveryCandidate,
 } from "../packages/core/dev-delivery-warrant.js";
 import { recoverLegacyTerminalDevDeliveryQueue } from "../packages/core/dev-delivery-warrant-legacy-recovery.js";
+import { reuseExactActiveDevDeliverySourceProof } from "../packages/core/dev-delivery-candidate-identity.js";
 import { runV4DeliveryWarrantReadCandidate } from "../packages/core/v4-delivery-warrant-read-candidate.js";
 
 import { GitHubDevDeliveryStore } from "./dev-delivery-warrant-store.mjs";
+import { persistDevDeliveryTransition } from "./dev-delivery-warrant-transition.mjs";
 import { devDeliveryCliOptions } from "./dev-delivery-warrant-options.mjs";
 export { GitHubDevDeliveryStore, devDeliveryCliOptions };
 
@@ -199,54 +200,60 @@ function transitionFor(command, queue, options) {
         "native command contract root does not match native-command",
       );
     }
+    const input = {
+      pullRequestNumber: positiveInteger(
+        options.pullRequestNumber,
+        "pullRequestNumber",
+      ),
+      sourceHead: exactSha(options.sourceHead, "sourceHead"),
+      ...(options.sourceRoot ? { sourceRoot: options.sourceRoot } : {}),
+      ...(options.assignmentRoot
+        ? { assignmentRoot: options.assignmentRoot }
+        : {}),
+      ...(options.initiativeRoot
+        ? { initiativeRoot: options.initiativeRoot }
+        : {}),
+      sourceIdentityRoot: exactRoot(
+        options.sourceIdentityRoot,
+        "sourceIdentityRoot",
+      ),
+      sourcePatchRoot: exactRoot(options.sourcePatchRoot, "sourcePatchRoot"),
+      sourceProofRoot: exactRoot(options.sourceProofRoot, "sourceProofRoot"),
+      planRoot: exactRoot(options.planRoot, "planRoot"),
+      closureRoot: exactRoot(options.closureRoot, "closureRoot"),
+      dependencyRoot: exactRoot(options.dependencyRoot, "dependencyRoot"),
+      toolchainRoot: exactRoot(options.toolchainRoot, "toolchainRoot"),
+      ...(options.environmentRoot
+        ? {
+            environmentRoot: exactRoot(
+              options.environmentRoot,
+              "environmentRoot",
+            ),
+          }
+        : {}),
+      ...(nativeCommandContract ? { nativeCommandContract } : {}),
+      affectedPaths: jsonList(options.affectedPaths, "affected paths"),
+      shardEvidenceRoots: jsonList(
+        options.shardEvidenceRoots,
+        "shard evidence roots",
+      ),
+      sourceWorkflowRunId: options.sourceWorkflowRunId
+        ? positiveInteger(options.sourceWorkflowRunId, "sourceWorkflowRunId")
+        : 0,
+      deliveryClass: options.deliveryClass,
+      priority: options.priority || "ordinary",
+      ...(options.releaseBlockerPriority
+        ? {
+            releaseBlockerPriority: jsonObject(
+              options.releaseBlockerPriority,
+              "release blocker priority",
+            ),
+          }
+        : {}),
+    };
     return submitDevDeliveryCandidate(
       queue,
-      {
-        pullRequestNumber: positiveInteger(
-          options.pullRequestNumber,
-          "pullRequestNumber",
-        ),
-        sourceHead: exactSha(options.sourceHead, "sourceHead"),
-        assignmentRoot: exactRoot(options.assignmentRoot, "assignmentRoot"),
-        initiativeRoot: exactRoot(options.initiativeRoot, "initiativeRoot"),
-        sourceIdentityRoot: exactRoot(
-          options.sourceIdentityRoot,
-          "sourceIdentityRoot",
-        ),
-        sourcePatchRoot: exactRoot(options.sourcePatchRoot, "sourcePatchRoot"),
-        sourceProofRoot: exactRoot(options.sourceProofRoot, "sourceProofRoot"),
-        planRoot: exactRoot(options.planRoot, "planRoot"),
-        closureRoot: exactRoot(options.closureRoot, "closureRoot"),
-        dependencyRoot: exactRoot(options.dependencyRoot, "dependencyRoot"),
-        toolchainRoot: exactRoot(options.toolchainRoot, "toolchainRoot"),
-        ...(options.environmentRoot
-          ? {
-              environmentRoot: exactRoot(
-                options.environmentRoot,
-                "environmentRoot",
-              ),
-            }
-          : {}),
-        ...(nativeCommandContract ? { nativeCommandContract } : {}),
-        affectedPaths: jsonList(options.affectedPaths, "affected paths"),
-        shardEvidenceRoots: jsonList(
-          options.shardEvidenceRoots,
-          "shard evidence roots",
-        ),
-        sourceWorkflowRunId: options.sourceWorkflowRunId
-          ? positiveInteger(options.sourceWorkflowRunId, "sourceWorkflowRunId")
-          : 0,
-        deliveryClass: options.deliveryClass,
-        priority: options.priority || "ordinary",
-        ...(options.releaseBlockerPriority
-          ? {
-              releaseBlockerPriority: jsonObject(
-                options.releaseBlockerPriority,
-                "release blocker priority",
-              ),
-            }
-          : {}),
-      },
+      reuseExactActiveDevDeliverySourceProof(queue.activeWarrant, input),
       { now: options.now },
     );
   }
@@ -461,51 +468,16 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
   }
   if (options.command === "observe") return observeQueue(loaded, options);
   const initialLoaded = loaded;
-  let changed = transitionFor(options.command, loaded.queue, options);
-  let mutates = changed.queue.stateRoot !== loaded.queue.stateRoot;
-  let write = null;
-  if (options.execute && mutates) {
-    if (changed.receipt.expectedOldStateRoot !== loaded.queue.stateRoot) {
-      throw new Error(
-        "transition receipt expected-old root does not match the loaded authority",
-      );
-    }
-    try {
-      write = await store.write({
-        stateRef: options.stateRef,
-        queue: changed.queue,
-        expectedCommitSha: loaded.commitSha,
-        expectedStateRoot: loaded.queue.stateRoot,
-        receiptRoot: changed.receiptRoot,
-      });
-    } catch (error) {
-      if (options.command !== "settle" || options.expectedOldStateRoot)
-        throw error;
-      const latest = await store.read({
-        stateRef: options.stateRef,
-        protectedBase: options.branch,
-        now: options.now,
-      });
-      const reconciled = transitionFor(options.command, latest.queue, options);
-      const reconciledMutates =
-        reconciled.queue.stateRoot !== latest.queue.stateRoot;
-      if (
-        reconciledMutates ||
-        reconciled.receipt.action !== "duplicate-terminal-event-noop"
-      )
-        throw error;
-      loaded = latest;
-      changed = reconciled;
-      mutates = false;
-      concurrencyRecovery = {
-        schema: "kungfu.buildchain.dev-delivery-concurrency-recovery/v1",
-        action: "terminal-settlement-race-noop",
-        initialCommitSha: initialLoaded.commitSha,
-        observedCommitSha: latest.commitSha,
-        observedStateRoot: latest.queue.stateRoot,
-      };
-    }
-  }
+  const persisted = await persistDevDeliveryTransition({
+    store,
+    options,
+    loaded,
+    initialLoaded,
+    changed: transitionFor(options.command, loaded.queue, options),
+    transitionFor,
+  });
+  loaded = persisted.loaded;
+  concurrencyRecovery = persisted.concurrencyRecovery || concurrencyRecovery;
   return {
     schema: "kungfu.buildchain.dev-delivery-command-result/v1",
     ok: true,
@@ -514,16 +486,21 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
     stateRef: options.stateRef,
     before: { commitSha: loaded.commitSha, stateRoot: loaded.queue.stateRoot },
     after: {
-      commitSha: write?.commitSha || loaded.commitSha,
-      stateRoot: changed.queue.stateRoot,
+      commitSha: persisted.write?.commitSha || loaded.commitSha,
+      stateRoot: persisted.changed.queue.stateRoot,
     },
     mutationAuthorized: options.execute,
-    mutationApplied: Boolean(write),
+    mutationApplied: Boolean(persisted.write),
     concurrencyRecovery,
-    receipt: changed.receipt,
-    receiptRoot: changed.receiptRoot,
-    warrant: changed.warrant || changed.queue.activeWarrant || null,
-    observation: observeDevDeliveryQueue(changed.queue, { now: options.now }),
+    receipt: persisted.changed.receipt,
+    receiptRoot: persisted.changed.receiptRoot,
+    warrant:
+      persisted.changed.warrant ||
+      persisted.changed.queue.activeWarrant ||
+      null,
+    observation: observeDevDeliveryQueue(persisted.changed.queue, {
+      now: options.now,
+    }),
   };
 }
 

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

@@ -723,7 +723,6 @@ function renderAdmissionComment(receipt, receiptRoot) {
     "GitHub auto-merge state is observed evidence only; it is not Buildchain admission authority.",
   ].join("\n");
 }
-
 async function publishAdmissionDiagnostic(client, options, receipt, receiptRoot) {
   const marker = `<!-- ${AGENT_ADMISSION_MARKER} pr=${receipt.pullRequestNumber} head=${receipt.expectedHeadSha} -->`;
   const body = renderAdmissionComment(receipt, receiptRoot);
@@ -743,7 +742,6 @@ async function publishAdmissionDiagnostic(client, options, receipt, receiptRoot)
   }
   return { commentId: comment?.id || null, commentUrl: comment?.html_url || "", statusPublished: Boolean(status) };
 }
-
 function createAdmissionReceipt({ options, pr = {}, state, reason, readiness, decision = {}, queue = null, warrant = null }) {
   return createDevPrAdmissionReceipt({ options, pr, state, reason, readiness, decision, queue, warrant, labels: labelsOf(pr), nextAction: nextAdmissionAction });
 }
@@ -751,16 +749,21 @@ function createAdmissionReceipt({ options, pr = {}, state, reason, readiness, de
 function targetedFailure({ options, pr, state, reason, readiness, decision, queue }) {
   const receipt = createAdmissionReceipt({ options, pr, state, reason, readiness, decision, queue });
   return {
-    schema: AGENT_ADMISSION_RESULT_SCHEMA,
-    ok: false,
-    mode: options.dryRun ? "plan" : "execute",
-    outcome: "targeted-admission-failed",
-    receipt,
-    receiptRoot: contentRoot(receipt),
-    diagnostic: null,
+    schema: AGENT_ADMISSION_RESULT_SCHEMA, ok: false, mode: options.dryRun ? "plan" : "execute",
+    outcome: "targeted-admission-failed", receipt, receiptRoot: contentRoot(receipt), diagnostic: null,
   };
 }
-
+async function readTargetPullRequest(client, number, options) {
+  let { pollMergeableAttempts: attempts, pollMergeableDelayMs: delayMs } = options;
+  for (; attempts > 1; attempts -= 1) {
+    try {
+      return await client.getPullRequest(number, { attempts, delayMs });
+    } catch {
+      await delay(delayMs);
+    }
+  }
+  return client.getPullRequest(number, { attempts, delayMs });
+}
 export async function runDevPrAdmission(optionsInput = {}, clientInput) {
   const options = normalizeOptions(optionsInput);
   if (!options.targetBranch) throw new Error("target branch is required");
@@ -776,12 +779,9 @@ export async function runDevPrAdmission(optionsInput = {}, clientInput) {
 
   let pr;
   try {
-    pr = await client.getPullRequest(options.targetPullRequestNumber, {
-      attempts: options.pollMergeableAttempts,
-      delayMs: options.pollMergeableDelayMs,
-    });
+    pr = await readTargetPullRequest(client, options.targetPullRequestNumber, options);
   } catch (error) {
-    return targetedFailure({ options, pr: {}, state: "missing", reason: "pull-request-not-found" });
+    return targetedFailure({ options, pr: {}, state: "blocked", reason: "pull-request-read-failed" });
   }
 
   const readinessFence = createPreReadinessQueueFence({ client, options, sleep: delay });

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

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { writeWorkflowSource } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourcePath = path.join(root, ".github/workflows/.build.yml");
@@ -403,7 +405,10 @@ export function generateChannelBuildWorkflow(source) {
       ].join("\n"),
     )
     .replace("\n  alpha:\n", `\n${routerControllerPlanJob()}\n\n  alpha:\n`);
-  return `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n\n${routerAggregateJob()}\n`;
+  return migrateV4UniversalWorkflowFacade(
+    `${generated.trimEnd()}\n\n${routerControllerReceiptJob()}\n\n${routerAggregateJob()}\n`,
+    ".github/workflows/build.yml",
+  );
 }
 
 function main() {
@@ -417,7 +422,7 @@ function main() {
     }
     return;
   }
-  fs.writeFileSync(targetPath, generated);
+  writeWorkflowSource(root, path.relative(root, targetPath), generated);
 }
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

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

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { writeWorkflowSource } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { migrateV4UniversalWorkflowFacade } from "./generate-v4-universal-workflow-facades.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourcePath = path.join(root, ".github/workflows/.release-candidate-promote.yml");
@@ -214,9 +216,9 @@ function consumerAdmissionJob() {
         id: policy
         env:
           BUILDCHAIN_CONSUMER_ROOT: .buildchain/consumer
-          BUILDCHAIN_INVOCATION_SOURCE_PATH: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/release-candidate-promote.yml' || inputs.publication-publisher-workflow-path }}
+          BUILDCHAIN_INVOCATION_SOURCE_PATH: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/self-ops-promotion-recovery.yml' && '.github/workflows/release-candidate-promote.yml' || inputs.publication-publisher-workflow-path }}
           BUILDCHAIN_EXPECTED_INVOCATION_CHANNEL: \${{ needs.resolve-promotion.outputs.channel }}
-          BUILDCHAIN_INVOKED_WORKFLOW: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/buildchain-ref-promotion-recovery.yml' && '.github/workflows/.release-candidate-promote.yml' || '.github/workflows/release-candidate-promote.yml' }}
+          BUILDCHAIN_INVOKED_WORKFLOW: \${{ inputs.publication-publisher-workflow-path == '.github/workflows/self-ops-promotion-recovery.yml' && '.github/workflows/.release-candidate-promote.yml' || '.github/workflows/release-candidate-promote.yml' }}
           BUILDCHAIN_WORKFLOW_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_RUNTIME_SHA: \${{ needs.resolve-promotion.outputs.router-sha }}
           BUILDCHAIN_STABLE_CONTRACT_LOCK_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
@@ -302,7 +304,7 @@ export function generateChannelPromotionWorkflow(source, { major = 2, shellRouti
     if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
   }
   const invokeForwarded = routedInputs(inputNames, alphaRoute, major);
-  return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
+  return migrateV4UniversalWorkflowFacade(`# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
 name: Release Candidate Promote
 
 on:
@@ -314,16 +316,7 @@ ${secrets.trimEnd()}
     outputs:
 ${publicOutputs(outputs)}
 
-permissions:
-  actions: write
-  artifact-metadata: write
-  attestations: write
-  checks: write
-  contents: write
-  id-token: write
-  issues: write
-  pull-requests: write
-
+# Provider authority is inherited from the explicit caller envelope.
 jobs:
   resolve-promotion:
     name: Resolve promotion workflow shell and runtime
@@ -358,7 +351,7 @@ jobs:
         run: |
           set -euo pipefail
           repository="\${BUILDCHAIN_ROUTER_REPOSITORY}"
-          ref="\${BUILDCHAIN_ROUTER_REF}"
+          ref="\${BUILDCHAIN_ROUTER_REF:-${alphaRoute.logicalRef}}"
           ref="\${ref#refs/heads/}"
           ref="\${ref#refs/tags/}"
           if [[ ! "\${repository}" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ || -z "\${ref}" || "\${ref}" = /* || "\${ref}" = *..* ]]; then
@@ -501,19 +494,11 @@ ${consumerAdmissionJob()}
     name: Invoke the single v4 publisher adapter
     needs: [resolve-promotion, consumer-admission]
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
-    permissions:
-      actions: write
-      artifact-metadata: write
-      attestations: write
-      checks: write
-      contents: write
-      id-token: write
-      issues: write
-      pull-requests: write
+    # Provider authority is inherited from the explicit caller envelope.
     with:
 ${invokeForwarded}
     secrets: inherit
-`;
+`, ".github/workflows/release-candidate-promote.yml");
 }
 
 function main() {
@@ -531,7 +516,7 @@ function main() {
     }
     return;
   }
-  fs.writeFileSync(targetPath, generated);
+  writeWorkflowSource(root, path.relative(root, targetPath), generated);
 }
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/scripts/generate-site-bundle.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readWorkflowTaxonomy, workflowPath } from "./workflow-taxonomy.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
@@ -755,9 +756,7 @@ function buildSiteBundle() {
     timestampFieldsParticipateInArtifactDigest: true,
     artifactDigestScope: "npm package dist/site JSON files",
   });
-
   const cliRegistry = createCliRegistry(packageJson);
-
   const manualRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-agent-manual-registry",
@@ -805,7 +804,6 @@ function buildSiteBundle() {
     ],
     guidance: "Agent consumers should use this registry to find packaged Buildchain manuals before inferring behavior from workflow snippets or release notes.",
   };
-
   const pageRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-site-page-registry",
@@ -821,14 +819,15 @@ function buildSiteBundle() {
     capabilityGroups: CAPABILITY_GROUPS.map((group) => group.id),
     pages,
   };
-
   const nodeApiRegistry = createSiteNodeApiRegistry({ root, packageJson, nodeApiMeta, sha256File, publicSurfaceLifecycle });
-
+  const taxonomy = readWorkflowTaxonomy(root);
   const workflowRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-workflow-registry",
     workflowSource: ".github/workflows reverse input enumeration",
     workflows: enumerateWorkflowInputs({ root }).map((entry) => {
+      const classification = taxonomy?.entries.find((item) => workflowPath(item) === entry.path || item.compatibility?.path === entry.path);
+      const semanticId = classification?.id || entry.id;
       const surfaceById = new Map([
         ["build", "channel-build-router"],
         [".build", "reusable-build"],
@@ -878,18 +877,19 @@ function buildSiteBundle() {
         ["engineering-housekeeper-monthly", "preview"],
         ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
-      const engineeringHousekeeper = entry.id.startsWith("engineering-housekeeper");
+      const engineeringHousekeeper = semanticId.startsWith("engineering-housekeeper");
       return {
         ...entry,
-        surface: surfaceById.get(entry.id) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
+        ...(classification ? { taxonomy: { id: classification.id, role: classification.role, category: classification.category, purpose: classification.purpose, status: classification.status, canonicalPath: workflowPath(classification), ...(classification.role === "self" && classification.migration ? { contractPath: classification.migration.previousPath } : {}), compatibilityAlias: entry.path !== workflowPath(classification) } } : {}),
+        surface: surfaceById.get(semanticId) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
         capabilityGroup: workflowCapabilityGroup({
-          ...entry,
-          status: statusById.get(entry.id) || "active",
+          ...entry, id: semanticId,
+          status: statusById.get(semanticId) || "active",
         }),
-        status: statusById.get(entry.id) || "active",
+        status: statusById.get(semanticId) || "active",
         ...publicSurfaceLifecycle({
           owner: "buildchain-workflows",
-          maturity: statusById.get(entry.id) || "active",
+          maturity: statusById.get(semanticId) || "active",
           introducedVersion: engineeringHousekeeper ? packageJson.version : undefined,
           nonDuplicationRationale: engineeringHousekeeper
             ? "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."