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

package/scripts/init-repo.mjs

@@ -3,21 +3,35 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
-import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
+import {
+  detectPackageManager,
+  assertPackageManager,
+} from "../packages/core/package-manager.js";
 import {
   PUBLICATION_REHEARSAL_WORKFLOW_PATH,
   appendPublicationRehearsalToml,
   mergePublicationRehearsalAgentInstructions,
   publicationRehearsalWorkflow,
 } from "../packages/core/publication-rehearsal-projection.js";
-
-const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
-const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
-const DEFAULT_PUBLICATION_LATEX_DIGEST = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8";
-const DEFAULT_PUBLICATION_LATEX_COMMAND = "latexmk -pdf -outdir=_build paper/main.tex";
+import {
+  appendNextDevelopmentToml,
+  mergeNextDevelopmentAgentInstructions,
+  nextDevelopmentWorkflowHeader,
+} from "../packages/core/next-development-projection.js";
+
+const BUILDCHAIN_WORKFLOW_REF =
+  "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
+const DEFAULT_PUBLICATION_LATEX_IMAGE =
+  "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
+const DEFAULT_PUBLICATION_LATEX_DIGEST =
+  "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8";
+const DEFAULT_PUBLICATION_LATEX_COMMAND =
+  "latexmk -pdf -outdir=_build paper/main.tex";
 
 function posixPath(value) {
-  return String(value || "").split(path.sep).join("/");
+  return String(value || "")
+    .split(path.sep)
+    .join("/");
 }
 
 function repoName(cwd) {
@@ -282,34 +296,42 @@ command = "make check"
 }
 
 function infraContractDesiredJson(cwd) {
-  return `${JSON.stringify({
-    service: repoName(cwd),
-    environment: "staging",
-    resources: [
-      {
-        kind: "static-site",
-        name: repoName(cwd),
-        desiredState: {
-          hostname: "staging.example.com",
-          accessControl: "managed-network",
-          owner: "platform",
+  return `${JSON.stringify(
+    {
+      service: repoName(cwd),
+      environment: "staging",
+      resources: [
+        {
+          kind: "static-site",
+          name: repoName(cwd),
+          desiredState: {
+            hostname: "staging.example.com",
+            accessControl: "managed-network",
+            owner: "platform",
+          },
         },
-      },
-    ],
-  }, null, 2)}\n`;
+      ],
+    },
+    null,
+    2,
+  )}\n`;
 }
 
 function infraContractOutputsJson(cwd) {
-  return `${JSON.stringify({
-    service: repoName(cwd),
-    environment: "staging",
-    observedMode: "manual-observed",
-    outputs: {
-      hostname: "staging.example.com",
-      distributionId: "observed-distribution-id",
-      bucket: "observed-bucket-name",
+  return `${JSON.stringify(
+    {
+      service: repoName(cwd),
+      environment: "staging",
+      observedMode: "manual-observed",
+      outputs: {
+        hostname: "staging.example.com",
+        distributionId: "observed-distribution-id",
+        bucket: "observed-bucket-name",
+      },
     },
-  }, null, 2)}\n`;
+    null,
+    2,
+  )}\n`;
 }
 
 function workflowArtifactPaths(type) {
@@ -333,7 +355,7 @@ function workflowArtifactPaths(type) {
 }
 
 function publicationWorkflowYaml() {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -365,7 +387,7 @@ jobs:
 }
 
 function workflowYaml({ type, runnerPreset, artifactName }) {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -398,9 +420,17 @@ jobs:
 `;
 }
 
+function devDeliveryWorkflowYaml() {
+  return fs.readFileSync(
+    new URL("../templates/native-dev-delivery.yml", import.meta.url),
+    "utf8",
+  );
+}
 function writeIfAllowed(filePath, content, { force }) {
   if (fs.existsSync(filePath) && !force) {
-    throw new Error(`${posixPath(filePath)} already exists; pass --force to overwrite`);
+    throw new Error(
+      `${posixPath(filePath)} already exists; pass --force to overwrite`,
+    );
   }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
@@ -408,7 +438,9 @@ function writeIfAllowed(filePath, content, { force }) {
 }
 
 function writeManagedAgentEntry(filePath, current) {
-  const content = mergePublicationRehearsalAgentInstructions(current);
+  const content = mergeNextDevelopmentAgentInstructions(
+    mergePublicationRehearsalAgentInstructions(current),
+  );
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
   return filePath;
@@ -424,27 +456,33 @@ export function initBuildchainRepo({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const manager = detectOrDefaultPackageManager(resolvedCwd, packageManager);
-  const toml = appendPublicationRehearsalToml((() => {
-    if (type === "package") {
-      return packageToml(resolvedCwd, manager);
-    }
-    if (type === "native") {
-      return nativeToml(resolvedCwd);
-    }
-    if (type === "web-surface") {
-      return webSurfaceToml(resolvedCwd);
-    }
-    if (type === "infra-contract") {
-      return infraContractToml(resolvedCwd);
-    }
-    if (type === "publication-artifact") {
-      return publicationArtifactToml(resolvedCwd);
-    }
-    if (type === "anchored-package") {
-      return anchoredPackageToml(resolvedCwd, manager);
-    }
-    throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
-  })());
+  const toml = appendNextDevelopmentToml(
+    appendPublicationRehearsalToml(
+      (() => {
+        if (type === "package") {
+          return packageToml(resolvedCwd, manager);
+        }
+        if (type === "native") {
+          return nativeToml(resolvedCwd);
+        }
+        if (type === "web-surface") {
+          return webSurfaceToml(resolvedCwd);
+        }
+        if (type === "infra-contract") {
+          return infraContractToml(resolvedCwd);
+        }
+        if (type === "publication-artifact") {
+          return publicationArtifactToml(resolvedCwd);
+        }
+        if (type === "anchored-package") {
+          return anchoredPackageToml(resolvedCwd, manager);
+        }
+        throw new Error(
+          "init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package",
+        );
+      })(),
+    ),
+  );
 
   const agentsPath = path.join(resolvedCwd, "AGENTS.md");
   const currentAgents = fs.existsSync(agentsPath)
@@ -452,7 +490,9 @@ export function initBuildchainRepo({
     : "";
 
   const written = [
-    writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
+    writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, {
+      force,
+    }),
     writeIfAllowed(
       path.join(resolvedCwd, ".github", "workflows", "build.yml"),
       type === "publication-artifact"
@@ -472,14 +512,41 @@ export function initBuildchainRepo({
     writeManagedAgentEntry(agentsPath, currentAgents),
   ];
 
-  if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {
-    written.push(writeIfAllowed(path.join(resolvedCwd, "release.json"), "{\n  \"upstream\": \"\",\n  \"version\": \"0.0.0\"\n}\n", { force }));
+  if (type === "native") {
+    written.push(
+      writeIfAllowed(
+        path.join(resolvedCwd, ".github", "workflows", "dev-delivery.yml"),
+        devDeliveryWorkflowYaml(),
+        { force },
+      ),
+    );
+  }
+
+  if (
+    type === "anchored-package" &&
+    !fs.existsSync(path.join(resolvedCwd, "release.json"))
+  ) {
+    written.push(
+      writeIfAllowed(
+        path.join(resolvedCwd, "release.json"),
+        '{\n  "upstream": "",\n  "version": "0.0.0"\n}\n',
+        { force },
+      ),
+    );
   }
 
   if (type === "infra-contract") {
     written.push(
-      writeIfAllowed(path.join(resolvedCwd, "infra", "desired.json"), infraContractDesiredJson(resolvedCwd), { force }),
-      writeIfAllowed(path.join(resolvedCwd, "infra", "outputs.json"), infraContractOutputsJson(resolvedCwd), { force }),
+      writeIfAllowed(
+        path.join(resolvedCwd, "infra", "desired.json"),
+        infraContractDesiredJson(resolvedCwd),
+        { force },
+      ),
+      writeIfAllowed(
+        path.join(resolvedCwd, "infra", "outputs.json"),
+        infraContractOutputsJson(resolvedCwd),
+        { force },
+      ),
     );
   }
 
@@ -489,7 +556,9 @@ export function initBuildchainRepo({
     cwd: resolvedCwd,
     packageManager: manager,
     workflowRef: BUILDCHAIN_WORKFLOW_REF,
-    written: written.map((filePath) => posixPath(path.relative(resolvedCwd, filePath))),
+    written: written.map((filePath) =>
+      posixPath(path.relative(resolvedCwd, filePath)),
+    ),
   };
 }
 
@@ -501,7 +570,11 @@ function readArg(name, fallback = "") {
   return process.argv[index + 1] || "";
 }
 
-if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (
+  !process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
   try {
     const result = initBuildchainRepo({
       cwd: readArg("cwd", process.cwd()),

package/scripts/next-development-self-dogfood-harness.mjs

@@ -0,0 +1,409 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { validateNextDevelopmentController } from "../packages/core/next-development-controller.js";
+import {
+  NEXT_DEVELOPMENT_REQUEST_CONTRACT,
+  NEXT_DEVELOPMENT_TRANSITION_CONTRACT,
+  materializeNextDevelopmentTransition,
+  nextDevelopmentRoot,
+} from "../packages/core/next-development-transition.js";
+
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const REPOSITORY = /^[^/\s]+\/[^/\s]+$/u;
+const ANCHOR_BYTES = '{"upstream":"v22.1.0"}\n';
+
+export const RECORDED_AT = "2026-08-11T02:00:00.000Z";
+export const PROTECTED_DEV_BRANCH = "dev/v3/v3.0";
+export const HOSTED_READBACK_PATHS = [
+  ".buildchain/release-impact.json",
+  "dist/site/buildchain-contract.json",
+  "package.json",
+];
+
+export function required(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+export function exactRoot(value, label) {
+  const normalized = required(value, label).toLowerCase();
+  if (!ROOT.test(normalized)) throw new Error(`${label} must be a sha256 root`);
+  return normalized;
+}
+
+export function exactSha(value, label) {
+  const normalized = required(value, label).toLowerCase();
+  if (!SHA.test(normalized)) {
+    throw new Error(`${label} must be an exact 40-character Git SHA`);
+  }
+  return normalized;
+}
+
+export function repository(value, label = "repository") {
+  const normalized = required(value, label);
+  if (!REPOSITORY.test(normalized)) throw new Error(`${label} must be owner/repo`);
+  return normalized;
+}
+
+export function fixtureSha(label) {
+  return nextDevelopmentRoot({ label }).slice("sha256:".length, 40 + 7);
+}
+
+function completedAlpha({ runtimeSha, contractRoot, model }) {
+  const version = model === "anchored" ? "22.0.0-alpha.1" : "3.0.9-alpha.1";
+  return {
+    outcome: "succeeded",
+    version,
+    exactTag: `v${version}`,
+    releaseSha: runtimeSha,
+    treeSha: fixtureSha(`completed-alpha-tree:${model}`),
+    publicationRoot: nextDevelopmentRoot({ runtimeSha, contractRoot, model }),
+    completedAt: "2026-08-11T01:00:00.000Z",
+  };
+}
+
+function adapterCheckout(model, version) {
+  const cwd = fs.mkdtempSync(
+    path.join(os.tmpdir(), `buildchain-next-development-self-dogfood-${model}-`),
+  );
+  fs.mkdirSync(path.join(cwd, ".buildchain"), { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, ".buildchain", "buildchain.toml"),
+    `schema = 1
+
+[version]
+required = true
+strategy = "${model === "anchored" ? "anchored" : "semver"}"
+next = "${model === "anchored" ? "manual" : "auto"}"
+${model === "anchored" ? 'manifest = "release.json"\n' : ""}
+[[version.files]]
+type = "json"
+path = "package.json"
+key = "version"
+`,
+  );
+  fs.writeFileSync(
+    path.join(cwd, "package.json"),
+    `${JSON.stringify({ name: "self-dogfood-fixture", version }, null, 2)}\n`,
+  );
+  if (model === "anchored") fs.writeFileSync(path.join(cwd, "release.json"), ANCHOR_BYTES);
+  return cwd;
+}
+
+export function anchorInput() {
+  return {
+    targetVersion: "22.1.0",
+    anchor: {
+      manifestPath: "release.json",
+      manifestRoot: `sha256:${crypto.createHash("sha256").update(ANCHOR_BYTES).digest("hex")}`,
+    },
+  };
+}
+
+function adapterRequest(route, model, reviewedInput) {
+  return {
+    contract: NEXT_DEVELOPMENT_REQUEST_CONTRACT,
+    repository: route.repository,
+    completedAlpha: completedAlpha({ ...route, model }),
+    recordedAt: RECORDED_AT,
+    ...(reviewedInput || {}),
+  };
+}
+
+export function adapterTransition(route, model) {
+  const alpha = completedAlpha({ ...route, model });
+  const cwd = adapterCheckout(model, alpha.version);
+  try {
+    return materializeNextDevelopmentTransition({
+      cwd,
+      request: adapterRequest(route, model),
+    });
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+function operationBody(record) {
+  const body = structuredClone(record);
+  delete body.operationRoot;
+  return body;
+}
+
+export function validateAdapterOperation(record) {
+  exactRoot(record?.operationKey, "adapter operation key");
+  exactRoot(record?.idempotencyKey, "adapter idempotency key");
+  exactRoot(record?.materializationRoot, "adapter materialization root");
+  if (
+    record?.adapterContract !== NEXT_DEVELOPMENT_TRANSITION_CONTRACT ||
+    !["semver", "anchored"].includes(record?.model)
+  ) {
+    throw new Error("real version-state adapter operation contract mismatch");
+  }
+  if (record.operationRoot !== nextDevelopmentRoot(operationBody(record))) {
+    throw new Error("real version-state adapter operation root drifted");
+  }
+  return structuredClone(record);
+}
+
+export function validateSelfDogfoodRoute(route) {
+  exactSha(route?.runtimeSha, "route.runtimeSha");
+  const targetRepository = repository(route?.repository, "route.repository");
+  if (
+    targetRepository !== "kungfu-systems/buildchain" ||
+    route.runtimeRef !== "v3-alpha" ||
+    route.publicWorkflow !==
+      `${targetRepository}/.github/workflows/build.yml@v3-alpha` ||
+    route.protectedDevBranch !== PROTECTED_DEV_BRANCH ||
+    JSON.stringify(route.hostedReadbackPaths) !==
+      JSON.stringify(HOSTED_READBACK_PATHS)
+  ) {
+    throw new Error("next-development evidence public route drifted");
+  }
+  return targetRepository;
+}
+
+export function validateRecoveryEvidence(recovery) {
+  const sameRunner =
+    required(recovery?.faultRunnerId, "faultRunnerId") ===
+    required(recovery?.resumeRunnerId, "resumeRunnerId");
+  const unchangedDev =
+    exactSha(recovery?.protectedDevMovement?.initialSha, "protected Dev initial SHA") ===
+    exactSha(recovery?.protectedDevMovement?.movedSha, "protected Dev moved SHA");
+  if (
+    recovery?.freshRunner !== true ||
+    sameRunner ||
+    recovery?.transientDurableStateFailures !== 1 ||
+    recovery?.recoveredAdapterOperations !== 1 ||
+    recovery?.alphaCandidateRebuilds !== 0 ||
+    recovery?.devMaterializationsBefore !== 1 ||
+    recovery?.devMaterializationsAfter !== 2 ||
+    recovery?.protectedDevMovement?.supersededAttempts !== 1 ||
+    unchangedDev ||
+    recovery?.protectedPrDelay?.status !== "pr-pending" ||
+    recovery?.protectedPrDelay?.delayedStatus !== "pr-pending" ||
+    recovery?.protectedPrDelay?.unchangedControllerRoot !== true
+  ) {
+    throw new Error("fresh-runner failure, Dev movement, or protected-PR delay proof is incomplete");
+  }
+}
+
+export function validateAdapterEvidence(adapter, semver, anchored) {
+  const operations = adapter?.operations || [];
+  operations.forEach(validateAdapterOperation);
+  const expectedKeys = [...semver.attempts, ...anchored.attempts]
+    .map((entry) => entry.operationKey)
+    .sort();
+  const observedKeys = operations.map((entry) => entry.operationKey).sort();
+  if (
+    adapter?.boundary !== "materializeNextDevelopmentTransition" ||
+    adapter?.contract !== NEXT_DEVELOPMENT_TRANSITION_CONTRACT ||
+    operations.length !== 3 ||
+    new Set(operations.map((entry) => entry.model)).size !== 2 ||
+    JSON.stringify(observedKeys) !== JSON.stringify(expectedKeys)
+  ) {
+    throw new Error("real version-state adapter boundary proof is incomplete");
+  }
+}
+
+export class DurableStore {
+  constructor(records = [], { transientFailures = 0 } = {}) {
+    this.records = new Map(
+      records.map((record) => {
+        const current = validateNextDevelopmentController(record);
+        return [current.childKey, current];
+      }),
+    );
+    this.transientFailuresRemaining = transientFailures;
+    this.transientFailures = 0;
+  }
+
+  async readChild(key) {
+    return structuredClone(this.records.get(key) || null);
+  }
+
+  async createChild(key, record) {
+    if (!this.records.has(key)) this.records.set(key, structuredClone(record));
+    return { record: structuredClone(this.records.get(key)) };
+  }
+
+  async compareAndSwapChild(key, expectedRoot, record) {
+    if (this.transientFailuresRemaining > 0) {
+      this.transientFailuresRemaining -= 1;
+      this.transientFailures += 1;
+      throw new Error("injected transient durable-state write failure");
+    }
+    const current = this.records.get(key);
+    if (!current || current.controllerRoot !== expectedRoot) {
+      throw new Error("self-dogfood durable store compare-and-swap failed");
+    }
+    this.records.set(key, structuredClone(record));
+    return { record: structuredClone(record) };
+  }
+
+  only() {
+    if (this.records.size !== 1) {
+      throw new Error("self-dogfood durable store expected exactly one child");
+    }
+    return structuredClone([...this.records.values()][0]);
+  }
+}
+
+export class VersionStateAdapterHarness {
+  constructor({
+    route,
+    operations = [],
+    devSha = fixtureSha("protected-dev:initial"),
+    movedDevSha = "",
+    moveAfterRecoveredOperation = false,
+    pullRequestReadsBeforeMerge = 0,
+  } = {}) {
+    this.operations = new Map(
+      operations.map((record) => {
+        const current = validateAdapterOperation(record);
+        return [current.operationKey, current];
+      }),
+    );
+    this.route = route ? structuredClone(route) : null;
+    this.devSha = devSha;
+    this.movedDevSha = movedDevSha;
+    this.moveAfterRecoveredOperation = moveAfterRecoveredOperation;
+    this.pullRequestReadsBeforeMerge = pullRequestReadsBeforeMerge;
+    this.materializations = operations.length;
+    this.recoveredOperations = 0;
+    this.pullRequestReads = 0;
+    this.pullRequest = null;
+  }
+
+  async readProtectedDev() {
+    return { sha: this.devSha };
+  }
+
+  async materialize({ operationKey, repository: targetRepository, baseDevSha, targetVersion, anchor }) {
+    const existing = this.operations.get(operationKey);
+    if (existing) {
+      this.recoveredOperations += 1;
+      if (this.moveAfterRecoveredOperation && this.movedDevSha) {
+        this.devSha = this.movedDevSha;
+        this.moveAfterRecoveredOperation = false;
+      }
+      return structuredClone(existing.result);
+    }
+    const model = anchor ? "anchored" : "semver";
+    const route = this.route || {
+      repository: targetRepository,
+      runtimeSha: model === "anchored" ? fixtureSha("anchored-runtime") : fixtureSha("semver-runtime"),
+      contractRoot: nextDevelopmentRoot({ model, targetRepository }),
+    };
+    const alpha = completedAlpha({ ...route, model });
+    const cwd = adapterCheckout(model, alpha.version);
+    let materialized;
+    try {
+      materialized = materializeNextDevelopmentTransition({
+        cwd,
+        request: adapterRequest(
+          route,
+          model,
+          model === "anchored" ? { targetVersion, anchor } : undefined,
+        ),
+        write: true,
+      });
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true });
+    }
+    if (materialized.state.status !== "materialized" || materialized.target.version !== targetVersion) {
+      throw new Error("real version-state adapter did not materialize the target");
+    }
+    const result = {
+      baseDevSha,
+      commitSha: fixtureSha(`prepared:${operationKey}:${materialized.materialization.materializationRoot}`),
+      treeSha: fixtureSha(`prepared-tree:${operationKey}:${materialized.materialization.materializationRoot}`),
+      sourceRoots: materialized.materialization.paths.map((entry) => ({
+        path: entry.path,
+        beforeRoot: entry.beforeRoot,
+        afterRoot: entry.afterRoot,
+        version: targetVersion,
+      })),
+      derivedRoots: [],
+      changedPaths: materialized.materialization.paths
+        .filter((entry) => entry.changed)
+        .map((entry) => entry.path)
+        .sort(),
+      lifecycleEvidenceRoot: materialized.materialization.materializationRoot,
+    };
+    const record = {
+      operationKey,
+      model,
+      adapterContract: materialized.contract,
+      idempotencyKey: materialized.idempotencyKey,
+      materializationRoot: materialized.materialization.materializationRoot,
+      result,
+    };
+    record.operationRoot = nextDevelopmentRoot(record);
+    this.operations.set(operationKey, validateAdapterOperation(record));
+    this.materializations += 1;
+    return structuredClone(result);
+  }
+
+  async ensurePullRequest({ baseBranch, headSha }) {
+    this.pullRequest = {
+      number: 91,
+      url: "https://github.com/kungfu-systems/buildchain/pull/91",
+      baseBranch,
+      headSha,
+      status: "open",
+      evidenceRoot: nextDevelopmentRoot({ baseBranch, headSha, pullRequest: 91 }),
+    };
+    return structuredClone(this.pullRequest);
+  }
+
+  async readPullRequest({ number }) {
+    if (!this.pullRequest) throw new Error(`self-dogfood pull request ${number} was not restored`);
+    this.pullRequestReads += 1;
+    if (this.pullRequestReads > this.pullRequestReadsBeforeMerge) {
+      this.pullRequest.status = "merged";
+      this.devSha = fixtureSha(`protected-merge:${this.pullRequest.headSha}`);
+    }
+    return structuredClone(this.pullRequest);
+  }
+
+  async readProtectedVersionState({ sourcePaths, derivedPaths, targetVersion, preparedCommitSha }) {
+    const operation = [...this.operations.values()].find(
+      (entry) => entry.result.commitSha === preparedCommitSha,
+    );
+    if (!operation) throw new Error("protected readback has no rooted adapter operation");
+    const sourceRoots = Object.fromEntries(
+      operation.result.sourceRoots.map((entry) => [entry.path, entry.afterRoot]),
+    );
+    const derivedRoots = Object.fromEntries(
+      operation.result.derivedRoots.map((entry) => [entry.path, entry.root]),
+    );
+    const body = {
+      branch: PROTECTED_DEV_BRANCH,
+      devSha: this.devSha,
+      preparedCommitSha,
+      targetVersion,
+      versionRoots: sourcePaths.map((filePath) => ({ path: filePath, root: sourceRoots[filePath] })),
+      derivedRoots: derivedPaths.map((filePath) => ({ path: filePath, root: derivedRoots[filePath] })),
+    };
+    return {
+      devSha: this.devSha,
+      treeSha: fixtureSha(`protected-readback-tree:${preparedCommitSha}`),
+      version: targetVersion,
+      containsPreparedCommit: true,
+      versionRoots: body.versionRoots,
+      derivedRoots: body.derivedRoots,
+      evidenceRoot: nextDevelopmentRoot(body),
+    };
+  }
+
+  operationRecords() {
+    return [...this.operations.values()].map((entry) => structuredClone(entry));
+  }
+}