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

package/packages/core/channel-promotion-baseline.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+
+const SHA = /^[0-9a-f]{40}$/;
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function exactSha(value, name) {
+  const normalized = text(value).toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${name} must be an exact 40-character SHA`);
+  return normalized;
+}
+
+export function normalizeManagedPromotionBaseline(input) {
+  const pullRequestNumber = Number(input?.pullRequestNumber);
+  if (!Number.isSafeInteger(pullRequestNumber) || pullRequestNumber <= 0) {
+    throw new Error(
+      "targetBaseline.pullRequestNumber must be a positive integer",
+    );
+  }
+  const pullRequestUrl = text(input?.pullRequestUrl);
+  if (!pullRequestUrl)
+    throw new Error("targetBaseline.pullRequestUrl is required");
+  return {
+    mode: text(input?.mode) || "managed-candidate-merge-source",
+    targetSha: exactSha(input?.targetSha, "targetBaseline.targetSha"),
+    sourceSha: exactSha(input?.sourceSha, "targetBaseline.sourceSha"),
+    pullRequestNumber,
+    pullRequestUrl,
+  };
+}
+
+export function normalizeChannelCandidateSelection(input) {
+  if (!input) return undefined;
+  const mode = text(input.mode);
+  if (!mode) throw new Error("selection.mode is required");
+  const skippedNewerCommitCount = Number(input.skippedNewerCommitCount || 0);
+  if (
+    !Number.isSafeInteger(skippedNewerCommitCount) ||
+    skippedNewerCommitCount < 0
+  ) {
+    throw new Error(
+      "selection.skippedNewerCommitCount must be a non-negative integer",
+    );
+  }
+  return {
+    mode,
+    observedSourceHeadSha: exactSha(
+      input.observedSourceHeadSha,
+      "selection.observedSourceHeadSha",
+    ),
+    skippedNewerCommitCount,
+    ...(input.targetBaseline
+      ? {
+          targetBaseline: normalizeManagedPromotionBaseline(
+            input.targetBaseline,
+          ),
+        }
+      : {}),
+  };
+}
+
+export async function resolveChannelComparisonBaseline({
+  client,
+  targetSha,
+  targetBranch,
+  sourceSha,
+  directComparison,
+}) {
+  if (
+    directComparison.status !== "diverged" ||
+    !client.resolveManagedPromotionBaseline
+  ) {
+    return { comparison: directComparison, targetBaseline: undefined };
+  }
+  const promoted = await client.resolveManagedPromotionBaseline(
+    targetSha,
+    targetBranch,
+  );
+  if (!promoted)
+    return { comparison: directComparison, targetBaseline: undefined };
+  const comparison = await client.compare(promoted.sourceSha, sourceSha);
+  if (!["ahead", "identical"].includes(comparison.status)) {
+    return { comparison: directComparison, targetBaseline: undefined };
+  }
+  return {
+    comparison,
+    targetBaseline: normalizeManagedPromotionBaseline(promoted),
+  };
+}
+
+export async function resolvePatrolSourceInputs({
+  client,
+  options,
+  requiredWorkflowPaths,
+  selectQualifiedSource,
+}) {
+  const [observedSourceHeadSha, targetSha] = await Promise.all([
+    client.resolveBranch(options.sourceBranch),
+    client.resolveBranch(options.targetBranch),
+  ]);
+  const directComparison = await client.compare(
+    targetSha,
+    observedSourceHeadSha,
+  );
+  const { comparison: headComparison, targetBaseline } =
+    await resolveChannelComparisonBaseline({
+      client,
+      targetSha,
+      targetBranch: options.targetBranch,
+      sourceSha: observedSourceHeadSha,
+      directComparison,
+    });
+  let sourceSha = observedSourceHeadSha;
+  let comparison = headComparison;
+  let workflowEvidence = [];
+  let skippedNewerCommitCount = 0;
+  let qualificationError;
+  if (
+    headComparison.status === "ahead" &&
+    Number(headComparison.ahead_by) > 0
+  ) {
+    const boundarySha = targetBaseline?.sourceSha || targetSha;
+    const [sourceHistory, ...workflowRunSets] = await Promise.all([
+      client.listBranchHistory(options.sourceBranch, boundarySha),
+      ...requiredWorkflowPaths.map((workflow) =>
+        client.listCompletedWorkflowRuns(workflow, options.sourceBranch),
+      ),
+    ]);
+    try {
+      const selected = selectQualifiedSource({
+        sourceHistory,
+        workflowRunsByPath: new Map(
+          requiredWorkflowPaths.map((workflow, index) => [
+            workflow,
+            workflowRunSets[index],
+          ]),
+        ),
+        requiredWorkflowPaths,
+        now: options.now,
+        maxAgeSeconds: options.maxAgeSeconds,
+      });
+      ({ sourceSha, skippedNewerCommitCount, workflowEvidence } = selected);
+      if (sourceSha !== observedSourceHeadSha)
+        comparison = await client.compare(boundarySha, sourceSha);
+    } catch (error) {
+      qualificationError = error;
+    }
+  }
+  return {
+    observedSourceHeadSha,
+    targetSha,
+    headComparison,
+    targetBaseline,
+    sourceSha,
+    comparison,
+    workflowEvidence,
+    skippedNewerCommitCount,
+    qualificationError,
+  };
+}
+
+export async function resolveManagedPromotionBaseline({
+  api,
+  targetSha,
+  targetBranch,
+  parseCandidate,
+}) {
+  const commit = await api(`/git/commits/${targetSha}`);
+  const parents = Array.isArray(commit.parents) ? commit.parents : [];
+  if (text(commit.sha) !== targetSha || parents.length !== 2) return null;
+  const sourceSha = text(parents[1]?.sha);
+  if (!SHA.test(sourceSha)) return null;
+  const associated = await api(`/commits/${targetSha}/pulls`);
+  const managed = associated
+    .filter(
+      (pullRequest) =>
+        text(pullRequest.merged_at) &&
+        text(pullRequest.merge_commit_sha) === targetSha &&
+        text(pullRequest.base?.ref) === targetBranch &&
+        text(pullRequest.head?.sha) === sourceSha,
+    )
+    .map((pullRequest) => ({
+      pullRequest,
+      candidate: parseCandidate(pullRequest, targetBranch),
+    }))
+    .filter(({ candidate }) => candidate?.sourceSha === sourceSha);
+  if (managed.length > 1)
+    throw new Error(`multiple managed promotion PRs bind target ${targetSha}`);
+  if (managed.length === 0) return null;
+  return normalizeManagedPromotionBaseline({
+    targetSha,
+    sourceSha,
+    pullRequestNumber: managed[0].pullRequest.number,
+    pullRequestUrl: managed[0].pullRequest.html_url,
+  });
+}

package/packages/core/dev-delivery-candidate-identity.js

@@ -0,0 +1,94 @@
+import {
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryPositiveInteger as positiveInteger,
+  devDeliveryText as text,
+} from "./dev-delivery-common.js";
+
+export const CHAINED_ATTEMPT_IDENTITY = "chained-attempt-v2";
+
+export function createDevDeliveryCandidateIdentity(
+  input,
+  expected,
+  deliveryClass,
+) {
+  const identity = {
+    repository: expected.repository,
+    protectedBase: expected.protectedBase,
+    pullRequestNumber: positiveInteger(
+      input.pullRequestNumber,
+      "pullRequestNumber",
+    ),
+    assignmentRoot: exactRoot(input.assignmentRoot, "assignmentRoot"),
+    initiativeRoot: exactRoot(input.initiativeRoot, "initiativeRoot"),
+    sourceIdentityRoot: exactRoot(
+      input.sourceIdentityRoot,
+      "sourceIdentityRoot",
+    ),
+    deliveryClass: deliveryClass(input.deliveryClass),
+  };
+  if (input.identitySemantics) {
+    if (text(input.identitySemantics) !== CHAINED_ATTEMPT_IDENTITY) {
+      throw new Error(
+        `unsupported candidate identity semantics ${input.identitySemantics}`,
+      );
+    }
+    identity.identitySemantics = CHAINED_ATTEMPT_IDENTITY;
+    identity.predecessorCandidateId = exactRoot(
+      input.predecessorCandidateId,
+      "predecessorCandidateId",
+    );
+  }
+  return { ...identity, candidateId: devDeliveryContentRoot(identity) };
+}
+
+export function validateDevDeliveryCandidateChain(candidates, terminalStates) {
+  const precedingCandidates = new Map();
+  for (const candidate of candidates) {
+    if (candidate.identitySemantics === CHAINED_ATTEMPT_IDENTITY) {
+      const predecessor = precedingCandidates.get(
+        candidate.predecessorCandidateId,
+      );
+      if (!predecessor)
+        throw new Error(
+          "chained candidate predecessor must appear earlier in the queue",
+        );
+      if (predecessor.pullRequestNumber !== candidate.pullRequestNumber) {
+        throw new Error(
+          "chained candidate predecessor must belong to the same pull request",
+        );
+      }
+      if (!terminalStates.has(predecessor.status)) {
+        throw new Error("chained candidate predecessor must be terminal");
+      }
+    }
+    precedingCandidates.set(candidate.candidateId, candidate);
+  }
+}
+
+export function chainedDevDeliveryAttemptInput({
+  queue,
+  candidate,
+  input,
+  currentTime,
+  terminalStates,
+}) {
+  const predecessor = [...queue.candidates]
+    .reverse()
+    .find(
+      (entry) =>
+        entry.pullRequestNumber === candidate.pullRequestNumber &&
+        terminalStates.has(entry.status),
+    );
+  if (!predecessor) return null;
+  return {
+    ...input,
+    identitySemantics: CHAINED_ATTEMPT_IDENTITY,
+    predecessorCandidateId: predecessor.candidateId,
+    enqueuedAt: input.enqueuedAt || currentTime,
+    updatedAt: currentTime,
+    attempts: input.attempts || 1,
+    recoveries: input.recoveries || 0,
+    status: "queued",
+  };
+}

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

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export function devDeliveryText(value = "") {
+  return String(value ?? "").trim();
+}
+
+export function devDeliveryClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+export function devDeliveryContentRoot(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(`${JSON.stringify(stableValue(value))}\n`)
+    .digest("hex")}`;
+}
+
+export function devDeliveryExactRoot(value, label) {
+  const normalized = devDeliveryText(value).toLowerCase();
+  if (!ROOT_PATTERN.test(normalized)) throw new Error(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+export function devDeliveryExactSha(value, label) {
+  const normalized = devDeliveryText(value).toLowerCase();
+  if (!SHA_PATTERN.test(normalized)) throw new Error(`${label} must be a 40-character Git SHA`);
+  return normalized;
+}
+
+export function devDeliveryPositiveInteger(value, label, fallback) {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`${label} must be a positive integer`);
+  return parsed;
+}
+
+export function devDeliveryTimestamp(value, label) {
+  const normalized = devDeliveryText(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) throw new Error(`${label} must be an ISO-8601 timestamp`);
+  return new Date(milliseconds).toISOString();
+}
+
+export function devDeliveryRepository(value) {
+  const normalized = devDeliveryText(value);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) {
+    throw new Error(`repository must be owner/repo, got ${normalized || "<empty>"}`);
+  }
+  return normalized;
+}
+
+export function devDeliveryProtectedBase(value) {
+  const normalized = devDeliveryText(value).replace(/^refs\/heads\//, "");
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(normalized)) {
+    throw new Error(`protectedBase must be dev/vN/vN.M, got ${normalized || "<empty>"}`);
+  }
+  return normalized;
+}

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

