machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/scripts/start-release-candidate.mjs

@@ -1,68 +1,115 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { defaultStateRoot, expandHome, selectedWorkspace } from "../src/local/state.mjs";
+import { ensureOwnerOnlyDirectorySync } from "../src/local/secure-file.mjs";
+import { createCandidateRuntimePrefix, isNonBlockingCandidateRuntimeCleanupError, pruneInactiveCandidateRuntimes } from "./candidate-runtime-store.mjs";
+import { ACTIVATION_SCHEMA_VERSION, writePrereleaseActivation } from "./prerelease-activation.mjs";
 import { verifyTarball } from "./release-acceptance.mjs";
+import { parseReleaseVersion } from "./release-channel.mjs";
+import { discoverForegroundDaemonRecovery } from "./foreground-daemon-recovery.mjs";
+import { assertPersistentActivationExecutionSurface, persistentActivationSpawnOptions, persistentCandidateFailureMessage, preflightPersistentActivationWorkerAuth, validateActivationRecoveryPayload } from "./persistent-activation-process.mjs";
+import { assertCandidateMatchesCurrentSource, validateCandidateManifest } from "./release-candidate-manifest.mjs";
+import { computePromotionContentDigest } from "./promotion-digest.mjs";
+import { createHardenedNpmSession, settleHardenedNpmSession } from "./hardened-npm-session.mjs";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { withReleaseRuntimeLock } from "../src/local/release-runtime-lock.mjs";
+import { releaseCommandFailure, releaseDiagnostic, releaseDiagnosticEvent } from "./release-diagnostic.mjs";
+import { inspectGlobalPackageInstallation } from "./global-package-installation.mjs";
+import { resolveNpmGlobalPrefix } from "./npm-global-prefix.mjs";
+import { resolveNpmCli } from "../src/local/npm-cli.mjs";
+import { publishReleaseBrowserExtension } from "./release-browser-extension-store.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const candidateDirectory = join(root, ".release-candidate");
 const manifestPath = join(candidateDirectory, "manifest.json");
-const installPrefix = join(candidateDirectory, "runtime");
-const npmCli = process.env.npm_execpath;
-
-if (!npmCli) fail("candidate startup must run through npm so npm_execpath is available");
+const foregroundInstallPrefix = join(candidateDirectory, "runtime");
+const installOnly = process.argv.includes("--install-only");
+const activateService = process.argv.includes("--activate-service");
+const allowWorkerDeploy = process.argv.includes("--allow-worker-deploy");
+const persistentActivation = activateService && !installOnly;
+const lifecycleNpmCli = process.env.npm_execpath;
+let sourceNpmCli = lifecycleNpmCli;
+let npmCli = "";
+let npmSession = null;
+let persistentExecutionSurface = "local";
 
 try {
-  const manifest = readJson(manifestPath, "release candidate manifest");
-  if (manifest.result !== "pending") throw new Error("release candidate manifest is not pending");
-  const tarball = join(candidateDirectory, String(manifest.filename || ""));
+  if (persistentActivation) persistentExecutionSurface = assertPersistentActivationExecutionSurface(process.env);
+  if (installOnly) sourceNpmCli = resolveNpmCli({ allowLifecycleNpmCli: false, allowFallbackLocations: false });
+  if (!sourceNpmCli) throw new Error("candidate live startup must run through npm so npm_execpath is available");
+  const currentPackage = readJson(join(root, "package.json"), "current package");
+  const manifest = validateCandidateManifest(
+    readJson(manifestPath, "release candidate manifest"),
+    { packageName: currentPackage.name, packageVersion: currentPackage.version },
+  );
+  assertCandidateMatchesCurrentSource(manifest, {
+    packageName: currentPackage.name,
+    packageVersion: currentPackage.version,
+    promotionDigest: computePromotionContentDigest(root, { npmCli: sourceNpmCli }),
+  });
+  const tarball = join(candidateDirectory, manifest.filename);
   verifyTarball(tarball, manifest);
+  if (!installOnly && !allowWorkerDeploy) {
+    throw new Error("candidate activation may update the configured same-name Worker; rerun with --allow-worker-deploy to authorize that live candidate deployment");
+  }
+  const globalPrefix = persistentActivation
+    ? resolveNpmGlobalPrefix(lifecycleNpmCli, { cwd: root, env: process.env })
+    : "";
+  npmSession = await createHardenedNpmSession();
+  npmCli = npmSession.cli;
 
   const npmVersion = runNpm(["--version"], root).stdout.trim();
-  if (Number(npmVersion.split(".")[0]) < 12) {
-    throw new Error(`candidate startup requires npm 12 or newer; current ${npmVersion}`);
+  if (npmVersion !== npmSession.version) {
+    throw new Error(`candidate startup hardened npm reported ${npmVersion || "no version"}, expected ${npmSession.version}`);
   }
 
-  rmSync(installPrefix, { recursive: true, force: true });
-  mkdirSync(installPrefix, { recursive: true });
-  runNpm([
-    "install",
-    "--global",
-    "--prefix", installPrefix,
-    "--omit=optional",
-    "--allow-scripts=esbuild,workerd,sharp,fsevents",
-    tarball,
-  ], root);
-
-  const globalRoot = runNpm(["root", "--global", "--prefix", installPrefix], root).stdout.trim();
-  const installedPackage = join(globalRoot, manifest.package_name);
-  const installed = readJson(join(installedPackage, "package.json"), "installed candidate package");
-  if (installed.version !== manifest.package_version) {
-    throw new Error(`installed candidate version ${installed.version} does not match ${manifest.package_version}`);
+  const stateRoot = resolve(expandHome(argumentValue("--state-dir") || defaultStateRoot()));
+  const forwardedArgs = process.argv.slice(2).filter((value) => ![
+    "--install-only", "--allow-worker-deploy", "--activate-service",
+  ].includes(value));
+  if (persistentActivation) {
+    await preflightPersistentActivationWorkerAuth({
+      surface: persistentExecutionSurface,
+      stateRoot,
+      packageRoot: root,
+      npmCli,
+      env: process.env,
+    });
+    await withReleaseRuntimeLock(stateRoot, async () => {
+      const installPrefix = createCandidateRuntimePrefix({ stateRoot, version: manifest.package_version, shasum: manifest.shasum });
+      const installedPackage = installCandidateRuntime({ installPrefix, manifest, tarball });
+      const previousInstallation = persistentActivation
+        ? currentGlobalInstallation(manifest.package_name, globalPrefix, npmCli)
+        : null;
+      disposeNpmSession();
+      activatePersistentCandidate({
+        manifest, installedPackage, installPrefix, stateRoot, forwardedArgs, previousInstallation,
+      });
+    });
+    process.exit(0);
   }
 
-  console.log(`Verified candidate tarball: ${manifest.filename} (${manifest.shasum})`);
-  console.log(`Installed isolated candidate: ${installedPackage}`);
-  const installOnly = process.argv.includes("--install-only");
-  const allowWorkerDeploy = process.argv.includes("--allow-worker-deploy");
+  const installPrefix = foregroundInstallPrefix;
+  rmSync(installPrefix, { recursive: true, force: true });
+  const installedPackage = installCandidateRuntime({ installPrefix, manifest, tarball });
+  disposeNpmSession();
   if (installOnly) {
-    console.log("Candidate installation check passed; startup was skipped by --install-only.");
+    rmSync(installPrefix, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    console.log("Candidate installation check passed; temporary runtime was removed and startup was skipped by --install-only.");
     process.exit(0);
   }
 
-  if (!allowWorkerDeploy) {
-    throw new Error("foreground candidate startup may update the configured same-name Worker; rerun with --allow-worker-deploy to authorize that live candidate deployment");
-  }
-
-  const forwardedArgs = process.argv.slice(2).filter((value) => value !== "--install-only" && value !== "--allow-worker-deploy");
   const cli = join(installedPackage, "bin", "machine-mcp.mjs");
   console.log("Authorized live candidate deployment: startup may update the configured same-name Worker when its version or deployment hash differs.");
   console.log("Starting the exact candidate in the foreground. Leave this process running while the coding agent verifies the Worker, relay, and local runtime end to end.");
   const child = spawn(process.execPath, [cli, ...forwardedArgs], {
     cwd: root,
-    env: process.env,
+    env: nestedNpmEnvironment(process.env),
     stdio: "inherit",
     windowsHide: true,
   });
@@ -83,22 +130,198 @@ try {
     process.exitCode = code ?? 1;
   });
 } catch (error) {
-  fail(error?.message || error);
+  const settled = settleNpmSession(error);
+  fail(settled?.message || settled);
+}
+
+function installCandidateRuntime({ installPrefix, manifest, tarball }) {
+  ensureOwnerOnlyDirectorySync(installPrefix);
+  runNpm([
+    "install",
+    "--dry-run=false",
+    "--workspaces=false",
+    "--ignore-scripts=false",
+    "--global",
+    "--prefix", installPrefix,
+    "--omit=optional",
+    "--include=prod",
+    "--package-lock-only=false",
+    "--allow-scripts=esbuild,workerd,sharp,fsevents",
+    tarball,
+  ], root);
+  const globalRoot = runNpm(["root", "--json=false", "--parseable=false", "--workspaces=false", "--global", "--prefix", installPrefix], root).stdout.trim();
+  const installedPackage = join(globalRoot, manifest.package_name);
+  const installed = readJson(join(installedPackage, "package.json"), "installed candidate package");
+  if (installed.version !== manifest.package_version) {
+    throw new Error(`installed candidate version ${installed.version} does not match ${manifest.package_version}`);
+  }
+  console.log(`Verified candidate tarball: ${manifest.filename} (${manifest.shasum})`);
+  console.log(`Installed isolated candidate: ${installedPackage}`);
+  return installedPackage;
+}
+
+function activatePersistentCandidate({
+  manifest, installedPackage, installPrefix, stateRoot, forwardedArgs, previousInstallation,
+}) {
+  const releaseVersion = parseReleaseVersion(manifest.package_version);
+  const cli = join(installedPackage, "bin", "machine-mcp.mjs");
+  const args = ["activate", ...withoutManagedFlags(forwardedArgs), "--state-dir", stateRoot, "--json"];
+  console.log("Activating the exact prerelease as the persistent login daemon. Portable-root startup does not prompt; a separately provisioned Secure Enclave broker may request one user-presence operation.");
+  const result = spawnSync(
+    process.execPath,
+    [cli, ...args],
+    persistentActivationSpawnOptions({ cwd: root, env: nestedNpmEnvironment(process.env) }),
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = result.stderr || result.stdout;
+    const requestedWorkspace = argumentListValue("--workspace", withoutManagedFlags(forwardedArgs))
+      || selectedWorkspace(stateRoot);
+    const previousRuntime = discoverForegroundDaemonRecovery({
+      output, stateRoot, workspace: requestedWorkspace,
+    });
+    throw new Error(persistentCandidateFailureMessage(output, { cli, stateRoot, previousRuntime }));
+  }
+  let activation;
+  try { activation = JSON.parse(result.stdout); } catch { throw new Error("persistent candidate activation did not return valid JSON"); }
+  if (
+    activation.ok !== true
+    || activation.version !== manifest.package_version
+    || activation.daemon?.version !== manifest.package_version
+    || activation.worker?.health?.version !== manifest.package_version
+  ) {
+    throw new Error("persistent candidate activation did not converge on the exact candidate version");
+  }
+  const recovery = validateActivationRecoveryPayload(activation);
+
+  let publishedBrowserExtension;
+  try {
+    publishedBrowserExtension = publishReleaseBrowserExtension({
+      stateRoot,
+      sourceDirectory: join(installedPackage, "browser-extension"),
+      expectedVersion: manifest.package_version,
+    });
+  } catch (error) {
+    throw new Error(
+      "persistent candidate activation converged, but the stable browser extension could not be published; the candidate Worker/service is live and must be inspected before retrying",
+      { cause: error },
+    );
+  }
+
+  let removedRuntimes = [];
+  let runtimeCleanupWarning = "";
+  try {
+    removedRuntimes = pruneInactiveCandidateRuntimes({ stateRoot, activePrefix: installPrefix });
+  } catch (error) {
+    if (!isNonBlockingCandidateRuntimeCleanupError(error)) throw error;
+    runtimeCleanupWarning = boundedCleanupWarning(error);
+  }
+  let recordPath = "";
+  if (releaseVersion.prerelease) {
+    recordPath = writePrereleaseActivation({
+      schema_version: ACTIVATION_SCHEMA_VERSION,
+      package_name: manifest.package_name,
+      package_version: manifest.package_version,
+      source: "local-candidate",
+      shasum: manifest.shasum,
+      integrity: manifest.integrity,
+      promotion_content_sha256: manifest.promotion_content_sha256,
+      activated_at: new Date().toISOString(),
+      workspace_hash: workspaceHash(activation.workspace),
+      runtime_entry: cli,
+      ...(recovery.recovered ? {
+        activation_recovered: true,
+        activation_recovery_reason: recovery.reason,
+        activation_recovery_detail: recovery.detail,
+      } : {}),
+      ...(previousInstallation ? { global_package_rollback_baseline: previousInstallation } : {}),
+    }, stateRoot);
+  }
+  if (recovery.recovered) {
+    console.warn(`Persistent activation used verified candidate-service recovery (${recovery.reason}): ${recovery.detail}`);
+  }
+  console.log(`Persistent release candidate activated: ${manifest.package_version}`);
+  console.log(`Stable browser extension published: ${publishedBrowserExtension.path}`);
+  if (recordPath) console.log(`Activation record: ${recordPath}`);
+  if (removedRuntimes.length) console.log(`Removed ${removedRuntimes.length} inactive candidate runtime(s).`);
+  if (runtimeCleanupWarning) console.warn(`Candidate activation succeeded but inactive runtime cleanup was incomplete: ${runtimeCleanupWarning}`);
+  console.log("The Worker and login daemon now run the exact candidate. The terminal may close; the coding agent should verify the live deployment through Machine Bridge.");
+  if (previousInstallation?.version) {
+    console.log(`Global package rollback baseline retained: ${previousInstallation.version}.`);
+  }
+}
+
+
+function currentGlobalInstallation(packageName, globalPrefix, npmExecutable) {
+  const globalRoot = runNpm(
+    ["root", "--json=false", "--parseable=false", "--workspaces=false", "--global", "--prefix", globalPrefix],
+    root,
+    npmExecutable,
+  ).stdout.trim();
+  return inspectGlobalPackageInstallation(globalRoot, packageName);
+}
+
+function withoutManagedFlags(args) {
+  const out = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--json" || value.startsWith("--json=")) continue;
+    if (value === "--state-dir") { index += 1; continue; }
+    if (value.startsWith("--state-dir=")) continue;
+    out.push(value);
+  }
+  return out;
+}
+
+function argumentListValue(name, args) {
+  const exact = args.find(value => value.startsWith(`${name}=`));
+  if (exact) return exact.slice(name.length + 1);
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] || "" : "";
+}
+
+function argumentValue(name) {
+  const exact = process.argv.find((value) => value.startsWith(`${name}=`));
+  if (exact) return exact.slice(name.length + 1);
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : "";
+}
+
+function workspaceHash(workspace) {
+  const value = process.platform === "win32" ? String(workspace).toLowerCase() : String(workspace);
+  return createHash("sha256").update(value).digest("hex").slice(0, 24);
 }
 
