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

package/packages/core/dev-delivery-execution-transfer.js

@@ -38,7 +38,10 @@ const FAILURE_FILES = [
 ];
 
 const V4_RUNTIME_SELECTOR =
-  /^(?:v4|v4-alpha|train\/v4\/v4\.0\/[a-z0-9][a-z0-9._-]*)$/u;
+  /^(?:[0-9a-f]{40}|v4|v4-alpha|train\/v4\/v4\.0\/[a-z0-9][a-z0-9._-]*)$/u;
+
+const V4_RUNTIME_SELECTOR_DESCRIPTION =
+  "runtime selector must be an exact immutable SHA, v4, v4-alpha, or train/v4/v4.0/<capability>";
 
 function requiredFiles(outcome) {
   if (outcome === "succeeded") return SUCCESS_FILES;
@@ -163,9 +166,7 @@ function runtimeBinding(input = {}) {
     selectionRoot: exactRoot(input.selectionRoot, "runtime selection root"),
   };
   if (!V4_RUNTIME_SELECTOR.test(runtime.selector)) {
-    throw new Error(
-      "runtime selector must be v4, v4-alpha, or train/v4/v4.0/<capability>",
-    );
+    throw new Error(V4_RUNTIME_SELECTOR_DESCRIPTION);
   }
   return runtime;
 }
@@ -207,9 +208,7 @@ function verifiedRuntimeSelection(directory, expected = {}) {
     throw new Error("runtime selection is not exact canonical content");
   }
   if (!V4_RUNTIME_SELECTOR.test(normalized.selector)) {
-    throw new Error(
-      "runtime selector must be v4, v4-alpha, or train/v4/v4.0/<capability>",
-    );
+    throw new Error(V4_RUNTIME_SELECTOR_DESCRIPTION);
   }
   const selectionRoot = sha256Bytes(
     Buffer.from(`${JSON.stringify(normalized, null, 2)}\n`),

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/release-tail-product-capabilities.js

@@ -0,0 +1,29 @@
+export const RELEASE_TAIL_PRODUCT_CAPABILITIES = Object.freeze([
+  Object.freeze({
+    id: "product.version-state.materialize",
+    executor: "provider-adapter",
+    adapter: "github-version-state",
+    effectKind: "product-version-state-materialization",
+    observationKind: "product-version-state-readback",
+    receiptKind: "product-version-state",
+    transactionState: "preparing",
+  }),
+  Object.freeze({
+    id: "product.package.publish",
+    executor: "provider-adapter",
+    adapter: "npm-trusted-publishing",
+    effectKind: "product-package-publication",
+    observationKind: "product-package-readback",
+    receiptKind: "product-package-publication",
+    transactionState: "publishing",
+  }),
+  Object.freeze({
+    id: "product.release-refs.converge",
+    executor: "provider-adapter",
+    adapter: "github-release-refs",
+    effectKind: "product-release-ref-convergence",
+    observationKind: "product-release-ref-readback",
+    receiptKind: "product-release-ref-convergence",
+    transactionState: "committing",
+  }),
+]);

package/packages/core/release-tail-provider-plane.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-
+import { RELEASE_TAIL_PRODUCT_CAPABILITIES } from "./release-tail-product-capabilities.js";
 export const RELEASE_TAIL_DECLARATION_CONTRACT =
   "kungfu-buildchain-release-tail-capabilities";
 export const RELEASE_TAIL_TRANSACTION_POLICY = "buildchain.release-tail/v1";
@@ -27,8 +27,8 @@ export const RELEASE_TAIL_STATES = Object.freeze([
   "repair-required",
   "terminal-failure",
 ]);
-
 export const RELEASE_TAIL_CAPABILITY_REGISTRY = Object.freeze([
+  ...RELEASE_TAIL_PRODUCT_CAPABILITIES,
   Object.freeze({
     id: "artifact.publish",
     executor: "provider-adapter",

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

@@ -56,11 +56,25 @@ const ROOT_DOMAINS = new Set([
   "stable-publication-fence",
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
+  "v4-product-required-artifacts",
+  "v4-product-publication-intent",
+  "v4-product-publication-operation",
+  "v4-product-publication-plan",
   "tail-reseal-plan",
   "tail-reseal-admission",
   "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,