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

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

@@ -0,0 +1,418 @@
+import {
+  devDeliveryClone as clone,
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryProtectedBase as protectedBase,
+  devDeliveryRepository as repository,
+  devDeliveryText as text,
+  devDeliveryTimestamp as timestamp,
+} 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";
+
+function exactRoots(values, label) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${label} must contain at least one content root`);
+  }
+  return [...new Set(values.map((value) => exactRoot(value, label)))].sort();
+}
+
+function normalizedPaths(values) {
+  if (!Array.isArray(values)) throw new Error("paths must be a JSON array");
+  return [
+    ...new Set(
+      values
+        .map(text)
+        .map((entry) => entry.replace(/^\.\//u, "").replace(/\/+$/u, ""))
+        .filter(Boolean),
+    ),
+  ].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;
+  delete identity.observationRoot;
+  return identity;
+}
+
+function proofObservation(body) {
+  return { qualifiedAt: body.qualifiedAt };
+}
+
+function rooted(body) {
+  return { ...body, decisionRoot: devDeliveryContentRoot(body) };
+}
+
+export function createNativeQualificationProof(input = {}) {
+  const body = {
+    schema: NATIVE_QUALIFICATION_PROOF_SCHEMA,
+    rootSemantics: NATIVE_QUALIFICATION_ROOT_SEMANTICS,
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    sourceIdentityRoot: exactRoot(
+      input.sourceIdentityRoot,
+      "sourceIdentityRoot",
+    ),
+    sourcePatchRoot: exactRoot(input.sourcePatchRoot, "sourcePatchRoot"),
+    planRoot: exactRoot(input.planRoot, "planRoot"),
+    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(
+      input.shardEvidenceRoots,
+      "shardEvidenceRoots",
+    ),
+    qualifiedAt: timestamp(input.qualifiedAt, "qualifiedAt"),
+  };
+  body.observationRoot = devDeliveryContentRoot(proofObservation(body));
+  return {
+    ...body,
+    proofRoot: devDeliveryContentRoot(proofIdentity(body)),
+  };
+}
+
+export function verifyNativeQualificationProof(proofInput, expected = {}) {
+  try {
+    const proof = clone(proofInput || {});
+    if (
+      ![
+        NATIVE_QUALIFICATION_PROOF_SCHEMA,
+        LEGACY_NATIVE_QUALIFICATION_PROOF_SCHEMA,
+      ].includes(proof.schema)
+    ) {
+      return { ok: false, reason: "unsupported-schema" };
+    }
+    const proofRoot = proof.proofRoot;
+    delete proof.proofRoot;
+    if (proof.rootSemantics !== NATIVE_QUALIFICATION_ROOT_SEMANTICS) {
+      return { ok: false, reason: "unsupported-root-semantics" };
+    }
+    if (devDeliveryContentRoot(proofIdentity(proof)) !== proofRoot) {
+      return { ok: false, reason: "proof-root-drift" };
+    }
+    if (
+      devDeliveryContentRoot(proofObservation(proof)) !== proof.observationRoot
+    ) {
+      return { ok: false, reason: "observation-root-drift" };
+    }
+    for (const [field, value] of Object.entries(expected)) {
+      if (value !== undefined && proof[field] !== value) {
+        return { ok: false, reason: `${field}-mismatch` };
+      }
+    }
+    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 };
+  }
+}
+
+function pathsOverlap(changedPath, affectedPath) {
+  if (affectedPath === "*" || affectedPath === "**") return true;
+  return (
+    changedPath === affectedPath ||
+    changedPath.startsWith(`${affectedPath}/`) ||
+    affectedPath.startsWith(`${changedPath}/`)
+  );
+}
+
+function nativeReuseBody(proof, current) {
+  const verification = verifyNativeQualificationProof(proof);
+  const currentBase = current.currentBase
+    ? exactSha(current.currentBase, "currentBase")
+    : null;
+  const changedPaths = normalizedPaths(current.changedPaths || []);
+  const base = {
+    schema: NATIVE_PROOF_REUSE_DECISION_SCHEMA,
+    proofRoot: verification.ok ? proof.proofRoot : null,
+    repository: verification.ok ? proof.repository : null,
+    protectedBase: verification.ok ? proof.protectedBase : null,
+    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",
+    reason: verification.reason,
+    requiredValidation: "full-native",
+  };
+  if (!verification.ok) return base;
+
+  const semanticFields = [
+    "sourceIdentityRoot",
+    "sourcePatchRoot",
+    "planRoot",
+    "closureRoot",
+    "dependencyRoot",
+    "toolchainRoot",
+    "environmentRoot",
+  ];
+  for (const field of semanticFields) {
+    if (!current[field] || current[field] !== proof[field]) {
+      return {
+        ...base,
+        reason: `${field}-changed-or-unknown`,
+      };
+    }
+  }
+  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,
+      reusable: true,
+      action: "accept-fresh-native-proof",
+      reason: "exact-qualified-base",
+      requiredValidation: "exact-merge-group",
+    };
+  }
+  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 attributedPaths = [
+    ...changedPaths,
+    ...base.renames.flatMap((rename) => [rename.from, rename.to]),
+  ];
+  const overlap = [...new Set(attributedPaths)].filter((changedPath) =>
+    proof.affectedPaths.some((affectedPath) =>
+      pathsOverlap(changedPath, affectedPath),
+    ),
+  );
+  if (overlap.length > 0) {
+    return {
+      ...base,
+      action: "rerun-affected-native-shards",
+      reason: "base-delta-overlaps-affected-closure",
+      requiredValidation: "incremental-or-full-native",
+      overlappingPaths: overlap,
+    };
+  }
+  return {
+    ...base,
+    reusable: true,
+    action: "reuse-native-proof",
+    reason: "semantic-source-stable-and-base-delta-disjoint",
+    requiredValidation: "exact-merge-group",
+  };
+}
+
+export function createNativeProofReuseDecision({ proof, current = {} } = {}) {
+  return rooted(nativeReuseBody(proof, current));
+}
+
+export function verifyNativeProofReuseDecision(
+  decisionInput,
+  { proof, current = {} } = {},
+) {
+  try {
+    const decision = clone(decisionInput || {});
+    if (decision.schema !== NATIVE_PROOF_REUSE_DECISION_SCHEMA) {
+      return { ok: false, reason: "unsupported-schema" };
+    }
+    const decisionRoot = decision.decisionRoot;
+    delete decision.decisionRoot;
+    if (devDeliveryContentRoot(decision) !== decisionRoot) {
+      return { ok: false, reason: "decision-root-drift" };
+    }
+    const recomputed = nativeReuseBody(proof, current);
+    if (JSON.stringify(decision) !== JSON.stringify(recomputed)) {
+      return { ok: false, reason: "decision-input-drift" };
+    }
+    return {
+      ok: decision.reusable === true,
+      reason: decision.reason,
+      decisionRoot,
+      action: decision.action,
+    };
+  } catch (error) {
+    return { ok: false, reason: "invalid-decision", error: error.message };
+  }
+}
+
+export function createDevDeliveryWarrantQualifier({
+  transition,
+  assertWarrantMutation,
+} = {}) {
+  return function qualifyDevDeliveryWarrant(
+    queueInput,
+    warrant,
+    {
+      nativeProof,
+      reuseDecision,
+      current = {},
+      now = new Date().toISOString(),
+    } = {},
+  ) {
+    const currentTime = timestamp(now, "now");
+    const transaction = transition(
+      queueInput,
+      (queue, before) => {
+        assertWarrantMutation(before, warrant, currentTime);
+        if (before.activeWarrant.phase !== "provisional") {
+          throw new Error(
+            "only a provisional Delivery Warrant can be qualified",
+          );
+        }
+        const active = before.activeWarrant;
+        const proofVerification = verifyNativeQualificationProof(nativeProof, {
+          repository: before.repository,
+          protectedBase: before.protectedBase,
+          sourceIdentityRoot: active.sourceIdentityRoot,
+          sourcePatchRoot: active.sourcePatchRoot,
+          planRoot: active.planRoot,
+          closureRoot: active.closureRoot,
+          dependencyRoot: active.dependencyRoot,
+          toolchainRoot: active.toolchainRoot,
+          environmentRoot: active.environmentRoot,
+        });
+        if (!proofVerification.ok) {
+          throw new Error(`native proof rejected: ${proofVerification.reason}`);
+        }
+        const reuseVerification = verifyNativeProofReuseDecision(
+          reuseDecision,
+          {
+            proof: nativeProof,
+            current: {
+              ...current,
+              sourceIdentityRoot: active.sourceIdentityRoot,
+              sourcePatchRoot: active.sourcePatchRoot,
+              planRoot: active.planRoot,
+              closureRoot: active.closureRoot,
+              dependencyRoot: active.dependencyRoot,
+              toolchainRoot: active.toolchainRoot,
+              environmentRoot: active.environmentRoot,
+            },
+          },
+        );
+        if (!reuseVerification.ok) {
+          throw new Error(
+            `native proof is not reusable: ${reuseVerification.reason}`,
+          );
+        }
+        queue.activeWarrant.phase = "qualified";
+        queue.activeWarrant.nativeProofRoot = proofVerification.proofRoot;
+        queue.activeWarrant.nativeProofReuseRoot =
+          reuseVerification.decisionRoot;
+        queue.activeWarrant.qualifiedAt = currentTime;
+        queue.activeWarrant.nextAction =
+          "Enter the GitHub merge queue at the exact fenced PR head; merge_group remains final authority.";
+        const candidate = queue.candidates.find(
+          (entry) => entry.candidateId === queue.activeWarrant.candidateId,
+        );
+        candidate.status = "qualified";
+        candidate.updatedAt = currentTime;
+        return { candidate, warrant: queue.activeWarrant };
+      },
+      currentTime,
+    );
+    const receipt = {
+      schema: DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA,
+      action: "qualified-warrant",
+      candidateId: transaction.result.candidate.candidateId,
+      fencingToken: transaction.result.warrant.fencingToken,
+      leaseGeneration: transaction.result.warrant.generation,
+      phase: transaction.result.warrant.phase,
+      nativeProofRoot: transaction.result.warrant.nativeProofRoot,
+      nativeProofReuseRoot: transaction.result.warrant.nativeProofReuseRoot,
+      qualifiedAt: transaction.result.warrant.qualifiedAt,
+      expectedOldStateRoot: transaction.expectedOldStateRoot,
+      nextStateRoot: transaction.after.stateRoot,
+      nextAction: transaction.result.warrant.nextAction,
+    };
+    return {
+      queue: transaction.after,
+      warrant: transaction.result.warrant,
+      receipt,
+      receiptRoot: devDeliveryContentRoot(receipt),
+    };
+  };
+}

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);
@@ -33,23 +60,39 @@ 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 candidate = samePullRequest.find((entry) => entry.sourceHead === identity.sourceHead) || null;
+    const matchingHead = samePullRequest.filter((entry) => entry.sourceHead === identity.sourceHead);
+    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) {
@@ -59,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 },
+    );
   };
 }