-function runNpm(args, cwd) {
-  const result = spawnSync(process.execPath, [npmCli, ...args], {
+function runNpm(args, cwd, npmExecutable = npmCli) {
+  const cli = String(npmExecutable || "");
+  if (!cli) throw new Error("nested npm CLI is unavailable");
+  const result = spawnSync(process.execPath, [cli, ...args], {
     cwd,
     encoding: "utf8",
-    env: process.env,
+    env: nestedNpmEnvironment(process.env),
     timeout: 300_000,
+    killSignal: "SIGKILL",
     windowsHide: true,
   });
-  if (result.error) throw result.error;
-  if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.stdout}`);
+  if (result.error || result.status !== 0) throw new Error(releaseCommandFailure("npm", args, result));
   return result;
 }
 
+function disposeNpmSession() {
+  const error = settleNpmSession();
+  if (error) throw error;
+}
+
+function settleNpmSession(primaryError = null) {
+  const session = npmSession;
+  npmSession = null;
+  return settleHardenedNpmSession(session, primaryError, "release candidate failed and hardened npm temporary cleanup was incomplete");
+}
+
+function boundedCleanupWarning(error) {
+  return releaseDiagnostic(error?.message || error || "candidate runtime cleanup failed", 600);
+}
+
 function readJson(path, label) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -108,6 +331,6 @@ function readJson(path, label) {
 }
 
 function fail(message) {
-  console.error(`release candidate startup failed: ${message}`);
+  console.error(JSON.stringify(releaseDiagnosticEvent("release.candidate.failed", message, 1200)));
   process.exit(1);
 }

package/scripts/syntax-check.mjs

@@ -1,28 +1,49 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { readdirSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import * as vm from "node:vm";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const roots = ["bin", "src/local", "scripts", "tests", "browser-extension"];
+const roots = ["bin", "src/local", "src/shared", "scripts", "tests", "browser-extension", ".github/scripts"];
 const files = roots.flatMap((entry) => collect(join(root, entry)))
   .filter((file) => [".js", ".mjs"].includes(extname(file)))
   .sort();
+const parserMode = process.argv.includes("--vm-parse");
 
-for (const file of files) {
-  const result = spawnSync(process.execPath, ["--check", file], {
-    cwd: root,
-    encoding: "utf8",
-    windowsHide: true,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    process.stderr.write(`syntax check failed: ${relative(root, file)}\n${result.stderr || result.stdout}`);
-    process.exit(1);
+if (parserMode) {
+  if (typeof vm.SourceTextModule !== "function") throw new Error("VM module parser is unavailable");
+  for (const file of files) {
+    try {
+      let source = readFileSync(file, "utf8");
+      if (source.startsWith("#!")) source = source.replace(/^#![^\n]*(?:\n|$)/, "\n");
+      new vm.SourceTextModule(source, { identifier: relative(root, file) });
+    } catch (error) {
+      process.stderr.write(`syntax check failed: ${relative(root, file)}\n${String(error?.stack || error)}\n`);
+      process.exit(1);
+    }
   }
+  process.exit(0);
+}
+
+const parser = spawnSync(process.execPath, [
+  "--experimental-vm-modules",
+  "--no-warnings",
+  fileURLToPath(import.meta.url),
+  "--vm-parse",
+], {
+  cwd: root,
+  encoding: "utf8",
+  windowsHide: true,
+  stdio: ["ignore", "pipe", "pipe"],
+  shell: false,
+});
+if (parser.error) throw parser.error;
+if (parser.status !== 0) {
+  process.stderr.write(parser.stderr || parser.stdout || "syntax parser failed without output\n");
+  process.exit(parser.status ?? 1);
 }
 
 if (process.platform !== "win32") {
@@ -31,6 +52,7 @@ if (process.platform !== "win32") {
     encoding: "utf8",
     windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
   });
   if (shell.error) throw shell.error;
   if (shell.status !== 0) {
@@ -39,7 +61,7 @@ if (process.platform !== "win32") {
   }
 }
 
-console.log(`syntax check ok (${files.length} JavaScript files${process.platform === "win32" ? "" : "; mbm shell wrapper"})`);
+console.log(`syntax check ok (${files.length} JavaScript files in one parser process${process.platform === "win32" ? "" : "; mbm shell wrapper"})`);
 
 function collect(directory) {
   const files = [];

package/scripts/verification-generation-guard.mjs

@@ -0,0 +1,15 @@
+export async function runWithStableGeneration({ captureGeneration, run, label = "verification inputs" }) {
+  if (typeof captureGeneration !== "function") throw new TypeError("captureGeneration must be a function");
+  if (typeof run !== "function") throw new TypeError("run must be a function");
+  const before = captureGeneration();
+  let result;
+  let runError;
+  try { result = await run(); }
+  catch (error) { runError = error; }
+  const after = captureGeneration();
+  if (after !== before) {
+    throw new Error(`${label} changed during verification; discard this run (${before} -> ${after})`);
+  }
+  if (runError) throw runError;
+  return result;
+}

package/scripts/verification-idle-sleep-guard.mjs

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+export const VERIFICATION_IDLE_SLEEP_GUARD_ENV = "MBM_CHECK_IDLE_SLEEP_GUARD";
+
+export async function rerunVerificationUnderIdleSleepGuard(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  if (platform !== "darwin" || env[VERIFICATION_IDLE_SLEEP_GUARD_ENV] === "1") return null;
+
+  const executable = String(options.execPath || process.execPath);
+  const argv = Array.isArray(options.argv) ? options.argv.map(String) : process.argv.slice(1);
+  if (!executable || argv.length === 0 || !argv[0]) {
+    throw new Error("verification idle-sleep guard requires the current Node executable and entrypoint");
+  }
+  const spawnProcess = typeof options.spawnProcess === "function" ? options.spawnProcess : spawn;
+  let child;
+  try {
+    child = spawnProcess("/usr/bin/caffeinate", ["-i", executable, ...argv], {
+      env: { ...env, [VERIFICATION_IDLE_SLEEP_GUARD_ENV]: "1" },
+      stdio: "inherit",
+      shell: false,
+      windowsHide: true,
+    });
+  } catch (error) {
+    throw new Error("could not start the macOS verification idle-sleep guard", { cause: error });
+  }
+  return await new Promise((resolvePromise, rejectPromise) => {
+    child.once("error", (error) => {
+      rejectPromise(new Error("could not start the macOS verification idle-sleep guard", { cause: error }));
+    });
+    child.once("close", (code, signal) => {
+      if (Number.isInteger(code)) resolvePromise(code);
+      else rejectPromise(new Error(`macOS verification idle-sleep guard ended by signal ${signal || "unknown"}`));
+    });
+  });
+}

package/scripts/verification-state.mjs

@@ -0,0 +1,108 @@
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { captureCoverageGeneration } from "./coverage-generation.mjs";
+import { replaceFileAtomicallySync } from "../src/local/exclusive-file.mjs";
+import { readBoundedRegularFileWithInfoSync } from "../src/local/secure-file.mjs";
+
+const RECEIPT_SCHEMA_VERSION = 1;
+const RECEIPT_MAX_BYTES = 16 * 1024;
+export const FULL_VERIFICATION_RECEIPT_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+const VERIFICATION_RUN_GENERATION_OPTIONS = {
+  roots: ["src", "scripts", "tests", "browser-extension", ".github", "docs", "bin", "native", "release-acceptance", ".release-candidate"],
+  files: [
+    "package.json", "package-lock.json", "tsconfig.json", "tsconfig.local.json", "wrangler.jsonc", "eslint.config.mjs",
+    ".npmrc", ".node-version", ".nvmrc", ".gitattributes", ".gitignore", ".privacy-denylist", ".privacy-denylist.example",
+    "mbm", "mbm.cmd", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", "LICENSE",
+    "CODE_OF_CONDUCT.md", "GOVERNANCE.md", "SUPPORT.md", "AGENTS.md",
+  ],
+};
+
+const VERIFIED_SOURCE_GENERATION_OPTIONS = {
+  ...VERIFICATION_RUN_GENERATION_OPTIONS,
+  roots: VERIFICATION_RUN_GENERATION_OPTIONS.roots.filter((name) => name !== ".release-candidate"),
+};
+
+export function captureVerificationRunGeneration(root) {
+  return captureCoverageGeneration(root, VERIFICATION_RUN_GENERATION_OPTIONS);
+}
+
+export function captureVerifiedSourceGeneration(root) {
+  return captureCoverageGeneration(root, VERIFIED_SOURCE_GENERATION_OPTIONS);
+}
+
+export function fullVerificationReceiptPath(root) {
+  return join(root, ".project-local", "full-verification.json");
+}
+
+export function clearFullVerificationReceipt(root) {
+  rmSync(fullVerificationReceiptPath(root), { force: true });
+}
+
+export function writeFullVerificationReceipt(root, generation, options = {}) {
+  if (!/^[0-9a-f]{64}$/.test(String(generation || ""))) throw new TypeError("full verification generation must be a SHA-256 digest");
+  const pkg = readPackage(root);
+  const verifiedAtMs = Number(options.now ?? Date.now());
+  if (!Number.isFinite(verifiedAtMs)) throw new TypeError("full verification receipt timestamp must be finite");
+  const receipt = {
+    schema_version: RECEIPT_SCHEMA_VERSION,
+    mode: "full",
+    generation_sha256: generation,
+    package_name: pkg.name,
+    package_version: pkg.version,
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    verified_at: new Date(verifiedAtMs).toISOString(),
+  };
+  const path = fullVerificationReceiptPath(root);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  replaceFileAtomicallySync(path, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+  return receipt;
+}
+
+export function assertFreshFullVerificationReceipt(root, options = {}) {
+  const path = fullVerificationReceiptPath(root);
+  let receipt;
+  try {
+    const snapshot = readBoundedRegularFileWithInfoSync(path, RECEIPT_MAX_BYTES, "full verification receipt", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+    receipt = JSON.parse(snapshot.buffer.toString("utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") throw staleReceiptError("full verification receipt is missing");
+    throw staleReceiptError(`full verification receipt is unreadable or invalid: ${error.message}`);
+  }
+  const pkg = readPackage(root);
+  const generation = (options.captureGeneration || captureVerifiedSourceGeneration)(root);
+  const now = Number(options.now ?? Date.now());
+  const verifiedAt = Date.parse(String(receipt?.verified_at || ""));
+  const maximumAgeMs = Number(options.maximumAgeMs ?? FULL_VERIFICATION_RECEIPT_MAX_AGE_MS);
+  const valid = receipt?.schema_version === RECEIPT_SCHEMA_VERSION
+    && receipt?.mode === "full"
+    && receipt?.generation_sha256 === generation
+    && receipt?.package_name === pkg.name
+    && receipt?.package_version === pkg.version
+    && receipt?.node_version === process.version
+    && receipt?.platform === process.platform
+    && receipt?.arch === process.arch
+    && Number.isFinite(verifiedAt)
+    && Number.isFinite(now)
+    && Number.isFinite(maximumAgeMs)
+    && maximumAgeMs >= 0
+    && now >= verifiedAt
+    && now - verifiedAt <= maximumAgeMs;
+  if (!valid) throw staleReceiptError("full verification receipt does not match the current source, runtime, or freshness window");
+  return receipt;
+}
+
+function readPackage(root) {
+  return JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+}
+
+function staleReceiptError(reason) {
+  const error = new Error(`${reason}; run npm run check:full on the frozen tree before release:candidate`);
+  error.code = "MBM_FULL_VERIFICATION_REQUIRED";
+  return error;
+}