@kungfu-tech/buildchain 4.0.1 → 4.0.2-alpha.2

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

@@ -0,0 +1,246 @@
+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";
+import {
+  TERMINAL_STATES,
+  normalizeDevDeliveryQueue,
+} from "./dev-delivery-warrant-state.js";
+
+export const LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-request/v1";
+export const LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA =
+  "kungfu.buildchain.legacy-hosted-terminal-evidence/v1";
+export const LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-receipt/v1";
+
+function legacyLiveNativeCandidate(candidate) {
+  return (
+    !TERMINAL_STATES.has(candidate.status) &&
+    candidate.deliveryClass !== "non-native-fast" &&
+    (!candidate.environmentRoot || !candidate.nativeCommandContract)
+  );
+}
+
+function normalizeProviderJob(input, runAttempt) {
+  const job = {
+    id: positiveInteger(input?.id, "provider job id"),
+    name: text(input?.name),
+    runAttempt: positiveInteger(input?.runAttempt, "provider job runAttempt"),
+    status: text(input?.status).toLowerCase(),
+    conclusion: text(input?.conclusion).toLowerCase(),
+    completedAt: timestamp(input?.completedAt, "provider job completedAt"),
+  };
+  if (job.runAttempt !== runAttempt) {
+    throw new Error("legacy provider job run attempt mismatch");
+  }
+  if (job.status !== "completed" || !job.conclusion) {
+    throw new Error(
+      "legacy recovery requires every provider job to be terminal",
+    );
+  }
+  return job;
+}
+
+function normalizeEvidence(input) {
+  const runAttempt = positiveInteger(input?.runAttempt, "runAttempt");
+  if (!Array.isArray(input?.jobs) || input.jobs.length === 0) {
+    throw new Error("legacy terminal evidence requires provider jobs");
+  }
+  const jobs = input.jobs
+    .map((job) => normalizeProviderJob(job, runAttempt))
+    .sort((left, right) => left.id - right.id);
+  if (new Set(jobs.map((job) => job.id)).size !== jobs.length) {
+    throw new Error(
+      "legacy terminal evidence contains duplicate provider jobs",
+    );
+  }
+  if (!jobs.some((job) => job.conclusion === "failure")) {
+    throw new Error(
+      "legacy failed run evidence requires a failed provider job",
+    );
+  }
+  const runUpdatedAt = timestamp(input?.runUpdatedAt, "runUpdatedAt");
+  if (
+    jobs.some((job) => Date.parse(job.completedAt) > Date.parse(runUpdatedAt))
+  ) {
+    throw new Error("legacy provider job completion follows the run readback");
+  }
+  const body = {
+    schema: text(input?.schema),
+    candidateId: exactRoot(input?.candidateId, "candidateId"),
+    pullRequestNumber: positiveInteger(
+      input?.pullRequestNumber,
+      "pullRequestNumber",
+    ),
+    sourceHead: exactSha(input?.sourceHead, "sourceHead"),
+    sourceWorkflowRunId: positiveInteger(
+      input?.sourceWorkflowRunId,
+      "sourceWorkflowRunId",
+    ),
+    runAttempt,
+    runStatus: text(input?.runStatus).toLowerCase(),
+    runConclusion: text(input?.runConclusion).toLowerCase(),
+    runUpdatedAt,
+    totalJobCount: jobs.length,
+    nonterminalJobCount: 0,
+    workerTerminationProven: true,
+    jobs,
+    reason: text(input?.reason),
+  };
+  if (body.schema !== LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA) {
+    throw new Error(
+      `legacy terminal evidence must use ${LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA}`,
+    );
+  }
+  if (
+    body.runStatus !== "completed" ||
+    body.runConclusion !== "failure" ||
+    !body.reason
+  ) {
+    throw new Error(
+      "legacy terminal evidence requires one completed failed run with zero nonterminal jobs and proven worker termination",
+    );
+  }
+  const evidenceRoot = devDeliveryContentRoot(body);
+  if (exactRoot(input?.evidenceRoot, "evidenceRoot") !== evidenceRoot) {
+    throw new Error("legacy terminal evidence root mismatch");
+  }
+  return { ...body, evidenceRoot };
+}
+
+function assertExactCoverage(candidates, evidence) {
+  const expected = candidates.map((candidate) => candidate.candidateId).sort();
+  const observed = evidence.map((entry) => entry.candidateId).sort();
+  if (
+    expected.length !== observed.length ||
+    expected.some((candidateId, index) => candidateId !== observed[index])
+  ) {
+    throw new Error(
+      "legacy terminal recovery must cover every live legacy native candidate exactly once",
+    );
+  }
+}
+
+export function recoverLegacyTerminalDevDeliveryQueue(
+  queueInput,
+  requestInput,
+  { now = new Date().toISOString() } = {},
+) {
+  const currentTime = timestamp(now, "now");
+  const request = requestInput || {};
+  if (request.schema !== LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA) {
+    throw new Error(
+      `legacy terminal recovery must use ${LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA}`,
+    );
+  }
+  const before = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback: true,
+  });
+  const expectedOldStateRoot = exactRoot(
+    request.expectedOldStateRoot,
+    "expectedOldStateRoot",
+  );
+  if (expectedOldStateRoot !== before.stateRoot) {
+    throw new Error("legacy terminal recovery expected-old state drift");
+  }
+  const legacyCandidates = before.candidates.filter(legacyLiveNativeCandidate);
+  if (legacyCandidates.length === 0) {
+    throw new Error("legacy terminal recovery found no live legacy candidate");
+  }
+  if (!Array.isArray(request.evidence)) {
+    throw new Error("legacy terminal recovery evidence must be an array");
+  }
+  const evidence = request.evidence.map(normalizeEvidence);
+  if (
+    new Set(evidence.map((entry) => entry.candidateId)).size !== evidence.length
+  ) {
+    throw new Error(
+      "legacy terminal recovery evidence contains duplicate candidates",
+    );
+  }
+  assertExactCoverage(legacyCandidates, evidence);
+
+  const queue = clone(before);
+  delete queue.stateRoot;
+  const transitions = [];
+  for (const entry of evidence) {
+    const candidate = queue.candidates.find(
+      (row) => row.candidateId === entry.candidateId,
+    );
+    if (
+      !candidate ||
+      candidate.pullRequestNumber !== entry.pullRequestNumber ||
+      candidate.sourceHead !== entry.sourceHead ||
+      candidate.sourceWorkflowRunId !== entry.sourceWorkflowRunId
+    ) {
+      throw new Error(
+        "legacy terminal evidence does not match candidate identity",
+      );
+    }
+    const active = queue.activeWarrant?.candidateId === candidate.candidateId;
+    if (!active && candidate.status !== "queued") {
+      throw new Error(
+        `legacy candidate status ${candidate.status} requires the exact active Warrant`,
+      );
+    }
+    const priorStatus = candidate.status;
+    candidate.status = "terminal-failure";
+    candidate.updatedAt = currentTime;
+    candidate.terminal = {
+      outcome: "terminal-failure",
+      reason: entry.reason,
+      evidenceRoot: entry.evidenceRoot,
+      authority: "legacy-hosted-native-terminal-recovery",
+      sourceWorkflowRunId: entry.sourceWorkflowRunId,
+      runAttempt: entry.runAttempt,
+      workerTerminationProven: true,
+      closedAt: currentTime,
+      ...(active
+        ? {
+            fencingToken: queue.activeWarrant.fencingToken,
+            leaseGeneration: queue.activeWarrant.generation,
+          }
+        : {}),
+    };
+    transitions.push({
+      candidateId: candidate.candidateId,
+      pullRequestNumber: candidate.pullRequestNumber,
+      sourceHead: candidate.sourceHead,
+      priorStatus,
+      activeWarrant: active,
+      outcome: "terminal-failure",
+      evidenceRoot: entry.evidenceRoot,
+    });
+  }
+  queue.activeWarrant = null;
+  queue.generation += 1;
+  queue.updatedAt = currentTime;
+  queue.stateRoot = devDeliveryContentRoot(queue);
+  const after = normalizeDevDeliveryQueue(queue);
+  const requestBody = {
+    schema: LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA,
+    expectedOldStateRoot,
+    evidence,
+  };
+  const requestRoot = devDeliveryContentRoot(requestBody);
+  const receipt = {
+    schema: LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA,
+    action: "legacy-terminal-recovery",
+    expectedOldStateRoot,
+    nextStateRoot: after.stateRoot,
+    requestRoot,
+    transitions,
+    nextAction: "Select the next strictly valid queued candidate, if any.",
+  };
+  return {
+    queue: after,
+    receipt,
+    receiptRoot: devDeliveryContentRoot(receipt),
+  };
+}

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 {
@@ -380,6 +382,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 +482,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 +499,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 =

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

@@ -61,6 +61,14 @@ 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",
+  "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-release-invocation.js

@@ -0,0 +1,356 @@
+import {
+  V4ContractFault,
+  v4CanonicalBytes,
+  v4ContentRoot,
+  validateV4Root,
+} from "./v4-canonical-contracts.js";
+
+export const V4_RELEASE_INVOCATION_CONTRACT =
+  "kungfu-buildchain-v4-release-invocation/v1";
+export const V4_RELEASE_INVOCATION_ADAPTER_CONTRACT =
+  "kungfu-buildchain-v4-release-invocation-adapter/v1";
+export const V4_RELEASE_TRANSACTION_CONTRACT =
+  "kungfu-buildchain-v4-release-transaction/v1";
+export const V4_RELEASE_RECEIPT_CONTRACT =
+  "kungfu-buildchain-v4-release-receipt/v1";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const TAG_PATTERN = /^v[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+const ROUTE_SURFACES = new Set([
+  "alpha",
+  "stable",
+  "public",
+  "private",
+  "declarative",
+  "legacy-compatible",
+]);
+const EXECUTION_MODES = new Set(["fresh", "resume"]);
+const COMPARISON_STATES = new Set(["identical", "ahead", "behind", "diverged"]);
+
+function fault(code, path, message) {
+  throw new V4ContractFault(code, path, message);
+}
+
+function exactKeys(value, keys, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fault("invalid-release-invocation", path, `${path} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((key, index) => key !== expected[index])
+  )
+    fault(
+      "invalid-release-invocation-shape",
+      path,
+      `${path} keys are not canonical`,
+    );
+}
+
+function sha(value, path, nullable = false) {
+  if (nullable && value === null) return value;
+  if (typeof value !== "string" || !SHA_PATTERN.test(value))
+    fault("invalid-release-sha", path, `${path} must be an exact Git SHA`);
+  return value;
+}
+
+function text(value, path) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    /[^\x20-\x7e]/u.test(value)
+  )
+    fault("invalid-release-text", path, `${path} must be printable ASCII`);
+  return value;
+}
+
+function validatePublisher(value) {
+  exactKeys(
+    value,
+    ["repository", "workflow", "workflowSha", "job"],
+    "$/publisher",
+  );
+  if (
+    value.repository !== "kungfu-systems/buildchain" ||
+    value.workflow !== ".github/workflows/.release-candidate-promote.yml" ||
+    value.job !== "apply"
+  )
+    fault(
+      "invalid-publisher-identity",
+      "$/publisher",
+      "publisher identity is not the canonical v4 APPLY job",
+    );
+  sha(value.workflowSha, "$/publisher/workflowSha");
+}
+
+function validateRuntime(value) {
+  exactKeys(value, ["repository", "commit", "tree"], "$/runtime");
+  if (value.repository !== "kungfu-systems/buildchain")
+    fault(
+      "invalid-runtime-identity",
+      "$/runtime/repository",
+      "runtime repository is not canonical",
+    );
+  sha(value.commit, "$/runtime/commit");
+  sha(value.tree, "$/runtime/tree");
+}
+
+function validateCandidate(value) {
+  exactKeys(value, ["repository", "commit", "tree", "version"], "$/candidate");
+  text(value.repository, "$/candidate/repository");
+  sha(value.commit, "$/candidate/commit");
+  sha(value.tree, "$/candidate/tree");
+  text(value.version, "$/candidate/version");
+}
+
+function validateTarget(value) {
+  exactKeys(value, ["channel", "tag", "expectedOldSha"], "$/target");
+  if (
+    !["alpha", "stable"].includes(value.channel) ||
+    !TAG_PATTERN.test(value.tag)
+  )
+    fault(
+      "invalid-release-target",
+      "$/target",
+      "release channel and exact tag are not canonical",
+    );
+  sha(value.expectedOldSha, "$/target/expectedOldSha", true);
+}
+
+function validateAuthority(value) {
+  exactKeys(
+    value,
+    ["policyRoot", "qualificationRoot", "warrantRoot"],
+    "$/authority",
+  );
+  for (const name of ["policyRoot", "qualificationRoot", "warrantRoot"])
+    validateV4Root(value[name], `$/authority/${name}`);
+}
+
+export function createV4ReleaseInvocation(value) {
+  exactKeys(
+    value,
+    ["schema", "publisher", "runtime", "candidate", "target", "authority"],
+    "$",
+  );
+  if (value.schema !== V4_RELEASE_INVOCATION_CONTRACT)
+    fault(
+      "invalid-release-invocation",
+      "$/schema",
+      "unsupported invocation schema",
+    );
+  validatePublisher(value.publisher);
+  validateRuntime(value.runtime);
+  validateCandidate(value.candidate);
+  validateTarget(value.target);
+  validateAuthority(value.authority);
+  v4CanonicalBytes(value);
+  const roots = {
+    publisherRoot: v4ContentRoot(
+      "release-invocation-publisher",
+      value.publisher,
+    ),
+    runtimeRoot: v4ContentRoot("release-invocation-runtime", value.runtime),
+    candidateRoot: v4ContentRoot(
+      "release-invocation-candidate",
+      value.candidate,
+    ),
+    targetRoot: v4ContentRoot("release-invocation-target", value.target),
+    authorityRoot: v4ContentRoot(
+      "release-invocation-authority",
+      value.authority,
+    ),
+  };
+  const invocationRoot = v4ContentRoot("release-invocation", {
+    schema: V4_RELEASE_INVOCATION_CONTRACT,
+    ...roots,
+  });
+  return { invocation: value, roots: { ...roots, invocationRoot } };
+}
+
+export function adaptV4ReleaseInvocation(value) {
+  exactKeys(value, ["schema", "route", "invocation"], "$adapter");
+  if (value.schema !== V4_RELEASE_INVOCATION_ADAPTER_CONTRACT)
+    fault(
+      "invalid-release-adapter",
+      "$adapter/schema",
+      "unsupported adapter schema",
+    );
+  exactKeys(value.route, ["surface", "execution"], "$adapter/route");
+  if (!ROUTE_SURFACES.has(value.route.surface))
+    fault(
+      "invalid-release-adapter",
+      "$adapter/route/surface",
+      "unsupported route surface",
+    );
+  if (!EXECUTION_MODES.has(value.route.execution))
+    fault(
+      "invalid-release-adapter",
+      "$adapter/route/execution",
+      "unsupported execution mode",
+    );
+  return createV4ReleaseInvocation(value.invocation);
+}
+
+export function planV4ReleaseRoute({
+  requestedSha,
+  observedSha,
+  comparisonStatus,
+  requestedChannel = "",
+  targetRef,
+  dryRun = false,
+  resume = false,
+}) {
+  sha(requestedSha, "$route/requestedSha");
+  sha(observedSha, "$route/observedSha");
+  if (!COMPARISON_STATES.has(comparisonStatus))
+    fault(
+      "invalid-release-route",
+      "$route/comparisonStatus",
+      "unsupported source comparison state",
+    );
+  text(targetRef, "$route/targetRef");
+  const alphaLane = /^alpha\/v[0-9]+\/v[0-9]+\.[0-9]+$/u.test(targetRef);
+  const stableLane =
+    /^release\/v[0-9]+\/v[0-9]+\.[0-9]+$/u.test(targetRef) ||
+    ["publish-gate/major", "major-gate"].includes(targetRef);
+  if (!alphaLane && !stableLane)
+    fault(
+      "invalid-release-route",
+      "$route/targetRef",
+      "source lane is not a supported v4 release lane",
+    );
+  const derivedChannel = alphaLane ? "alpha" : "stable";
+  const normalizedRequested =
+    requestedChannel === "alpha"
+      ? "alpha"
+      : ["release", "stable", "major"].includes(requestedChannel)
+        ? "stable"
+        : requestedChannel === ""
+          ? derivedChannel
+          : "";
+  if (!normalizedRequested || normalizedRequested !== derivedChannel)
+    fault(
+      "invalid-release-route",
+      "$route/channel",
+      "requested channel does not match the source lane",
+    );
+  let decision = resume ? "Resume" : "Fresh";
+  let reason = resume ? "resume" : "fresh";
+  if (comparisonStatus === "ahead" && !resume && !dryRun) {
+    decision = "NoOp";
+    reason = "source-advanced";
+  } else if (
+    requestedSha !== observedSha &&
+    !(resume && comparisonStatus === "ahead") &&
+    !(dryRun && comparisonStatus === "ahead")
+  ) {
+    decision = "Blocked";
+    reason = `source-${comparisonStatus}`;
+  }
+  return Object.freeze({
+    decision,
+    reason,
+    channel: normalizedRequested,
+    targetRef,
+    requestedSha,
+    observedSha,
+  });
+}
+
+export function createV4ReleaseTransaction(value) {
+  exactKeys(
+    value,
+    ["invocationRoot", "publisherRoot", "runtimeRoot"],
+    "$transaction",
+  );
+  for (const name of ["invocationRoot", "publisherRoot", "runtimeRoot"])
+    validateV4Root(value[name], `$transaction/${name}`);
+  const transaction = {
+    schema: V4_RELEASE_TRANSACTION_CONTRACT,
+    invocationRoot: value.invocationRoot,
+    publisherRoot: value.publisherRoot,
+    runtimeRoot: value.runtimeRoot,
+    phases: ["QUALIFY", "APPLY", "SETTLE"],
+    writer: "canonical-v4-apply",
+  };
+  return {
+    transaction,
+    transactionRoot: v4ContentRoot("release-transaction", transaction),
+  };
+}
+
+export function createV4ReleaseReceipt(value) {
+  exactKeys(
+    value,
+    [
+      "schema",
+      "transactionRoot",
+      "outcome",
+      "releasePassportRoot",
+      "providerTransactionRoot",
+      "providerStateRoot",
+      "providerReceiptRoots",
+    ],
+    "$receipt",
+  );
+  if (value.schema !== V4_RELEASE_RECEIPT_CONTRACT)
+    fault(
+      "invalid-release-receipt",
+      "$receipt/schema",
+      "unsupported receipt schema",
+    );
+  validateV4Root(value.transactionRoot, "$receipt/transactionRoot");
+  if (!["complete", "blocked"].includes(value.outcome))
+    fault(
+      "invalid-release-receipt",
+      "$receipt/outcome",
+      "unsupported receipt outcome",
+    );
+  for (const name of [
+    "releasePassportRoot",
+    "providerTransactionRoot",
+    "providerStateRoot",
+  ]) {
+    if (value[name] !== null) validateV4Root(value[name], `$receipt/${name}`);
+  }
+  if (!Array.isArray(value.providerReceiptRoots))
+    fault(
+      "invalid-release-receipt",
+      "$receipt/providerReceiptRoots",
+      "receipt roots must be an array",
+    );
+  value.providerReceiptRoots.forEach((root, index) =>
+    validateV4Root(root, `$receipt/providerReceiptRoots/${index}`),
+  );
+  const canonicalRoots = [...new Set(value.providerReceiptRoots)].sort();
+  if (
+    canonicalRoots.length !== value.providerReceiptRoots.length ||
+    canonicalRoots.some(
+      (root, index) => root !== value.providerReceiptRoots[index],
+    )
+  )
+    fault(
+      "invalid-release-receipt",
+      "$receipt/providerReceiptRoots",
+      "provider receipt roots must be sorted and unique",
+    );
+  if (
+    value.outcome === "complete" &&
+    [
+      value.releasePassportRoot,
+      value.providerTransactionRoot,
+      value.providerStateRoot,
+    ].some((root) => root === null)
+  )
+    fault(
+      "invalid-release-receipt",
+      "$receipt/outcome",
+      "complete receipt requires every terminal root",
+    );
+  v4CanonicalBytes(value);
+  return {
+    receipt: value,
+    receiptRoot: v4ContentRoot("release-receipt", value),
+  };
+}