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

package/packages/core/paper.js

@@ -35,6 +35,7 @@ import {
   PAPER_AGENT_ENTRY_CONTRACT,
   collectPaperAgentEntry,
   paperAgentEntryFiles,
+  resolvePaperBuildchainSha,
 } from "./paper-agent-entry.js";
 import {
   managedPaperPackageJson,
@@ -44,6 +45,7 @@ import {
   scaffoldPackageJson,
   scaffoldReadme,
 } from "./paper-scaffold-content.js";
+import { executePaperNpmBootstrap as executePaperNpmBootstrapOperation } from "./paper-npm-bootstrap.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
 export {
@@ -72,6 +74,7 @@ export {
   collectPaperFleetAudit,
   discoverPaperFleet,
   planPaperFleetUpdate,
+  paperFleetTransitionWorkspace,
   writePaperFleetUpdate,
 } from "./paper-fleet.js";
 
@@ -111,6 +114,7 @@ const PAPER_SCAFFOLD_PATHS = Object.freeze([
   PAPER_PATHS.buildWorkflow,
   PAPER_PATHS.verifyWorkflow,
   PAPER_PATHS.releaseWorkflow,
+  PAPER_PATHS.pnpmWorkspace,
   PAPER_PATHS.provisioningAuthority,
   "Makefile",
   "package.json",
@@ -132,6 +136,7 @@ const DEFAULT_TOOLCHAIN_COMMAND = "latexmk -pdf -outdir=_build paper/main.tex";
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/i;
 const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
 const PACKAGE_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+const BUILDCHAIN_PACKAGE_NAME = "@kungfu-tech/buildchain";
 
 function toPosix(value) {
   return String(value || "")
@@ -147,6 +152,66 @@ function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function paperPnpmWorkspace(current, buildchainVersion) {
+  const entry = `${BUILDCHAIN_PACKAGE_NAME}@${buildchainVersion}`;
+  const source = String(current || "");
+  const lines = source ? source.replace(/\r\n/g, "\n").split("\n") : [];
+  if (lines.at(-1) === "") lines.pop();
+  const keyLines = lines
+    .map((line, index) =>
+      /^minimumReleaseAgeExclude:\s*(?:#.*)?$/.test(line) ? index : -1,
+    )
+    .filter((index) => index >= 0);
+  const unsupportedKey = lines.some(
+    (line) =>
+      /^minimumReleaseAgeExclude\s*:/.test(line) &&
+      !/^minimumReleaseAgeExclude:\s*(?:#.*)?$/.test(line),
+  );
+  if (unsupportedKey || keyLines.length > 1) {
+    throw new Error(
+      "paper migration requires minimumReleaseAgeExclude to be one top-level block sequence",
+    );
+  }
+  if (keyLines.length === 0) {
+    const prefix = lines.length > 0 ? [...lines, ""] : [];
+    return `${[...prefix, "minimumReleaseAgeExclude:", `  - '${entry}'`].join(
+      "\n",
+    )}\n`;
+  }
+  const keyIndex = keyLines[0];
+  let blockEnd = lines.length;
+  for (let index = keyIndex + 1; index < lines.length; index += 1) {
+    if (/^[^\s#]/.test(lines[index])) {
+      blockEnd = index;
+      break;
+    }
+  }
+  const retained = [];
+  for (const line of lines.slice(keyIndex + 1, blockEnd)) {
+    if (!line.trim() || /^\s*#/.test(line)) {
+      retained.push(line);
+      continue;
+    }
+    const item = line.match(/^\s*-\s+(.+?)\s*(?:#.*)?$/);
+    if (!item) {
+      throw new Error(
+        "paper migration requires minimumReleaseAgeExclude to contain scalar package entries",
+      );
+    }
+    const value = item[1]
+      .trim()
+      .replace(/^'(.*)'$/, "$1")
+      .replace(/^"(.*)"$/, "$1");
+    if (!value.startsWith(`${BUILDCHAIN_PACKAGE_NAME}@`)) retained.push(line);
+  }
+  return `${[
+    ...lines.slice(0, keyIndex + 1),
+    ...retained,
+    `  - '${entry}'`,
+    ...lines.slice(blockEnd),
+  ].join("\n")}\n`;
+}
+
 function existingFileFact(cwd, relativePath) {
   const filePath = path.resolve(cwd, relativePath);
   if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
@@ -177,8 +242,11 @@ function buildchainPackageIdentity(buildchainRoot, explicitVersion = "") {
   };
 }
 
-function runtimeGitSha(buildchainRoot, buildchainVersion = "") {
-  const value = gitValue(buildchainRoot, ["rev-parse", "HEAD"]);
+export function resolvePaperRuntimeGitSha(
+  buildchainRoot,
+  buildchainVersion = "",
+) {
+  const value = resolvePaperBuildchainSha(buildchainRoot);
   if (GIT_SHA_PATTERN.test(value)) return value;
   const identity = buildchainPackageIdentity(buildchainRoot, buildchainVersion);
   if (!identity.version) return "";
@@ -416,6 +484,7 @@ ${passportInput}    secrets:
       BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
       BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
       BUILDCHAIN_GENERATED_WRITE_TOKEN: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}
+      BUILDCHAIN_PROMOTION_TOKEN: \${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
 `;
 }
 
@@ -598,6 +667,7 @@ function scaffoldFiles({
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
     [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
+    [PAPER_PATHS.pnpmWorkspace, paperPnpmWorkspace("", buildchainVersion)],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ...agentEntry,
     [
@@ -661,7 +731,8 @@ export function planPaperScaffold({
     buildchainVersion,
   );
   const runtimeSha =
-    buildchainSha || runtimeGitSha(buildchainRoot, runtimeIdentity.version);
+    buildchainSha ||
+    resolvePaperRuntimeGitSha(buildchainRoot, runtimeIdentity.version);
   if (!GIT_SHA_PATTERN.test(runtimeSha)) {
     throw new Error(
       "paper scaffold cannot resolve the exact Buildchain runtime SHA; pass buildchainSha or use a published Buildchain package with npm gitHead provenance",
@@ -854,7 +925,8 @@ function migrationFiles({
     "paper publish package",
   );
   const runtimeSha =
-    buildchainSha || runtimeGitSha(buildchainRoot, buildchainVersion);
+    buildchainSha ||
+    resolvePaperRuntimeGitSha(buildchainRoot, buildchainVersion);
   if (!GIT_SHA_PATTERN.test(runtimeSha)) {
     throw new Error("paper migration requires an exact Buildchain source SHA");
   }
@@ -917,12 +989,20 @@ function migrationFiles({
     currentPackage.value,
     runtimeIdentity.version,
   );
+  const pnpmWorkspacePath = path.resolve(cwd, PAPER_PATHS.pnpmWorkspace);
+  const pnpmWorkspace = paperPnpmWorkspace(
+    fs.existsSync(pnpmWorkspacePath)
+      ? fs.readFileSync(pnpmWorkspacePath, "utf8")
+      : "",
+    runtimeIdentity.version,
+  );
   const files = new Map([
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
     [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
+    [PAPER_PATHS.pnpmWorkspace, pnpmWorkspace],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ...agentEntry,
     ["package.json", jsonText(packageJson)],
@@ -1224,8 +1304,7 @@ function releaseTransactionFacts(candidates, version) {
   };
 }
 
-export function collectPaperStatus({ cwd = process.cwd() } = {}) {
-  const resolvedCwd = path.resolve(cwd);
+function collectPaperGovernanceFacts(resolvedCwd) {
   const configResult = paperConfig(resolvedCwd);
   const loaded = configResult.loaded;
   const publication = loaded?.config?.publication;
@@ -1266,7 +1345,13 @@ export function collectPaperStatus({ cwd = process.cwd() } = {}) {
     gitRepo.ok &&
     gitRepo.stdout === "true",
   );
+  return {
+    configResult, loaded, publication, packageName, version, configFact,
+    scaffoldFacts, contractLockError, scaffoldOk, governedOk,
+  };
+}
 
+function collectPaperEvidenceFacts(resolvedCwd, publication, version) {
   const admissionInputs = [PAPER_PATHS.capability, PAPER_PATHS.admission].map(
     (relativePath) => ({
       relativePath,
@@ -1324,6 +1409,82 @@ export function collectPaperStatus({ cwd = process.cwd() } = {}) {
     visibility.value,
     "production",
   );
+  return {
+    admitted, bootstrapValue, trustValue, content, reproducibility, deterministic,
+    sealedOk, sealedError, candidates, transactionFacts, packagePublished,
+    alphaComplete, stagingVisible, productionVisible,
+  };
+}
+
+function paperStatusBlockingNextActions({ stateMap, deterministic, transactionFacts }) {
+  const actions = [];
+  if (!stateMap.scaffolded.satisfied) {
+    actions.push({
+      id: "scaffold-paper",
+      command: "buildchain paper scaffold --help",
+      description: "Plan a no-overwrite Buildchain paper scaffold.",
+    });
+  } else if (!stateMap.governed.satisfied) {
+    actions.push({
+      id: "restore-governance",
+      command: "buildchain paper preflight --json",
+      description:
+        "Repair the Git/contract-lock governance checks reported by preflight.",
+    });
+  } else if (!stateMap["content-ready"].satisfied) {
+    actions.push({
+      id: "complete-paper-content",
+      command: "make check",
+      description: "Add every declared paper source and metadata input.",
+    });
+  } else if (!deterministic) {
+    actions.push({
+      id: "build-reproducible-artifact",
+      command: "buildchain paper build --execute --json",
+      description:
+        "Run the existing two-clean-build reproducibility gate and promote exact bytes.",
+    });
+  } else if (
+    !stateMap.bootstrapped.satisfied ||
+    !stateMap["trust-bound"].satisfied
+  ) {
+    actions.push({
+      id: "bootstrap-npm",
+      command: "buildchain paper bootstrap npm --json",
+      description:
+        "Inspect the dry-run npm bootstrap and Trusted Publishing handoff.",
+    });
+  } else if (!stateMap["alpha-complete"].satisfied) {
+    actions.push({
+      id: transactionFacts.selected ? "resume-alpha" : "start-alpha",
+      command: transactionFacts.selected
+        ? "buildchain paper resume --json"
+        : "buildchain paper alpha --json",
+      description: transactionFacts.selected
+        ? "Resume the exact sealed release transaction."
+        : "Plan the protected dev-to-alpha publication PR.",
+    });
+  }
+  return actions;
+}
+
+export function collectPaperStatus({ cwd = process.cwd() } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const governance = collectPaperGovernanceFacts(resolvedCwd);
+  const evidence = collectPaperEvidenceFacts(
+    resolvedCwd,
+    governance.publication,
+    governance.version,
+  );
+  const {
+    configResult, loaded, publication, packageName, version, configFact,
+    scaffoldFacts, contractLockError, scaffoldOk, governedOk,
+  } = governance;
+  const {
+    admitted, bootstrapValue, trustValue, content, reproducibility, deterministic,
+    sealedOk, sealedError, candidates, transactionFacts, packagePublished,
+    alphaComplete, stagingVisible, productionVisible,
+  } = evidence;
 
   const states = [
     state(
@@ -1433,54 +1594,7 @@ export function collectPaperStatus({ cwd = process.cwd() } = {}) {
   const highestEvidenceState =
     [...states].reverse().find((entry) => entry.satisfied)?.id || "none";
   const stateMap = Object.fromEntries(states.map((entry) => [entry.id, entry]));
-  const blockingNextActions = [];
-  if (!stateMap.scaffolded.satisfied) {
-    blockingNextActions.push({
-      id: "scaffold-paper",
-      command: "buildchain paper scaffold --help",
-      description: "Plan a no-overwrite Buildchain paper scaffold.",
-    });
-  } else if (!stateMap.governed.satisfied) {
-    blockingNextActions.push({
-      id: "restore-governance",
-      command: "buildchain paper preflight --json",
-      description:
-        "Repair the Git/contract-lock governance checks reported by preflight.",
-    });
-  } else if (!stateMap["content-ready"].satisfied) {
-    blockingNextActions.push({
-      id: "complete-paper-content",
-      command: "make check",
-      description: "Add every declared paper source and metadata input.",
-    });
-  } else if (!deterministic) {
-    blockingNextActions.push({
-      id: "build-reproducible-artifact",
-      command: "buildchain paper build --execute --json",
-      description:
-        "Run the existing two-clean-build reproducibility gate and promote exact bytes.",
-    });
-  } else if (
-    !stateMap.bootstrapped.satisfied ||
-    !stateMap["trust-bound"].satisfied
-  ) {
-    blockingNextActions.push({
-      id: "bootstrap-npm",
-      command: "buildchain paper bootstrap npm --json",
-      description:
-        "Inspect the dry-run npm bootstrap and Trusted Publishing handoff.",
-    });
-  } else if (!stateMap["alpha-complete"].satisfied) {
-    blockingNextActions.push({
-      id: transactionFacts.selected ? "resume-alpha" : "start-alpha",
-      command: transactionFacts.selected
-        ? "buildchain paper resume --json"
-        : "buildchain paper alpha --json",
-      description: transactionFacts.selected
-        ? "Resume the exact sealed release transaction."
-        : "Plan the protected dev-to-alpha publication PR.",
-    });
-  }
+  const blockingNextActions = paperStatusBlockingNextActions({ stateMap, deterministic, transactionFacts });
   return {
     schemaVersion: 1,
     contract: PAPER_STATUS_CONTRACT,
@@ -1734,7 +1848,8 @@ function runtimeFacts({
     version: identity.version,
     ref: buildchainRef,
     resolvedSha:
-      buildchainSha || runtimeGitSha(buildchainRoot, identity.version),
+      buildchainSha ||
+      resolvePaperRuntimeGitSha(buildchainRoot, identity.version),
     contract: contractWorld.contract,
     contractDigest: contractWorld.contractDigest,
     compatibilityDigest: contractWorld.compatibilityDigest,
@@ -2043,146 +2158,8 @@ function localToolchainObservation(cwd, publication) {
   };
 }
 
-export function collectPaperPreflight({
-  cwd = process.cwd(),
-  buildchainRoot = process.cwd(),
-  buildchainVersion = "",
-  buildchainRef = "v3",
-  buildchainSha = "",
-  registry = NPM_REGISTRY,
-  offline = false,
-  agentEntryMode = "contract",
-} = {}) {
-  const resolvedCwd = path.resolve(cwd);
-  const status = collectPaperStatus({ cwd: resolvedCwd });
-  const provisioning = validatePaperProvisioningAuthority(resolvedCwd);
-  const configResult = paperConfig(resolvedCwd);
-  let validation;
-  let validationError = "";
-  try {
-    validation = validateBuildchainConfig(resolvedCwd, {
-      requireLifecycleStages: ["verify"],
-    });
-  } catch (error) {
-    validationError = error.message;
-  }
-  const runtime = runtimeFacts({
-    buildchainRoot,
-    buildchainVersion,
-    buildchainRef: provisioning.value?.runtime?.ref || buildchainRef,
-    buildchainSha,
-  });
-  const agentEntry = collectPaperAgentEntry({
-    cwd: resolvedCwd,
-    buildchainSha: runtime.resolvedSha,
-    mode: agentEntryMode,
-  });
-  const lockPath = path.resolve(resolvedCwd, PAPER_PATHS.contractLock);
-  let lockEvaluation = {
-    status: "missing-lock",
-    compatible: false,
-    drift: false,
-    reasons: ["Buildchain contract lock is missing"],
-  };
-  try {
-    const lock = readBuildchainContractLock(lockPath);
-    if (lock) {
-      const current = runtimeContractWorld(buildchainRoot);
-      lockEvaluation = evaluateBuildchainContractLock({
-        lock,
-        current,
-        runtimeRef: runtime.ref,
-        runtimeSha: runtime.resolvedSha,
-        runtimeClass: /alpha/i.test(runtime.ref) ? "alpha" : "stable",
-      });
-    }
-  } catch (error) {
-    lockEvaluation = {
-      status: "invalid-lock",
-      compatible: false,
-      drift: false,
-      reasons: [error.message],
-    };
-  }
-  const source = {
-    repositoryRoot: gitValue(resolvedCwd, ["rev-parse", "--show-toplevel"]),
-    head: gitValue(resolvedCwd, ["rev-parse", "HEAD"]),
-    tree: gitValue(resolvedCwd, ["rev-parse", "HEAD^{tree}"]),
-    branch: gitValue(resolvedCwd, ["branch", "--show-current"]),
-    clean: gitResult(resolvedCwd, ["status", "--porcelain"]).stdout === "",
-  };
-  const packageName = status.identity.package;
-  const repository = status.identity.repository;
-  const expectedPublisher = expectedPaperTrustedPublisher(provisioning.value, {
-    repository,
-    workflow: path.posix.basename(PAPER_PATHS.releaseWorkflow),
-  });
-  const npm =
-    offline || !packageName
-      ? {
-          package: {
-            status: "unknown",
-            exists: null,
-            version: "",
-            registry,
-            errorCode: offline ? "offline" : "package-unresolved",
-          },
-          auth: {
-            status: "unknown",
-            authenticated: null,
-            identity: "",
-            errorCode: offline ? "offline" : "package-unresolved",
-          },
-          trust: {
-            status: "unknown",
-            configured: null,
-            publishers: [],
-            errorCode: offline ? "offline" : "package-unresolved",
-          },
-        }
-      : {
-          package: liveNpmPackageObservation(
-            packageName,
-            registry,
-            resolvedCwd,
-          ),
-          auth: liveNpmAuthObservation(registry, resolvedCwd),
-          trust: liveNpmTrustObservation(
-            packageName,
-            registry,
-            resolvedCwd,
-            expectedPublisher,
-          ),
-        };
-  const repositoryPermissions = offline
-    ? {
-        status: "unknown",
-        repository,
-        canWrite: null,
-        errorCode: "offline",
-      }
-    : liveRepositoryPermissionObservation(repository, resolvedCwd);
-  const repositoryActions = offline
-    ? {
-        status: "unknown",
-        defaultWorkflowPermissions: "",
-        canApprovePullRequestReviews: null,
-        errorCode: "offline",
-      }
-    : liveRepositoryActionsPolicyObservation(repository, resolvedCwd);
-  const generatedWriteAuthority = offline
-    ? {
-        status: "unknown",
-        configured: null,
-        mode: "",
-        errorCode: "offline",
-      }
-    : liveGeneratedWriteAuthorityObservation(repository, resolvedCwd);
-  const toolchain = localToolchainObservation(
-    resolvedCwd,
-    configResult.loaded?.config?.publication,
-  );
-  const checks = [
+function paperPreflightLocalChecks({ agentEntry, provisioning, validationError, source, toolchain, runtime, lockEvaluation }) {
+  return [
     ...agentEntry.checks.map((entry) => ({
       ...entry,
       blocking: true,
@@ -2249,6 +2226,11 @@ export function collectPaperPreflight({
         ? `Buildchain runtime contract is ${lockEvaluation.status}.`
         : `Buildchain runtime contract is not admitted: ${(lockEvaluation.reasons || []).join("; ")}`,
     },
+  ];
+}
+
+function paperPreflightRepositoryChecks({ repositoryPermissions, repositoryActions, generatedWriteAuthority }) {
+  return [
     {
       id: "repository.write-permission",
       status:
@@ -2302,6 +2284,11 @@ export function collectPaperPreflight({
             ? "No GitHub App or compatible narrow generated-write credential is configured."
             : `Generated-write authority is unknown (${generatedWriteAuthority.errorCode}).`,
     },
+  ];
+}
+
+function paperPreflightPublicationChecks({ npm, status }) {
+  return [
     {
       id: "npm.package",
       status:
@@ -2358,24 +2345,19 @@ export function collectPaperPreflight({
           : `${status.conflicts.length} release-state conflict(s) require repair.`,
     },
   ];
-  const blockingChecks = checks.filter(
-    (entry) => entry.blocking && ["fail", "unknown"].includes(entry.status),
-  );
-  const externalMutationChecks = checks.filter(
-    (entry) =>
-      entry.scope === "external-mutation" &&
-      ["fail", "pending", "unknown"].includes(entry.status),
-  );
-  const nextActions = [];
+}
+
+function paperPreflightNextActions({ validationError, source, lockEvaluation, npm, repositoryActions, generatedWriteAuthority, status }) {
+  const actions = [];
   if (validationError) {
-    nextActions.push({
+    actions.push({
       id: "repair-config",
       command: "buildchain validate --require-lifecycle-stages verify",
       description: validationError,
     });
   }
   if (!source.clean) {
-    nextActions.push({
+    actions.push({
       id: "commit-source",
       command: "git status --short",
       description:
@@ -2383,7 +2365,7 @@ export function collectPaperPreflight({
     });
   }
   if (!lockEvaluation.compatible) {
-    nextActions.push({
+    actions.push({
       id: "refresh-contract-lock",
       command: "buildchain paper scaffold --json",
       description:
@@ -2391,7 +2373,7 @@ export function collectPaperPreflight({
     });
   }
   if (npm.package.exists === false || npm.trust.configured === false) {
-    nextActions.push({
+    actions.push({
       id: "bootstrap-npm",
       command: "buildchain paper bootstrap npm --json",
       description:
@@ -2403,7 +2385,7 @@ export function collectPaperPreflight({
     (repositoryActions.defaultWorkflowPermissions !== "read" ||
       repositoryActions.canApprovePullRequestReviews !== false)
   ) {
-    nextActions.push({
+    actions.push({
       id: "constrain-repository-actions",
       command: "",
       description:
@@ -2411,7 +2393,7 @@ export function collectPaperPreflight({
     });
   }
   if (generatedWriteAuthority.configured === false) {
-    nextActions.push({
+    actions.push({
       id: "configure-generated-write-authority",
       command: "",
       description:
@@ -2419,12 +2401,149 @@ export function collectPaperPreflight({
     });
   }
   if (status.deterministicBuild.status !== "qualifying") {
-    nextActions.push({
+    actions.push({
       id: "build-paper",
       command: "buildchain paper build --execute --json",
       description: "Run the existing qualifying two-clean-build gate.",
     });
   }
+  return actions;
+}
+
+export function collectPaperPreflight({
+  cwd = process.cwd(),
+  buildchainRoot = process.cwd(),
+  buildchainVersion = "",
+  buildchainRef = "v3",
+  buildchainSha = "",
+  registry = NPM_REGISTRY,
+  offline = false,
+  agentEntryMode = "contract",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const status = collectPaperStatus({ cwd: resolvedCwd });
+  const provisioning = validatePaperProvisioningAuthority(resolvedCwd);
+  const configResult = paperConfig(resolvedCwd);
+  let validation;
+  let validationError = "";
+  try {
+    validation = validateBuildchainConfig(resolvedCwd, { requireLifecycleStages: ["verify"] });
+  } catch (error) {
+    validationError = error.message;
+  }
+  const runtime = runtimeFacts({
+    buildchainRoot, buildchainVersion,
+    buildchainRef: provisioning.value?.runtime?.ref || buildchainRef, buildchainSha,
+  });
+  const agentEntry = collectPaperAgentEntry({ cwd: resolvedCwd, buildchainSha: runtime.resolvedSha, mode: agentEntryMode });
+  const lockPath = path.resolve(resolvedCwd, PAPER_PATHS.contractLock);
+  let lockEvaluation = {
+    status: "missing-lock",
+    compatible: false,
+    drift: false,
+    reasons: ["Buildchain contract lock is missing"],
+  };
+  try {
+    const lock = readBuildchainContractLock(lockPath);
+    if (lock) {
+      const current = runtimeContractWorld(buildchainRoot);
+      lockEvaluation = evaluateBuildchainContractLock({
+        lock,
+        current,
+        runtimeRef: runtime.ref,
+        runtimeSha: runtime.resolvedSha,
+        runtimeClass: /alpha/i.test(runtime.ref) ? "alpha" : "stable",
+      });
+    }
+  } catch (error) {
+    lockEvaluation = {
+      status: "invalid-lock",
+      compatible: false,
+      drift: false,
+      reasons: [error.message],
+    };
+  }
+  const source = {
+    repositoryRoot: gitValue(resolvedCwd, ["rev-parse", "--show-toplevel"]),
+    head: gitValue(resolvedCwd, ["rev-parse", "HEAD"]),
+    tree: gitValue(resolvedCwd, ["rev-parse", "HEAD^{tree}"]),
+    branch: gitValue(resolvedCwd, ["branch", "--show-current"]),
+    clean: gitResult(resolvedCwd, ["status", "--porcelain"]).stdout === "",
+  };
+  const packageName = status.identity.package;
+  const repository = status.identity.repository;
+  const expectedPublisher = expectedPaperTrustedPublisher(provisioning.value, {
+    repository, workflow: path.posix.basename(PAPER_PATHS.releaseWorkflow),
+  });
+  const npm =
+    offline || !packageName
+      ? {
+          package: {
+            status: "unknown",
+            exists: null,
+            version: "",
+            registry,
+            errorCode: offline ? "offline" : "package-unresolved",
+          },
+          auth: {
+            status: "unknown",
+            authenticated: null,
+            identity: "",
+            errorCode: offline ? "offline" : "package-unresolved",
+          },
+          trust: {
+            status: "unknown",
+            configured: null,
+            publishers: [],
+            errorCode: offline ? "offline" : "package-unresolved",
+          },
+        }
+      : {
+          package: liveNpmPackageObservation(packageName, registry, resolvedCwd),
+          auth: liveNpmAuthObservation(registry, resolvedCwd),
+          trust: liveNpmTrustObservation(packageName, registry, resolvedCwd, expectedPublisher),
+        };
+  const repositoryPermissions = offline
+    ? {
+        status: "unknown",
+        repository,
+        canWrite: null,
+        errorCode: "offline",
+      }
+    : liveRepositoryPermissionObservation(repository, resolvedCwd);
+  const repositoryActions = offline
+    ? {
+        status: "unknown",
+        defaultWorkflowPermissions: "",
+        canApprovePullRequestReviews: null,
+        errorCode: "offline",
+      }
+    : liveRepositoryActionsPolicyObservation(repository, resolvedCwd);
+  const generatedWriteAuthority = offline
+    ? {
+        status: "unknown",
+        configured: null,
+        mode: "",
+        errorCode: "offline",
+      }
+    : liveGeneratedWriteAuthorityObservation(repository, resolvedCwd);
+  const toolchain = localToolchainObservation(resolvedCwd, configResult.loaded?.config?.publication);
+  const checks = [
+    ...paperPreflightLocalChecks({ agentEntry, provisioning, validationError, source, toolchain, runtime, lockEvaluation }),
+    ...paperPreflightRepositoryChecks({ repositoryPermissions, repositoryActions, generatedWriteAuthority }),
+    ...paperPreflightPublicationChecks({ npm, status }),
+  ];
+  const blockingChecks = checks.filter(
+    (entry) => entry.blocking && ["fail", "unknown"].includes(entry.status),
+  );
+  const externalMutationChecks = checks.filter(
+    (entry) =>
+      entry.scope === "external-mutation" &&
+      ["fail", "pending", "unknown"].includes(entry.status),
+  );
+  const nextActions = paperPreflightNextActions({
+    validationError, source, lockEvaluation, npm, repositoryActions, generatedWriteAuthority, status,
+  });
   return {
     schemaVersion: 1,
     contract: PAPER_PREFLIGHT_CONTRACT,
@@ -2718,467 +2837,30 @@ function bootstrapPackageShape({ packageName, version }) {
   };
 }
 
-export function executePaperNpmBootstrap({
-  cwd = process.cwd(),
-  packageName = "",
-  bootstrapVersion = DEFAULT_BOOTSTRAP_VERSION,
-  registry = NPM_REGISTRY,
-  repository = "",
-  workflow = "paper-release.yml",
-  environment = "",
-  execute = false,
-  confirmedPackage = "",
-  userconfig = "",
-  offline = false,
-} = {}) {
-  const resolvedCwd = path.resolve(cwd);
-  if (registry !== NPM_REGISTRY) {
-    throw new Error(
-      `paper npm bootstrap requires the official registry ${NPM_REGISTRY}`,
-    );
-  }
-  if (bootstrapVersion !== DEFAULT_BOOTSTRAP_VERSION) {
-    throw new Error(
-      `paper npm bootstrap version is fixed at ${DEFAULT_BOOTSTRAP_VERSION}`,
-    );
-  }
-  const configResult = paperConfig(resolvedCwd);
-  if (configResult.error) throw new Error(configResult.error);
-  const name = normalizePackageName(
-    packageName ||
-      configResult.loaded.config.publish?.package ||
-      configResult.loaded.config.publish?.mainPackage,
-  );
-  const repo = normalizeRepository(
-    repository || resolvePaperRepository(resolvedCwd),
-  );
-  const provisioning = validatePaperProvisioningAuthority(resolvedCwd);
-  if (!provisioning.valid) {
-    throw new Error(
-      `paper npm bootstrap requires a valid provisioning authority: ${provisioning.errors.join("; ")}`,
-    );
-  }
-  const expectedPublisher = expectedPaperTrustedPublisher(provisioning.value);
-  if (
-    provisioning.value.package?.name !== name ||
-    expectedPublisher.repository !== repo ||
-    expectedPublisher.workflow !== toPosix(workflow).replace(/^\/+/, "") ||
-    expectedPublisher.environment !== String(environment || "")
-  ) {
-    throw new Error(
-      "paper npm bootstrap coordinates differ from the exact provisioning authority",
-    );
-  }
-  if (execute && confirmedPackage !== name) {
-    throw new Error(
-      `real npm bootstrap requires --confirm-public-package ${name}`,
-    );
-  }
-  if (execute && offline) {
-    throw new Error("real npm bootstrap cannot run with --offline");
-  }
-  if (execute && (!repo || !workflow)) {
-    throw new Error(
-      "real npm bootstrap requires GitHub repository and workflow coordinates",
-    );
-  }
-  const packageObservation = offline
-    ? {
-        status: "unknown",
-        exists: null,
-        version: "",
-        registry,
-        errorCode: "offline",
-      }
-    : liveNpmPackageObservation(name, registry, resolvedCwd);
-  const auth = offline
-    ? {
-        status: "unknown",
-        authenticated: null,
-        identity: "",
-        errorCode: "offline",
-      }
-    : liveNpmAuthObservation(registry, resolvedCwd);
-  const plan = {
-    schemaVersion: 1,
-    contract: PAPER_NPM_BOOTSTRAP_CONTRACT,
-    ok: true,
-    dryRun: !execute,
-    externalMutation: execute,
-    package: {
-      name,
-      bootstrapVersion,
-      registry,
-      existsBefore: packageObservation.exists,
-      observedVersion: packageObservation.version,
-    },
-    repository: {
-      github: repo,
-      workflow,
-      environment,
-    },
-    authority: {
-      digest: provisioning.value.authorityDigest,
-      policyDigest: provisioning.value.policy.policyDigest,
-    },
-    auth: {
-      authenticated: auth.authenticated,
-      identity: auth.identity,
-      errorCode: auth.errorCode,
-    },
-    publish: {
-      status: packageObservation.exists === true ? "existing" : "planned",
-      distTag: "bootstrap",
-      access: "public",
-    },
-    trust: {
-      status: "planned",
-      urls: [],
-    },
-    receipts: [],
-    nextActions: execute
-      ? []
-      : [
-          {
-            id: "confirm-public-bootstrap",
-            command: `buildchain paper bootstrap npm --execute --confirm-public-package ${name} --json`,
-            description:
-              "After reviewing this dry-run, bootstrap the exact public package and configure GitHub Trusted Publishing.",
-          },
-        ],
-  };
-  if (!execute) {
-    const dryRunRoot = fs.mkdtempSync(
-      path.join(os.tmpdir(), "buildchain-paper-bootstrap-dry-run-"),
-    );
-    try {
-      fs.writeFileSync(
-        path.join(dryRunRoot, "package.json"),
-        jsonText(
-          bootstrapPackageShape({
-            packageName: name,
-            version: bootstrapVersion,
-          }),
-        ),
-      );
-      const configArgs = userconfig ? ["--userconfig", userconfig] : [];
-      const pack = commandResult(
-        "npm",
-        [
-          "pack",
-          "--dry-run",
-          "--json",
-          "--ignore-scripts",
-          `--registry=${registry}`,
-          ...configArgs,
-        ],
-        { cwd: dryRunRoot },
-      );
-      const publish = commandResult(
-        "npm",
-        [
-          "publish",
-          "--dry-run",
-          "--ignore-scripts",
-          "--access",
-          "public",
-          "--tag",
-          "bootstrap",
-          `--registry=${registry}`,
-          ...configArgs,
-        ],
-        { cwd: dryRunRoot },
-      );
-      return {
-        ...plan,
-        ok: pack.ok && publish.ok,
-        errorCode: !pack.ok
-          ? "npm-pack-dry-run-failed"
-          : !publish.ok
-            ? "npm-publish-dry-run-failed"
-            : "",
-        dryRunChecks: {
-          minimalPackageOnly: true,
-          pack: {
-            status: pack.ok ? "pass" : "fail",
-            entryCount: (() => {
-              const parsed = safeParseJson(pack.stdout);
-              const value = Array.isArray(parsed) ? parsed[0] : parsed;
-              return Array.isArray(value?.files) ? value.files.length : 0;
-            })(),
-          },
-          publish: {
-            status: publish.ok ? "pass" : "fail",
-            registry,
-            access: "public",
-            distTag: "bootstrap",
-          },
-        },
-      };
-    } finally {
-      fs.rmSync(dryRunRoot, { recursive: true, force: true });
-    }
-  }
-  if (packageObservation.exists === null) {
-    return {
-      ...plan,
-      ok: false,
-      errorCode: "npm-package-status-unknown",
-      publish: {
-        ...plan.publish,
-        status: "blocked",
-      },
-      trust: {
-        status: "blocked",
-        urls: [],
-      },
-      nextActions: [
-        {
-          id: "verify-npm-package",
-          command: `npm view ${name} version --json --registry=${registry}`,
-          description:
-            "Resolve whether the exact public package exists before any publish mutation.",
-        },
-      ],
-    };
-  }
-  if (auth.authenticated !== true) {
-    return {
-      ...plan,
-      ok: false,
-      errorCode: "npm-auth-required",
-      publish: {
-        ...plan.publish,
-        status: "blocked",
-      },
-      trust: {
-        status: "blocked",
-        urls: [],
-      },
-      nextActions: [
-        {
-          id: "authenticate-npm",
-          command: `npm whoami --registry=${registry}`,
-          description:
-            "Authenticate npm without sharing token contents, then rerun the exact bootstrap command.",
-        },
-      ],
-    };
-  }
-  const tempRoot = fs.mkdtempSync(
-    path.join(os.tmpdir(), "buildchain-paper-bootstrap-"),
-  );
-  try {
-    fs.writeFileSync(
-      path.join(tempRoot, "package.json"),
-      jsonText(
-        bootstrapPackageShape({ packageName: name, version: bootstrapVersion }),
-      ),
-    );
-    const configArgs = userconfig ? ["--userconfig", userconfig] : [];
-    const pack = commandResult(
-      "npm",
-      [
-        "pack",
-        "--dry-run",
-        "--json",
-        "--ignore-scripts",
-        `--registry=${registry}`,
-        ...configArgs,
-      ],
-      { cwd: tempRoot },
-    );
-    if (!pack.ok) {
-      return {
-        ...plan,
-        ok: false,
-        errorCode: "npm-pack-dry-run-failed",
-        publish: { ...plan.publish, status: "blocked" },
-        trust: { status: "blocked", urls: [] },
-      };
-    }
-    const publishDryRun = commandResult(
-      "npm",
-      [
-        "publish",
-        "--dry-run",
-        "--ignore-scripts",
-        "--access",
-        "public",
-        "--tag",
-        "bootstrap",
-        `--registry=${registry}`,
-        ...configArgs,
-      ],
-      { cwd: tempRoot },
-    );
-    if (!publishDryRun.ok) {
-      return {
-        ...plan,
-        ok: false,
-        errorCode: "npm-publish-dry-run-failed",
-        publish: { ...plan.publish, status: "blocked" },
-        trust: { status: "blocked", urls: [] },
-      };
-    }
-    let publishStatus =
-      packageObservation.exists === true ? "existing" : "published";
-    if (packageObservation.exists !== true) {
-      const published = commandResult(
-        "npm",
-        [
-          "publish",
-          "--ignore-scripts",
-          "--access",
-          "public",
-          "--tag",
-          "bootstrap",
-          `--registry=${registry}`,
-          ...configArgs,
-        ],
-        { cwd: tempRoot, timeout: 60000 },
-      );
-      if (!published.ok) {
-        const failure = {
-          ...plan,
-          ok: false,
-          errorCode: "npm-publish-failed",
-          publish: { ...plan.publish, status: "failed" },
-          trust: { status: "blocked", urls: [] },
-        };
-        failure.receipts = [
-          writePaperReceipt(resolvedCwd, PAPER_PATHS.npmBootstrap, failure),
-        ];
-        return failure;
-      }
-    }
-    const trustArgs = [
-      "trust",
-      "github",
-      name,
-      "--repo",
-      repo,
-      "--file",
-      workflow,
-      ...(environment ? ["--env", environment] : []),
-      "--allow-publish",
-      "--yes",
-      "--json",
-      `--registry=${registry}`,
-      ...configArgs,
-    ];
-    const trustCommand = commandResult("npm", trustArgs, {
-      cwd: resolvedCwd,
-      timeout: 60000,
-    });
-    const parsedTrust = safeParseJson(trustCommand.stdout);
-    const urls = [
-      ...extractUrls(
-        parsedTrust || `${trustCommand.stdout}\n${trustCommand.stderr}`,
-      ),
-    ];
-    const trustList =
-      trustCommand.ok && urls.length === 0
-        ? liveNpmTrustObservation(
-            name,
-            registry,
-            resolvedCwd,
-            expectedPublisher,
-          )
-        : {
-            status: "unknown",
-            configured: null,
-            publishers: [],
-            errorCode:
-              urls.length > 0 ? "web-action-required" : "npm-trust-failed",
-          };
-    const trustStatus =
-      trustCommand.ok && trustList.configured === true
-        ? "configured"
-        : urls.length > 0
-          ? "action-required"
-          : "failed";
-    const packageAfter = liveNpmPackageObservation(name, registry, resolvedCwd);
-    const packageVerified = packageAfter.exists === true;
-    const receipt = {
-      ...plan,
-      ok: trustStatus !== "failed" && packageVerified,
-      dryRun: false,
-      externalMutation: true,
-      errorCode:
-        trustStatus === "failed"
-          ? "npm-trust-failed"
-          : packageVerified
-            ? ""
-            : "npm-package-readback-failed",
-      package: {
-        ...plan.package,
-        existsAfter: packageAfter.exists,
-        observedVersionAfter: packageAfter.version,
-        readbackStatus: packageAfter.status,
-      },
-      publish: {
-        ...plan.publish,
-        status: publishStatus,
-      },
-      trust: {
-        status: trustStatus,
-        urls,
-        expectedPublisher,
-        exactBinding: trustList.exactBinding === true,
-        publishers: trustList.publishers,
-      },
-      nextActions:
-        trustStatus === "configured" && packageVerified
-          ? [
-              {
-                id: "paper-preflight",
-                command: "buildchain paper preflight --json",
-                description:
-                  "Verify package existence and Trusted Publisher binding from live read-only sources.",
-              },
-            ]
-          : trustStatus === "action-required" && packageVerified
-            ? [
-                {
-                  id: "complete-npm-web-action",
-                  command: "",
-                  description:
-                    "Open the exact npm URL returned below, complete the web step, then rerun preflight.",
-                  urls,
-                },
-              ]
-            : !packageVerified
-              ? [
-                  {
-                    id: "verify-npm-package-readback",
-                    command: `npm view ${name} version --json --registry=${registry}`,
-                    description:
-                      "The mutation returned but the official registry did not prove package existence; do not infer success.",
-                  },
-                ]
-              : [
-                  {
-                    id: "retry-npm-trust",
-                    command: `buildchain paper bootstrap npm --execute --confirm-public-package ${name} --json`,
-                    description:
-                      "The package exists; retry only the idempotent Trusted Publisher configuration path.",
-                  },
-                ],
-    };
-    receipt.receipts = [
-      writePaperReceipt(resolvedCwd, PAPER_PATHS.npmBootstrap, receipt),
-    ];
-    if (
-      packageVerified &&
-      (trustStatus === "configured" || trustStatus === "action-required")
-    ) {
-      receipt.receipts.push(
-        writePaperReceipt(resolvedCwd, PAPER_PATHS.npmTrust, receipt),
-      );
-    }
-    return receipt;
-  } finally {
-    fs.rmSync(tempRoot, { recursive: true, force: true });
-  }
+export function executePaperNpmBootstrap(options = {}) {
+  return executePaperNpmBootstrapOperation(options, {
+    DEFAULT_BOOTSTRAP_VERSION,
+    NPM_REGISTRY,
+    PAPER_NPM_BOOTSTRAP_CONTRACT,
+    PAPER_PATHS,
+    bootstrapPackageShape,
+    commandResult,
+    expectedPaperTrustedPublisher,
+    extractUrls,
+    fs,
+    jsonText,
+    liveNpmAuthObservation,
+    liveNpmPackageObservation,
+    liveNpmTrustObservation,
+    normalizePackageName,
+    normalizeRepository,
+    os,
+    paperConfig,
+    path,
+    resolvePaperRepository,
+    safeParseJson,
+    toPosix,
+    validatePaperProvisioningAuthority,
+    writePaperReceipt,
+  });
 }