@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/scripts/maintainability-public-surface.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+} from "./universal-facade-maintainability.mjs";
+
+function readJson(root, file) {
+  return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
+}
+
+function readJsonAtRevision(root, revision, file) {
+  return JSON.parse(
+    execFileSync("git", ["show", `${revision}:${file}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  );
+}
+
+function publicSurfaceContract(entry, kind) {
+  if (kind === "cli") return { id: entry.id, usage: entry.usage };
+  if (kind === "node")
+    return {
+      export: entry.export,
+      specifier: entry.specifier,
+      target: entry.target,
+    };
+  return {
+    id: entry.id,
+    path: entry.path,
+    reusable: entry.reusable,
+    inputs: entry.inputs || [],
+    secrets: entry.secrets || [],
+    outputs: entry.outputs || [],
+  };
+}
+
+function evaluatePublicSurface({
+  root,
+  revision,
+  policy,
+  migration = loadUniversalFacadeMigration(root),
+}) {
+  const issues = [];
+  const capabilityGroups = new Set(
+    readJson(root, "dist/site/capability-registry.json").groups.map(
+      (entry) => entry.id,
+    ),
+  );
+  const definitions = [
+    ["dist/site/cli-registry.json", "commands", "cli", "id"],
+    ["dist/site/node-api-registry.json", "exports", "node", "export"],
+    ["dist/site/workflow-registry.json", "workflows", "workflow", "id"],
+    ["dist/site/workflow-registry.json", "actions", "action", "id"],
+  ];
+  for (const [file, collection, kind, key] of definitions) {
+    const current = readJson(root, file)[collection] || [];
+    const baseline = readJsonAtRevision(root, revision, file)[collection] || [];
+    const previousByKey = new Map(baseline.map((entry) => [entry[key], entry]));
+    for (const entry of current) {
+      const label = `${kind}:${entry[key]}`;
+      for (const field of policy.publicSurfacePolicy.requiredLifecycleFields) {
+        if (
+          !Object.prototype.hasOwnProperty.call(entry, field) ||
+          typeof entry[field] !== "string"
+        )
+          issues.push(`${label}: lifecycle field ${field} is missing`);
+      }
+      if (!capabilityGroups.has(entry.capabilityGroup))
+        issues.push(
+          `${label}: capability group ${entry.capabilityGroup || "<empty>"} is not registered`,
+        );
+      const previous = previousByKey.get(entry[key]);
+      const currentContract = publicSurfaceContract(entry, kind);
+      if (
+        previous &&
+        JSON.stringify(currentContract) !==
+          JSON.stringify(publicSurfaceContract(previous, kind))
+      ) {
+        const approval = policy.approvedPublicSurfaceTransitions?.[label];
+        const approvedContract =
+          approval?.fromRevision === revision &&
+          String(approval?.rationale || "").trim()
+            ? approval.contract
+            : null;
+        const generated = isGeneratedFacadePublicTransition({
+          entry,
+          kind,
+          migration,
+          baseContract:
+            approvedContract || publicSurfaceContract(previous, kind),
+          currentContract,
+        });
+        if (
+          !generated &&
+          (!approvedContract ||
+            JSON.stringify(approvedContract) !==
+              JSON.stringify(currentContract))
+        )
+          issues.push(
+            `${label}: existing public contract drifted from ${revision}`,
+          );
+      }
+      if (!previous && !entry.nonDuplicationRationale)
+        issues.push(
+          `${label}: new public surface requires a non-duplication rationale`,
+        );
+    }
+  }
+  return issues;
+}
+
+export { evaluatePublicSurface, publicSurfaceContract };

package/scripts/next-development-review.mjs

@@ -0,0 +1,313 @@
+import { nextPatchDevelopmentVersion } from "../packages/core/publication-development.js";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { verifyVersionStateDelta } from "./verify-version-state-delta.mjs";
+import { readBinaryPublicationEvidence } from "./binary-publication-evidence.mjs";
+import { releaseAssetClient } from "./release-asset-client.mjs";
+import { enqueueNextDevelopmentPullRequest } from "../actions/release-candidate-promote/next-development-queue.js";
+
+const REPOSITORY = "kungfu-systems/buildchain";
+const WORKFLOW = ".github/workflows/self-build-verify.yml";
+const REVIEWER = "kungfu-origin";
+const SHA = /^[a-f0-9]{40}$/u;
+const BRANCH =
+  /^chore\/next-development\/((?:0|[1-9]\d*)\.\d+\.\d+-alpha\.\d+)-[a-f0-9]{16}$/u;
+
+export function assertReviewRun(run, { repository, runId, headSha } = {}) {
+  if (
+    repository !== REPOSITORY ||
+    run.repository?.full_name !== repository ||
+    String(run.id) !== String(runId) ||
+    run.path !== WORKFLOW ||
+    run.name !== "Verify" ||
+    run.event !== "pull_request" ||
+    run.status !== "completed" ||
+    run.conclusion !== "success" ||
+    !SHA.test(run.head_sha || "") ||
+    !BRANCH.test(run.head_branch || "") ||
+    (headSha && run.head_sha !== headSha)
+  )
+    throw new Error("unqualified next-development verification run");
+}
+
+export function assertReviewPull(
+  pull,
+  { repository, headSha, baseSha, branch },
+) {
+  if (
+    repository !== REPOSITORY ||
+    pull.head?.repo?.full_name !== repository ||
+    pull.base?.repo?.full_name !== repository ||
+    pull.head?.sha !== headSha ||
+    pull.base?.sha !== baseSha ||
+    pull.head?.ref !== branch ||
+    !BRANCH.test(branch || "") ||
+    pull.base?.ref !== `dev/v${BRANCH.exec(branch)?.[1].split(".")[0]}/v${BRANCH.exec(branch)?.[1].split(".").slice(0, 2).join(".")}` ||
+    pull.state !== "open" ||
+    pull.draft ||
+    pull.merged_at ||
+    !SHA.test(baseSha || "") ||
+    !SHA.test(headSha || "") ||
+    pull.user?.login === REVIEWER
+  )
+    throw new Error(
+      "next-development review identity or protected base changed",
+    );
+}
+
+function observe(client, repository, runId, expected = {}) {
+  const prefix = `repos/${repository}`;
+  const run = client.json(`${prefix}/actions/runs/${runId}`);
+  assertReviewRun(run, { repository, runId, headSha: expected.headSha });
+  const associated = client.pages(`${prefix}/commits/${run.head_sha}/pulls`);
+  const matches = associated.filter(
+    (pull) =>
+      pull.head?.sha === run.head_sha &&
+      pull.head?.ref === run.head_branch &&
+      pull.head?.repo?.full_name === repository &&
+      pull.state === "open",
+  );
+  if (matches.length !== 1) throw new Error("ambiguous next-development PR");
+  const pull = client.json(`${prefix}/pulls/${matches[0].number}`);
+  const baseSha = client.json(`${prefix}/git/ref/heads/${pull.base.ref}`).object
+    .sha;
+  assertReviewPull(pull, {
+    repository,
+    headSha: run.head_sha,
+    baseSha,
+    branch: run.head_branch,
+  });
+  if (
+    expected.baseSha &&
+    (baseSha !== expected.baseSha || pull.number !== expected.number)
+  )
+    throw new Error("next-development review plan became stale");
+  const checks = client.pages(
+    `${prefix}/actions/runs/${runId}/jobs?filter=latest`,
+    "jobs",
+  );
+  const check = checks.filter((job) => job.name === "check");
+  if (
+    check.length !== 1 ||
+    check[0].status !== "completed" ||
+    check[0].conclusion !== "success"
+  )
+    throw new Error("exact Verify check did not succeed");
+  return { run, pull, baseSha };
+}
+
+export async function verifyNextDevelopmentReview({
+  client,
+  repository,
+  runId,
+  git,
+  verifyDelta,
+  publication,
+}) {
+  const { run, pull, baseSha } = observe(client, repository, runId);
+  if (git("rev-parse", "HEAD") !== baseSha)
+    throw new Error(
+      "review runtime is not the exact protected development base",
+    );
+  git("fetch", "--no-tags", "origin", run.head_sha);
+  const parents = git("show", "-s", "--format=%P", run.head_sha).split(" ");
+  if (parents.length !== 1 || parents[0] !== baseSha)
+    throw new Error("next-development must have one exact protected parent");
+  const version = JSON.parse(git("show", `${baseSha}:package.json`)).version;
+  const targetVersion = BRANCH.exec(run.head_branch)[1];
+  const stable = targetVersion.endsWith("-alpha.0");
+  const completedStableVersion = version.split("-alpha.")[0];
+  if (stable && nextPatchDevelopmentVersion(completedStableVersion) !== targetVersion)
+    throw new Error("development target is not the completed stable patch successor");
+  const tag = `v${stable ? completedStableVersion : version}`;
+  const sourceSha = client.json(`repos/${repository}/commits/${tag}`).sha;
+  const settlement = await publication({ repository, tag, sourceSha });
+  const publishedTree = settlement.documents.passport.source.treeHash;
+  if (!stable && publishedTree !== git("rev-parse", `${baseSha}^{tree}`))
+    throw new Error("development base is not the completed alpha source tree");
+  if (stable && (settlement.documents.passport.release?.version !== completedStableVersion || settlement.documents.invocation?.target?.channel !== "stable"))
+    throw new Error("stable publication evidence differs from the completed version");
+  const projection = verifyDelta({ baseSha, headSha: run.head_sha, ...(stable ? { completedStableVersion } : {}) });
+  if (targetVersion !== projection.version)
+    throw new Error("next-development branch version differs from regenerated version");
+  observe(client, repository, runId, {
+    headSha: run.head_sha,
+    baseSha,
+    number: pull.number,
+  });
+  return {
+    schema: "buildchain.next-development-review/v1",
+    repository,
+    runId,
+    number: pull.number,
+    headSha: run.head_sha,
+    baseSha,
+    branch: run.head_branch,
+    publicationReceiptRoot: settlement.documents.receipt.receiptRoot,
+    projection,
+  };
+}
+
+export async function approveNextDevelopment({ client, reviewer, plan }) {
+  if (plan.schema !== "buildchain.next-development-review/v1")
+    throw new Error("missing verified next-development plan");
+  const { pull } = observe(client, plan.repository, plan.runId, plan);
+  const identity = reviewer.json("user");
+  if (identity.login !== REVIEWER || identity.login === pull.user?.login)
+    throw new Error(
+      "next-development requires the independent CODEOWNER identity",
+    );
+  const endpoint = `repos/${plan.repository}/pulls/${plan.number}/reviews`;
+  const approved = (review) =>
+    review.user?.login === REVIEWER &&
+    review.commit_id === plan.headSha &&
+    review.state === "APPROVED";
+  const reviews = client.pages(endpoint);
+  const latest = reviews
+    .filter(
+      (review) =>
+        review.user?.login === REVIEWER &&
+        ["APPROVED", "CHANGES_REQUESTED", "DISMISSED"].includes(review.state),
+    )
+    .at(-1);
+  if (latest?.state === "CHANGES_REQUESTED")
+    throw new Error(
+      "independent reviewer requested changes; automation cannot override it",
+    );
+  if (!latest || !approved(latest)) {
+    observe(client, plan.repository, plan.runId, plan);
+    await reviewer.post(endpoint, {
+      event: "APPROVE",
+      commit_id: plan.headSha,
+      body: `Verified the exact version-only transition by regenerating all tracked bytes from protected base ${plan.baseSha}. Completed publication receipt: ${plan.publicationReceiptRoot}. Verification run: https://github.com/${plan.repository}/actions/runs/${plan.runId}.`,
+    });
+  }
+  observe(client, plan.repository, plan.runId, plan);
+  const readback = client.pages(endpoint).filter(approved).at(-1);
+  if (!readback)
+    throw new Error("independent exact-head approval readback failed");
+  return { ...plan, reviewId: readback.id, reviewUrl: readback.html_url };
+}
+
+function api(token) {
+  const call = (endpoint, args = [], input) =>
+    JSON.parse(
+      execFileSync("gh", ["api", endpoint, ...args], {
+        encoding: "utf8",
+        input,
+        env: { ...process.env, GH_TOKEN: token },
+        maxBuffer: 8 * 1024 * 1024,
+        stdio: ["pipe", "pipe", "pipe"],
+      }),
+    );
+  return {
+    json: (endpoint) => call(endpoint),
+    pages: (endpoint, field) =>
+      call(endpoint, ["--paginate", "--slurp"]).flatMap((page) =>
+        field ? page[field] : page,
+      ),
+    post: (endpoint, body) =>
+      call(
+        endpoint,
+        ["--method", "POST", "--input", "-"],
+        JSON.stringify(body),
+      ),
+  };
+}
+
+async function main(mode) {
+  const repository = process.env.GITHUB_REPOSITORY;
+  const runId = process.env.VERIFY_RUN_ID;
+  if (!/^\d+$/u.test(runId || "") || repository !== REPOSITORY)
+    throw new Error("exact repository and verification run required");
+  const client = api(process.env.GH_TOKEN);
+  const file = ".buildchain/next-development-review.json";
+  if (mode === "verify") {
+    if (process.env.BUILDCHAIN_APPROVAL_TOKEN)
+      throw new Error("verification must not receive the approval credential");
+    const git = (...args) =>
+      execFileSync("git", args, {
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim();
+    const plan = await verifyNextDevelopmentReview({
+      client,
+      repository,
+      runId,
+      git,
+      verifyDelta: verifyVersionStateDelta,
+      publication: (args) =>
+        readBinaryPublicationEvidence({
+          ...args,
+          client: releaseAssetClient(repository),
+          attempts: 1,
+        }),
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(plan, null, 2)}\n`);
+  } else if (mode === "approve") {
+    if (!process.env.BUILDCHAIN_APPROVAL_TOKEN)
+      throw new Error("independent approval credential missing");
+    const plan = JSON.parse(fs.readFileSync(file));
+    if (plan.repository !== repository || String(plan.runId) !== runId)
+      throw new Error("review plan is from another invocation");
+    const result = await approveNextDevelopment({
+      client,
+      plan,
+      reviewer: api(process.env.BUILDCHAIN_APPROVAL_TOKEN),
+    });
+    fs.writeFileSync(file, `${JSON.stringify(result, null, 2)}\n`);
+    console.log(
+      JSON.stringify({ reviewId: result.reviewId, headSha: result.headSha }),
+    );
+  } else if (mode === "enqueue") {
+    const plan = JSON.parse(fs.readFileSync(file));
+    if (
+      plan.repository !== repository ||
+      String(plan.runId) !== runId ||
+      !plan.reviewId
+    )
+      throw new Error(
+        "exact independent review readback required before enqueue",
+      );
+    const { pull } = observe(client, repository, runId, plan);
+    const reviews = client.pages(
+      `repos/${repository}/pulls/${plan.number}/reviews`,
+    );
+    if (
+      !reviews.some(
+        (review) =>
+          review.id === plan.reviewId &&
+          review.user?.login === REVIEWER &&
+          review.commit_id === plan.headSha &&
+          review.state === "APPROVED",
+      )
+    )
+      throw new Error("independent approval no longer qualifies enqueue");
+    await enqueueNextDevelopmentPullRequest({
+      pull,
+      headSha: plan.headSha,
+      mutationOctokit: {
+        graphql: async (query, variables) => {
+          const result = client.post("graphql", { query, variables });
+          if (result.errors?.length)
+            throw new Error(
+              result.errors.map((error) => error.message).join("; "),
+            );
+          return result.data;
+        },
+      },
+      wait: (delay) => new Promise((resolve) => setTimeout(resolve, delay)),
+      maxPolls: 20,
+    });
+  } else throw new Error("expected verify, approve or enqueue");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  main(process.argv[2]).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/scripts/oci-compose-preview.mjs

@@ -0,0 +1,261 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { verifyPublicationSettlement } from "./publication-settlement.mjs";
+import {
+  verifyComposePublication,
+  verifyComposeQualification,
+} from "../packages/core/oci-compose-qualification.js";
+import { releaseTailRoot } from "../packages/core/release-tail-provider-plane.js";
+import { createRegistryClient } from "../actions/release-candidate-promote/oci-registry-client.js";
+import { ociPublicationTag } from "../packages/core/oci-publication-graph.js";
+
+const digest = (bytes) =>
+  `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+function check(condition, message) {
+  if (!condition) throw new Error(`Compose preview: ${message}`);
+}
+function gh(args) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+const api = (route) => JSON.parse(gh(["api", route]));
+const read = (file) => JSON.parse(fs.readFileSync(file));
+export function createComposePreviewRegistry(environment, fetchImpl = fetch) {
+  const token = environment.BUILDCHAIN_REGISTRY_TOKEN;
+  const actor = environment.GITHUB_ACTOR;
+  check(
+    typeof token === "string" &&
+      token.length > 0 &&
+      typeof actor === "string" &&
+      actor.length > 0,
+    "explicit scoped registry identity required",
+  );
+  return createRegistryClient(token, fetchImpl, actor);
+}
+function output(name, value) {
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+}
+
+export async function promoteComposePreview({
+  context,
+  registry,
+  receipt,
+  fetchManifest,
+}) {
+  const { application, policy } = context;
+  const exact = await fetchManifest(
+    ociPublicationTag(application, context.tag.slice(1)),
+  );
+  check(
+    exact.digest === application.digest,
+    "immutable application digest changed",
+  );
+  const current = await fetchManifest(policy.alias, true);
+  check(
+    current.digest === policy.previousDigest ||
+      current.digest === application.digest,
+    "preview changed since qualification",
+  );
+  const plan = {
+    schema: "kungfu-buildchain-compose-preview-plan/v1",
+    ...context,
+    qualificationRoot: releaseTailRoot(receipt),
+    expectedOld: policy.previousDigest,
+    targetDigest: application.digest,
+    operation: "digest-preserving-preview-promotion",
+  };
+  if (current.digest !== application.digest) {
+    const result = await registry(application, `manifests/${policy.alias}`, {
+      write: true,
+      method: "PUT",
+      body: exact.bytes,
+      headers: {
+        "content-type": exact.mediaType,
+        "content-length": String(exact.bytes.length),
+      },
+    });
+    check(
+      result.status === 201,
+      `preview write uncertain (HTTP ${result.status}); retain the original qualification for readback`,
+    );
+  }
+  const observed = await fetchManifest(policy.alias);
+  check(observed.digest === application.digest, "preview readback mismatch");
+  const body = {
+    schema: "kungfu-buildchain-compose-preview-receipt/v1",
+    repository: context.repository,
+    tag: context.tag,
+    sourceSha: context.sourceSha,
+    publicationReceiptRoot: context.publicationReceiptRoot,
+    planRoot: releaseTailRoot(plan),
+    qualificationRoot: plan.qualificationRoot,
+    previousDigest: policy.previousDigest,
+    application: `${application.repository}@${application.digest}`,
+    alias: `${application.repository}:${policy.alias}`,
+    observedDigest: observed.digest,
+    outcome: "complete",
+  };
+  return { ...body, receiptRoot: releaseTailRoot(body) };
+}
+
+async function run(mode) {
+  const repository = process.env.GITHUB_REPOSITORY,
+    event = read(process.env.GITHUB_EVENT_PATH);
+  check(
+    process.env.GITHUB_EVENT_NAME === "workflow_run" && event.workflow_run?.id,
+    "requires a completed qualification workflow event",
+  );
+  check(
+    /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/u.test(repository),
+    "invalid repository",
+  );
+  const id = String(event.workflow_run.id);
+  check(/^\d+$/u.test(id), "invalid qualification run");
+  const run = api(`repos/${repository}/actions/runs/${id}`),
+    tag = run.head_branch;
+  check(
+    /^v\d+\.\d+\.\d+-alpha\.\d+$/u.test(tag),
+    "qualification must run on an exact alpha tag",
+  );
+  const release = api(`repos/${repository}/releases/tags/${tag}`);
+  check(release.prerelease && !release.draft, "public alpha release required");
+  const root = path.resolve(".buildchain/compose-preview");
+  fs.mkdirSync(path.join(root, "public"), { recursive: true });
+  const names = [
+    "oci-family.json",
+    "oci-publication-readback.json",
+    "buildchain-publication-settlement.json",
+    "buildchain.release.json",
+  ];
+  for (const name of names) {
+    check(
+      release.assets.filter((asset) => asset.name === name).length === 1,
+      `missing exact public asset ${name}`,
+    );
+    gh([
+      "release",
+      "download",
+      tag,
+      "--repo",
+      repository,
+      "--pattern",
+      name,
+      "--dir",
+      path.join(root, "public"),
+      "--clobber",
+    ]);
+  }
+  const [family, readback, settlement, publicPassport] = names.map((name) =>
+    read(path.join(root, "public", name)),
+  );
+  const documents = settlement.documents;
+  const tagged = api(`repos/${repository}/commits/${tag}`).sha;
+  verifyPublicationSettlement(documents, {
+    repository,
+    tag,
+    sourceSha: tagged,
+    publicPassport,
+  });
+  const context = verifyComposePublication({
+    family,
+    readback,
+    documents,
+    repository,
+    tag,
+  });
+  verifyComposeQualification(context, run);
+  const artifactName = `oci-compose-qualification-${id}-${run.run_attempt}`;
+  const artifacts = api(
+    `repos/${repository}/actions/runs/${id}/artifacts?per_page=100`,
+  ).artifacts.filter(
+    (artifact) => artifact.name === artifactName && !artifact.expired,
+  );
+  check(
+    artifacts.length === 1,
+    "qualification artifact is missing or ambiguous",
+  );
+  if (mode === "prepare") {
+    output("artifact-id", artifacts[0].id);
+    output("run-id", id);
+    output("source-sha", tagged);
+    return;
+  }
+  check(mode === "apply", "unsupported mode");
+  const evidenceRoot = path.join(root, "qualification");
+  const receipt = read(path.join(evidenceRoot, "qualification.json"));
+  verifyComposeQualification(context, run, receipt);
+  for (const item of receipt.evidence) {
+    const file = path.join(evidenceRoot, item.path);
+    check(
+      !fs.lstatSync(file).isSymbolicLink() &&
+        fs.statSync(file).size < 2_000_000 &&
+        digest(fs.readFileSync(file)) === item.sha256,
+      "qualification evidence bytes mismatch",
+    );
+  }
+  const { registry } = createComposePreviewRegistry(process.env);
+  async function fetchManifest(ref, allowAbsent = false) {
+    const response = await registry(context.application, `manifests/${ref}`, {
+      headers: {
+        accept:
+          "application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json",
+      },
+    });
+    if (allowAbsent && response.status === 404) return { digest: "none" };
+    check(response.ok, "public registry readback unavailable");
+    const bytes = Buffer.from(await response.arrayBuffer()),
+      value = digest(bytes);
+    check(
+      !response.headers.get("docker-content-digest") ||
+        response.headers.get("docker-content-digest") === value,
+      "registry digest mismatch",
+    );
+    return { bytes, digest: value, mediaType: JSON.parse(bytes).mediaType };
+  }
+  const result = await promoteComposePreview({
+    context,
+    registry,
+    receipt,
+    fetchManifest,
+  });
+  const file = path.join(
+    root,
+    `buildchain-compose-preview-${id}-${run.run_attempt}.json`,
+  );
+  fs.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+  const existing = release.assets.find(
+    (asset) => asset.name === path.basename(file),
+  );
+  if (existing) {
+    const previous = path.join(root, "previous");
+    fs.mkdirSync(previous, { recursive: true });
+    gh([
+      "release",
+      "download",
+      tag,
+      "--repo",
+      repository,
+      "--pattern",
+      path.basename(file),
+      "--dir",
+      previous,
+      "--clobber",
+    ]);
+    check(
+      fs.readFileSync(path.join(previous, path.basename(file)), "utf8") ===
+        fs.readFileSync(file, "utf8"),
+      "existing preview receipt conflict",
+    );
+  } else gh(["release", "upload", tag, file, "--repo", repository]);
+  process.stdout.write(`Verified ${result.alias}@${result.observedDigest}\n`);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  run(process.argv[2]).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });

package/scripts/paper-work-fleet-cli.mjs

@@ -418,6 +418,8 @@ function runMigration(options) {
       options.buildchainVersion,
     ),
     buildchainSha: options.buildchainSha,
+    stableBuildchainRoot: readFlag(options.args, "stable-buildchain-root", ""),
+    alphaBuildchainRoot: readFlag(options.args, "alpha-buildchain-root", ""),
   });
   return options.args.some((entry) => ["--write", "--execute"].includes(entry))
     ? writePaperMigration(plan)