@kungfu-tech/buildchain 3.0.9-alpha.1 → 3.0.9-alpha.10

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

@@ -2,10 +2,12 @@ import { devDeliveryClone as clone, devDeliveryContentRoot, devDeliveryExactRoot
 import { chainedDevDeliveryAttemptInput, createDevDeliveryCandidateIdentity, validateDevDeliveryCandidateChain } from "./dev-delivery-candidate-identity.js";
 import { DEV_DELIVERY_CANCELLATION_RECEIPT_SCHEMA, createCancelQueuedDevDeliveryCandidate } from "./dev-delivery-warrant-cancellation.js";
 import { DEV_DELIVERY_SETTLEMENT_RECEIPT_SCHEMA, createDevDeliveryTerminalSettler } from "./dev-delivery-warrant-settlement.js";
+import { createDevDeliveryWarrantQualifier } from "./dev-delivery-native-proof.js";
 import { compareReleaseBlockerPriority, normalizeReleaseBlockerPriorityClaim } from "./release-blocker-priority.js";
 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, 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";
@@ -21,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`);
@@ -59,7 +68,7 @@ function normalizeCandidate(input, expected) {
     throw new Error(`candidateId mismatch for PR #${identity.pullRequestNumber}`);
   }
   const status = text(input.status || "queued");
-  if (!["queued", "selected", "proving", "waiting", "blocked", ...TERMINAL_STATES].includes(status)) {
+  if (!["queued", "selected", "provisional", "proving", "qualified", "waiting", "blocked", ...TERMINAL_STATES].includes(status)) {
     throw new Error(`unsupported candidate status ${status || "<empty>"}`);
   }
   const candidate = {
@@ -71,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"),
@@ -80,6 +96,10 @@ function normalizeCandidate(input, expected) {
     status,
     terminal: input.terminal || null,
   };
+  if (Object.hasOwn(input, "affectedPaths")) {
+    if (!Array.isArray(input.affectedPaths)) throw new Error("candidate affectedPaths must be an array");
+    candidate.affectedPaths = [...new Set(input.affectedPaths.map(text).filter(Boolean))].sort();
+  }
   if (Object.hasOwn(input, "releaseBlockerPriority")) candidate.releaseBlockerPriority = normalizeReleaseBlockerPriorityClaim(input.releaseBlockerPriority, candidate, expected);
   return candidate;
 }
@@ -140,12 +160,20 @@ export function normalizeDevDeliveryQueue(input, expected = {}) {
     warrant.generation = positiveInteger(warrant.generation, "Warrant generation");
     warrant.issuedAt = timestamp(warrant.issuedAt, "Warrant issuedAt");
     warrant.expiresAt = timestamp(warrant.expiresAt, "Warrant expiresAt");
-    const activeCandidates = queue.candidates.filter((candidate) => ["selected", "proving", "waiting", "blocked"].includes(candidate.status));
+    const warrantPhase = text(warrant.phase || "qualified");
+    if (!["provisional", "qualified"].includes(warrantPhase)) throw new Error("active Warrant phase is unsupported");
+    if (Object.hasOwn(warrant, "phase")) warrant.phase = warrantPhase;
+    if (warrantPhase === "qualified") {
+      if (warrant.nativeProofRoot) warrant.nativeProofRoot = exactRoot(warrant.nativeProofRoot, "Warrant nativeProofRoot");
+      if (warrant.nativeProofReuseRoot) warrant.nativeProofReuseRoot = exactRoot(warrant.nativeProofReuseRoot, "Warrant nativeProofReuseRoot");
+      if (warrant.qualifiedAt) warrant.qualifiedAt = timestamp(warrant.qualifiedAt, "Warrant qualifiedAt");
+    }
+    const activeCandidates = queue.candidates.filter((candidate) => ["selected", "provisional", "proving", "qualified", "waiting", "blocked"].includes(candidate.status));
     if (activeCandidates.length !== 1 || activeCandidates[0].candidateId !== warrant.candidateId) {
       throw new Error("exactly one active candidate must match the active Warrant");
     }
     if (warrant.releaseBlockerPriority?.claimRoot !== activeCandidates[0].releaseBlockerPriority?.claimRoot) throw new Error("active Warrant release-blocker priority drift");
-  } else if (queue.candidates.some((candidate) => ["selected", "proving", "waiting", "blocked"].includes(candidate.status))) {
+  } else if (queue.candidates.some((candidate) => ["selected", "provisional", "proving", "qualified", "waiting", "blocked"].includes(candidate.status))) {
     throw new Error("active candidate exists without an active Warrant");
   }
   const rooted = withQueueRoot(queue);
@@ -183,7 +211,8 @@ 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 } : {}),
     deliveryClass: candidate.deliveryClass,
