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

package/scripts/official-mcp-conformance.mjs

@@ -0,0 +1,267 @@
+import { createServer } from "node:http";
+import { lstatSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { runExecutable } from "../src/local/shell.mjs";
+import { nestedNpmEnvironment } from "../src/local/npm-environment.mjs";
+import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+
+const MAX_PROXY_REQUEST_BYTES = 16 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export async function runOfficialMcpConformance(options) {
+  const checkout = validateConformanceCheckout(options.checkout);
+  const upstream = validatedUpstream(options.upstream);
+  const accessToken = boundedSecret(options.accessToken, "access token", 16 * 1024);
+  const scenario = requiredText(options.scenario, "conformance scenario");
+  const specVersion = String(options.specVersion || "2026-07-28");
+  const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS);
+  const proxy = await startBearerProxy({ upstream, accessToken });
+  try {
+    const npmCli = requiredText(process.env.npm_execpath, "npm_execpath");
+    const result = await runCommand({
+      command: process.execPath,
+      args: [
+        npmCli, "start", "--workspaces=false", "--global=false", "--ignore-scripts=false", "--if-present=false", "--prefix", checkout, "--", "server", "--url", `${proxy.origin}/mcp`,
+        "--scenario", scenario, "--spec-version", specVersion,
+        ...(options.expectedFailures ? ["--expected-failures", String(options.expectedFailures)] : []),
+        ...(options.verbose === true ? ["--verbose"] : []),
+      ],
+      cwd: checkout,
+      timeoutMs,
+    });
+    return Object.freeze({ ...result, scenario, specVersion, proxyOrigin: proxy.origin });
+  } finally {
+    await proxy.close();
+  }
+}
+
+async function startBearerProxy({ upstream, accessToken }) {
+  const server = createServer((request, response) => {
+    void proxyRequest(request, response, upstream, accessToken);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("conformance proxy did not bind a TCP port");
+  return {
+    origin: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => { if (error) reject(error); else resolve(); });
+      server.closeAllConnections?.();
+    }),
+  };
+}
+
+async function proxyRequest(request, response, upstream, accessToken) {
+  const controller = new AbortController();
+  request.once("aborted", () => controller.abort());
+  response.once("close", () => { if (!response.writableEnded) controller.abort(); });
+  try {
+    const body = await readBoundedBody(request, MAX_PROXY_REQUEST_BYTES);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+      if (value === undefined || ["host", "connection", "content-length", "transfer-encoding"].includes(name.toLowerCase())) continue;
+      if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+      else headers.set(name, value);
+    }
+    headers.set("authorization", `Bearer ${accessToken}`);
+    const target = conformanceProxyTarget(request.url, upstream);
+    const upstreamResponse = await fetch(target, {
+      method: request.method,
+      headers,
+      body: body.length ? body : undefined,
+      signal: controller.signal,
+      redirect: "manual",
+    });
+    const responseHeaders = {};
+    upstreamResponse.headers.forEach((value, name) => {
+      if (!["connection", "content-encoding", "content-length", "transfer-encoding"].includes(name.toLowerCase())) responseHeaders[name] = value;
+    });
+    response.writeHead(upstreamResponse.status, responseHeaders);
+    if (!upstreamResponse.body) return response.end();
+    const reader = upstreamResponse.body.getReader();
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value && !response.write(Buffer.from(value))) {
+          await new Promise((resolve) => { response.once("drain", resolve); });
+        }
+      }
+      response.end();
+    } finally {
+      reader.releaseLock();
+    }
+  } catch (error) {
+    if (controller.signal.aborted) return response.destroy();
+    if (!response.headersSent) response.writeHead(error?.code === "request_too_large" ? 413 : 502, { "content-type": "application/json" });
+    response.end(JSON.stringify({ error: "conformance_proxy_failure" }));
+  }
+}
+
+function readBoundedBody(request, maximumBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      request.removeListener("data", onData);
+      request.removeListener("end", onEnd);
+      request.removeListener("aborted", onAborted);
+      request.removeListener("error", onError);
+      callback(value);
+    };
+    const onData = (chunk) => {
+      bytes += chunk.length;
+      if (bytes > maximumBytes) {
+        const error = new Error("conformance proxy request is too large");
+        error.code = "request_too_large";
+        finish(reject, error);
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    };
+    const onEnd = () => finish(resolve, Buffer.concat(chunks, bytes));
+    const onAborted = () => finish(reject, proxyInputError("conformance proxy request was aborted"));
+    const onError = (error) => finish(reject, error);
+    request.on("data", onData);
+    request.once("end", onEnd);
+    request.once("aborted", onAborted);
+    request.once("error", onError);
+  });
+}
+
+async function runCommand({ command, args, cwd, timeoutMs }) {
+  const result = await runExecutable(command, args, {
+    cwd,
+    env: { ...nestedNpmEnvironment(process.env), NO_COLOR: "1", CI: "1" },
+    capture: true,
+    allowFailure: true,
+    timeoutMs,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  return Object.freeze({ ...result, signal: null });
+}
+
+export function validateConformanceCheckout(value, options = {}) {
+  const inspect = options.lstatSync || lstatSync;
+  const canonicalize = options.realpathSync || realpathSync.native;
+  const readBounded = options.readBoundedRegularFileSync || readBoundedRegularFileSync;
+  const requested = resolve(requiredText(value, "conformance checkout"));
+  const requestedInfo = inspectConformancePath(requested, "conformance checkout", inspect);
+  if (!requestedInfo) throw new Error("conformance checkout does not exist");
+  if (requestedInfo.isSymbolicLink() || !requestedInfo.isDirectory()) {
+    throw new Error("conformance checkout must be a real directory");
+  }
+  const checkout = canonicalize(requested);
+  for (const file of ["package.json", "package-lock.json"]) {
+    const path = join(checkout, file);
+    const info = inspectConformancePath(path, `conformance checkout ${file}`, inspect);
+    if (!info) throw new Error(`conformance checkout omits ${file}`);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error(`conformance checkout ${file} must be a regular file`);
+  }
+  let packageState;
+  try {
+    packageState = JSON.parse(readBounded(join(checkout, "package.json"), 1024 * 1024, "conformance checkout package.json", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }).toString("utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error("conformance checkout package.json is invalid", { cause: error });
+    throw error;
+  }
+  if (typeof packageState?.scripts?.start !== "string" || !packageState.scripts.start.trim()) {
+    throw new Error("conformance checkout omits its start command");
+  }
+  const nodeModules = join(checkout, "node_modules");
+  const nodeModulesInfo = inspectConformancePath(nodeModules, "conformance checkout node_modules", inspect);
+  if (!nodeModulesInfo) {
+    throw new Error("conformance checkout dependencies are not installed; run npm ci --ignore-scripts in the checkout");
+  }
+  if (nodeModulesInfo.isSymbolicLink() || !nodeModulesInfo.isDirectory()) {
+    throw new Error("conformance checkout node_modules must be a real directory");
+  }
+  return checkout;
+}
+
+function inspectConformancePath(path, label, inspect) {
+  try { return inspect(path); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`${label} could not be inspected`, { cause: error });
+  }
+}
+
+export function conformanceProxyTarget(requestTarget, upstream) {
+  const raw = String(requestTarget || "/mcp");
+  if (Buffer.byteLength(raw) > 8192) throw proxyInputError("conformance proxy request target is too large");
+  let parsed;
+  try { parsed = new URL(raw, "http://proxy.invalid"); }
+  catch { throw proxyInputError("conformance proxy request target is invalid"); }
+  if (parsed.origin !== "http://proxy.invalid" || parsed.hash) {
+    throw proxyInputError("conformance proxy requires a relative request target");
+  }
+  if (parsed.pathname !== "/mcp") throw proxyInputError("conformance proxy accepts only its MCP endpoint");
+  const target = new URL(upstream.href);
+  if (parsed.search) target.search = parsed.search;
+  return target;
+}
+
+function validatedUpstream(value) {
+  let upstream;
+  try { upstream = new URL(requiredText(value, "upstream MCP URL")); }
+  catch { throw new Error("upstream MCP URL is invalid"); }
+  if (upstream.username || upstream.password || upstream.hash) throw new Error("upstream MCP URL must not contain credentials or a fragment");
+  const loopback = upstream.hostname === "localhost" || upstream.hostname === "127.0.0.1" || upstream.hostname === "[::1]";
+  if (upstream.protocol !== "https:" && !(upstream.protocol === "http:" && loopback)) {
+    throw new Error("upstream MCP URL must use HTTPS or loopback HTTP");
+  }
+  return upstream;
+}
+
+function boundedSecret(value, label, maximumBytes) {
+  const text = requiredText(value, label);
+  if (Buffer.byteLength(text) > maximumBytes) throw new Error(`${label} is too large`);
+  return text;
+}
+
+function proxyInputError(message) {
+  const error = new Error(message);
+  error.code = "invalid_proxy_input";
+  return error;
+}
+
+function requiredText(value, label) {
+  const text = String(value || "").trim();
+  if (!text) throw new Error(`${label} is required`);
+  return text;
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : fallback;
+}
+
+async function main() {
+  const result = await runOfficialMcpConformance({
+    checkout: process.env.MBM_OFFICIAL_CONFORMANCE_CHECKOUT,
+    upstream: process.env.MBM_OFFICIAL_CONFORMANCE_UPSTREAM,
+    accessToken: process.env.MBM_OFFICIAL_CONFORMANCE_ACCESS_TOKEN,
+    scenario: process.env.MBM_OFFICIAL_CONFORMANCE_SCENARIO,
+    specVersion: process.env.MBM_OFFICIAL_CONFORMANCE_SPEC_VERSION || "2026-07-28",
+    timeoutMs: process.env.MBM_OFFICIAL_CONFORMANCE_TIMEOUT_MS,
+    verbose: process.env.MBM_OFFICIAL_CONFORMANCE_VERBOSE === "1",
+    expectedFailures: process.env.MBM_OFFICIAL_CONFORMANCE_BASELINE,
+  });
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  process.exitCode = result.code;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) await main();

package/scripts/persistent-activation-process.mjs

@@ -0,0 +1,101 @@
+import { normalizeActivationRecovery } from "../src/shared/activation-recovery.mjs";
+import { EXECUTION_SURFACE, executionSurface } from "../src/local/execution-surface.mjs";
+import { runWrangler as defaultRunWrangler } from "../src/local/shell.mjs";
+
+export function assertPersistentActivationExecutionSurface(environment = process.env) {
+  const surface = executionSurface(environment);
+  if (!surface || surface === EXECUTION_SURFACE.managedJob) return surface || "local";
+  const error = new Error(
+    `persistent activation cannot run from ${surface}; use a durable managed job or an ordinary local terminal because activation intentionally replaces the current Machine Bridge daemon`,
+  );
+  error.code = "unsafe_activation_execution_surface";
+  error.sideEffectsStarted = false;
+  throw error;
+}
+
+export function persistentActivationSpawnOptions({ cwd, env = process.env } = {}) {
+  if (typeof cwd !== "string" || !cwd) {
+    throw new TypeError("persistent activation subprocess requires cwd");
+  }
+  if (!env || typeof env !== "object" || Array.isArray(env)) {
+    throw new TypeError("persistent activation subprocess requires an environment record");
+  }
+  // The activation child owns bounded deployment, network, relay, and service
+  // stages plus transactional cleanup. An outer timeout could SIGKILL the child
+  // while detached helpers remain alive and before compensation releases locks.
+  return { cwd, env, encoding: "utf8", windowsHide: true };
+}
+
+export async function preflightPersistentActivationWorkerAuth({
+  surface = "local",
+  stateRoot,
+  packageRoot,
+  npmCli,
+  env = process.env,
+  runWrangler = defaultRunWrangler,
+} = {}) {
+  if (surface !== "local" && surface !== EXECUTION_SURFACE.managedJob) {
+    throw new TypeError("persistent activation Wrangler preflight requires a local or managed-job execution surface");
+  }
+  if (typeof stateRoot !== "string" || !stateRoot) throw new TypeError("persistent activation Wrangler preflight requires stateRoot");
+  if (typeof packageRoot !== "string" || !packageRoot) throw new TypeError("persistent activation Wrangler preflight requires packageRoot");
+  if (typeof runWrangler !== "function") throw new TypeError("persistent activation Wrangler preflight requires runWrangler");
+  const shared = { stateRoot, packageRoot, npmCli, env };
+  const whoami = await runWrangler(["whoami"], { ...shared, capture: true, allowFailure: true });
+  if (whoami?.code === 0) return { authenticated: true, login_performed: false };
+  if (surface === EXECUTION_SURFACE.managedJob) throw workerAuthenticationRequiredError(
+    "persistent activation cannot start interactive Wrangler login from a detached managed job; authenticate Cloudflare Wrangler in an ordinary owner terminal before retrying",
+  );
+  await runWrangler(["login"], shared);
+  const verified = await runWrangler(["whoami"], { ...shared, capture: true, allowFailure: true });
+  if (verified?.code !== 0) throw workerAuthenticationRequiredError(
+    "Cloudflare Wrangler login completed without a verifiable authenticated session; the persistent activation was not started",
+  );
+  return { authenticated: true, login_performed: true };
+}
+
+export function persistentCandidateFailureMessage(output, { cli, stateRoot, previousRuntime = null } = {}) {
+  const detail = String(output || "").trim() || "activation subprocess exited unsuccessfully";
+  if (!/foreground daemon is active/i.test(detail)) return `persistent candidate activation failed: ${detail}`;
+  const quotedCli = JSON.stringify(String(cli || "machine-mcp"));
+  const quotedStateRoot = JSON.stringify(String(stateRoot || ""));
+  const recovery = previousRuntime?.cli && previousRuntime?.pid
+    ? [
+      `Verified foreground runtime: ${previousRuntime.version || "unknown"} (pid ${previousRuntime.pid}).`,
+      "Stop that foreground daemon, then restore its existing login service with:",
+      `node ${JSON.stringify(previousRuntime.cli)} service start`,
+      `node ${quotedCli} service status --workspace ${JSON.stringify(previousRuntime.workspace)} --state-dir ${quotedStateRoot}`,
+      "Retry candidate activation only after status reports provider active and a verified service daemon for that workspace.",
+    ]
+    : [
+      "The foreground runtime could not be independently resolved to a trusted installed CLI.",
+      "Keep it running and inspect its daemon lock and command line before attempting a manual service recovery.",
+    ];
+  return [
+    `persistent candidate activation failed: ${detail}`,
+    "No Worker deployment or service replacement was started.",
+    ...recovery,
+  ].join("\n");
+}
+
+export function validateActivationRecoveryPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("persistent activation result is invalid");
+  }
+  try {
+    return normalizeActivationRecovery({
+      recovered: value.activation_recovered,
+      reason: value.activation_recovery_reason,
+      detail: value.activation_recovery_detail,
+    });
+  } catch (error) {
+    throw new Error(`persistent ${String(error?.message || "activation recovery metadata is invalid")}`, { cause: error });
+  }
+}
+
+function workerAuthenticationRequiredError(message) {
+  const error = new Error(message);
+  error.code = "worker_authentication_required";
+  error.sideEffectsStarted = false;
+  return error;
+}

package/scripts/prepare-pinned-npm.mjs

@@ -1,89 +1,32 @@
-import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-
-const NPM_VERSION = "12.0.1";
-const NPM_TARBALL_URL = "https://registry.npmjs.org/npm/-/npm-12.0.1.tgz";
-const NPM_TARBALL_INTEGRITY = "sha512-L5T9i/YAQWQWqTS/xZxJkei/9zcu99hCeE4qi41IyBVV7mRQad3qc2JfuOktwmH+qwGI/V2rbCL+/UYxb1+RQA==";
-const MAX_TARBALL_BYTES = 20 * 1024 * 1024;
+import { prepareHardenedNpm } from "../src/local/hardened-npm.mjs";
 
 const githubPath = process.env.GITHUB_PATH;
 if (!githubPath) throw new Error("GITHUB_PATH is required; this bootstrap is intended for GitHub Actions");
 
 const root = mkdtempSync(join(process.env.RUNNER_TEMP || tmpdir(), "mbm-npm-bootstrap-"));
 try {
-  const archive = join(root, `npm-${NPM_VERSION}.tgz`);
-  const extracted = join(root, "extracted");
+  const hardened = join(root, "hardened");
   const bin = join(root, "bin");
-  mkdirSync(extracted, { recursive: true });
   mkdirSync(bin, { recursive: true });
-
-  const response = await fetch(NPM_TARBALL_URL, { redirect: "error" });
-  if (!response.ok) throw new Error(`failed to download pinned npm tarball: HTTP ${response.status}`);
-  const declaredBytes = Number(response.headers.get("content-length"));
-  if (Number.isFinite(declaredBytes) && declaredBytes > MAX_TARBALL_BYTES) throw new Error("pinned npm tarball exceeds 20 MiB");
-  const bytes = await readBoundedBody(response, MAX_TARBALL_BYTES);
-  verifyIntegrity(bytes, NPM_TARBALL_INTEGRITY);
-  writeFileSync(archive, bytes, { mode: 0o600 });
-
-  run("tar", ["-xzf", archive, "-C", extracted]);
-  const cli = join(extracted, "package", "bin", "npm-cli.js");
-  const version = run(process.execPath, [cli, "--version"], { capture: true }).trim();
-  if (version !== NPM_VERSION) throw new Error(`pinned npm tarball reported ${version}, expected ${NPM_VERSION}`);
+  const prepared = await prepareHardenedNpm(hardened);
 
   const posixWrapper = join(bin, "npm");
-  writeFileSync(posixWrapper, `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(cli)} "$@"\n`, { mode: 0o755 });
+  writeFileSync(posixWrapper, `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(prepared.cli)} "$@"\n`, { mode: 0o755 });
   chmodSync(posixWrapper, 0o755);
-  writeFileSync(join(bin, "npm.cmd"), `@echo off\r\n"${cmdQuote(process.execPath)}" "${cmdQuote(cli)}" %*\r\n`);
+  writeFileSync(join(bin, "npm.cmd"), `@echo off\r\n"${cmdQuote(process.execPath)}" "${cmdQuote(prepared.cli)}" %*\r\n`);
   writeFileSync(githubPath, `${bin}\n`, { flag: "a" });
-  console.log(`Prepared integrity-verified npm ${NPM_VERSION} at ${bin}`);
+  console.log(`Prepared integrity-verified hardened npm ${prepared.version} (undici ${prepared.undiciVersion}; brace-expansion ${prepared.braceExpansionVersion}) at ${bin}`);
 } catch (error) {
-  rmSync(root, { recursive: true, force: true });
-  throw error;
-}
-
-
-async function readBoundedBody(response, maximumBytes) {
-  if (!response.body) throw new Error("pinned npm tarball response has no body");
-  const reader = response.body.getReader();
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > maximumBytes) throw new Error("pinned npm tarball exceeds 20 MiB");
-      chunks.push(Buffer.from(value));
-    }
-  } finally {
-    reader.releaseLock();
+  let cleanupError = null;
+  try { rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 }); }
+  catch (failure) { cleanupError = failure; }
+  if (cleanupError) {
+    throw new AggregateError([error, cleanupError], "pinned npm bootstrap failed and temporary cleanup was incomplete");
   }
-  return Buffer.concat(chunks, total);
-}
-
-function verifyIntegrity(bytes, integrity) {
-  const match = /^sha512-(.+)$/.exec(integrity);
-  if (!match) throw new Error("pinned npm integrity must be SHA-512 SRI");
-  const actual = createHash("sha512").update(bytes).digest();
-  const expected = Buffer.from(match[1], "base64");
-  if (actual.length !== expected.length || !actual.equals(expected)) throw new Error("pinned npm tarball failed SHA-512 verification");
-}
-
-function run(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    encoding: options.capture ? "utf8" : undefined,
-    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
-    shell: false,
-  });
-  if (result.error) throw result.error;
-  if (result.status !== 0) {
-    const detail = options.capture ? String(result.stderr || result.stdout || "").trim() : "";
-    throw new Error(`${command} exited ${result.status}${detail ? `: ${detail}` : ""}`);
-  }
-  return options.capture ? String(result.stdout || "") : "";
+  throw error;
 }
 
 function shellQuote(value) {

package/scripts/prerelease-activation.mjs

@@ -0,0 +1,160 @@
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { defaultStateRoot, expandHome } from "../src/local/state.mjs";
+import { replaceFileAtomicallySync } from "../src/local/exclusive-file.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { normalizeActivationRecovery as normalizeSharedActivationRecovery } from "../src/shared/activation-recovery.mjs";
+import { assertSoakEligiblePrerelease } from "./release-channel.mjs";
+
+export const ACTIVATION_SCHEMA_VERSION = 2;
+const MAX_ACTIVATION_BYTES = 64 * 1024;
+const SOURCES = new Set(["local-candidate", "npm-prerelease"]);
+const ACTIVATION_FIELDS = new Set([
+  "schema_version", "package_name", "package_version", "source", "shasum", "integrity",
+  "promotion_content_sha256", "activated_at", "npm_dist_tag", "published_at", "workspace_hash",
+  "runtime_entry", "activation_recovered", "activation_recovery_reason", "activation_recovery_detail",
+  "global_package_rollback_baseline",
+]);
+
+export function prereleaseActivationPath(version, stateRoot = defaultStateRoot()) {
+  const parsed = assertSoakEligiblePrerelease(version);
+  return join(resolve(expandHome(stateRoot)), "release-channels", "activations", `v${parsed.raw}.json`);
+}
+
+export function writePrereleaseActivation(record, stateRoot = defaultStateRoot()) {
+  const normalized = validatePrereleaseActivation(record);
+  const file = prereleaseActivationPath(normalized.package_version, stateRoot);
+  ensureOwnerOnlyDirectorySync(dirname(file));
+  replaceFileAtomicallySync(file, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+export function readPrereleaseActivation(version, stateRoot = defaultStateRoot(), options = {}) {
+  const file = prereleaseActivationPath(version, stateRoot);
+  const readRecord = options.readBoundedRegularFileSync || readBoundedRegularFileSync;
+  let bytes;
+  try {
+    bytes = readRecord(file, MAX_ACTIVATION_BYTES, "prerelease activation record", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`prerelease activation record is missing: ${file}`, { cause: error });
+    throw new Error("prerelease activation record is unavailable", { cause: error });
+  }
+  let value;
+  try { value = JSON.parse(bytes.toString("utf8")); }
+  catch (error) { throw new Error("prerelease activation record is invalid", { cause: error }); }
+  return validatePrereleaseActivation(value);
+}
+
+export function assertPrereleaseActivationRuntimeRoot(activation, runtimeRoot, options = {}) {
+  const runtimeEntry = String(activation?.runtime_entry || "");
+  if (!runtimeEntry || !isAbsolute(runtimeEntry)) throw new Error("prerelease activation runtime entry is missing");
+  const executingRoot = String(runtimeRoot || "");
+  if (!executingRoot || !isAbsolute(executingRoot)) throw new Error("executing canary runtime root is invalid");
+  const canonicalize = options.realpathSync || realpathSync;
+  let activatedRoot;
+  let canonicalExecutingRoot;
+  try {
+    activatedRoot = canonicalize(resolve(dirname(runtimeEntry), ".."));
+    canonicalExecutingRoot = canonicalize(resolve(executingRoot));
+  } catch (error) {
+    throw new Error("prerelease activation runtime package identity is unavailable", { cause: error });
+  }
+  const platform = String(options.platform || process.platform);
+  const same = platform === "win32"
+    ? activatedRoot.toLowerCase() === canonicalExecutingRoot.toLowerCase()
+    : activatedRoot === canonicalExecutingRoot;
+  if (!same) throw new Error("prerelease activation runtime package does not match the executing canary");
+  return canonicalExecutingRoot;
+}
+
+export function validatePrereleaseActivation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("prerelease activation record must be an object");
+  const unknown = Object.keys(value).filter((key) => !ACTIVATION_FIELDS.has(key));
+  if (unknown.length) throw new Error(`prerelease activation record contains unsupported fields: ${unknown.join(", ")}`);
+  const schemaVersion = value.schema_version;
+  if (schemaVersion !== ACTIVATION_SCHEMA_VERSION) {
+    throw new Error("unsupported prerelease activation schema");
+  }
+  const parsed = assertSoakEligiblePrerelease(value.package_version);
+  if (value.package_name !== "machine-bridge-mcp") throw new Error("prerelease activation package name is invalid");
+  if (!SOURCES.has(value.source)) throw new Error("prerelease activation source is invalid");
+  if (!/^[0-9a-f]{40}$/.test(String(value.shasum || ""))) throw new Error("prerelease activation SHA-1 is invalid");
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(String(value.integrity || ""))) throw new Error("prerelease activation integrity is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(value.promotion_content_sha256 || ""))) throw new Error("prerelease activation promotion digest is invalid");
+  const activatedAt = Date.parse(String(value.activated_at || ""));
+  if (!Number.isFinite(activatedAt)) throw new Error("prerelease activation timestamp is invalid");
+  if (value.source === "npm-prerelease") {
+    if (value.npm_dist_tag !== parsed.npmTag) throw new Error("prerelease activation npm dist-tag is invalid");
+    const publishedAt = Date.parse(String(value.published_at || ""));
+    if (!Number.isFinite(publishedAt) || publishedAt > activatedAt + 5 * 60 * 1000) throw new Error("prerelease activation publication timestamp is invalid");
+  }
+  const workspaceHash = String(value.workspace_hash || "");
+  if (workspaceHash && !/^[0-9a-f]{24}$/.test(workspaceHash)) throw new Error("prerelease activation workspace hash is invalid");
+  const runtimeEntry = String(value.runtime_entry || "");
+  if (runtimeEntry && !isAbsolute(runtimeEntry)) throw new Error("prerelease activation runtime entry must be absolute");
+  const activationRecovery = normalizeActivationRecovery(value);
+  const globalPackageRollbackBaseline = value.global_package_rollback_baseline === undefined
+    ? undefined
+    : validateGlobalPackageRollbackBaseline(value.global_package_rollback_baseline);
+  return Object.freeze({
+    schema_version: ACTIVATION_SCHEMA_VERSION,
+    package_name: value.package_name,
+    package_version: parsed.raw,
+    source: value.source,
+    shasum: value.shasum,
+    integrity: value.integrity,
+    promotion_content_sha256: value.promotion_content_sha256,
+    activated_at: new Date(activatedAt).toISOString(),
+    ...(value.source === "npm-prerelease" ? {
+      npm_dist_tag: value.npm_dist_tag,
+      published_at: new Date(Date.parse(value.published_at)).toISOString(),
+    } : {}),
+    ...(workspaceHash ? { workspace_hash: workspaceHash } : {}),
+    ...(runtimeEntry ? { runtime_entry: runtimeEntry } : {}),
+    ...activationRecovery,
+    ...(globalPackageRollbackBaseline ? { global_package_rollback_baseline: globalPackageRollbackBaseline } : {}),
+  });
+}
+
+function normalizeActivationRecovery(value) {
+  if (value.activation_recovered !== undefined && typeof value.activation_recovered !== "boolean") {
+    throw new Error("prerelease activation recovery flag is invalid");
+  }
+  if (value.activation_recovered !== true
+      && (String(value.activation_recovery_reason || "") || String(value.activation_recovery_detail || ""))) {
+    throw new Error("prerelease activation recovery metadata requires a recovered activation");
+  }
+  let normalized;
+  try {
+    normalized = normalizeSharedActivationRecovery({
+      recovered: value.activation_recovered === true,
+      reason: value.activation_recovery_reason,
+      detail: value.activation_recovery_detail,
+    });
+  } catch (error) {
+    const message = String(error?.message || "activation recovery metadata is invalid")
+      .replace(/^activation recovery /, "prerelease activation recovery ");
+    throw new Error(message, { cause: error });
+  }
+  if (!normalized.recovered) return Object.freeze({});
+  return Object.freeze({
+    activation_recovered: true,
+    activation_recovery_reason: normalized.reason,
+    activation_recovery_detail: normalized.detail,
+  });
+}
+
+function validateGlobalPackageRollbackBaseline(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("prerelease activation global package rollback baseline is invalid");
+  }
+  const version = String(value.version || "");
+  const entry = String(value.entry || "");
+  if (!version || !entry || !isAbsolute(entry)) {
+    throw new Error("prerelease activation global package rollback baseline is invalid");
+  }
+  return Object.freeze({ version, entry });
+}