@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.55

package/scripts/check-v4-runtime-semantic-closure.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const V4_RUNTIME_SEMANTIC_CLOSURE_CONTRACT =
+  "kungfu-buildchain-v4-runtime-semantic-closure";
+export const V4_RUNTIME_SEMANTIC_CLOSURE_PATH =
+  "architecture/v4-runtime-semantic-closure.json";
+export const REQUIRED_RUNTIME_EVIDENCE = Object.freeze([
+  "positive",
+  "negative",
+  "failure",
+  "recovery",
+  "idempotence",
+]);
+
+function loadJson(root, relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
+}
+
+function sorted(values) {
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function sameMembers(left, right) {
+  return JSON.stringify(sorted(left)) === JSON.stringify(sorted(right));
+}
+
+function publicSurfaceIds(root) {
+  const packageJson = loadJson(root, "package.json");
+  const cli = loadJson(root, "dist/site/cli-registry.json");
+  const workflows = loadJson(root, "dist/site/workflow-registry.json");
+  return new Set([
+    ...Object.keys(packageJson.exports || {}).map((id) => `export:${id}`),
+    ...(cli.commands || []).map((entry) => `cli:${entry.id}`),
+    ...(workflows.workflows || []).map((entry) => `workflow:${entry.id}`),
+    ...(workflows.actions || []).map((entry) => `action:${entry.id}`),
+  ]);
+}
+
+function validateEvidence(root, mechanism, capability, issues) {
+  const sourceTests = new Set(mechanism.testPaths || []);
+  for (const dimension of REQUIRED_RUNTIME_EVIDENCE) {
+    const entries = capability.evidence?.[dimension];
+    if (!Array.isArray(entries) || entries.length === 0) {
+      issues.push(`${capability.id}: ${dimension} evidence is empty`);
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry?.path || !entry?.name) {
+        issues.push(`${capability.id}: ${dimension} evidence is incomplete`);
+        continue;
+      }
+      if (!sourceTests.has(entry.path))
+        issues.push(
+          `${capability.id}: ${dimension} evidence is outside the reverse-scanned test set: ${entry.path}`,
+        );
+      const absolute = path.join(root, entry.path);
+      if (!fs.existsSync(absolute)) {
+        issues.push(
+          `${capability.id}: evidence path is missing: ${entry.path}`,
+        );
+        continue;
+      }
+      const source = fs.readFileSync(absolute, "utf8");
+      if (!source.includes(`test(${JSON.stringify(entry.name)}`))
+        issues.push(
+          `${capability.id}: evidence test is missing from ${entry.path}: ${entry.name}`,
+        );
+    }
+  }
+}
+
+function validateResidualClosure(mechanism, capability, issues) {
+  const sourceResiduals = mechanism.unresolved || [];
+  const closed = capability.resolvedResiduals || [];
+  if (
+    !sameMembers(
+      sourceResiduals,
+      closed.map((entry) => entry?.source || ""),
+    )
+  )
+    issues.push(
+      `${capability.id}: resolved residual identities do not match the reverse scan`,
+    );
+  for (const entry of closed) {
+    if (!String(entry?.resolution || "").trim())
+      issues.push(`${capability.id}: residual resolution is empty`);
+  }
+}
+
+function validateImplementation(root, mechanism, capability, issues) {
+  if (
+    !Array.isArray(capability.implementation) ||
+    capability.implementation.length === 0
+  ) {
+    issues.push(`${capability.id}: implementation route is empty`);
+    return;
+  }
+  const reverseScanned = new Set(mechanism.sourcePaths || []);
+  let boundToReverseScan = false;
+  for (const relativePath of capability.implementation) {
+    if (!fs.existsSync(path.join(root, relativePath)))
+      issues.push(
+        `${capability.id}: implementation path is missing: ${relativePath}`,
+      );
+    if (reverseScanned.has(relativePath)) boundToReverseScan = true;
+  }
+  if (!boundToReverseScan)
+    issues.push(
+      `${capability.id}: implementation is not bound to a reverse-scanned v3 mechanism route`,
+    );
+}
+
+function validateAuthority(capability, stateMachine, issues) {
+  for (const field of [
+    "exactHeadFence",
+    "immutableRootFence",
+    "providerReadbackBeforeRetry",
+    "idempotentReplay",
+  ]) {
+    if (capability.invariants?.[field] !== true)
+      issues.push(`${capability.id}: ${field} must remain true`);
+  }
+  if (capability.routeKind !== "v4-native")
+    issues.push(`${capability.id}: routeKind must be v4-native`);
+  if (capability.legacyFallbackAllowed !== false)
+    issues.push(`${capability.id}: legacy fallback must remain disabled`);
+  if (capability.providerDecisionAuthorityAllowed !== false)
+    issues.push(
+      `${capability.id}: provider decision authority must remain disabled`,
+    );
+  if (stateMachine) {
+    if (capability.stateAuthority !== "single-writer-state-machine")
+      issues.push(
+        `${capability.id}: state-machine authority classification drifted`,
+      );
+    if (
+      stateMachine.writer?.authoritative !== true ||
+      stateMachine.writer?.secondWriterBudget !== 0
+    )
+      issues.push(`${capability.id}: v4 state machine is not single-writer`);
+    if (
+      !Array.isArray(stateMachine.recovery) ||
+      stateMachine.recovery.length === 0
+    )
+      issues.push(`${capability.id}: v4 state machine recovery is empty`);
+  } else if (capability.stateAuthority !== "bounded-protocol") {
+    issues.push(
+      `${capability.id}: bounded protocol authority classification drifted`,
+    );
+  }
+}
+
+export function validateRuntimeSemanticClosure({
+  root = process.cwd(),
+  manifest = loadJson(root, V4_RUNTIME_SEMANTIC_CLOSURE_PATH),
+  v3Inventory = loadJson(root, "architecture/v3-core-mechanism-inventory.json"),
+  v4Manifest = loadJson(
+    root,
+    "architecture/v4-capability-state-machine-manifest.json",
+  ),
+} = {}) {
+  const issues = [];
+  if (
+    manifest?.schemaVersion !== 1 ||
+    manifest?.contract !== V4_RUNTIME_SEMANTIC_CLOSURE_CONTRACT
+  )
+    issues.push(
+      "runtime semantic closure contract or schemaVersion is invalid",
+    );
+  if (!sameMembers(manifest?.requiredEvidence || [], REQUIRED_RUNTIME_EVIDENCE))
+    issues.push("runtime semantic closure evidence dimensions drifted");
+
+  const mechanisms = new Map(
+    (v3Inventory.mechanisms || []).map((entry) => [entry.id, entry]),
+  );
+  const v4Capabilities = new Map(
+    (v4Manifest.capabilities || []).map((entry) => [entry.id, entry]),
+  );
+  const stateMachines = new Map(
+    (v4Manifest.stateMachines || []).map((entry) => [entry.id, entry]),
+  );
+  const capabilities = Array.isArray(manifest?.capabilities)
+    ? manifest.capabilities
+    : [];
+  if (
+    !sameMembers(
+      capabilities.map((entry) => entry.id),
+      mechanisms.keys(),
+    )
+  )
+    issues.push(
+      "runtime semantic closure does not cover every v3 mechanism exactly once",
+    );
+  if (
+    !sameMembers(
+      capabilities.map((entry) => entry.id),
+      v4Capabilities.keys(),
+    )
+  )
+    issues.push(
+      "runtime semantic closure does not match the v4 capability manifest",
+    );
+
+  const surfaces = publicSurfaceIds(root);
+  const ids = new Set();
+  for (const capability of capabilities) {
+    if (!capability?.id || ids.has(capability.id)) {
+      issues.push(
+        `runtime semantic capability id is missing or duplicated: ${capability?.id || "<empty>"}`,
+      );
+      continue;
+    }
+    ids.add(capability.id);
+    const mechanism = mechanisms.get(capability.id);
+    const v4Capability = v4Capabilities.get(capability.id);
+    if (!mechanism || !v4Capability) continue;
+    if (capability.sourceMechanismId !== capability.id)
+      issues.push(`${capability.id}: source mechanism identity drifted`);
+    validateImplementation(root, mechanism, capability, issues);
+    validateResidualClosure(mechanism, capability, issues);
+    validateEvidence(root, mechanism, capability, issues);
+    validateAuthority(capability, stateMachines.get(capability.id), issues);
+    for (const surface of v4Capability.surfaces || []) {
+      if (!surfaces.has(surface))
+        issues.push(
+          `${capability.id}: executable v4 surface is absent: ${surface}`,
+        );
+    }
+  }
+
+  if (issues.length)
+    throw new Error(
+      `v4 runtime semantic closure failed:\n- ${issues.join("\n- ")}`,
+    );
+  return {
+    capabilities: capabilities.length,
+    evidenceDimensions: capabilities.length * REQUIRED_RUNTIME_EVIDENCE.length,
+    residualsClosed: capabilities.reduce(
+      (sum, entry) => sum + entry.resolvedResiduals.length,
+      0,
+    ),
+    legacyFallbacks: 0,
+    providerDecisionAuthorities: 0,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    const report = validateRuntimeSemanticClosure();
+    console.log(
+      `v4 runtime semantic closure passed: ${report.capabilities} capabilities, ` +
+        `${report.evidenceDimensions} evidence dimensions, ${report.residualsClosed} reverse-scan residuals closed, ` +
+        "0 legacy fallbacks, 0 provider decision authorities",
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/scripts/dev-delivery-source-proof-replay.mjs

@@ -0,0 +1,153 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SHA = /^[0-9a-f]{40}$/u;
+
+function exactSha(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${label} must be an exact 40-hex Git SHA`);
+  return normalized;
+}
+
+function git(args, { cwd, encoding = "utf8" }) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.status !== 0)
+    throw new Error(
+      `git ${args.join(" ")} failed: ${String(result.stderr || "").trim()}`,
+    );
+  return encoding === null ? result.stdout : String(result.stdout || "").trim();
+}
+
+function patchRoot(base, head, cwd) {
+  const patch = git(
+    [
+      "diff",
+      "--binary",
+      "--full-index",
+      "--no-ext-diff",
+      `${base}..${head}`,
+    ],
+    { cwd, encoding: null },
+  );
+  return `sha256:${crypto.createHash("sha256").update(patch).digest("hex")}`;
+}
+
+function linearRange(base, head, cwd) {
+  try {
+    git(["merge-base", "--is-ancestor", base, head], { cwd });
+  } catch {
+    return null;
+  }
+  const commits = git(
+    ["rev-list", "--reverse", "--topo-order", `${base}..${head}`],
+    { cwd },
+  )
+    .split(/\s+/u)
+    .filter(Boolean);
+  if (commits.length === 0) return null;
+  let expectedParent = base;
+  const trees = [];
+  const patchRoots = [];
+  for (const rangeCommit of commits) {
+    const [observedCommit, ...parents] = git(
+      ["rev-list", "--parents", "-n", "1", rangeCommit],
+      { cwd },
+    ).split(/\s+/u);
+    if (
+      observedCommit !== rangeCommit ||
+      parents.length !== 1 ||
+      parents[0] !== expectedParent
+    ) {
+      return null;
+    }
+    trees.push(
+      exactSha(
+        git(["rev-parse", `${rangeCommit}^{tree}`], { cwd }),
+        "replayedCommitTree",
+      ),
+    );
+    patchRoots.push(patchRoot(expectedParent, rangeCommit, cwd));
+    expectedParent = rangeCommit;
+  }
+  return { commits, trees, patchRoots };
+}
+
+export function exactMergeGroupBinding(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const mergeGroupHead = exactSha(input.mergeGroupHead, "mergeGroupHead");
+  const expectedTree = exactSha(input.mergeGroupTree, "mergeGroupTree");
+  const qualifiedBase = exactSha(input.qualifiedBase, "qualifiedBase");
+  const currentBase = exactSha(input.currentBase, "currentBase");
+  const sourceHead = exactSha(input.sourceHead, "sourceHead");
+  const sourcePatchRoot = String(input.sourcePatchRoot || "").trim();
+  const actualTree = exactSha(
+    git(["rev-parse", `${mergeGroupHead}^{tree}`], { cwd }),
+    "mergeGroupTree",
+  );
+  if (actualTree !== expectedTree)
+    return { ok: false, reason: "merge-group-tree-mismatch" };
+  try {
+    git(["merge-base", "--is-ancestor", qualifiedBase, currentBase], { cwd });
+  } catch {
+    return {
+      ok: false,
+      reason: "current-base-not-descendant-of-qualified-base",
+    };
+  }
+  if (!/^sha256:[0-9a-f]{64}$/u.test(sourcePatchRoot))
+    throw new Error("sourcePatchRoot must be an exact SHA-256 root");
+  if (patchRoot(currentBase, mergeGroupHead, cwd) !== sourcePatchRoot)
+    return { ok: false, reason: "merge-group-source-patch-mismatch" };
+
+  const [commit, ...parents] = git(
+    ["rev-list", "--parents", "-n", "1", mergeGroupHead],
+    { cwd },
+  ).split(/\s+/u);
+  if (commit !== mergeGroupHead)
+    return { ok: false, reason: "merge-group-parent-mismatch" };
+  if (
+    parents.length === 2 &&
+    parents[0] === currentBase &&
+    parents[1] === sourceHead
+  ) {
+    return {
+      ok: true,
+      mergeGroupHead,
+      mergeGroupTree: actualTree,
+      parents,
+      compositionMode: "two-parent-merge",
+      replayedCommitTrees: [],
+      replayedCommitPatchRoots: [],
+    };
+  }
+
+  const sourceRange = linearRange(qualifiedBase, sourceHead, cwd);
+  const mergeGroupRange = linearRange(currentBase, mergeGroupHead, cwd);
+  if (
+    !sourceRange ||
+    !mergeGroupRange ||
+    sourceRange.commits.length !== mergeGroupRange.commits.length ||
+    sourceRange.patchRoots.some(
+      (root, index) => root !== mergeGroupRange.patchRoots[index],
+    )
+  ) {
+    return { ok: false, reason: "merge-group-parent-mismatch" };
+  }
+  return {
+    ok: true,
+    mergeGroupHead,
+    mergeGroupTree: actualTree,
+    parents,
+    compositionMode: "linear-replay",
+    replayedCommitTrees: mergeGroupRange.trees,
+    replayedCommitPatchRoots: mergeGroupRange.patchRoots,
+  };
+}

package/scripts/dev-delivery-source-proof-reuse.mjs

@@ -11,6 +11,7 @@ import {
   verifySourceQualificationProof,
 } from "../packages/core/dev-delivery-warrant.js";
 import { validateControllerReceipt } from "../packages/core/controller-evidence.js";
+import { exactMergeGroupBinding } from "./dev-delivery-source-proof-replay.mjs";
 
 const REUSE_DECISION_SCHEMA =
   "kungfu.buildchain.source-qualification-reuse-decision/v1";
@@ -113,98 +114,6 @@ function gitPathRoot(ref, paths, label, cwd) {
   });
 }
 
-function exactMergeGroupBinding(input = {}) {
-  const cwd = path.resolve(input.cwd || process.cwd());
-  const mergeGroupHead = exactSha(input.mergeGroupHead, "mergeGroupHead");
-  const expectedTree = exactSha(input.mergeGroupTree, "mergeGroupTree");
-  const currentBase = exactSha(input.currentBase, "currentBase");
-  const sourceHead = exactSha(input.sourceHead, "sourceHead");
-  const actualTree = exactSha(
-    git(["rev-parse", `${mergeGroupHead}^{tree}`], { cwd }),
-    "mergeGroupTree",
-  );
-  if (actualTree !== expectedTree)
-    return { ok: false, reason: "merge-group-tree-mismatch" };
-  const [commit, ...parents] = git(
-    ["rev-list", "--parents", "-n", "1", mergeGroupHead],
-    { cwd },
-  ).split(/\s+/u);
-  if (commit !== mergeGroupHead) {
-    return { ok: false, reason: "merge-group-parent-mismatch" };
-  }
-  if (
-    parents.length === 2 &&
-    parents[0] === currentBase &&
-    parents[1] === sourceHead
-  ) {
-    return {
-      ok: true,
-      mergeGroupHead,
-      mergeGroupTree: actualTree,
-      parents,
-      compositionMode: "two-parent-merge",
-      replayedCommitTrees: [],
-    };
-  }
-
-  const linearRange = (head) => {
-    try {
-      git(["merge-base", "--is-ancestor", currentBase, head], { cwd });
-    } catch {
-      return null;
-    }
-    const commits = git(
-      ["rev-list", "--reverse", "--topo-order", `${currentBase}..${head}`],
-      { cwd },
-    )
-      .split(/\s+/u)
-      .filter(Boolean);
-    if (commits.length === 0) return null;
-    let expectedParent = currentBase;
-    const trees = [];
-    for (const rangeCommit of commits) {
-      const [observedCommit, ...rangeParents] = git(
-        ["rev-list", "--parents", "-n", "1", rangeCommit],
-        { cwd },
-      ).split(/\s+/u);
-      if (
-        observedCommit !== rangeCommit ||
-        rangeParents.length !== 1 ||
-        rangeParents[0] !== expectedParent
-      ) {
-        return null;
-      }
-      trees.push(
-        exactSha(
-          git(["rev-parse", `${rangeCommit}^{tree}`], { cwd }),
-          "replayedCommitTree",
-        ),
-      );
-      expectedParent = rangeCommit;
-    }
-    return trees;
-  };
-
-  const sourceTrees = linearRange(sourceHead);
-  const mergeGroupTrees = linearRange(mergeGroupHead);
-  if (
-    !sourceTrees ||
-    !mergeGroupTrees ||
-    sourceTrees.length !== mergeGroupTrees.length ||
-    sourceTrees.some((tree, index) => tree !== mergeGroupTrees[index])
-  ) {
-    return { ok: false, reason: "merge-group-parent-mismatch" };
-  }
-  return {
-    ok: true,
-    mergeGroupHead,
-    mergeGroupTree: actualTree,
-    parents,
-    compositionMode: "linear-replay",
-    replayedCommitTrees: mergeGroupTrees,
-  };
-}
-
 export function sourceQualificationPredicates(input = {}) {
   const cwd = path.resolve(input.cwd || process.cwd());
   const repository = required(input.repository, "repository");
@@ -397,7 +306,8 @@ export function materializeReuseLifecycleEvidence({
       decisionRoot: decision.decisionRoot,
       sourceWorkflowRunId: decision.sourceWorkflowRunId,
       sourceHead: decision.sourceHead,
-      qualifiedBase: decision.currentBase,
+      qualifiedBase: decision.qualifiedBase,
+      currentBase: decision.currentBase,
       mergeGroupHead: decision.mergeGroupHead,
       mergeGroupTree: decision.mergeGroupTree,
     },
@@ -446,7 +356,7 @@ export function verifySourceQualificationReuse(input = {}) {
   const verification = verifySourceQualificationProof(proof, {
     repository: required(input.repository, "repository"),
     protectedBase: required(input.protectedBase, "protectedBase"),
-    qualifiedBase: exactSha(input.currentBase, "currentBase"),
+    qualifiedBase: exactSha(proof.qualifiedBase, "qualifiedBase"),
     sourceHead: exactSha(input.sourceHead, "sourceHead"),
     sourceWorkflowRunId: Number(input.sourceWorkflowRunId),
     controllerReceiptRoot: receipt.digest,
@@ -462,7 +372,7 @@ export function verifySourceQualificationReuse(input = {}) {
   }
   const current = sourceQualificationPredicates({
     ...input,
-    qualifiedBase: input.currentBase,
+    qualifiedBase: proof.qualifiedBase,
   });
   const classification = classifyDevDeliveryDelta({
     proof,
@@ -476,7 +386,11 @@ export function verifySourceQualificationReuse(input = {}) {
       reason: classification.reason,
     });
   }
-  const mergeGroup = exactMergeGroupBinding(input);
+  const mergeGroup = exactMergeGroupBinding({
+    ...input,
+    qualifiedBase: proof.qualifiedBase,
+    sourcePatchRoot: proof.sourcePatchRoot,
+  });
   if (!mergeGroup.ok) {
     return rootedDecision({
       schema: REUSE_DECISION_SCHEMA,
@@ -493,12 +407,14 @@ export function verifySourceQualificationReuse(input = {}) {
     sourceProofRoot: proof.proofRoot,
     sourceWorkflowRunId: proof.sourceWorkflowRunId,
     sourceHead: proof.sourceHead,
-    currentBase: proof.qualifiedBase,
+    qualifiedBase: proof.qualifiedBase,
+    currentBase: exactSha(input.currentBase, "currentBase"),
     mergeGroupHead: mergeGroup.mergeGroupHead,
     mergeGroupTree: mergeGroup.mergeGroupTree,
     mergeGroupParents: mergeGroup.parents,
     mergeGroupCompositionMode: mergeGroup.compositionMode,
     mergeGroupReplayTrees: mergeGroup.replayedCommitTrees,
+    mergeGroupReplayPatchRoots: mergeGroup.replayedCommitPatchRoots,
     predicateRoots: {
       sourceIdentityRoot: proof.sourceIdentityRoot,
       sourcePatchRoot: proof.sourcePatchRoot,

package/scripts/dev-delivery-warrant-options.mjs

@@ -7,6 +7,32 @@ export function hasFlag(args, name) {
   return args.includes(`--${name}`);
 }
 
+function terminalEvidenceOptions(rest, environment) {
+  return {
+    outcome: flag(rest, "outcome", environment.BUILDCHAIN_DEV_DELIVERY_OUTCOME),
+    eventAction: flag(
+      rest,
+      "event-action",
+      environment.BUILDCHAIN_DEV_DELIVERY_EVENT_ACTION,
+    ),
+    evidenceRoot: flag(
+      rest,
+      "evidence-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_EVIDENCE_ROOT,
+    ),
+    expectedPriorEvidenceRoot: flag(
+      rest,
+      "expected-prior-evidence-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_PRIOR_EVIDENCE_ROOT,
+    ),
+    integrationProofPath: flag(
+      rest,
+      "integration-proof",
+      environment.BUILDCHAIN_DEV_DELIVERY_INTEGRATION_PROOF,
+    ),
+  };
+}
+
 export function devDeliveryCliOptions(args = [], environment = process.env) {
   const [command = "", ...rest] = args;
   return {
@@ -196,17 +222,7 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       "lease-seconds",
       environment.BUILDCHAIN_DEV_DELIVERY_LEASE_SECONDS,
     ),
-    outcome: flag(rest, "outcome", environment.BUILDCHAIN_DEV_DELIVERY_OUTCOME),
-    eventAction: flag(
-      rest,
-      "event-action",
-      environment.BUILDCHAIN_DEV_DELIVERY_EVENT_ACTION,
-    ),
-    evidenceRoot: flag(
-      rest,
-      "evidence-root",
-      environment.BUILDCHAIN_DEV_DELIVERY_EVIDENCE_ROOT,
-    ),
+    ...terminalEvidenceOptions(rest, environment),
     transferRoot: flag(rest, "transfer-root"),
     finalizerBoundaryRoot: flag(rest, "finalizer-boundary-root"),
     nativeJobId: flag(rest, "native-job-id"),

package/scripts/dev-delivery-warrant-store.mjs

@@ -46,7 +46,7 @@ function decodeBlob(blob) {
   ).toString("utf8");
 }
 
-function validateStoredState(queue) {
+function validateStoredState(queue, { allowLegacyV3Readback = false } = {}) {
   const body = structuredClone(queue || {});
   const embeddedStateRoot = body.stateRoot;
   delete body.stateRoot;
@@ -59,7 +59,7 @@ function validateStoredState(queue) {
   ) {
     normalizeDevDeliveryAuthorityState(queue);
   } else {
-    normalizeDevDeliveryQueue(queue);
+    normalizeDevDeliveryQueue(queue, { allowLegacyV3Readback });
   }
   return queue;
 }
@@ -108,7 +108,7 @@ export class GitHubDevDeliveryStore {
     return data;
   }
 
-  async read({ stateRef, protectedBase, now }) {
+  async read({ stateRef, protectedBase, now, allowLegacyV3Readback = false }) {
     let ref;
     try {
       ref = await this.request(
@@ -128,11 +128,13 @@ export class GitHubDevDeliveryStore {
       };
     }
     const commitSha = exactSha(ref?.object?.sha, "state ref commit");
-    const readback = await this.readCommit(commitSha);
+    const readback = await this.readCommit(commitSha, {
+      allowLegacyV3Readback,
+    });
     return { exists: true, ...readback };
   }
 
-  async readCommit(commitShaInput) {
+  async readCommit(commitShaInput, { allowLegacyV3Readback = false } = {}) {
     const commitSha = exactSha(commitShaInput, "state commit");
     const commit = await this.request(
       "GET",
@@ -152,7 +154,9 @@ export class GitHubDevDeliveryStore {
       `/repos/${this.repository.fullName}/git/blobs/${entry.sha}`,
     );
     const bytes = decodeBlob(blob);
-    const queue = validateStoredState(JSON.parse(bytes));
+    const queue = validateStoredState(JSON.parse(bytes), {
+      allowLegacyV3Readback,
+    });
     return { commitSha, queue, bytes };
   }