@@ -198,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,
@@ -213,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`);
@@ -224,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 exactProofMatches = exactProofFields.every((field) => existing[field] === attemptedCandidate[field]) && existing.releaseBlockerPriority?.claimRoot === attemptedCandidate.releaseBlockerPriority?.claimRoot;
+        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) {
@@ -241,6 +293,8 @@ export function submitDevDeliveryCandidate(queueInput, input, { now = new Date()
           const headChanged = existing.sourceHead !== attemptedCandidate.sourceHead;
           existing.sourceHead = attemptedCandidate.sourceHead;
           for (const field of exactProofFields) existing[field] = attemptedCandidate[field];
+          if (Object.hasOwn(attemptedCandidate, "affectedPaths")) existing.affectedPaths = attemptedCandidate.affectedPaths;
+          else delete existing.affectedPaths;
           if (Object.hasOwn(attemptedCandidate, "releaseBlockerPriority")) existing.releaseBlockerPriority = attemptedCandidate.releaseBlockerPriority;
           else delete existing.releaseBlockerPriority;
           existing.updatedAt = currentTime;
@@ -308,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,
@@ -378,16 +432,18 @@ 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 } : {}),
         deliveryClass: candidate.deliveryClass,
         generation: next.fencingCounter,
+        phase: "provisional",
         expectedOldStateRoot: before.stateRoot,
         issuedAt,
         expiresAt: new Date(Date.parse(issuedAt) + effectiveLeaseSeconds * 1000).toISOString(),
         fencingToken: "",
-        nextAction: "Replay on the exact current dev base, prove required checks, then enqueue the unchanged PR head.",
+        nextAction: "Run or reuse the exact semantic native proof, then atomically qualify this fenced Warrant.",
       };
       warrant.fencingToken = warrantToken(warrant);
       next.activeWarrant = warrant;
@@ -414,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,
@@ -454,7 +514,7 @@ export function heartbeatDevDeliveryWarrant(queueInput, warrant, { now = new Dat
       const effectiveLeaseSeconds = positiveInteger(leaseSeconds, "leaseSeconds", queue.policy.leaseSeconds);
       queue.activeWarrant.expiresAt = new Date(Date.parse(currentTime) + effectiveLeaseSeconds * 1000).toISOString();
       const candidate = queue.candidates.find((entry) => entry.candidateId === queue.activeWarrant.candidateId);
-      candidate.status = "proving";
+      candidate.status = queue.activeWarrant.phase === "qualified" ? "qualified" : "proving";
       candidate.updatedAt = currentTime;
       return { candidate, warrant: queue.activeWarrant };
     },
@@ -478,6 +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);
+}
 export function recoverExpiredDevDeliveryWarrant(queueInput, { now = new Date().toISOString() } = {}) {
   const currentTime = timestamp(now, "now");
   const before = normalizeDevDeliveryQueue(queueInput);
@@ -496,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),
   };
@@ -534,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,
@@ -559,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,
@@ -576,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);
@@ -604,6 +673,19 @@ export function observeDevDeliveryQueue(queueInput, { now = new Date().toISOStri
       queueAgeSeconds: entry.priority.ageSeconds,
       attempts: entry.candidate.attempts,
       recoveries: entry.candidate.recoveries,
+      assignmentRoot: entry.candidate.assignmentRoot,
+      initiativeRoot: entry.candidate.initiativeRoot,
+      sourceIdentityRoot: entry.candidate.sourceIdentityRoot,
+      sourcePatchRoot: entry.candidate.sourcePatchRoot,
+      sourceProofRoot: entry.candidate.sourceProofRoot,
+      planRoot: entry.candidate.planRoot,
+      closureRoot: entry.candidate.closureRoot,
+      dependencyRoot: entry.candidate.dependencyRoot,
+      toolchainRoot: entry.candidate.toolchainRoot, ...(entry.candidate.environmentRoot ? { environmentRoot: entry.candidate.environmentRoot } : {}),
+      sourceWorkflowRunId: entry.candidate.sourceWorkflowRunId || 0,
+      affectedPaths: entry.candidate.affectedPaths || [],
+      deliveryClass: entry.candidate.deliveryClass,
+      priority: entry.candidate.priority,
       nextAction: index === 0 && !queue.activeWarrant ? "eligible-for-selection" : "wait-for-active-warrant",
     })),
     observedAt: currentTime,

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

@@ -0,0 +1,167 @@
+import kfdCategoryCatalog from "@kungfu-tech/kfd/adopter-conformance/category-profiles.json" with { type: "json" };
+import kfdPackageJson from "@kungfu-tech/kfd/package.json" with { type: "json" };
+import { resolveAdopterCategoryProfiles } from "@kungfu-tech/kfd/adopter-conformance/category-profile-resolver";
+import { verifyAdopterCategoryInstanceManifest } from "@kungfu-tech/kfd/adopter-conformance/category-instance-verifier";
+import { verifyAdopterManifestFromPackage } from "@kungfu-tech/kfd/adopter-conformance/toolchain";
+
+import {
+  ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+  adopterDeliveryGateDigest,
+  defineAdopterProtocolDriver,
+} from "./adopter-delivery-gate.js";
+
+export const KFD_ADOPTER_CATEGORY_PROTOCOL_ID =
+  "kfd.adopter-category/instance-manifest";
+export const KFD_ADOPTER_CATEGORY_PROTOCOL_VERSION = "1.0.0";
+export const KFD_ADOPTER_CATEGORY_DRIVER_REPORT_CONTRACT =
+  "kungfu-buildchain-kfd-adopter-category-driver-report";
+
+function freezeJson(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) freezeJson(child);
+  }
+  return value;
+}
+
+const publishedCatalog = freezeJson(structuredClone(kfdCategoryCatalog));
+
+function catalogCopy() {
+  return structuredClone(publishedCatalog);
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+export function resolvePublishedKfdAdopterCategoryProfiles(selection) {
+  return resolveAdopterCategoryProfiles(
+    structuredClone(selection),
+    catalogCopy(),
+  );
+}
+
+export function verifyPublishedKfdAdopterCategoryInstance(
+  instanceManifest,
+  { adopterManifest, verifiedAt, maxAgeSeconds } = {},
+) {
+  const adopterReport = verifyAdopterManifestFromPackage(adopterManifest, {
+    packageArtifactRoot: instanceManifest?.kfdCut?.packageRoot,
+    verifiedAt,
+    maxAgeSeconds,
+  });
+  return verifyAdopterCategoryInstanceManifest(instanceManifest, {
+    catalog: catalogCopy(),
+    adopterManifest,
+    adopterReport,
+    verifiedAt,
+    maxAgeSeconds,
+  });
+}
+
+function deliveryBindingIssues(request, adopterManifest) {
+  const instance = request.declaration;
+  const issues = [];
+  if (
+    request.project.instanceId !== instance?.instanceId ||
+    request.project.adopterId !== instance?.project?.adopterId
+  ) {
+    issues.push(
+      issue(
+        "delivery-kfd-instance-binding-mismatch",
+        "/project",
+        "Delivery project identity must match the KFD category instance.",
+      ),
+    );
+  }
+  if (!sameJson(request.artifact, instance?.project?.artifact)) {
+    issues.push(
+      issue(
+        "delivery-kfd-instance-binding-mismatch",
+        "/artifact",
+        "Delivery artifact must match the KFD category instance artifact.",
+      ),
+    );
+  }
+  if (
+    adopterManifest?.kfdCut?.package?.name !== kfdPackageJson.name ||
+    adopterManifest?.kfdCut?.package?.version !== kfdPackageJson.version ||
+    instance?.kfdCut?.packageVersion !== kfdPackageJson.version
+  ) {
+    issues.push(
+      issue(
+        "delivery-kfd-package-cut-mismatch",
+        "/declaration/kfdCut",
+        "KFD declarations must bind the exact installed published package version.",
+      ),
+    );
+  }
+  return issues;
+}
+
+function driverReport(categoryReport, adapterIssues) {
+  const valid = categoryReport?.valid === true && adapterIssues.length === 0;
+  const report = {
+    schemaVersion: 1,
+    contract: KFD_ADOPTER_CATEGORY_DRIVER_REPORT_CONTRACT,
+    valid,
+    conforming: valid,
+    qualifying: false,
+    selfCertified: false,
+    independentlyCertified: false,
+    kfdPackage: {
+      name: kfdPackageJson.name,
+      version: kfdPackageJson.version,
+    },
+    categoryReport,
+    adapterIssues,
+    nonClaims: [
+      "Category conformance does not grant runtime permission or release authorization.",
+      "Buildchain carries the published KFD decision and does not certify or reinterpret it.",
+    ],
+  };
+  return {
+    valid,
+    report,
+    reportRoot: adopterDeliveryGateDigest(report),
+    issues: [...(categoryReport?.issues ?? []), ...adapterIssues],
+  };
+}
+
+export function createKfdAdopterCategoryProtocolDriver() {
+  return defineAdopterProtocolDriver({
+    interface: ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+    id: KFD_ADOPTER_CATEGORY_PROTOCOL_ID,
+    version: KFD_ADOPTER_CATEGORY_PROTOCOL_VERSION,
+    verify({ request, context }) {
+      const adapterIssues = deliveryBindingIssues(
+        request,
+        context?.adopterManifest,
+      );
+      let categoryReport = null;
+      try {
+        categoryReport = verifyPublishedKfdAdopterCategoryInstance(
+          request.declaration,
+          context,
+        );
+      } catch {
+        adapterIssues.push(
+          issue(
+            "delivery-kfd-verification-context-invalid",
+            "/protocol",
+            "Published KFD verification could not reproduce from the supplied exact context.",
+          ),
+        );
+      }
+      return driverReport(categoryReport, adapterIssues);
+    },
+  });
+}