@kungfu-tech/buildchain 4.0.2-alpha.0 → 4.0.2-alpha.4

package/packages/core/dev-delivery-provider-heartbeat.js

@@ -138,14 +138,21 @@ function terminal(jobInput) {
 function heartbeatEntry(result, previousStateRoot) {
   const warrant = selectedWarrant(result);
   const receipt = result.receipt;
+  const expectedOldStateRoot = receipt?.expectedOldStateRoot;
+  const recovery = result.concurrencyRecovery;
+  const rebased = expectedOldStateRoot !== previousStateRoot;
   if (
     receipt?.action !== "heartbeat" ||
-    result.before?.stateRoot !== previousStateRoot ||
-    receipt.expectedOldStateRoot !== previousStateRoot ||
+    result.before?.stateRoot !== expectedOldStateRoot ||
     result.after?.stateRoot !== receipt.nextStateRoot ||
     result.observation?.stateRoot !== receipt.nextStateRoot ||
     warrant?.fencingToken !== receipt.fencingToken ||
-    warrant?.generation !== receipt.leaseGeneration
+    warrant?.generation !== receipt.leaseGeneration ||
+    (rebased &&
+      (recovery?.action !== "heartbeat-state-root-rebased" ||
+        recovery.requestedStateRoot !== previousStateRoot ||
+        recovery.observedStateRoot !== expectedOldStateRoot)) ||
+    (!rebased && recovery)
   ) {
     throw new Error(
       "durable provider heartbeat transition is not root-continuous",
@@ -155,8 +162,10 @@ function heartbeatEntry(result, previousStateRoot) {
     throw new Error("durable provider heartbeat receipt root drift");
   }
   return {
-    expectedOldStateRoot: receipt.expectedOldStateRoot,
+    previousStateRoot,
+    expectedOldStateRoot,
     nextStateRoot: receipt.nextStateRoot,
+    concurrencyRecovery: recovery || null,
     receipt,
     receiptRoot: result.receiptRoot,
     heartbeatAt: timestamp(warrant.heartbeatAt, "durable heartbeatAt"),
@@ -274,13 +283,20 @@ function verifyHeartbeatContinuity(receipt, initial) {
   let previousRoot = initial.stateRoot;
   let previousTime = Date.parse(receipt.initialHeartbeatAt);
   for (const entry of receipt.heartbeats) {
+    const rebased = entry.expectedOldStateRoot !== previousRoot;
+    const recovery = entry.concurrencyRecovery;
     if (
-      entry.expectedOldStateRoot !== previousRoot ||
+      entry.previousStateRoot !== previousRoot ||
       devDeliveryContentRoot(entry.receipt) !== entry.receiptRoot ||
       entry.receipt.expectedOldStateRoot !== entry.expectedOldStateRoot ||
       entry.receipt.nextStateRoot !== entry.nextStateRoot ||
       entry.receipt.fencingToken !== initial.fencingToken ||
-      entry.receipt.leaseGeneration !== initial.generation
+      entry.receipt.leaseGeneration !== initial.generation ||
+      (rebased &&
+        (recovery?.action !== "heartbeat-state-root-rebased" ||
+          recovery.requestedStateRoot !== previousRoot ||
+          recovery.observedStateRoot !== entry.expectedOldStateRoot)) ||
+      (!rebased && recovery)
     ) {
       throw new Error("provider heartbeat root continuity mismatch");
     }

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

@@ -218,7 +218,8 @@ export function recoverLegacyTerminalDevDeliveryQueue(
       evidenceRoot: entry.evidenceRoot,
     });
   }
-  queue.activeWarrant = null;
+  if (transitions.some((entry) => entry.activeWarrant))
+    queue.activeWarrant = null;
   queue.generation += 1;
   queue.updatedAt = currentTime;
   queue.stateRoot = devDeliveryContentRoot(queue);
@@ -236,7 +237,8 @@ export function recoverLegacyTerminalDevDeliveryQueue(
     nextStateRoot: after.stateRoot,
     requestRoot,
     transitions,
-    nextAction: "Select the next strictly valid queued candidate, if any.",
+    nextAction:
+      "Continue the exact active Warrant, or select the next candidate.",
   };
   return {
     queue: after,

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

@@ -0,0 +1,33 @@
+export function lacksExactNativeExecutionContract(
+  candidate,
+  allowLegacyV3Readback = false,
+) {
+  const native =
+    candidate.deliveryClass !== "non-native-fast" ||
+    candidate.environmentRoot ||
+    candidate.nativeCommandContract;
+  return Boolean(
+    native &&
+    (!candidate.environmentRoot ||
+      (!candidate.nativeCommandContract && !allowLegacyV3Readback)),
+  );
+}
+
+export function lacksLiveNativeProof(
+  candidate,
+  status,
+  { allowLegacyV3Readback = false, allowLegacyQueuedReadback = false } = {},
+) {
+  return (
+    lacksExactNativeExecutionContract(candidate, allowLegacyV3Readback) &&
+    !(status === "queued" && allowLegacyQueuedReadback) &&
+    !TERMINAL_STATES.has(status)
+  );
+}
+const TERMINAL_STATES = new Set([
+  "merged",
+  "terminal-failure",
+  "dequeued",
+  "cancelled",
+  "superseded",
+]);

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

@@ -12,6 +12,8 @@ import {
 import {
   chainedDevDeliveryAttemptInput,
   createDevDeliveryCandidateIdentity,
+  EXACT_DEV_DELIVERY_PROOF_FIELDS,
+  matchesExactDevDeliveryCandidate,
   validateDevDeliveryCandidateChain,
 } from "./dev-delivery-candidate-identity.js";
 import {
@@ -19,6 +21,10 @@ import {
   normalizeNativeCommandContract,
   validateActiveDevDeliveryWarrant,
 } from "./dev-delivery-native-proof.js";
+import {
+  lacksExactNativeExecutionContract,
+  lacksLiveNativeProof,
+} from "./dev-delivery-warrant-native-compatibility.js";
 import {
   normalizeProviderFailureAuthorityBinding,
   normalizeTerminalEvidenceCorrection,
@@ -34,6 +40,8 @@ export const DEV_DELIVERY_WARRANT_SCHEMA =
   "kungfu.buildchain.dev-delivery-warrant/v1";
 export const DEV_DELIVERY_SUBMISSION_RECEIPT_SCHEMA =
   "kungfu.buildchain.dev-delivery-submission-receipt/v1";
+export const DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT =
+  "sha256:54a203cadf0b14d4e3c198a3cc3c177c42813aa1c0cca03e900df714b6ae5563";
 export const DEV_DELIVERY_SELECTION_RECEIPT_SCHEMA =
   "kungfu.buildchain.dev-delivery-selection-receipt/v1";
 export const DEV_DELIVERY_LEASE_RECEIPT_SCHEMA =
@@ -146,7 +154,7 @@ function exactRoots(values, label) {
   return [...new Set(values.map((value) => exactRoot(value, label)))].sort();
 }
 function normalizePolicy(policy = {}) {
-  return {
+  const normalized = {
     agingSeconds: positiveInteger(
       policy.agingSeconds,
       "policy agingSeconds",
@@ -160,22 +168,17 @@ function normalizePolicy(policy = {}) {
     ),
     emergencyPolicy: text(policy.emergencyPolicy || "reviewed-explicit-only"),
   };
+  if (Object.hasOwn(policy, "minimumWriterProtocolRoot")) {
+    const root = exactRoot(
+      policy.minimumWriterProtocolRoot,
+      "policy minimumWriterProtocolRoot",
+    );
+    if (root !== DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT)
+      throw new Error("unsupported dev delivery minimum writer protocol");
+    normalized.minimumWriterProtocolRoot = root;
+  }
+  return normalized;
 }
-
-function lacksLiveNativeProof(candidate, status, allowLegacyV3Readback) {
-  const { environmentRoot, nativeCommandContract } = candidate;
-  const native =
-    candidate.deliveryClass !== "non-native-fast" ||
-    environmentRoot ||
-    nativeCommandContract;
-  return (
-    native &&
-    (!environmentRoot ||
-      (!nativeCommandContract && allowLegacyV3Readback !== true)) &&
-    !TERMINAL_STATES.has(status)
-  );
-}
-
 function normalizeCandidate(input, expected) {
   const identity = createDevDeliveryCandidateIdentity(
     input,
@@ -274,7 +277,12 @@ function normalizeCandidate(input, expected) {
       "candidate shardEvidenceRoots",
     );
   }
-  if (lacksLiveNativeProof(candidate, status, expected.allowLegacyV3Readback))
+  if (
+    lacksLiveNativeProof(candidate, status, {
+      allowLegacyV3Readback: expected.allowLegacyV3Readback,
+      allowLegacyQueuedReadback: expected.allowLegacyQueuedNativeReadback,
+    })
+  )
     throw new Error("live native candidate requires exact native proof");
   if (Object.hasOwn(input, "releaseBlockerPriority"))
     candidate.releaseBlockerPriority = normalizeReleaseBlockerPriorityClaim(
@@ -308,7 +316,10 @@ export function createDevDeliveryQueue({
     protectedBase: protectedBase(protectedBaseInput),
     generation: 0,
     fencingCounter: 0,
-    policy: normalizePolicy(policy),
+    policy: {
+      ...normalizePolicy(policy),
+      minimumWriterProtocolRoot: DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+    },
     activeWarrant: null,
     candidates: [],
     updatedAt: timestamp(now, "now"),
@@ -344,16 +355,19 @@ export function normalizeDevDeliveryQueue(input, expected = {}) {
     "queue fencingCounter",
   );
   queue.policy = normalizePolicy(queue.policy);
+  const hasExecutionReceipt = !!queue.activeWarrant?.nativeExecutionReceiptRoot;
+  const hasQualificationReceipt =
+    !!queue.activeWarrant?.qualificationReceiptRoot;
   const allowLegacyV3Readback =
     expected.allowLegacyV3Readback === true &&
-    !(queue.candidates || []).some(
-      (candidate) => candidate?.nativeCommandContract,
-    ) &&
-    !queue.activeWarrant?.nativeCommandContract &&
-    !queue.activeWarrant?.nativeExecutionReceiptRoot &&
-    !queue.activeWarrant?.qualificationReceiptRoot;
+    hasExecutionReceipt === hasQualificationReceipt;
+  const candidateExpected = {
+    ...queue,
+    allowLegacyV3Readback,
+    allowLegacyQueuedNativeReadback: true,
+  };
   queue.candidates = (queue.candidates || []).map((candidate) =>
-    normalizeCandidate(candidate, { ...queue, allowLegacyV3Readback }),
+    normalizeCandidate(candidate, candidateExpected),
   );
   validateDevDeliveryCandidateChain(queue.candidates, TERMINAL_STATES);
   queue.updatedAt = timestamp(queue.updatedAt, "queue updatedAt");
@@ -380,6 +394,8 @@ export function transitionDevDeliveryQueue(queueInput, mutate, nowInput) {
   delete queue.stateRoot;
   const now = timestamp(nowInput, "now");
   const result = mutate(queue, before, now);
+  if (result.preserveState)
+    return { before, after: before, expectedOldStateRoot, result };
   queue.generation += 1;
   queue.updatedAt = now;
   const after = withQueueRoot(queue);
@@ -478,34 +494,14 @@ export function submitDevDeliveryCandidate(
             `candidate ${attemptedCandidate.candidateId} is terminal and cannot be resubmitted`,
           );
         }
-        const exactProofFields = [
-          "sourcePatchRoot",
-          "sourceProofRoot",
-          "planRoot",
-          "closureRoot",
-          "dependencyRoot",
-          "toolchainRoot",
-          "environmentRoot",
-          "sourceWorkflowRunId",
-        ];
-        const exactProofMatches =
-          exactProofFields.every(
-            (field) => existing[field] === attemptedCandidate[field],
-          ) &&
-          JSON.stringify(existing.affectedPaths || []) ===
-            JSON.stringify(attemptedCandidate.affectedPaths || []) &&
-          JSON.stringify(existing.shardEvidenceRoots || []) ===
-            JSON.stringify(attemptedCandidate.shardEvidenceRoots || []) &&
-          existing.nativeCommandContract?.commandRoot ===
-            attemptedCandidate.nativeCommandContract?.commandRoot &&
-          existing.releaseBlockerPriority?.claimRoot ===
-            attemptedCandidate.releaseBlockerPriority?.claimRoot;
-        if (
-          existing.sourceHead === attemptedCandidate.sourceHead &&
-          exactProofMatches
-        ) {
-          action = "duplicate-noop";
+        if (matchesExactDevDeliveryCandidate(existing, attemptedCandidate)) {
+          action =
+            before.activeWarrant?.candidateId === existing.candidateId
+              ? "active-warrant-noop"
+              : "duplicate-noop";
           selected = existing;
+          if (action === "active-warrant-noop")
+            return { candidate: selected, action, preserveState: true };
         } else {
           if (before.activeWarrant?.candidateId === existing.candidateId) {
             throw new Error(
@@ -515,7 +511,7 @@ export function submitDevDeliveryCandidate(
           const headChanged =
             existing.sourceHead !== attemptedCandidate.sourceHead;
           existing.sourceHead = attemptedCandidate.sourceHead;
-          for (const field of exactProofFields)
+          for (const field of EXACT_DEV_DELIVERY_PROOF_FIELDS)
             existing[field] = attemptedCandidate[field];
           if (attemptedCandidate.nativeCommandContract)
             existing.nativeCommandContract =
@@ -585,7 +581,11 @@ export function rankDevDeliveryCandidates(
   });
   const currentTime = timestamp(now, "now");
   return queue.candidates
-    .filter((candidate) => candidate.status === "queued")
+    .filter(
+      (candidate) =>
+        candidate.status === "queued" &&
+        !lacksExactNativeExecutionContract(candidate),
+    )
     .map((candidate) => ({
       candidate,
       priority: effectivePriority(candidate, queue.policy, currentTime),

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

@@ -29,6 +29,7 @@ import {
   DEV_DELIVERY_QUEUE_CONTRACT,
   DEV_DELIVERY_SELECTION_RECEIPT_SCHEMA,
   DEV_DELIVERY_SUBMISSION_RECEIPT_SCHEMA,
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
   DEV_DELIVERY_WARRANT_SCHEMA,
   TERMINAL_STATES,
   createDevDeliveryQueue,
@@ -38,6 +39,10 @@ import {
   submitDevDeliveryCandidate,
   transitionDevDeliveryQueue as transition,
 } from "./dev-delivery-warrant-state.js";
+import {
+  DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA,
+  fenceDevDeliveryWriterProtocol,
+} from "./dev-delivery-writer-protocol-transition.js";
 
 export { devDeliveryContentRoot } from "./dev-delivery-common.js";
 export {
@@ -85,8 +90,11 @@ export {
   DEV_DELIVERY_QUEUE_CONTRACT,
   DEV_DELIVERY_SELECTION_RECEIPT_SCHEMA,
   DEV_DELIVERY_SUBMISSION_RECEIPT_SCHEMA,
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+  DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA,
   DEV_DELIVERY_WARRANT_SCHEMA,
   createDevDeliveryQueue,
+  fenceDevDeliveryWriterProtocol,
   normalizeDevDeliveryQueue,
   rankDevDeliveryCandidates,
   submitDevDeliveryCandidate,

package/packages/core/dev-delivery-writer-protocol-transition.js

@@ -0,0 +1,72 @@
+import { devDeliveryContentRoot } from "./dev-delivery-common.js";
+import {
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+  TERMINAL_STATES,
+  transitionDevDeliveryQueue,
+} from "./dev-delivery-warrant-state.js";
+
+export const DEV_DELIVERY_WRITER_PROTOCOL = Object.freeze({
+  schema: "kungfu.buildchain.dev-delivery-writer-protocol/v1",
+  requiredCandidateCapabilities: [
+    "environment-root-v1",
+    "native-command-contract-v1",
+  ],
+});
+export const DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA =
+  "kungfu.buildchain.dev-delivery-writer-protocol-fence-receipt/v1";
+if (
+  devDeliveryContentRoot(DEV_DELIVERY_WRITER_PROTOCOL) !==
+  DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT
+) {
+  throw new Error("dev delivery writer protocol root drift");
+}
+
+export function fenceDevDeliveryWriterProtocol(
+  queueInput,
+  { now = new Date().toISOString() } = {},
+) {
+  const transaction = transitionDevDeliveryQueue(
+    queueInput,
+    (queue) => {
+      if (
+        queue.policy.minimumWriterProtocolRoot ===
+        DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT
+      ) {
+        return {
+          action: "minimum-writer-protocol-already-fenced",
+          preserveState: true,
+        };
+      }
+      if (
+        queue.activeWarrant ||
+        queue.candidates.some(
+          (candidate) => !TERMINAL_STATES.has(candidate.status),
+        )
+      ) {
+        throw new Error(
+          "minimum writer protocol can be fenced only while the queue is idle",
+        );
+      }
+      queue.policy.minimumWriterProtocolRoot =
+        DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT;
+      return { action: "minimum-writer-protocol-fenced" };
+    },
+    now,
+  );
+  const receipt = {
+    schema: DEV_DELIVERY_WRITER_PROTOCOL_FENCE_RECEIPT_SCHEMA,
+    action: transaction.result.action,
+    repository: transaction.after.repository,
+    protectedBase: transaction.after.protectedBase,
+    minimumWriterProtocolRoot: DEV_DELIVERY_MINIMUM_WRITER_PROTOCOL_ROOT,
+    expectedOldStateRoot: transaction.expectedOldStateRoot,
+    nextStateRoot: transaction.after.stateRoot,
+    nextAction:
+      "Use only a Buildchain runtime that preserves the rooted minimum writer protocol.",
+  };
+  return {
+    queue: transaction.after,
+    receipt,
+    receiptRoot: devDeliveryContentRoot(receipt),
+  };
+}

package/packages/core/v4-canonical-contracts.js

@@ -61,6 +61,16 @@ const ROOT_DOMAINS = new Set([
   "tail-reseal-artifact-files",
   "tail-reseal-receipt",
   "release-candidate-passport",
+  "release-invocation-publisher",
+  "release-invocation-runtime",
+  "release-invocation-candidate",
+  "release-invocation-target",
+  "release-invocation-authority",
+  "release-invocation-provider",
+  "release-invocation-parent",
+  "release-invocation",
+  "release-transaction",
+  "release-receipt",
 ]);
 const FAULT_CLASSES = new Set([
   "validation",

package/packages/core/v4-floating-consumer-policy.js

@@ -302,8 +302,11 @@ function classifyBuildchainUses(records, failures, { repository } = {}) {
       parsed.selector === ALPHA_RECOVERY_BOOTSTRAP.selector;
     const protectedBootstrap =
       repository === BUILDCHAIN_REPOSITORY && bootstrapShape;
+    const unauthorizedBootstrap =
+      repository !== BUILDCHAIN_REPOSITORY && bootstrapShape;
     const channel =
-      CHANNELS[parsed.selector] || (protectedBootstrap ? "alpha" : "");
+      !unauthorizedBootstrap &&
+      (CHANNELS[parsed.selector] || (protectedBootstrap ? "alpha" : ""));
     uses.push({
       ...record,
       ...parsed,

package/packages/core/v4-protected-publication-source.js

@@ -0,0 +1,93 @@
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/u;
+
+function exactSha(value, label) {
+  const normalized = String(value || "").toLowerCase();
+  if (!SHA_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be an exact Git SHA`);
+  }
+  return normalized;
+}
+
+function exactParents(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an ordered Git parent list`);
+  }
+  return value.map((entry, index) => exactSha(entry, `${label}[${index}]`));
+}
+
+export function bindV4ProtectedPublicationSource({
+  repository,
+  protectedCommit,
+  candidateCommit,
+  pullRequest,
+} = {}) {
+  if (!/^[^/\s]+\/[^/\s]+$/u.test(String(repository || ""))) {
+    throw new Error("protected publication source requires owner/repository");
+  }
+  const protectedSource = {
+    sha: exactSha(protectedCommit?.sha, "protected source SHA"),
+    tree: exactSha(protectedCommit?.tree, "protected source tree"),
+    parents: exactParents(protectedCommit?.parents, "protected source parents"),
+  };
+  const candidateSource = {
+    sha: exactSha(candidateCommit?.sha, "candidate source SHA"),
+    tree: exactSha(candidateCommit?.tree, "candidate source tree"),
+    parents: exactParents(candidateCommit?.parents, "candidate source parents"),
+  };
+  if (protectedSource.tree !== candidateSource.tree) {
+    throw new Error(
+      "protected publication source tree does not match the qualified candidate tree",
+    );
+  }
+
+  let mode = "exact-commit";
+  let pullRequestNumber = null;
+  if (protectedSource.sha !== candidateSource.sha) {
+    mode = "merge-equivalent";
+    const sameParents =
+      protectedSource.parents.length === candidateSource.parents.length &&
+      protectedSource.parents.every(
+        (parent, index) => parent === candidateSource.parents[index],
+      );
+    if (!sameParents) {
+      throw new Error(
+        "protected publication source is not parent-equivalent to the qualified merge candidate",
+      );
+    }
+    pullRequestNumber = Number(pullRequest?.number || 0);
+    const pullRequestHead = exactSha(
+      pullRequest?.headSha,
+      "publication pull request head SHA",
+    );
+    const pullRequestMerge = exactSha(
+      pullRequest?.mergeSha,
+      "publication pull request merge SHA",
+    );
+    if (
+      !Number.isSafeInteger(pullRequestNumber) ||
+      pullRequestNumber <= 0 ||
+      pullRequest?.merged !== true ||
+      pullRequestMerge !== protectedSource.sha ||
+      !candidateSource.parents.includes(pullRequestHead)
+    ) {
+      throw new Error(
+        "protected publication source does not match the merged pull request and qualified merge candidate",
+      );
+    }
+  }
+
+  const binding = {
+    schema: "kungfu.buildchain.v4-protected-publication-source/v1",
+    repository,
+    mode,
+    protectedSource,
+    candidateSource,
+    pullRequestNumber,
+  };
+  return {
+    ...binding,
+    bindingRoot: v4ContentRoot("candidate-identity", binding),
+  };
+}

package/packages/core/v4-publication-qualification.js

@@ -207,6 +207,7 @@ export function validateV4PublicationQualificationReceipt(
 export function assertV4DeclarativePromotionInputs(inputs) {
   const forbidden = Object.entries(inputs || {}).filter(
     ([name, value]) =>
+      name !== "dry-run" &&
       /(command|cmd|script|shell|run)$/iu.test(name) &&
       String(value || "").trim() !== "",
   );