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

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

@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  runNextDevelopmentController,
+  validateNextDevelopmentController,
+} from "../packages/core/next-development-controller.js";
+import {
+  NEXT_DEVELOPMENT_TRANSITION_CONTRACT,
+  nextDevelopmentRoot,
+} from "../packages/core/next-development-transition.js";
+import {
+  DurableStore,
+  HOSTED_READBACK_PATHS,
+  PROTECTED_DEV_BRANCH,
+  RECORDED_AT,
+  VersionStateAdapterHarness,
+  adapterTransition,
+  anchorInput,
+  exactRoot,
+  exactSha,
+  fixtureSha,
+  repository,
+  required,
+  validateAdapterEvidence,
+  validateAdapterOperation,
+  validateRecoveryEvidence,
+  validateSelfDogfoodRoute,
+} from "./next-development-self-dogfood-harness.mjs";
+
+export const NEXT_DEVELOPMENT_SELF_DOGFOOD_CHECKPOINT =
+  "kungfu-buildchain-next-development-self-dogfood-checkpoint/v1";
+export const NEXT_DEVELOPMENT_SELF_DOGFOOD_EVIDENCE =
+  "kungfu-buildchain-next-development-self-dogfood/v1";
+export const HOSTED_SELF_DOGFOOD_EVIDENCE =
+  "kungfu-buildchain-alpha-self-dogfood";
+
+function checkpointBody(checkpoint) {
+  const body = structuredClone(checkpoint);
+  delete body.checkpointRoot;
+  return body;
+}
+
+function evidenceBody(evidence) {
+  const body = structuredClone(evidence);
+  delete body.evidenceRoot;
+  return body;
+}
+
+export function validateSelfDogfoodCheckpoint(checkpoint) {
+  if (checkpoint?.contract !== NEXT_DEVELOPMENT_SELF_DOGFOOD_CHECKPOINT) {
+    throw new Error(
+      "next-development self-dogfood checkpoint contract mismatch",
+    );
+  }
+  const runtimeSha = exactSha(checkpoint.route?.runtimeSha, "route.runtimeSha");
+  exactRoot(checkpoint.route?.contractRoot, "route.contractRoot");
+  const targetRepository = repository(
+    checkpoint.route?.repository,
+    "route.repository",
+  );
+  if (
+    checkpoint.route.runtimeRef !== "v4-alpha" ||
+    checkpoint.route.publicWorkflow !==
+      `${targetRepository}/.github/workflows/build.yml@v4-alpha` ||
+    targetRepository !== "kungfu-systems/buildchain"
+  ) {
+    throw new Error("checkpoint requires the public owner/repo v4-alpha route");
+  }
+  if (runtimeSha !== checkpoint.route.runtimeSha) {
+    throw new Error("checkpoint runtime SHA is not canonical");
+  }
+  required(checkpoint.faultRunnerId, "faultRunnerId");
+  const semver = validateNextDevelopmentController(
+    checkpoint.semver.controller,
+  );
+  const anchored = validateNextDevelopmentController(
+    checkpoint.anchored.controller,
+  );
+  if (
+    semver.transition.state.status !== "planned" ||
+    semver.activeAttempt !== null ||
+    checkpoint.semver.materializations !== 1 ||
+    checkpoint.semver.adapterOperations?.length !== 1 ||
+    checkpoint.semver.durableStateFailures !== 1
+  ) {
+    throw new Error(
+      "semver checkpoint must prove one transient durable-state failure",
+    );
+  }
+  checkpoint.semver.adapterOperations.forEach(validateAdapterOperation);
+  if (
+    anchored.transition.state.status !== "waiting-anchor" ||
+    anchored.transition.target.version !== null ||
+    checkpoint.anchored.materializations !== 0
+  ) {
+    throw new Error("anchored checkpoint must persist manual waiting");
+  }
+  if (checkpoint.alphaCandidateRebuilds !== 0) {
+    throw new Error("post-Alpha proof must not rebuild the Alpha candidate");
+  }
+  if (
+    checkpoint.checkpointRoot !==
+    nextDevelopmentRoot(checkpointBody(checkpoint))
+  ) {
+    throw new Error("next-development self-dogfood checkpoint root drifted");
+  }
+  return structuredClone(checkpoint);
+}
+
+export async function createSelfDogfoodCheckpoint({
+  repository: targetRepository,
+  runtimeRef,
+  runtimeSha,
+  contractRoot,
+  runnerId,
+} = {}) {
+  const routeRepository = repository(targetRepository);
+  const route = {
+    repository: routeRepository,
+    publicWorkflow: `${routeRepository}/.github/workflows/build.yml@v4-alpha`,
+    runtimeRef: required(runtimeRef, "runtimeRef"),
+    runtimeSha: exactSha(runtimeSha, "runtimeSha"),
+    contractRoot: exactRoot(contractRoot, "contractRoot"),
+    protectedDevBranch: PROTECTED_DEV_BRANCH,
+    hostedReadbackPaths: HOSTED_READBACK_PATHS,
+  };
+  if (
+    route.repository !== "kungfu-systems/buildchain" ||
+    route.runtimeRef !== "v4-alpha"
+  ) {
+    throw new Error(
+      "self-dogfood checkpoint requires the public kungfu-systems/buildchain v4-alpha route",
+    );
+  }
+
+  const semverStore = new DurableStore([], { transientFailures: 1 });
+  const semverExecutor = new VersionStateAdapterHarness({ route });
+  await runNextDevelopmentController(
+    {
+      transition: adapterTransition(route, "semver"),
+      protectedDevBranch: PROTECTED_DEV_BRANCH,
+      recordedAt: RECORDED_AT,
+    },
+    { store: semverStore, executor: semverExecutor },
+  ).then(
+    () => {
+      throw new Error("transient durable-state fault injection did not run");
+    },
+    (error) => {
+      if (
+        !/injected transient durable-state write failure/u.test(error.message)
+      ) {
+        throw error;
+      }
+    },
+  );
+
+  const anchoredStore = new DurableStore();
+  const anchoredExecutor = new VersionStateAdapterHarness({ route });
+  await runNextDevelopmentController(
+    {
+      transition: adapterTransition(route, "anchored"),
+      protectedDevBranch: PROTECTED_DEV_BRANCH,
+      recordedAt: RECORDED_AT,
+    },
+    { store: anchoredStore, executor: anchoredExecutor },
+  );
+
+  const checkpoint = {
+    schemaVersion: 1,
+    contract: NEXT_DEVELOPMENT_SELF_DOGFOOD_CHECKPOINT,
+    route,
+    faultRunnerId: required(runnerId, "runnerId"),
+    alphaCandidateRebuilds: 0,
+    semver: {
+      controller: semverStore.only(),
+      materializations: semverExecutor.materializations,
+      adapterOperations: semverExecutor.operationRecords(),
+      durableStateFailures: semverStore.transientFailures,
+    },
+    anchored: {
+      controller: anchoredStore.only(),
+      materializations: anchoredExecutor.materializations,
+    },
+  };
+  checkpoint.checkpointRoot = nextDevelopmentRoot(checkpoint);
+  return validateSelfDogfoodCheckpoint(checkpoint);
+}
+
+function assertVerifiedModel(model, label) {
+  const controller = validateNextDevelopmentController(model?.controller);
+  if (
+    model.status !== "verified" ||
+    controller.transition.state.status !== "verified" ||
+    model.controllerRoot !== controller.controllerRoot ||
+    model.readbackRoot !== nextDevelopmentRoot(controller.readback)
+  ) {
+    throw new Error(
+      `${label} does not bind its verified controller and readback`,
+    );
+  }
+  return controller;
+}
+
+export function validateSelfDogfoodEvidence(evidence) {
+  if (evidence?.contract !== NEXT_DEVELOPMENT_SELF_DOGFOOD_EVIDENCE) {
+    throw new Error("next-development self-dogfood evidence contract mismatch");
+  }
+  exactRoot(evidence.checkpointRoot, "checkpointRoot");
+  exactRoot(evidence.transactionRoot, "transactionRoot");
+  exactRoot(evidence.protectedDevReadbackRoot, "protectedDevReadbackRoot");
+  validateSelfDogfoodRoute(evidence.route);
+  const semver = assertVerifiedModel(
+    evidence.models?.semverAuto,
+    "semver/auto",
+  );
+  const anchored = assertVerifiedModel(
+    evidence.models?.anchoredManual,
+    "anchored/manual",
+  );
+  if (evidence.status !== "passed")
+    throw new Error("self-dogfood evidence did not pass");
+  validateRecoveryEvidence(evidence.recovery);
+  if (
+    semver.controllerRoot !== evidence.transactionRoot ||
+    nextDevelopmentRoot(semver.readback) !==
+      evidence.protectedDevReadbackRoot ||
+    evidence.models.anchoredManual.waitingStatus !== "waiting-anchor" ||
+    evidence.models.anchoredManual.waitingControllerRoot ===
+      anchored.controllerRoot
+  ) {
+    throw new Error("both legal next-development models must be proved");
+  }
+  validateAdapterEvidence(evidence.adapter, semver, anchored);
+  if (
+    evidence.adoption?.coordinate !==
+      "kungfu-systems/buildchain/.github/workflows/build.yml@v4" ||
+    evidence.adoption?.exactShaProductionPin !== false
+  ) {
+    throw new Error("Kungfu adoption must use the floating v4 coordinate");
+  }
+  if (evidence.evidenceRoot !== nextDevelopmentRoot(evidenceBody(evidence))) {
+    throw new Error("next-development self-dogfood evidence root drifted");
+  }
+  return structuredClone(evidence);
+}
+
+export async function resumeSelfDogfoodCheckpoint(
+  checkpointInput,
+  { runnerId } = {},
+) {
+  const checkpoint = validateSelfDogfoodCheckpoint(checkpointInput);
+  const resumeRunnerId = required(runnerId, "runnerId");
+  if (resumeRunnerId === checkpoint.faultRunnerId) {
+    throw new Error("post-Alpha recovery must run on a fresh runner identity");
+  }
+
+  const initialDevSha = fixtureSha("protected-dev:initial");
+  const movedDevSha = fixtureSha("protected-dev:moved-during-recovery");
+  const semverStore = new DurableStore([checkpoint.semver.controller]);
+  const semverExecutor = new VersionStateAdapterHarness({
+    route: checkpoint.route,
+    operations: checkpoint.semver.adapterOperations,
+    devSha: initialDevSha,
+    movedDevSha,
+    moveAfterRecoveredOperation: true,
+    pullRequestReadsBeforeMerge: 2,
+  });
+  const input = {
+    transition: adapterTransition(checkpoint.route, "semver"),
+    protectedDevBranch: PROTECTED_DEV_BRANCH,
+    recordedAt: RECORDED_AT,
+  };
+  const superseded = await runNextDevelopmentController(input, {
+    store: semverStore,
+    executor: semverExecutor,
+  });
+  const pending = await runNextDevelopmentController(input, {
+    store: semverStore,
+    executor: semverExecutor,
+  });
+  const delayed = await runNextDevelopmentController(input, {
+    store: semverStore,
+    executor: semverExecutor,
+  });
+  const semver = await runNextDevelopmentController(input, {
+    store: semverStore,
+    executor: semverExecutor,
+  });
+
+  const anchoredStore = new DurableStore([checkpoint.anchored.controller]);
+  const anchoredExecutor = new VersionStateAdapterHarness({
+    route: checkpoint.route,
+  });
+  const anchored = await runNextDevelopmentController(
+    {
+      transition: adapterTransition(checkpoint.route, "anchored"),
+      protectedDevBranch: PROTECTED_DEV_BRANCH,
+      reviewedInput: anchorInput(),
+      recordedAt: RECORDED_AT,
+    },
+    { store: anchoredStore, executor: anchoredExecutor },
+  );
+
+  const semverReadbackRoot = nextDevelopmentRoot(semver.readback);
+  const anchoredReadbackRoot = nextDevelopmentRoot(anchored.readback);
+  const evidence = {
+    schemaVersion: 1,
+    contract: NEXT_DEVELOPMENT_SELF_DOGFOOD_EVIDENCE,
+    status: "passed",
+    route: checkpoint.route,
+    checkpointRoot: checkpoint.checkpointRoot,
+    transactionRoot: semver.controllerRoot,
+    protectedDevReadbackRoot: semverReadbackRoot,
+    recovery: {
+      faultRunnerId: checkpoint.faultRunnerId,
+      resumeRunnerId,
+      freshRunner: true,
+      transientDurableStateFailures: checkpoint.semver.durableStateFailures,
+      recoveredAdapterOperations: semverExecutor.recoveredOperations,
+      alphaCandidateRebuilds: 0,
+      devMaterializationsBefore: checkpoint.semver.materializations,
+      devMaterializationsAfter: semverExecutor.materializations,
+      protectedDevMovement: {
+        initialSha: initialDevSha,
+        movedSha: movedDevSha,
+        supersededAttempts: superseded.attempts.filter(
+          (attempt) => attempt.status === "superseded",
+        ).length,
+      },
+      protectedPrDelay: {
+        status: pending.transition.state.status,
+        delayedStatus: delayed.transition.state.status,
+        unchangedControllerRoot:
+          pending.controllerRoot === delayed.controllerRoot,
+      },
+    },
+    adapter: {
+      boundary: "materializeNextDevelopmentTransition",
+      contract: NEXT_DEVELOPMENT_TRANSITION_CONTRACT,
+      operations: [
+        ...semverExecutor.operationRecords(),
+        ...anchoredExecutor.operationRecords(),
+      ],
+    },
+    models: {
+      semverAuto: {
+        status: semver.transition.state.status,
+        targetVersion: semver.transition.target.version,
+        controllerRoot: semver.controllerRoot,
+        readbackRoot: semverReadbackRoot,
+        controller: semver,
+      },
+      anchoredManual: {
+        waitingStatus: checkpoint.anchored.controller.transition.state.status,
+        waitingControllerRoot: checkpoint.anchored.controller.controllerRoot,
+        status: anchored.transition.state.status,
+        targetVersion: anchored.transition.target.version,
+        controllerRoot: anchored.controllerRoot,
+        readbackRoot: anchoredReadbackRoot,
+        controller: anchored,
+      },
+    },
+    adoption: {
+      coordinate: "kungfu-systems/buildchain/.github/workflows/build.yml@v4",
+      runtimeRef: "v4",
+      exactShaProductionPin: false,
+    },
+  };
+  evidence.evidenceRoot = nextDevelopmentRoot(evidence);
+  return validateSelfDogfoodEvidence(evidence);
+}
+
+function normalizeHostedReadback(value, route) {
+  const paths = (value?.versionRoots || [])
+    .map((entry, index) => ({
+      path: required(entry?.path, `hosted versionRoots[${index}].path`),
+      gitBlobSha: exactSha(
+        entry?.gitBlobSha,
+        `hosted versionRoots[${index}].gitBlobSha`,
+      ),
+    }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  if (
+    JSON.stringify(paths.map((entry) => entry.path)) !==
+    JSON.stringify(route.hostedReadbackPaths)
+  ) {
+    throw new Error(
+      "hosted protected Dev readback must exactly cover declared paths",
+    );
+  }
+  const body = {
+    repository: repository(value?.repository, "hosted readback repository"),
+    branch: required(value?.branch, "hosted readback branch"),
+    commitSha: exactSha(value?.commitSha, "hosted readback commitSha"),
+    treeSha: exactSha(value?.treeSha, "hosted readback treeSha"),
+    versionRoots: paths,
+  };
+  if (
+    body.repository !== route.repository ||
+    body.branch !== route.protectedDevBranch
+  ) {
+    throw new Error("hosted protected Dev readback route drifted");
+  }
+  return { ...body, evidenceRoot: nextDevelopmentRoot(body) };
+}
+
+export function createHostedSelfDogfoodEvidence({
+  nextDevelopment,
+  observation,
+} = {}) {
+  const proof = validateSelfDogfoodEvidence(nextDevelopment);
+  const hostedProtectedDevReadback = normalizeHostedReadback(
+    observation?.protectedDevReadback,
+    proof.route,
+  );
+  const observed = structuredClone(observation?.observed || {});
+  const failures = [];
+  if (observed.alpha?.ref !== "v4-alpha")
+    failures.push("alpha runtime ref mismatch");
+  if (observed.alpha?.class !== "alpha")
+    failures.push("alpha runtime class mismatch");
+  if (observed.alpha?.sha !== observed.alpha?.expectedSha)
+    failures.push("alpha runtime SHA mismatch");
+  if (observed.alpha?.sha !== proof.route.runtimeSha)
+    failures.push("next-development runtime SHA mismatch");
+  if (observed.stable?.ref !== "v4")
+    failures.push("stable runtime ref mismatch");
+  if (observed.stable?.class !== "stable")
+    failures.push("stable runtime class mismatch");
+  if (observed.stable?.sha !== observed.stable?.expectedSha)
+    failures.push("stable runtime SHA mismatch");
+  for (const [lane, item] of Object.entries(observed)) {
+    exactSha(item?.sha, `observed ${lane} SHA`);
+    exactSha(item?.expectedSha, `expected ${lane} SHA`);
+  }
+  const evidence = {
+    schemaVersion: 1,
+    contract: HOSTED_SELF_DOGFOOD_EVIDENCE,
+    repository: repository(observation?.repository),
+    callerSha: exactSha(observation?.callerSha, "callerSha"),
+    checkedAt: required(observation?.checkedAt, "checkedAt"),
+    status: failures.length === 0 ? "passed" : "failed",
+    observed,
+    nextDevelopment: proof,
+    hostedProtectedDevReadback,
+    failures,
+  };
+  if (evidence.repository !== proof.route.repository) {
+    throw new Error("hosted evidence repository differs from the public route");
+  }
+  evidence.evidenceRoot = nextDevelopmentRoot(evidence);
+  return evidence;
+}
+
+export function validateHostedSelfDogfoodEvidence(evidence) {
+  if (evidence?.contract !== HOSTED_SELF_DOGFOOD_EVIDENCE) {
+    throw new Error("hosted self-dogfood evidence contract mismatch");
+  }
+  const proof = validateSelfDogfoodEvidence(evidence.nextDevelopment);
+  repository(evidence.repository);
+  exactSha(evidence.callerSha, "callerSha");
+  required(evidence.checkedAt, "checkedAt");
+  for (const [lane, item] of Object.entries(evidence.observed || {})) {
+    exactSha(item?.sha, `observed ${lane} SHA`);
+    exactSha(item?.expectedSha, `expected ${lane} SHA`);
+  }
+  const readback = normalizeHostedReadback(
+    evidence.hostedProtectedDevReadback,
+    proof.route,
+  );
+  if (
+    readback.evidenceRoot !==
+      evidence.hostedProtectedDevReadback?.evidenceRoot ||
+    evidence.evidenceRoot !== nextDevelopmentRoot(evidenceBody(evidence))
+  ) {
+    throw new Error("hosted self-dogfood evidence root drifted");
+  }
+  if (
+    evidence.status !== "passed" ||
+    evidence.failures?.length !== 0 ||
+    evidence.repository !== proof.route.repository ||
+    evidence.observed?.alpha?.ref !== "v4-alpha" ||
+    evidence.observed?.alpha?.class !== "alpha" ||
+    evidence.observed?.alpha?.sha !== evidence.observed?.alpha?.expectedSha ||
+    evidence.observed?.alpha?.sha !== proof.route.runtimeSha ||
+    evidence.observed?.stable?.ref !== "v4" ||
+    evidence.observed?.stable?.class !== "stable" ||
+    evidence.observed?.stable?.sha !== evidence.observed?.stable?.expectedSha
+  ) {
+    throw new Error(
+      "hosted self-dogfood evidence is not a passing exact readback",
+    );
+  }
+  return structuredClone(evidence);
+}
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index];
+    if (!name.startsWith("--") || index + 1 >= argv.length) {
+      throw new Error(`invalid argument: ${name}`);
+    }
+    options[
+      name.slice(2).replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase())
+    ] = argv[index + 1];
+    index += 1;
+  }
+  return options;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(path.resolve(filePath), "utf8"));
+}
+
+function writeJson(filePath, value) {
+  const output = path.resolve(filePath);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeActionsOutputs(value) {
+  const output = process.env.GITHUB_OUTPUT;
+  if (!output) return;
+  fs.appendFileSync(
+    output,
+    [
+      `transaction-root=${value.transactionRoot || value.nextDevelopment?.transactionRoot || ""}`,
+      `protected-dev-readback-root=${value.protectedDevReadbackRoot || value.hostedProtectedDevReadback?.evidenceRoot || ""}`,
+      `evidence-root=${value.evidenceRoot || value.checkpointRoot || ""}`,
+    ].join("\n") + "\n",
+  );
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const command = argv.shift();
+  const options = parseArgs(argv);
+  if (command === "checkpoint") {
+    const checkpoint = await createSelfDogfoodCheckpoint({
+      repository: options.repository,
+      runtimeRef: options.runtimeRef,
+      runtimeSha: options.runtimeSha,
+      contractRoot: options.contractRoot,
+      runnerId: options.runnerId,
+    });
+    writeJson(required(options.output, "output"), checkpoint);
+    writeActionsOutputs(checkpoint);
+    return checkpoint;
+  }
+  if (command === "resume") {
+    const evidence = await resumeSelfDogfoodCheckpoint(
+      readJson(required(options.input, "input")),
+      { runnerId: options.runnerId },
+    );
+    writeJson(required(options.output, "output"), evidence);
+    writeActionsOutputs(evidence);
+    return evidence;
+  }
+  if (command === "attest-hosted") {
+    const evidence = createHostedSelfDogfoodEvidence({
+      nextDevelopment: readJson(required(options.input, "input")),
+      observation: readJson(required(options.observation, "observation")),
+    });
+    writeJson(required(options.output, "output"), evidence);
+    writeActionsOutputs(evidence);
+    return evidence;
+  }
+  if (command === "verify") {
+    return validateSelfDogfoodEvidence(
+      readJson(required(options.input, "input")),
+    );
+  }
+  if (command === "verify-hosted") {
+    return validateHostedSelfDogfoodEvidence(
+      readJson(required(options.input, "input")),
+    );
+  }
+  throw new Error(
+    "usage: next-development-self-dogfood.mjs checkpoint|resume|attest-hosted|verify|verify-hosted ...",
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    process.stderr.write(`next-development self-dogfood: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/next-development-transition.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { materializeNextDevelopmentTransition } from "../packages/core/next-development-transition.js";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : String(args[index + 1] || "");
+}
+
+function usage() {
+  return `usage: node scripts/next-development-transition.mjs materialize --input <request.json> [--cwd <checkout>] [--write]\n`;
+}
+
+export function runNextDevelopmentAdapter(args = process.argv.slice(2)) {
+  const [command] = args;
+  if (command !== "materialize") throw new Error(usage().trim());
+  const inputPath = flag(args, "input");
+  if (!inputPath)
+    throw new Error(
+      "next-development materialize requires --input <request.json>",
+    );
+  const cwd = path.resolve(flag(args, "cwd", process.cwd()));
+  const request = JSON.parse(fs.readFileSync(path.resolve(inputPath), "utf8"));
+  return materializeNextDevelopmentTransition({
+    cwd,
+    request,
+    write: args.includes("--write"),
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    process.stdout.write(
+      `${JSON.stringify(runNextDevelopmentAdapter(), null, 2)}\n`,
+    );
+  } catch (error) {
+    process.stderr.write(`next-development transition: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/site-capability-metadata.mjs

@@ -39,6 +39,10 @@ export function cliCommandMeta(id) {
     "explain-artifact": { group: "release-passport-trust", purpose: "Explain artifact evidence for humans or agents." },
     "explain-release": { group: "release-passport-trust", purpose: "Explain a release passport for humans or agents." },
     facts: { group: "observability-diagnostics", purpose: "Inspect build facts command families." },
+    "facts-compatibility-project": { group: "governance-versioning", purpose: "Project legacy digest and proof views from the current Cut-bound compatibility Fact registry." },
+    "facts-compatibility-query": { group: "governance-versioning", purpose: "Verify one explicit directional compatibility path and emit a rooted receipt." },
+    "facts-compatibility-query-template": { group: "governance-versioning", purpose: "Create a direct query template for one current compatibility Fact." },
+    "facts-compatibility-verify": { group: "governance-versioning", purpose: "Verify the exact append-only compatibility Fact registry and current Cut." },
     help: { group: "getting-started", purpose: "Print Buildchain CLI help." },
     homebrew: { group: "distribution-indexes", purpose: "Inspect Homebrew distribution-index command families." },
     "homebrew-check": { group: "distribution-indexes", purpose: "Verify Homebrew tap metadata against upstream release passport evidence." },
@@ -139,6 +143,7 @@ export function cliCommandMeta(id) {
     "paper-status": { group: "reusable-build", purpose: "Report explicit evidence for every paper lifecycle state without unsupported inference." },
     "paper-work-start": { group: "getting-started", purpose: "Create a safe Paper work branch from the exact canonical remote development SHA." },
     "paper-work-submit": { group: "governance-versioning", purpose: "Push a Paper work branch without force and open or reuse the correctly targeted development PR." },
+    "next-development": { group: "governance-versioning", purpose: "Plan or apply one rooted declared-path next-development version transition without release or ref authority." },
     "publish-source": { group: "release-passport-trust", purpose: "Create, inspect, or verify publish-gate source-lock refs." },
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
@@ -151,6 +156,7 @@ export function cliCommandMeta(id) {
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
     "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
     "release-tail": { group: "release-passport-trust", purpose: "Plan, initialize, resume, and verify one declarative provider-owned release-tail transaction." },
+    "tail-reseal": { group: "release-passport-trust", purpose: "Plan, admit, byte-verify, and seal one exact retained v4 Alpha candidate signing-finalization tail." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
@@ -215,8 +221,13 @@ export function nodeApiMeta(exportName) {
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./v4-floating-consumer-policy": { group: "governance-versioning", summary: "Semantic floating-selector admission, dual-lock receipt, and independent v4 consumer certification APIs." },
     "./v4-runtime-ref-resume-authority": { group: "release-passport-trust", summary: "Transient exact-runtime authorization, persisted-selector rejection, fresh-attempt Stage Capsule reuse, and A+B Passport lineage APIs." },
+    "./v4-tail-reseal": { group: "release-passport-trust", summary: "Effect-pure retained Stage Capsule validation and explicit Warrant-, credential-, and release-tail-fenced macOS reseal planning APIs." },
+    "./v4-tail-reseal-receipt": { group: "release-passport-trust", summary: "Four-platform byte readback, standard candidate Passport binding, and terminal v4 tail-reseal receipt APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
     "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility APIs." },
+    "./next-development-transition": { group: "governance-versioning", summary: "Provider-neutral completed-Alpha preservation and rooted next-development state, version-model, idempotency, and local materialization APIs." },
+    "./next-development-controller": { group: "governance-versioning", summary: "Durable completed-Alpha child scheduling, fresh-runner checkpoint resume, latest protected-Dev reconciliation, and exact version-root readback APIs." },
+    "./next-development-projection": { group: "governance-versioning", summary: "Canonical generated config, Agent, workflow-header, and manual projections for the next-development transition contract." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
@@ -225,6 +236,7 @@ export function nodeApiMeta(exportName) {
     "./release-tail-compatibility": { group: "release-passport-trust", summary: "Bounded v3 release-hook compatibility diagnostics that reject new executable release-tail inputs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
+    "./compatibility-fact-authority": { group: "governance-versioning", summary: "Directional Cut-bound compatibility Fact, lifecycle, explicit path receipt, legacy projection, and Release Passport evidence APIs." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },