@kungfu-tech/buildchain 3.0.6-alpha.0 → 3.0.6-alpha.2

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

@@ -0,0 +1,94 @@
+import { devDeliveryClone as clone, devDeliveryContentRoot, devDeliveryExactRoot as exactRoot, devDeliveryExactSha as exactSha, devDeliveryPositiveInteger as positiveInteger, devDeliveryText as text, devDeliveryTimestamp as timestamp } from "./dev-delivery-common.js";
+
+export const DEV_DELIVERY_CANCELLATION_RECEIPT_SCHEMA = "kungfu.buildchain.dev-delivery-cancellation-receipt/v1";
+
+const TERMINAL_STATES = new Set(["merged", "terminal-failure", "dequeued", "cancelled"]);
+const QUEUED_CANCELLATION_EVENTS = new Map([
+  ["closed", "cancelled"],
+  ["cancelled", "cancelled"],
+  ["dequeued", "dequeued"],
+]);
+
+function cancellationReceipt(queue, candidate, identity, action, expectedOldStateRoot) {
+  return {
+    schema: DEV_DELIVERY_CANCELLATION_RECEIPT_SCHEMA,
+    action,
+    repository: queue.repository,
+    protectedBase: queue.protectedBase,
+    candidateId: candidate.candidateId,
+    pullRequestNumber: candidate.pullRequestNumber,
+    expectedSourceHead: identity.expectedSourceHead,
+    observedSourceHead: identity.observedSourceHead,
+    eventAction: identity.eventAction,
+    outcome: identity.outcome,
+    evidenceRoot: identity.evidenceRoot,
+    expectedOldStateRoot,
+    nextStateRoot: queue.stateRoot,
+    nextAction: "Select the next queued candidate, if any.",
+  };
+}
+
+function normalizeCancellation(input) {
+  const identity = {
+    candidateId: exactRoot(input?.candidateId, "candidateId"),
+    pullRequestNumber: positiveInteger(input?.pullRequestNumber, "pullRequestNumber"),
+    expectedSourceHead: exactSha(input?.expectedSourceHead, "expectedSourceHead"),
+    observedSourceHead: exactSha(input?.observedSourceHead, "observedSourceHead"),
+    eventAction: text(input?.eventAction).toLowerCase(),
+    outcome: text(input?.outcome).toLowerCase(),
+    evidenceRoot: exactRoot(input?.evidenceRoot, "evidenceRoot"),
+    reason: text(input?.reason),
+  };
+  const requiredOutcome = QUEUED_CANCELLATION_EVENTS.get(identity.eventAction);
+  if (!requiredOutcome) throw new Error(`eventAction must be one of ${[...QUEUED_CANCELLATION_EVENTS.keys()].join(", ")}`);
+  if (identity.outcome !== requiredOutcome) throw new Error(`eventAction ${identity.eventAction} requires outcome ${requiredOutcome}`);
+  return identity;
+}
+
+function terminalBinding(identity) {
+  return {
+    outcome: identity.outcome,
+    reason: identity.reason,
+    evidenceRoot: identity.evidenceRoot,
+    authority: "queued-candidate-cancellation",
+    expectedSourceHead: identity.expectedSourceHead,
+    observedSourceHead: identity.observedSourceHead,
+    eventAction: identity.eventAction,
+  };
+}
+
+export function createCancelQueuedDevDeliveryCandidate(normalizeDevDeliveryQueue) {
+  return function cancelQueuedDevDeliveryCandidate(queueInput, input, { now = new Date().toISOString() } = {}) {
+    const currentTime = timestamp(now, "now");
+    const identity = normalizeCancellation(input);
+    const before = normalizeDevDeliveryQueue(queueInput);
+    const candidate = before.candidates.find((entry) => entry.candidateId === identity.candidateId);
+    if (!candidate) throw new Error(`queued candidate ${identity.candidateId} does not exist`);
+    if (candidate.pullRequestNumber !== identity.pullRequestNumber) throw new Error("queued candidate PR mismatch");
+    if (candidate.sourceHead !== identity.expectedSourceHead) throw new Error("queued candidate recorded sourceHead mismatch");
+    if (before.activeWarrant?.candidateId === identity.candidateId) throw new Error("active candidate requires fenced Warrant closeout");
+
+    const terminal = terminalBinding(identity);
+    if (TERMINAL_STATES.has(candidate.status)) {
+      if (!Object.entries(terminal).every(([field, value]) => candidate.terminal?.[field] === value)) {
+        throw new Error("terminal candidate does not match the exact queued cancellation evidence");
+      }
+      const receipt = cancellationReceipt(before, candidate, identity, "duplicate-cancellation-noop", before.stateRoot);
+      return { queue: before, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+    }
+    if (candidate.status !== "queued") throw new Error(`candidate status ${candidate.status} requires fenced Warrant closeout`);
+
+    const queue = clone(before);
+    delete queue.stateRoot;
+    const queued = queue.candidates.find((entry) => entry.candidateId === identity.candidateId);
+    queued.status = identity.outcome;
+    queued.updatedAt = currentTime;
+    queued.terminal = { ...terminal, closedAt: currentTime };
+    queue.generation += 1;
+    queue.updatedAt = currentTime;
+    queue.stateRoot = devDeliveryContentRoot(queue);
+    const after = normalizeDevDeliveryQueue(queue);
+    const receipt = cancellationReceipt(after, queued, identity, "queued-candidate-cancelled", before.stateRoot);
+    return { queue: after, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+  };
+}

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

@@ -0,0 +1,73 @@
+import { devDeliveryContentRoot, devDeliveryExactRoot as exactRoot, devDeliveryExactSha as exactSha, devDeliveryPositiveInteger as positiveInteger, devDeliveryText as text } from "./dev-delivery-common.js";
+
+export const DEV_DELIVERY_SETTLEMENT_RECEIPT_SCHEMA = "kungfu.buildchain.dev-delivery-settlement-receipt/v1";
+
+function noopReceipt(queue, identity, candidate, action) {
+  return {
+    schema: DEV_DELIVERY_SETTLEMENT_RECEIPT_SCHEMA,
+    action,
+    applicable: action !== "terminal-event-not-applicable",
+    repository: queue.repository,
+    protectedBase: queue.protectedBase,
+    pullRequestNumber: identity.pullRequestNumber,
+    sourceHead: identity.sourceHead,
+    outcome: identity.outcome,
+    candidateId: candidate?.candidateId || null,
+    evidenceRoot: candidate?.terminal?.evidenceRoot || identity.evidenceRoot || null,
+    expectedOldStateRoot: queue.stateRoot,
+    nextStateRoot: queue.stateRoot,
+    nextAction: "No fenced delivery state remains for this terminal event.",
+  };
+}
+
+export function createDevDeliveryTerminalSettler({ normalizeQueue, closeWarrant, cancelQueued, terminalStates }) {
+  return function settleDevDeliveryTerminalEvent(queueInput, input, { now = new Date().toISOString() } = {}) {
+    const queue = normalizeQueue(queueInput);
+    const identity = {
+      pullRequestNumber: positiveInteger(input?.pullRequestNumber, "pullRequestNumber"),
+      sourceHead: exactSha(input?.sourceHead, "sourceHead"),
+      outcome: text(input?.outcome),
+      evidenceRoot: input?.evidenceRoot ? exactRoot(input.evidenceRoot, "evidenceRoot") : "",
+      reason: text(input?.reason),
+      eventAction: text(input?.eventAction).toLowerCase(),
+    };
+    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 candidate = samePullRequest.find((entry) => entry.sourceHead === identity.sourceHead) || 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) };
+    }
+
+    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 });
+    }
+
+    if (!candidate) {
+      const receipt = noopReceipt(queue, identity, null, "terminal-event-not-applicable");
+      return { queue, receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+    }
+    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 });
+  };
+}