@kungfu-tech/buildchain 3.0.9-alpha.8 → 3.0.9-alpha.9

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

@@ -10,11 +10,15 @@ import {
 } from "./dev-delivery-common.js";
 
 export const NATIVE_QUALIFICATION_PROOF_SCHEMA =
+  "kungfu.buildchain.native-qualification-proof/v2";
+const LEGACY_NATIVE_QUALIFICATION_PROOF_SCHEMA =
   "kungfu.buildchain.native-qualification-proof/v1";
 export const NATIVE_PROOF_REUSE_DECISION_SCHEMA =
   "kungfu.buildchain.native-proof-reuse-decision/v1";
 export const DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA =
   "kungfu.buildchain.dev-delivery-qualification-receipt/v1";
+export const NATIVE_PROOF_BASE_DELTA_SCHEMA =
+  "kungfu.buildchain.native-proof-base-delta/v1";
 
 const NATIVE_QUALIFICATION_ROOT_SEMANTICS = "semantic-native-identity-v1";
 
@@ -37,6 +41,35 @@ function normalizedPaths(values) {
   ].sort();
 }
 
+function normalizedRenames(values) {
+  if (!Array.isArray(values)) throw new Error("renames must be a JSON array");
+  return values
+    .map((entry) => ({
+      from: normalizedPaths([entry?.from])[0] || "",
+      to: normalizedPaths([entry?.to])[0] || "",
+    }))
+    .filter((entry) => entry.from && entry.to)
+    .sort(
+      (left, right) =>
+        left.from.localeCompare(right.from) || left.to.localeCompare(right.to),
+    );
+}
+
+export function createNativeProofBaseDelta(input = {}) {
+  const body = {
+    schema: NATIVE_PROOF_BASE_DELTA_SCHEMA,
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    qualifiedBase: exactSha(input.qualifiedBase, "qualifiedBase"),
+    currentBase: exactSha(input.currentBase, "currentBase"),
+    graphKnown: input.graphKnown === true,
+    attributionComplete: input.attributionComplete === true,
+    changedPaths: normalizedPaths(input.changedPaths || []),
+    renames: normalizedRenames(input.renames || []),
+  };
+  return { ...body, deltaRoot: devDeliveryContentRoot(body) };
+}
+
 function proofIdentity(body) {
   const identity = clone(body);
   delete identity.qualifiedAt;
@@ -67,6 +100,7 @@ export function createNativeQualificationProof(input = {}) {
     closureRoot: exactRoot(input.closureRoot, "closureRoot"),
     dependencyRoot: exactRoot(input.dependencyRoot, "dependencyRoot"),
     toolchainRoot: exactRoot(input.toolchainRoot, "toolchainRoot"),
+    environmentRoot: exactRoot(input.environmentRoot, "environmentRoot"),
     qualifiedBase: exactSha(input.qualifiedBase, "qualifiedBase"),
     affectedPaths: normalizedPaths(input.affectedPaths || []),
     shardEvidenceRoots: exactRoots(
@@ -85,7 +119,12 @@ export function createNativeQualificationProof(input = {}) {
 export function verifyNativeQualificationProof(proofInput, expected = {}) {
   try {
     const proof = clone(proofInput || {});
-    if (proof.schema !== NATIVE_QUALIFICATION_PROOF_SCHEMA) {
+    if (
+      ![
+        NATIVE_QUALIFICATION_PROOF_SCHEMA,
+        LEGACY_NATIVE_QUALIFICATION_PROOF_SCHEMA,
+      ].includes(proof.schema)
+    ) {
       return { ok: false, reason: "unsupported-schema" };
     }
     const proofRoot = proof.proofRoot;
@@ -106,7 +145,26 @@ export function verifyNativeQualificationProof(proofInput, expected = {}) {
         return { ok: false, reason: `${field}-mismatch` };
       }
     }
-    createNativeQualificationProof(proof);
+    if (proof.schema === NATIVE_QUALIFICATION_PROOF_SCHEMA) {
+      createNativeQualificationProof(proof);
+    } else {
+      repository(proof.repository);
+      protectedBase(proof.protectedBase);
+      exactSha(proof.qualifiedBase, "qualifiedBase");
+      for (const field of [
+        "sourceIdentityRoot",
+        "sourcePatchRoot",
+        "planRoot",
+        "closureRoot",
+        "dependencyRoot",
+        "toolchainRoot",
+      ]) {
+        exactRoot(proof[field], field);
+      }
+      normalizedPaths(proof.affectedPaths || []);
+      exactRoots(proof.shardEvidenceRoots, "shardEvidenceRoots");
+      timestamp(proof.qualifiedAt, "qualifiedAt");
+    }
     return { ok: true, reason: "exact-native-proof", proofRoot };
   } catch (error) {
     return { ok: false, reason: "invalid-proof", error: error.message };
@@ -136,7 +194,10 @@ function nativeReuseBody(proof, current) {
     qualifiedBase: verification.ok ? proof.qualifiedBase : null,
     currentBase,
     graphKnown: current.graphKnown === true,
+    attributionComplete: current.attributionComplete === true,
     changedPaths,
+    renames: normalizedRenames(current.renames || []),
+    baseDeltaRoot: null,
     overlappingPaths: [],
     reusable: false,
     action: "rerun-full-native-qualification",
@@ -152,6 +213,7 @@ function nativeReuseBody(proof, current) {
     "closureRoot",
     "dependencyRoot",
     "toolchainRoot",
+    "environmentRoot",
   ];
   for (const field of semanticFields) {
     if (!current[field] || current[field] !== proof[field]) {
@@ -164,6 +226,18 @@ function nativeReuseBody(proof, current) {
   if (!currentBase) {
     return { ...base, reason: "current-base-unknown" };
   }
+  const delta = createNativeProofBaseDelta({
+    repository: proof.repository,
+    protectedBase: proof.protectedBase,
+    qualifiedBase: proof.qualifiedBase,
+    currentBase,
+    graphKnown: current.graphKnown,
+    attributionComplete: current.attributionComplete,
+    changedPaths,
+    renames: current.renames || [],
+  });
+  base.baseDeltaRoot = delta.deltaRoot;
+  base.renames = delta.renames;
   if (currentBase === proof.qualifiedBase) {
     return {
       ...base,
@@ -173,13 +247,22 @@ function nativeReuseBody(proof, current) {
       requiredValidation: "exact-merge-group",
     };
   }
-  if (current.graphKnown !== true || !Array.isArray(current.changedPaths)) {
+  if (
+    current.graphKnown !== true ||
+    current.attributionComplete !== true ||
+    !Array.isArray(current.changedPaths) ||
+    !Array.isArray(current.renames)
+  ) {
     return { ...base, reason: "base-delta-attribution-unknown" };
   }
   if (proof.affectedPaths.length === 0) {
     return { ...base, reason: "affected-closure-paths-unknown" };
   }
-  const overlap = changedPaths.filter((changedPath) =>
+  const attributedPaths = [
+    ...changedPaths,
+    ...base.renames.flatMap((rename) => [rename.from, rename.to]),
+  ];
+  const overlap = [...new Set(attributedPaths)].filter((changedPath) =>
     proof.affectedPaths.some((affectedPath) =>
       pathsOverlap(changedPath, affectedPath),
     ),
@@ -269,6 +352,7 @@ export function createDevDeliveryWarrantQualifier({
           closureRoot: active.closureRoot,
           dependencyRoot: active.dependencyRoot,
           toolchainRoot: active.toolchainRoot,
+          environmentRoot: active.environmentRoot,
         });
         if (!proofVerification.ok) {
           throw new Error(`native proof rejected: ${proofVerification.reason}`);
@@ -285,6 +369,7 @@ export function createDevDeliveryWarrantQualifier({
               closureRoot: active.closureRoot,
               dependencyRoot: active.dependencyRoot,
               toolchainRoot: active.toolchainRoot,
+              environmentRoot: active.environmentRoot,
             },
           },
         );

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

@@ -2,7 +2,7 @@ import { devDeliveryContentRoot, devDeliveryExactRoot as exactRoot, devDeliveryE
 
 export const DEV_DELIVERY_SETTLEMENT_RECEIPT_SCHEMA = "kungfu.buildchain.dev-delivery-settlement-receipt/v1";
 
-function noopReceipt(queue, identity, candidate, action) {
+function noopReceipt(queue, identity, candidate, action, details = {}) {
   return {
     schema: DEV_DELIVERY_SETTLEMENT_RECEIPT_SCHEMA,
     action,
@@ -17,9 +17,36 @@ function noopReceipt(queue, identity, candidate, action) {
     expectedOldStateRoot: queue.stateRoot,
     nextStateRoot: queue.stateRoot,
     nextAction: "No fenced delivery state remains for this terminal event.",
+    ...details,
   };
 }
 
+function settleTerminalCandidate(queue, identity, candidate) {
+  if (candidate.status !== identity.outcome) {
+    if (identity.outcome !== "dequeued") throw new Error("terminal candidate outcome does not match the terminal event");
+    const receipt = noopReceipt(queue, identity, candidate, "stale-transient-dequeue-noop", {
+      terminalClass: "transient-dequeue",
+      authoritativeOutcome: candidate.status,
+      nextAction: "Retain the authoritative terminal settlement; the stale dequeue cannot rewrite it.",
+    });
+    return { queue, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+  }
+  const receipt = noopReceipt(queue, identity, candidate, "duplicate-terminal-event-noop");
+  return { queue, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+}
+
+function retainDequeuedWarrant(queue, identity, candidate, fencingToken, leaseGeneration, now) {
+  const leaseFresh = Date.parse(queue.activeWarrant.expiresAt) > Date.parse(now);
+  const receipt = noopReceipt(queue, identity, candidate, leaseFresh ? "transient-dequeue-retained-active-warrant" : "expired-active-warrant-awaits-fenced-settlement", {
+    terminalClass: "transient-dequeue",
+    fencingToken,
+    leaseGeneration,
+    warrantExpiresAt: queue.activeWarrant.expiresAt,
+    nextAction: leaseFresh ? "Continue the exact active native execution and heartbeat; later candidates remain queued." : "Prove the stale native worker stopped, then close this exact fenced generation before selecting a successor.",
+  });
+  return { queue, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+}
+
 export function createDevDeliveryTerminalSettler({ normalizeQueue, closeWarrant, cancelQueued, terminalStates }) {
   return function settleDevDeliveryTerminalEvent(queueInput, input, { now = new Date().toISOString() } = {}) {
     const queue = normalizeQueue(queueInput);
@@ -34,26 +61,38 @@ export function createDevDeliveryTerminalSettler({ normalizeQueue, closeWarrant,
     if (!terminalStates.has(identity.outcome)) throw new Error(`outcome must be one of ${[...terminalStates].join(", ")}`);
     const samePullRequest = queue.candidates.filter((entry) => entry.pullRequestNumber === identity.pullRequestNumber);
     const matchingHead = samePullRequest.filter((entry) => entry.sourceHead === identity.sourceHead);
-    const activeCandidate = queue.activeWarrant
-      ? matchingHead.find((entry) => entry.candidateId === queue.activeWarrant.candidateId)
-      : null;
+    const activeCandidate = queue.activeWarrant ? matchingHead.find((entry) => entry.candidateId === queue.activeWarrant.candidateId) : null;
     const candidate = activeCandidate || matchingHead.at(-1) || null;
     if (!candidate && samePullRequest.length > 0) throw new Error("terminal event sourceHead does not match the recorded candidate");
 
     if (candidate && terminalStates.has(candidate.status)) {
-      if (candidate.status !== identity.outcome) throw new Error("terminal candidate outcome does not match the terminal event");
-      const receipt = noopReceipt(queue, identity, candidate, "duplicate-terminal-event-noop");
-      return { queue, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+      return settleTerminalCandidate(queue, identity, candidate);
     }
 
     if (queue.activeWarrant) {
       if (!candidate || queue.activeWarrant.candidateId !== candidate.candidateId) throw new Error("terminal event does not match the active Delivery Warrant");
       if (!identity.evidenceRoot) throw new Error("active terminal settlement requires evidenceRoot");
-      return closeWarrant(queue, {
-        candidateId: candidate.candidateId,
-        fencingToken: exactRoot(input?.fencingToken, "fencingToken"),
-        generation: positiveInteger(input?.leaseGeneration, "leaseGeneration"),
-      }, { outcome: identity.outcome, evidenceRoot: identity.evidenceRoot, reason: identity.reason, now });
+      const fencingToken = exactRoot(input?.fencingToken, "fencingToken");
+      const leaseGeneration = positiveInteger(input?.leaseGeneration, "leaseGeneration");
+      if (fencingToken !== queue.activeWarrant.fencingToken) throw new Error("stale fencing token");
+      if (leaseGeneration !== queue.activeWarrant.generation) throw new Error("stale lease generation");
+      if (identity.outcome === "dequeued") {
+        return retainDequeuedWarrant(queue, identity, candidate, fencingToken, leaseGeneration, now);
+      }
+      return closeWarrant(
+        queue,
+        {
+          candidateId: candidate.candidateId,
+          fencingToken,
+          generation: leaseGeneration,
+        },
+        {
+          outcome: identity.outcome,
+          evidenceRoot: identity.evidenceRoot,
+          reason: identity.reason,
+          now,
+        },
+      );
     }
 
     if (!candidate) {
@@ -63,15 +102,19 @@ export function createDevDeliveryTerminalSettler({ normalizeQueue, closeWarrant,
     if (candidate.status !== "queued") throw new Error(`candidate status ${candidate.status} requires an active Delivery Warrant`);
     if (!["cancelled", "dequeued"].includes(identity.outcome)) throw new Error("queued candidate cannot settle as merged or terminal-failure");
     if (!identity.evidenceRoot) throw new Error("queued terminal settlement requires evidenceRoot");
-    return cancelQueued(queue, {
-      candidateId: candidate.candidateId,
-      pullRequestNumber: identity.pullRequestNumber,
-      expectedSourceHead: identity.sourceHead,
-      observedSourceHead: identity.sourceHead,
-      eventAction: identity.eventAction || (identity.outcome === "dequeued" ? "dequeued" : "closed"),
-      outcome: identity.outcome,
-      evidenceRoot: identity.evidenceRoot,
-      reason: identity.reason,
-    }, { now });
+    return cancelQueued(
+      queue,
+      {
+        candidateId: candidate.candidateId,
+        pullRequestNumber: identity.pullRequestNumber,
+        expectedSourceHead: identity.sourceHead,
+        observedSourceHead: identity.sourceHead,
+        eventAction: identity.eventAction || (identity.outcome === "dequeued" ? "dequeued" : "closed"),
+        outcome: identity.outcome,
+        evidenceRoot: identity.evidenceRoot,
+        reason: identity.reason,
+      },
+      { now },
+    );
   };
 }

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

@@ -7,7 +7,7 @@ import { compareReleaseBlockerPriority, normalizeReleaseBlockerPriorityClaim } f
 export { devDeliveryContentRoot } from "./dev-delivery-common.js";
 export { RELEASE_BLOCKER_PRIORITY_CLAIM_SCHEMA, createReleaseBlockerPriorityClaim } from "./release-blocker-priority.js";
 export { SOURCE_QUALIFICATION_PROOF_SCHEMA, PROJECT_CUT_REPLAY_PROOF_SCHEMA, INTEGRATION_DELIVERY_PROOF_SCHEMA, classifyDevDeliveryDelta, createIntegrationDeliveryProof, createProjectCutReplayPlan, createProjectCutReplayProof, createSourceQualificationProof, verifyIntegrationDeliveryProof, verifyProjectCutReplayProof, verifySourceQualificationProof } from "./dev-delivery-proof.js";
-export { DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA, NATIVE_QUALIFICATION_PROOF_SCHEMA, NATIVE_PROOF_REUSE_DECISION_SCHEMA, createNativeProofReuseDecision, createNativeQualificationProof, verifyNativeProofReuseDecision, verifyNativeQualificationProof } from "./dev-delivery-native-proof.js";
+export { DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA, NATIVE_QUALIFICATION_PROOF_SCHEMA, NATIVE_PROOF_REUSE_DECISION_SCHEMA, NATIVE_PROOF_BASE_DELTA_SCHEMA, createNativeProofBaseDelta, createNativeProofReuseDecision, createNativeQualificationProof, verifyNativeProofReuseDecision, verifyNativeQualificationProof } from "./dev-delivery-native-proof.js";
 export { DEV_DELIVERY_CANCELLATION_RECEIPT_SCHEMA };
 export const DEV_DELIVERY_QUEUE_CONTRACT = "kungfu-buildchain-dev-delivery-warrant-queue";
 export const DEV_DELIVERY_WARRANT_SCHEMA = "kungfu.buildchain.dev-delivery-warrant/v1";
@@ -23,7 +23,14 @@ export const DEV_DELIVERY_PRIORITIES = Object.freeze({
 
 export const DEV_DELIVERY_CLASSES = Object.freeze(["non-native-fast", "native-proof-required", "cross-platform", "release"]);
 
-const TERMINAL_STATES = new Set(["merged", "terminal-failure", "dequeued", "cancelled"]);
+const TERMINAL_STATES = new Set(["merged", "terminal-failure", "dequeued", "cancelled", "superseded"]);
+const TERMINAL_CLASSES = Object.freeze({
+  merged: "authoritative-completion",
+  "terminal-failure": "authoritative-failure",
+  cancelled: "authoritative-cancellation",
+  superseded: "authoritative-supersession",
+  dequeued: "transient-dequeue",
+});
 function nonNegativeInteger(value, label, fallback = 0) {
   const parsed = Number(value ?? fallback);
   if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${label} must be a non-negative integer`);
@@ -73,7 +80,14 @@ function normalizeCandidate(input, expected) {
     closureRoot: exactRoot(input.closureRoot, "closureRoot"),
     dependencyRoot: exactRoot(input.dependencyRoot, "dependencyRoot"),
     toolchainRoot: exactRoot(input.toolchainRoot, "toolchainRoot"),
-    ...(Object.hasOwn(input, "sourceWorkflowRunId") ? { sourceWorkflowRunId: nonNegativeInteger(input.sourceWorkflowRunId, "candidate sourceWorkflowRunId", 0) } : {}),
+    ...(input.environmentRoot
+      ? { environmentRoot: exactRoot(input.environmentRoot, "environmentRoot") }
+      : {}),
+    ...(Object.hasOwn(input, "sourceWorkflowRunId")
+      ? {
+          sourceWorkflowRunId: nonNegativeInteger(input.sourceWorkflowRunId, "candidate sourceWorkflowRunId", 0),
+        }
+      : {}),
     priority: priority(input.priority),
     enqueuedAt: timestamp(input.enqueuedAt, "candidate enqueuedAt"),
     updatedAt: timestamp(input.updatedAt || input.enqueuedAt, "candidate updatedAt"),
@@ -197,7 +211,7 @@ function submissionReceipt({ before, after, candidate, action, now }) {
     planRoot: candidate.planRoot,
     closureRoot: candidate.closureRoot,
     dependencyRoot: candidate.dependencyRoot,
-    toolchainRoot: candidate.toolchainRoot,
+    toolchainRoot: candidate.toolchainRoot, ...(candidate.environmentRoot ? { environmentRoot: candidate.environmentRoot } : {}),
     ...(Object.hasOwn(candidate, "affectedPaths") ? { affectedPaths: candidate.affectedPaths } : {}),
     sourceWorkflowRunId: candidate.sourceWorkflowRunId,
     ...(Object.hasOwn(candidate, "releaseBlockerPriority") ? { releaseBlockerPriority: candidate.releaseBlockerPriority } : {}),
@@ -213,6 +227,21 @@ function submissionReceipt({ before, after, candidate, action, now }) {
   };
 }
 
+function reconcileSourceWorkflowRunId(existing, attempted, activeCandidateId, currentTime) {
+  const current = existing.sourceWorkflowRunId || 0;
+  const next = attempted.sourceWorkflowRunId || 0;
+  if (existing.sourceHead !== attempted.sourceHead) {
+    existing.sourceWorkflowRunId = next;
+    return "head-change";
+  }
+  if (current > 0 && next > 0 && current !== next) throw new Error("candidate sourceWorkflowRunId cannot change for the same sourceHead");
+  if (current !== 0 || next === 0) return "retained";
+  if (activeCandidateId === existing.candidateId) return "active";
+  existing.sourceWorkflowRunId = next;
+  existing.updatedAt = currentTime;
+  return "upgraded";
+}
+
 export function submitDevDeliveryCandidate(queueInput, input, { now = new Date().toISOString() } = {}) {
   const transaction = transition(
     queueInput,
@@ -228,7 +257,13 @@ export function submitDevDeliveryCandidate(queueInput, input, { now = new Date()
         },
         queue,
       );
-      const chainedInput = chainedDevDeliveryAttemptInput({ queue, candidate, input, currentTime, terminalStates: TERMINAL_STATES });
+      const chainedInput = chainedDevDeliveryAttemptInput({
+        queue,
+        candidate,
+        input,
+        currentTime,
+        terminalStates: TERMINAL_STATES,
+      });
       const attemptedCandidate = chainedInput ? normalizeCandidate(chainedInput, queue) : candidate;
       const conflicting = queue.candidates.find((entry) => entry.pullRequestNumber === attemptedCandidate.pullRequestNumber && entry.candidateId !== attemptedCandidate.candidateId && !TERMINAL_STATES.has(entry.status));
       if (conflicting) throw new Error(`PR #${candidate.pullRequestNumber} already has a different active semantic source`);
@@ -239,10 +274,12 @@ export function submitDevDeliveryCandidate(queueInput, input, { now = new Date()
         if (TERMINAL_STATES.has(existing.status)) {
           throw new Error(`candidate ${attemptedCandidate.candidateId} is terminal and cannot be resubmitted`);
         }
-        const exactProofFields = ["sourcePatchRoot", "sourceProofRoot", "planRoot", "closureRoot", "dependencyRoot", "toolchainRoot"];
+        const exactProofFields = ["sourcePatchRoot", "sourceProofRoot", "planRoot", "closureRoot", "dependencyRoot", "toolchainRoot", "environmentRoot"];
         const exactProofMatches = exactProofFields.every((field) => existing[field] === attemptedCandidate[field]) && JSON.stringify(existing.affectedPaths || []) === JSON.stringify(attemptedCandidate.affectedPaths || []) && existing.releaseBlockerPriority?.claimRoot === attemptedCandidate.releaseBlockerPriority?.claimRoot;
+        const bindingAction = reconcileSourceWorkflowRunId(existing, attemptedCandidate, before.activeWarrant?.candidateId, currentTime);
         if (existing.sourceHead === attemptedCandidate.sourceHead && exactProofMatches) {
-          action = "duplicate-noop";
+          if (bindingAction === "active") return { candidate: existing, action: "active-warrant-retained-noop" };
+          action = bindingAction === "upgraded" ? "source-workflow-run-upgrade-retained-age" : "duplicate-noop";
           selected = existing;
         } else {
           if (before.activeWarrant?.candidateId === existing.candidateId) {
@@ -325,26 +362,26 @@ function warrantToken(input) {
 
 export function selectDevDeliveryWarrant(queueInput, { now = new Date().toISOString(), leaseSeconds } = {}) {
   const currentTime = timestamp(now, "now");
-  let queue = normalizeDevDeliveryQueue(queueInput);
+  const queue = normalizeDevDeliveryQueue(queueInput);
   let recoveryReceipt = null;
   if (queue.activeWarrant && Date.parse(queue.activeWarrant.expiresAt) <= Date.parse(currentTime)) {
     const recovered = recoverExpiredDevDeliveryWarrant(queue, {
       now: currentTime,
     });
-    queue = recovered.queue;
     recoveryReceipt = recovered.receipt;
   }
   if (queue.activeWarrant) {
+    const expired = Date.parse(queue.activeWarrant.expiresAt) <= Date.parse(currentTime);
     const receipt = {
       schema: DEV_DELIVERY_SELECTION_RECEIPT_SCHEMA,
-      selected: true,
-      reason: "non-preemptive-active-warrant",
+      selected: !expired,
+      reason: expired ? "expired-active-warrant-awaits-fenced-settlement" : "non-preemptive-active-warrant",
       candidateId: queue.activeWarrant.candidateId,
       fencingToken: queue.activeWarrant.fencingToken,
       leaseGeneration: queue.activeWarrant.generation,
       expectedOldStateRoot: recoveryReceipt?.expectedOldStateRoot || queue.stateRoot,
       nextStateRoot: queue.stateRoot,
-      nextAction: "Continue the active delivery attempt; later candidates remain visibly queued.",
+      nextAction: expired ? "Prove the stale native worker stopped, then close this exact fenced generation before selecting a successor." : "Continue the active delivery attempt; later candidates remain visibly queued.",
     };
     return {
       queue,
@@ -395,7 +432,7 @@ export function selectDevDeliveryWarrant(queueInput, { now = new Date().toISOStr
         planRoot: candidate.planRoot,
         closureRoot: candidate.closureRoot,
         dependencyRoot: candidate.dependencyRoot,
-        toolchainRoot: candidate.toolchainRoot,
+        toolchainRoot: candidate.toolchainRoot, ...(candidate.environmentRoot ? { environmentRoot: candidate.environmentRoot } : {}),
         ...(Object.hasOwn(candidate, "affectedPaths") ? { affectedPaths: candidate.affectedPaths } : {}),
         sourceWorkflowRunId: candidate.sourceWorkflowRunId,
         ...(Object.hasOwn(candidate, "releaseBlockerPriority") ? { releaseBlockerPriority: candidate.releaseBlockerPriority } : {}),
@@ -433,9 +470,13 @@ export function selectDevDeliveryWarrant(queueInput, { now = new Date().toISOStr
     planRoot: transaction.result.candidate.planRoot,
     closureRoot: transaction.result.candidate.closureRoot,
     dependencyRoot: transaction.result.candidate.dependencyRoot,
-    toolchainRoot: transaction.result.candidate.toolchainRoot,
+    toolchainRoot: transaction.result.candidate.toolchainRoot, ...(transaction.result.candidate.environmentRoot ? { environmentRoot: transaction.result.candidate.environmentRoot } : {}),
     sourceWorkflowRunId: transaction.result.candidate.sourceWorkflowRunId,
-    ...(Object.hasOwn(transaction.result.candidate, "releaseBlockerPriority") ? { releaseBlockerPriority: transaction.result.candidate.releaseBlockerPriority } : {}),
+    ...(Object.hasOwn(transaction.result.candidate, "releaseBlockerPriority")
+      ? {
+          releaseBlockerPriority: transaction.result.candidate.releaseBlockerPriority,
+        }
+      : {}),
     deliveryClass: transaction.result.candidate.deliveryClass,
     queueAgeSeconds: selected.priority.ageSeconds,
     basePriority: selected.priority.basePriority,
@@ -497,8 +538,13 @@ export function heartbeatDevDeliveryWarrant(queueInput, warrant, { now = new Dat
   };
 }
 
-const qualifyDevDeliveryWarrantTransition = createDevDeliveryWarrantQualifier({ transition, assertWarrantMutation });
-export function qualifyDevDeliveryWarrant(queueInput, warrant, options) { return qualifyDevDeliveryWarrantTransition(queueInput, warrant, options); }
+const qualifyDevDeliveryWarrantTransition = createDevDeliveryWarrantQualifier({
+  transition,
+  assertWarrantMutation,
+});
+export function qualifyDevDeliveryWarrant(queueInput, warrant, options) {
+  return qualifyDevDeliveryWarrantTransition(queueInput, warrant, options);
+}
 export function recoverExpiredDevDeliveryWarrant(queueInput, { now = new Date().toISOString() } = {}) {
   const currentTime = timestamp(now, "now");
   const before = normalizeDevDeliveryQueue(queueInput);
@@ -517,33 +563,21 @@ export function recoverExpiredDevDeliveryWarrant(queueInput, { now = new Date().
       receiptRoot: devDeliveryContentRoot(receipt),
     };
   }
-  const transaction = transition(
-    before,
-    (queue) => {
-      const expired = clone(queue.activeWarrant);
-      const candidate = queue.candidates.find((entry) => entry.candidateId === expired.candidateId);
-      candidate.status = "queued";
-      candidate.recoveries += 1;
-      candidate.attempts += 1;
-      candidate.updatedAt = currentTime;
-      queue.activeWarrant = null;
-      return { candidate, expired };
-    },
-    currentTime,
-  );
+  const expired = before.activeWarrant;
+  const candidate = before.candidates.find((entry) => entry.candidateId === expired.candidateId);
   const receipt = {
     schema: DEV_DELIVERY_LEASE_RECEIPT_SCHEMA,
-    action: "recovered-expired-lease",
-    candidateId: transaction.result.candidate.candidateId,
-    rejectedFencingToken: transaction.result.expired.fencingToken,
-    expiredLeaseGeneration: transaction.result.expired.generation,
-    retainedEnqueuedAt: transaction.result.candidate.enqueuedAt,
-    expectedOldStateRoot: transaction.expectedOldStateRoot,
-    nextStateRoot: transaction.after.stateRoot,
-    nextAction: "Re-select through the queue to mint a new lease generation and fencing token.",
+    action: "expired-lease-fenced-stop-required",
+    candidateId: candidate.candidateId,
+    rejectedFencingToken: expired.fencingToken,
+    expiredLeaseGeneration: expired.generation,
+    retainedEnqueuedAt: candidate.enqueuedAt,
+    expectedOldStateRoot: before.stateRoot,
+    nextStateRoot: before.stateRoot,
+    nextAction: "Prove the stale native worker stopped, then close this exact fenced generation before selecting a successor.",
   };
   return {
-    queue: transaction.after,
+    queue: before,
     receipt,
     receiptRoot: devDeliveryContentRoot(receipt),
   };
@@ -555,16 +589,22 @@ export function closeDevDeliveryWarrant(queueInput, warrant, { outcome, evidence
   if (!TERMINAL_STATES.has(normalizedOutcome)) {
     throw new Error(`outcome must be one of ${[...TERMINAL_STATES].join(", ")}`);
   }
+  if (normalizedOutcome === "dequeued") {
+    throw new Error("transient dequeue cannot close an active Delivery Warrant");
+  }
   const transaction = transition(
     queueInput,
     (queue, before) => {
-      assertWarrantMutation(before, warrant, currentTime, { allowExpired: true });
+      assertWarrantMutation(before, warrant, currentTime, {
+        allowExpired: true,
+      });
       const active = clone(queue.activeWarrant);
       const candidate = queue.candidates.find((entry) => entry.candidateId === active.candidateId);
       candidate.status = normalizedOutcome;
       candidate.updatedAt = currentTime;
       candidate.terminal = {
         outcome: normalizedOutcome,
+        terminalClass: TERMINAL_CLASSES[normalizedOutcome],
         reason: text(reason),
         evidenceRoot: exactRoot(evidenceRoot, "evidenceRoot"),
         closedAt: currentTime,
@@ -580,6 +620,7 @@ export function closeDevDeliveryWarrant(queueInput, warrant, { outcome, evidence
     schema: DEV_DELIVERY_LEASE_RECEIPT_SCHEMA,
     action: "terminal-closeout",
     outcome: normalizedOutcome,
+    terminalClass: TERMINAL_CLASSES[normalizedOutcome],
     reason: text(reason),
     candidateId: transaction.result.candidate.candidateId,
     fencingToken: transaction.result.active.fencingToken,
@@ -597,8 +638,15 @@ export function closeDevDeliveryWarrant(queueInput, warrant, { outcome, evidence
 }
 
 const cancelQueuedDevDeliveryCandidateTransition = createCancelQueuedDevDeliveryCandidate(normalizeDevDeliveryQueue);
-export function cancelQueuedDevDeliveryCandidate(queueInput, input, options) { return cancelQueuedDevDeliveryCandidateTransition(queueInput, input, options); }
-export const settleDevDeliveryTerminalEvent = createDevDeliveryTerminalSettler({ normalizeQueue: normalizeDevDeliveryQueue, closeWarrant: closeDevDeliveryWarrant, cancelQueued: cancelQueuedDevDeliveryCandidate, terminalStates: TERMINAL_STATES });
+export function cancelQueuedDevDeliveryCandidate(queueInput, input, options) {
+  return cancelQueuedDevDeliveryCandidateTransition(queueInput, input, options);
+}
+export const settleDevDeliveryTerminalEvent = createDevDeliveryTerminalSettler({
+  normalizeQueue: normalizeDevDeliveryQueue,
+  closeWarrant: closeDevDeliveryWarrant,
+  cancelQueued: cancelQueuedDevDeliveryCandidate,
+  terminalStates: TERMINAL_STATES,
+});
 
 export function observeDevDeliveryQueue(queueInput, { now = new Date().toISOString() } = {}) {
   const queue = normalizeDevDeliveryQueue(queueInput);
@@ -633,7 +681,7 @@ export function observeDevDeliveryQueue(queueInput, { now = new Date().toISOStri
       planRoot: entry.candidate.planRoot,
       closureRoot: entry.candidate.closureRoot,
       dependencyRoot: entry.candidate.dependencyRoot,
-      toolchainRoot: entry.candidate.toolchainRoot,
+      toolchainRoot: entry.candidate.toolchainRoot, ...(entry.candidate.environmentRoot ? { environmentRoot: entry.candidate.environmentRoot } : {}),
       sourceWorkflowRunId: entry.candidate.sourceWorkflowRunId || 0,
       affectedPaths: entry.candidate.affectedPaths || [],
       deliveryClass: entry.candidate.deliveryClass,

package/scripts/buildchain-cli-help.mjs

@@ -132,6 +132,9 @@ export const BUILDCHAIN_USAGE = `Usage:
   buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|cancel-queued|observe>
                              --repository <owner/repo> --branch <dev/vN/vN.M>
                              [--execute] [--output <file>] [--json]
+  buildchain dev authority <migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe>
+                             --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--execute] [--output <file>] [--json]
   buildchain dev proof <source|verify-source|classify|native|verify-native|classify-native|verify-native-reuse|replay|integration|verify-integration>
                              [--output <file>] [--json]
   buildchain dev two-phase --repository <owner/repo> --branch <dev/vN/vN.M>