@@ -0,0 +1,252 @@
+import { devDeliveryClone as clone, devDeliveryContentRoot, devDeliveryExactRoot as exactRoot, devDeliveryExactSha as exactSha, devDeliveryPositiveInteger as positiveInteger, devDeliveryProtectedBase as protectedBase, devDeliveryRepository as repository, devDeliveryText as text, devDeliveryTimestamp as timestamp } from "./dev-delivery-common.js";
+
+export const SOURCE_QUALIFICATION_PROOF_SCHEMA = "kungfu.buildchain.source-qualification-proof/v1";
+export const PROJECT_CUT_REPLAY_PROOF_SCHEMA = "kungfu.buildchain.project-cut-replay-proof/v1";
+export const INTEGRATION_DELIVERY_PROOF_SCHEMA = "kungfu.buildchain.integration-delivery-proof/v1";
+
+const SOURCE_QUALIFICATION_ROOT_SEMANTICS = "qualification-identity-v1";
+
+const DEV_DELIVERY_WARRANT_SCHEMA = "kungfu.buildchain.dev-delivery-warrant/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 rootedProof(body) {
+  return { ...body, proofRoot: devDeliveryContentRoot(body) };
+}
+
+function sourceQualificationIdentity(body) {
+  const identity = clone(body);
+  delete identity.qualifiedAt;
+  delete identity.observationRoot;
+  return identity;
+}
+
+function sourceQualificationObservation(body) {
+  return { qualifiedAt: body.qualifiedAt };
+}
+
+export function createSourceQualificationProof(input = {}) {
+  const body = {
+    schema: SOURCE_QUALIFICATION_PROOF_SCHEMA,
+    rootSemantics: SOURCE_QUALIFICATION_ROOT_SEMANTICS,
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    sourceIdentityRoot: exactRoot(input.sourceIdentityRoot, "sourceIdentityRoot"),
+    sourceHead: exactSha(input.sourceHead, "sourceHead"),
+    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"),
+    affectedPaths: [...new Set((input.affectedPaths || []).map(text).filter(Boolean))].sort(),
+    shardEvidenceRoots: exactRoots(input.shardEvidenceRoots, "shardEvidenceRoots"),
+    qualifiedAt: timestamp(input.qualifiedAt, "qualifiedAt"),
+  };
+  body.observationRoot = devDeliveryContentRoot(sourceQualificationObservation(body));
+  return { ...body, proofRoot: devDeliveryContentRoot(sourceQualificationIdentity(body)) };
+}
+
+export function verifySourceQualificationProof(proofInput, expected = {}) {
+  try {
+    const proof = clone(proofInput || {});
+    if (proof.schema !== SOURCE_QUALIFICATION_PROOF_SCHEMA) return { ok: false, reason: "unsupported-schema" };
+    const proofRoot = proof.proofRoot;
+    delete proof.proofRoot;
+    if (proof.rootSemantics === undefined) {
+      if (devDeliveryContentRoot(proof) !== proofRoot) return { ok: false, reason: "proof-root-drift" };
+    } else {
+      if (proof.rootSemantics !== SOURCE_QUALIFICATION_ROOT_SEMANTICS) return { ok: false, reason: "unsupported-root-semantics" };
+      if (devDeliveryContentRoot(sourceQualificationIdentity(proof)) !== proofRoot) return { ok: false, reason: "proof-root-drift" };
+      if (devDeliveryContentRoot(sourceQualificationObservation(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` };
+    }
+    createSourceQualificationProof(proof);
+    return { ok: true, reason: "exact-source-proof", proofRoot };
+  } catch (error) {
+    return { ok: false, reason: "invalid-proof", error: error.message };
+  }
+}
+
+export function classifyDevDeliveryDelta({ proof, current = {} } = {}) {
+  const verification = verifySourceQualificationProof(proof);
+  if (!verification.ok)
+    return {
+      action: "rerun-full-source-qualification",
+      reason: verification.reason,
+      reusable: false,
+    };
+  const exactPredicates = ["sourceIdentityRoot", "sourcePatchRoot", "planRoot", "closureRoot", "dependencyRoot", "toolchainRoot"];
+  for (const field of exactPredicates) {
+    if (!current[field] || current[field] !== proof[field]) {
+      return {
+        action: "rerun-full-source-qualification",
+        reason: `${field}-changed-or-unknown`,
+        reusable: false,
+      };
+    }
+  }
+  if (current.graphKnown !== true || !Array.isArray(current.changedPaths)) {
+    return {
+      action: "rerun-full-source-qualification",
+      reason: "dependency-attribution-unknown",
+      reusable: false,
+    };
+  }
+  const affected = new Set(proof.affectedPaths || []);
+  const overlap = [...new Set(current.changedPaths.map(text).filter((entry) => affected.has(entry)))].sort();
+  if (overlap.length > 0) {
+    return {
+      action: "rerun-affected-source-shards",
+      reason: "dev-delta-overlaps-affected-closure",
+      reusable: false,
+      overlappingPaths: overlap,
+      requiredFinalGate: "exact-integration-delivery-proof",
+    };
+  }
+  return {
+    action: "reuse-source-qualification",
+    reason: "unrelated-dev-delta",
+    reusable: true,
+    proofRoot: proof.proofRoot,
+    requiredReplay: "cheap-project-cut-replay",
+    requiredFinalGate: "exact-integration-delivery-proof",
+  };
+}
+
+export function createProjectCutReplayPlan(input = {}) {
+  const sourceHead = exactSha(input.sourceHead, "sourceHead");
+  const previousBase = exactSha(input.previousBase, "previousBase");
+  const currentBase = exactSha(input.currentBase, "currentBase");
+  return rootedProof({
+    schema: "kungfu.buildchain.project-cut-replay-plan/v1",
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    pullRequestNumber: positiveInteger(input.pullRequestNumber, "pullRequestNumber"),
+    sourceHead,
+    previousBase,
+    currentBase,
+    sourcePatchRoot: exactRoot(input.sourcePatchRoot, "sourcePatchRoot"),
+    replayTree: exactSha(input.replayTree, "replayTree"),
+    sourceHeadMutationRequired: false,
+    action: previousBase === currentBase ? "verify-existing-replay" : "replay-on-latest-base",
+    finalAuthority: "github-merge-group",
+  });
+}
+
+export function createProjectCutReplayProof(input = {}) {
+  const qualification = input.qualificationReceipt || input.qualification || {};
+  if (qualification.schema !== "project.cut.merge-queue-admission/v1") throw new Error("Project Cut qualification schema is invalid");
+  if (qualification.ok !== true || qualification.decision !== "qualified") throw new Error("Project Cut qualification is not qualified");
+  if (!Array.isArray(qualification.reasonCodes) || qualification.reasonCodes.length !== 0) throw new Error("Project Cut qualification retains failure reasons");
+  if (typeof qualification.compositionChanged !== "boolean") throw new Error("Project Cut qualification compositionChanged is invalid");
+  if (!qualification.compositionChanged && qualification.compositionRoot != null) throw new Error("unchanged Project Cut qualification must not claim a compositionRoot");
+  const sourceHead = exactSha(input.sourceHead, "sourceHead");
+  const currentBase = exactSha(input.currentBase, "currentBase");
+  const replayTree = exactSha(input.replayTree, "replayTree");
+  if (exactSha(qualification.baseCommitOid, "qualification.baseCommitOid") !== currentBase) throw new Error("Project Cut qualification base does not match currentBase");
+  if (exactSha(qualification.headCommitOid, "qualification.headCommitOid") !== sourceHead) throw new Error("Project Cut qualification head does not match sourceHead");
+  if (exactSha(qualification.candidateTreeOid, "qualification.candidateTreeOid") !== replayTree) throw new Error("Project Cut qualification tree does not match replayTree");
+  const normalizedQualification = {
+    schema: qualification.schema,
+    ok: true,
+    decision: "qualified",
+    baseCommitOid: currentBase,
+    headCommitOid: sourceHead,
+    candidateCommitOid: exactSha(qualification.candidateCommitOid, "qualification.candidateCommitOid"),
+    candidateTreeOid: replayTree,
+    replayedCommitCount: positiveInteger(qualification.replayedCommitCount, "qualification.replayedCommitCount"),
+    compositionChanged: Boolean(qualification.compositionChanged),
+    compositionRoot: qualification.compositionChanged
+      ? exactRoot(qualification.compositionRoot, "qualification.compositionRoot")
+      : null,
+    reasonCodes: [],
+  };
+  return rootedProof({
+    schema: PROJECT_CUT_REPLAY_PROOF_SCHEMA,
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    pullRequestNumber: positiveInteger(input.pullRequestNumber, "pullRequestNumber"),
+    sourceHead,
+    sourcePatchRoot: exactRoot(input.sourcePatchRoot, "sourcePatchRoot"),
+    currentBase,
+    replayTree,
+    qualification: normalizedQualification,
+    qualificationRoot: devDeliveryContentRoot(normalizedQualification),
+    requiredContextRoots: exactRoots(input.requiredContextRoots, "requiredContextRoots"),
+    verifiedAt: timestamp(input.verifiedAt, "verifiedAt"),
+    sourceHeadMutationRequired: false,
+    finalAuthority: "exact-project-cut-replay",
+  });
+}
+
+export function verifyProjectCutReplayProof(proofInput, expected = {}) {
+  try {
+    const proof = clone(proofInput || {});
+    if (proof.schema !== PROJECT_CUT_REPLAY_PROOF_SCHEMA) return { ok: false, reason: "unsupported-schema" };
+    const proofRoot = proof.proofRoot;
+    delete proof.proofRoot;
+    if (devDeliveryContentRoot(proof) !== proofRoot) return { ok: false, reason: "proof-root-drift" };
+    if (devDeliveryContentRoot(proof.qualification) !== proof.qualificationRoot) return { ok: false, reason: "qualification-root-drift" };
+    if (proof.finalAuthority !== "exact-project-cut-replay") return { ok: false, reason: "non-exact-final-authority" };
+    if (proof.sourceHeadMutationRequired !== false) return { ok: false, reason: "source-head-mutation-required" };
+    for (const [field, value] of Object.entries(expected)) {
+      if (value !== undefined && proof[field] !== value) return { ok: false, reason: `${field}-mismatch` };
+    }
+    createProjectCutReplayProof(proof);
+    return { ok: true, reason: "exact-project-cut-replay", proofRoot };
+  } catch (error) {
+    return { ok: false, reason: "invalid-proof", error: error.message };
+  }
+}
+
+export function createIntegrationDeliveryProof(input = {}) {
+  const warrant = input.warrant || {};
+  if (warrant.schema !== DEV_DELIVERY_WARRANT_SCHEMA) throw new Error("integration proof requires a Delivery Warrant");
+  return rootedProof({
+    schema: INTEGRATION_DELIVERY_PROOF_SCHEMA,
+    repository: repository(input.repository),
+    protectedBase: protectedBase(input.protectedBase),
+    sourceProofRoot: exactRoot(input.sourceProofRoot, "sourceProofRoot"),
+    currentBase: exactSha(input.currentBase, "currentBase"),
+    replayTree: exactSha(input.replayTree, "replayTree"),
+    mergeGroupHead: exactSha(input.mergeGroupHead, "mergeGroupHead"),
+    mergeGroupTree: exactSha(input.mergeGroupTree, "mergeGroupTree"),
+    warrantCandidateId: exactRoot(warrant.candidateId, "Warrant candidateId"),
+    warrantFencingToken: exactRoot(warrant.fencingToken, "Warrant fencingToken"),
+    warrantGeneration: positiveInteger(warrant.generation, "Warrant generation"),
+    requiredContextRoots: exactRoots(input.requiredContextRoots, "requiredContextRoots"),
+    verifiedAt: timestamp(input.verifiedAt, "verifiedAt"),
+    finalAuthority: "exact-github-merge-group",
+  });
+}
+
+export function verifyIntegrationDeliveryProof(proofInput, expected = {}) {
+  try {
+    const proof = clone(proofInput || {});
+    if (proof.schema !== INTEGRATION_DELIVERY_PROOF_SCHEMA) return { ok: false, reason: "unsupported-schema" };
+    const proofRoot = proof.proofRoot;
+    delete proof.proofRoot;
+    if (devDeliveryContentRoot(proof) !== proofRoot) return { ok: false, reason: "proof-root-drift" };
+    if (proof.finalAuthority !== "exact-github-merge-group") return { ok: false, reason: "non-exact-final-authority" };
+    for (const [field, value] of Object.entries(expected)) {
+      if (value !== undefined && proof[field] !== value) return { ok: false, reason: `${field}-mismatch` };
+    }
+    createIntegrationDeliveryProof({
+      ...proof,
+      warrant: {
+        schema: DEV_DELIVERY_WARRANT_SCHEMA,
+        candidateId: proof.warrantCandidateId,
+        fencingToken: proof.warrantFencingToken,
+        generation: proof.warrantGeneration,
+      },
+    });
+    return { ok: true, reason: "exact-integration-proof", proofRoot };
+  } catch (error) {
+    return { ok: false, reason: "invalid-proof", error: error.message };
+  }
+}