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

package/scripts/published-release.mjs

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import { resolveTrustedGithubCli } from "../src/local/trusted-github-cli.mjs";
+
+export function readPublishedNpmPrerelease(name, version, distTag, options = {}) {
+  const run = options.run || runNpmView;
+  const actualVersion = run([`${name}@${version}`, "version", "--json"]);
+  const integrity = run([`${name}@${version}`, "dist.integrity", "--json"]);
+  const shasum = run([`${name}@${version}`, "dist.shasum", "--json"]);
+  const tags = run([name, "dist-tags", "--json"]);
+  const times = run([name, "time", "--json"]);
+  return normalizePublishedNpmPrerelease({
+    requestedVersion: version,
+    requestedTag: distTag,
+    actualVersion,
+    integrity,
+    shasum,
+    tags,
+    times,
+  });
+}
+
+export function normalizePublishedNpmPrerelease(value) {
+  const actualVersion = unwrapNpmJsonValue(value.actualVersion);
+  const tags = unwrapNpmJsonValue(value.tags);
+  const times = unwrapNpmJsonValue(value.times);
+  const version = String(actualVersion || "");
+  const requestedVersion = String(value.requestedVersion || "");
+  const distTag = String(value.requestedTag || "");
+  const integrity = String(unwrapNpmJsonValue(value.integrity) || "");
+  const shasum = String(unwrapNpmJsonValue(value.shasum) || "");
+  const publishedAt = String(times?.[requestedVersion] || "");
+  if (version !== requestedVersion) throw new Error("npm registry returned another prerelease version");
+  if (tags?.[distTag] !== requestedVersion) throw new Error(`npm dist-tag ${distTag} does not point to ${requestedVersion}`);
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(integrity)) throw new Error("npm prerelease integrity is invalid");
+  if (!/^[0-9a-f]{40}$/.test(shasum)) throw new Error("npm prerelease SHA-1 is invalid");
+  if (!Number.isFinite(Date.parse(publishedAt))) throw new Error("npm prerelease publication timestamp is invalid");
+  return Object.freeze({ version, integrity, shasum, distTag, publishedAt: new Date(Date.parse(publishedAt)).toISOString() });
+}
+
+function unwrapNpmJsonValue(value) {
+  return Array.isArray(value) && value.length === 1 ? value[0] : value;
+}
+
+export function readGithubPrerelease(version, options = {}) {
+  const run = options.run || runGh;
+  const value = run(["release", "view", `v${version}`, "--json", "tagName,isPrerelease,publishedAt,assets"]);
+  return normalizeGithubPrerelease(value, version);
+}
+
+export function normalizeGithubPrerelease(value, version) {
+  const tag = String(value?.tagName || "");
+  const publishedAt = String(value?.publishedAt || "");
+  if (tag !== `v${version}` || value?.isPrerelease !== true) throw new Error("GitHub prerelease is missing or not marked as a prerelease");
+  if (!Number.isFinite(Date.parse(publishedAt))) throw new Error("GitHub prerelease publication timestamp is invalid");
+  if (!Array.isArray(value?.assets)) throw new Error("GitHub prerelease asset inventory is unavailable");
+  const expectedAsset = `machine-bridge-mcp-${version}.tgz`;
+  const asset = value.assets.find((entry) => entry && typeof entry === "object" && entry.name === expectedAsset);
+  if (!asset) throw new Error(`GitHub prerelease is missing ${expectedAsset}`);
+  const size = Number(asset.size);
+  if (!Number.isSafeInteger(size) || size < 1) throw new Error("GitHub prerelease package asset size is invalid");
+  return Object.freeze({
+    tag,
+    isPrerelease: true,
+    publishedAt: new Date(Date.parse(publishedAt)).toISOString(),
+    asset: Object.freeze({ name: expectedAsset, size }),
+  });
+}
+
+function runNpmView(args) {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) throw new Error("npm registry verification must run through npm");
+  const result = spawnSync(process.execPath, [npmCli, "view", ...args], {
+    encoding: "utf8",
+    env: process.env,
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm view ${args[0]} failed: ${String(result.stderr || result.stdout).trim()}`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error(`npm view ${args[0]} returned invalid JSON`); }
+}
+
+function runGh(args) {
+  const result = spawnSync(resolveTrustedGithubCli({ workspace: process.cwd() }), args, { encoding: "utf8", env: process.env, windowsHide: true });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`gh ${args[0]} failed: ${String(result.stderr || result.stdout).trim()}`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error("GitHub prerelease query returned invalid JSON"); }
+}

package/scripts/release-acceptance.mjs

@@ -8,12 +8,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { compareReleaseVersions, parseReleaseVersion } from "./release-channel.mjs";
 
 export const ACCEPTANCE_SCHEMA_VERSION = 1;
 export const ACCEPTANCE_POLICY_VERSION = "1.2.8";
 export const AGENT_VERIFIED_ACCEPTANCE_VERSION = "1.2.9";
 export const AGENT_OPERATED_ACCEPTANCE_VERSION = "2.0.0";
 export const ACCEPTANCE_CONFIRMATION = "owner-authorized-agent-operated-local-candidate";
+export const PROMOTION_DIGEST_POLICY_VERSION = "3.0.0-beta.1";
+export const PERSISTENT_OWNER_ACTIVATED_ACCEPTANCE_VERSION = "3.0.0-beta.1";
+export const PERSISTENT_OWNER_ACTIVATED_CONFIRMATION = "owner-activated-agent-verified-persistent-candidate";
 export const OWNER_STARTED_ACCEPTANCE_CONFIRMATION = "owner-started-agent-verified-local-candidate";
 export const LEGACY_ACCEPTANCE_CONFIRMATION = "repository-owner-local-test";
 const MAX_ACCEPTANCE_BYTES = 64 * 1024;
@@ -25,6 +29,9 @@ export function requiresLocalAcceptance(version) {
 
 export function acceptanceConfirmationForVersion(version) {
   const parsed = parseVersion(version);
+  if (compareReleaseVersions(parseReleaseVersion(version), parseReleaseVersion(PERSISTENT_OWNER_ACTIVATED_ACCEPTANCE_VERSION)) >= 0) {
+    return PERSISTENT_OWNER_ACTIVATED_CONFIRMATION;
+  }
   if (compareVersions(parsed, parseVersion(AGENT_OPERATED_ACCEPTANCE_VERSION)) >= 0) return ACCEPTANCE_CONFIRMATION;
   if (compareVersions(parsed, parseVersion(AGENT_VERIFIED_ACCEPTANCE_VERSION)) >= 0) return OWNER_STARTED_ACCEPTANCE_CONFIRMATION;
   return LEGACY_ACCEPTANCE_CONFIRMATION;
@@ -105,6 +112,12 @@ export function verifyAcceptanceRecord(record, metadata) {
   if (!record || typeof record !== "object" || Array.isArray(record)) {
     throw new Error("release acceptance record must be an object");
   }
+  const allowed = new Set([
+    "schema_version", "result", "confirmation", "package_name", "package_version", "filename",
+    "shasum", "integrity", "accepted_at", "package_content_sha256", "promotion_content_sha256",
+  ]);
+  const unknown = Object.keys(record).filter((key) => !allowed.has(key));
+  if (unknown.length) throw new Error(`release acceptance record contains unsupported fields: ${unknown.join(", ")}`);
   if (record.schema_version !== ACCEPTANCE_SCHEMA_VERSION) {
     throw new Error(`unsupported release acceptance schema: ${record.schema_version}`);
   }
@@ -118,12 +131,28 @@ export function verifyAcceptanceRecord(record, metadata) {
   if (!/^[0-9a-f]{64}$/.test(String(record.package_content_sha256 || ""))) {
     throw new Error("local release acceptance portable package-content digest is missing or invalid");
   }
+  if (compareReleaseVersions(parseReleaseVersion(metadata.package_version), parseReleaseVersion(PROMOTION_DIGEST_POLICY_VERSION)) >= 0
+    && !/^[0-9a-f]{64}$/.test(String(record.promotion_content_sha256 || ""))) {
+    throw new Error("local release acceptance promotion-content digest is missing or invalid");
+  }
   for (const key of ["package_name", "package_version", "filename", "shasum", "integrity"]) {
     if (record[key] !== metadata[key]) {
       throw new Error(`local release acceptance ${key} does not match the current npm package`);
     }
   }
-  return record;
+  return Object.freeze({
+    schema_version: ACCEPTANCE_SCHEMA_VERSION,
+    result: "passed",
+    confirmation: expectedConfirmation,
+    package_name: metadata.package_name,
+    package_version: metadata.package_version,
+    filename: metadata.filename,
+    shasum: metadata.shasum,
+    integrity: metadata.integrity,
+    accepted_at: new Date(acceptedAt).toISOString(),
+    package_content_sha256: String(record.package_content_sha256),
+    ...(record.promotion_content_sha256 ? { promotion_content_sha256: String(record.promotion_content_sha256) } : {}),
+  });
 }
 
 export function verifyCurrentReleaseAcceptance(root) {

package/scripts/release-candidate-manifest.mjs

@@ -0,0 +1,40 @@
+import { parseReleaseVersion } from "./release-channel.mjs";
+
+export const CANDIDATE_MANIFEST_SCHEMA_VERSION = 1;
+const FIELDS = new Set([
+  "schema_version", "result", "package_name", "package_version", "filename", "shasum", "integrity",
+  "promotion_content_sha256", "prepared_at",
+]);
+
+export function validateCandidateManifest(value, expected = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("release candidate manifest must be an object");
+  const unknown = Object.keys(value).filter((key) => !FIELDS.has(key));
+  if (unknown.length) throw new Error(`release candidate manifest contains unsupported fields: ${unknown.join(", ")}`);
+  if (value.schema_version !== CANDIDATE_MANIFEST_SCHEMA_VERSION || value.result !== "pending") {
+    throw new Error("release candidate manifest is not pending current-schema state");
+  }
+  const version = parseReleaseVersion(value.package_version).raw;
+  const packageName = String(value.package_name || "");
+  if (packageName !== "machine-bridge-mcp") throw new Error("release candidate manifest package is invalid");
+  if (expected.packageName && packageName !== expected.packageName) throw new Error("release candidate manifest package does not match the current package");
+  if (expected.packageVersion && version !== expected.packageVersion) throw new Error("release candidate manifest version does not match the current package");
+  const filename = String(value.filename || "");
+  const expectedFilename = `${packageName}-${version}.tgz`;
+  if (filename !== expectedFilename) throw new Error(`release candidate manifest filename is invalid; expected ${expectedFilename}`);
+  if (!/^[0-9a-f]{40}$/.test(String(value.shasum || ""))) throw new Error("release candidate manifest SHA-1 is invalid");
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(String(value.integrity || ""))) throw new Error("release candidate manifest integrity is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(value.promotion_content_sha256 || ""))) throw new Error("release candidate promotion digest is invalid");
+  const preparedAt = Date.parse(String(value.prepared_at || ""));
+  if (!Number.isFinite(preparedAt)) throw new Error("release candidate preparation timestamp is invalid");
+  return Object.freeze({
+    schema_version: CANDIDATE_MANIFEST_SCHEMA_VERSION,
+    result: "pending",
+    package_name: packageName,
+    package_version: version,
+    filename,
+    shasum: String(value.shasum),
+    integrity: String(value.integrity),
+    promotion_content_sha256: String(value.promotion_content_sha256),
+    prepared_at: new Date(preparedAt).toISOString(),
+  });
+}

package/scripts/release-channel.mjs

@@ -0,0 +1,106 @@
+const CHANNEL_TAGS = Object.freeze({ dev: "dev", beta: "beta", rc: "next" });
+const SOAK_SECONDS = Object.freeze({ major: 7 * 24 * 60 * 60, minor: 3 * 24 * 60 * 60, patch: 24 * 60 * 60 });
+
+export const SOAK_POLICY_VERSION = "3.0.0";
+export const SOAK_CONFIRMATION = "owner-reported-published-prerelease-soak-passed";
+
+export function parseReleaseVersion(value) {
+  const raw = String(value || "").trim();
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z]+)\.(\d+))?$/.exec(raw);
+  if (!match) throw new Error(`release version must use x.y.z or x.y.z-(dev|beta|rc).n: ${raw || "<empty>"}`);
+  const channel = match[4] || "";
+  if (channel && !Object.hasOwn(CHANNEL_TAGS, channel)) {
+    throw new Error(`unsupported prerelease channel ${channel}; use dev, beta, or rc`);
+  }
+  const sequence = channel ? Number(match[5]) : 0;
+  if (channel && (!Number.isSafeInteger(sequence) || sequence < 1)) {
+    throw new Error("prerelease sequence must be a positive integer");
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  const patch = Number(match[3]);
+  for (const part of [major, minor, patch]) {
+    if (!Number.isSafeInteger(part) || part < 0) throw new Error("release version contains an invalid numeric component");
+  }
+  return Object.freeze({
+    raw,
+    major,
+    minor,
+    patch,
+    channel,
+    sequence,
+    prerelease: Boolean(channel),
+    baseVersion: `${major}.${minor}.${patch}`,
+    npmTag: channel ? CHANNEL_TAGS[channel] : "latest",
+  });
+}
+
+export function compareReleaseVersions(leftValue, rightValue) {
+  const left = typeof leftValue === "string" ? parseReleaseVersion(leftValue) : leftValue;
+  const right = typeof rightValue === "string" ? parseReleaseVersion(rightValue) : rightValue;
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] - right[key];
+  }
+  if (!left.prerelease && !right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  const channelOrder = { dev: 0, beta: 1, rc: 2 };
+  if (left.channel !== right.channel) return channelOrder[left.channel] - channelOrder[right.channel];
+  return left.sequence - right.sequence;
+}
+
+export function requiresSoakForStable(version) {
+  const parsed = parseReleaseVersion(version);
+  return !parsed.prerelease && compareReleaseVersions(parsed, parseReleaseVersion(SOAK_POLICY_VERSION)) >= 0;
+}
+
+export function assertPublishTag(version, requestedTag) {
+  const parsed = parseReleaseVersion(version);
+  const actual = String(requestedTag || (parsed.prerelease ? "latest" : "latest")).trim().toLowerCase();
+  if (actual !== parsed.npmTag) {
+    throw new Error(`${parsed.raw} must be published with npm dist-tag ${parsed.npmTag}, not ${actual || "<empty>"}`);
+  }
+  return parsed.npmTag;
+}
+
+export function assertSoakEligiblePrerelease(version) {
+  const parsed = parseReleaseVersion(version);
+  if (!parsed.prerelease || !["beta", "rc"].includes(parsed.channel)) {
+    throw new Error("stable-release soak requires a published beta or rc version");
+  }
+  return parsed;
+}
+
+export function assertStablePromotion(stableVersion, prereleaseVersion) {
+  const stable = parseReleaseVersion(stableVersion);
+  const prerelease = assertSoakEligiblePrerelease(prereleaseVersion);
+  if (stable.prerelease) throw new Error("stable promotion target must not contain a prerelease suffix");
+  if (stable.baseVersion !== prerelease.baseVersion) {
+    throw new Error(`prerelease ${prerelease.raw} cannot promote to unrelated stable version ${stable.raw}`);
+  }
+  return { stable, prerelease };
+}
+
+export function minimumSoakSeconds(baseVersion, previousStableVersion = "") {
+  const target = parseReleaseVersion(baseVersion);
+  if (target.prerelease) throw new Error("minimum soak target must be a stable base version");
+  if (!previousStableVersion) {
+    if (target.minor === 0 && target.patch === 0) return SOAK_SECONDS.major;
+    if (target.patch === 0) return SOAK_SECONDS.minor;
+    return SOAK_SECONDS.patch;
+  }
+  const previous = parseReleaseVersion(previousStableVersion);
+  if (previous.prerelease) throw new Error("previous stable version must not be a prerelease");
+  if (compareReleaseVersions(target, previous) <= 0) throw new Error("target stable version must be newer than the previous stable version");
+  if (target.major !== previous.major) return SOAK_SECONDS.major;
+  if (target.minor !== previous.minor) return SOAK_SECONDS.minor;
+  return SOAK_SECONDS.patch;
+}
+
+export function formatSoakDuration(seconds) {
+  const value = Number(seconds);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("soak duration must be a non-negative integer");
+  if (value % (24 * 60 * 60) === 0) return `${value / (24 * 60 * 60)}d`;
+  if (value % (60 * 60) === 0) return `${value / (60 * 60)}h`;
+  return `${value}s`;
+}

package/scripts/release-impact-check.mjs

@@ -2,12 +2,17 @@
 
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { compareReleaseVersions, parseReleaseVersion } from "./release-channel.mjs";
+import { createTrustedGitResolver } from "../src/local/trusted-git-executable.mjs";
 
 const VERSION_TAG = /^v(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
 
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-const current = parseVersion(String(pkg.version || ""));
-if (!current) fail("package.json contains an invalid version");
+const root = new URL("../", import.meta.url);
+const pkg = JSON.parse(readFileSync(new URL("package.json", root), "utf8"));
+const gitExecutable = createTrustedGitResolver({ workspace: fileURLToPath(root) });
+let current;
+try { current = parseReleaseVersion(String(pkg.version || "")); } catch { fail("package.json contains an invalid version"); }
 
 const tags = git(["tag", "--merged", "HEAD", "--sort=-version:refname", "--list", "v[0-9]*"])
   .split("\n")
@@ -19,7 +24,7 @@ if (!tags.length) {
 }
 
 const latestTag = tags[0];
-const latest = parseVersion(latestTag.slice(1));
+const latest = parseReleaseVersion(latestTag.slice(1));
 const changed = new Set([
   ...lines(git(["diff", "--name-only", latestTag, "--"])),
   ...lines(git(["ls-files", "--others", "--exclude-standard"])),
@@ -35,11 +40,11 @@ if (!packageRelevant.length) {
   process.stderr.write(`release impact check ok: ${relevant.length} repository-only file(s) changed since ${latestTag}; npm package content is unchanged\n`);
   process.exit(0);
 }
-if (compareVersions(current, latest) <= 0) {
+if (compareReleaseVersions(current, latest) <= 0) {
   fail(`npm-package changes exist since ${latestTag}, but package.json is still ${pkg.version}; bump the npm version and add a CHANGELOG section before merging`);
 }
 
-const changelog = readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");
+const changelog = readFileSync(new URL("CHANGELOG.md", root), "utf8");
 const heading = new RegExp(`^## ${escapeRegExp(pkg.version)}(?:\\s+-[^\\n]*)?$`, "m");
 if (!heading.test(changelog)) fail(`CHANGELOG.md has no section for ${pkg.version}`);
 
@@ -58,7 +63,7 @@ export function isPackageRelevant(path, packageFiles = []) {
 
 function git(args) {
   try {
-    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    return execFileSync(gitExecutable(), args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
   } catch (error) {
     const detail = String(error?.stderr || error?.message || error).trim();
     fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
@@ -69,21 +74,6 @@ function lines(value) {
   return value ? value.split("\n").map((item) => item.trim()).filter(Boolean) : [];
 }
 
-function parseVersion(value) {
-  const match = String(value).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] || "" } : null;
-}
-
-function compareVersions(left, right) {
-  for (const key of ["major", "minor", "patch"]) {
-    if (left[key] !== right[key]) return left[key] - right[key];
-  }
-  if (left.prerelease === right.prerelease) return 0;
-  if (!left.prerelease) return 1;
-  if (!right.prerelease) return -1;
-  return left.prerelease.localeCompare(right.prerelease);
-}
-
 function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/scripts/release-soak.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { replaceFileAtomicallySync } from "../src/local/exclusive-file.mjs";
+import { readPrereleaseActivation } from "./prerelease-activation.mjs";
+import { computePromotionContentDigest } from "./promotion-digest.mjs";
+import {
+  SOAK_CONFIRMATION,
+  assertSoakEligiblePrerelease,
+  assertStablePromotion,
+  compareReleaseVersions,
+  formatSoakDuration,
+  minimumSoakSeconds,
+  parseReleaseVersion,
+  requiresSoakForStable,
+} from "./release-channel.mjs";
+import { verifyCurrentReleaseAcceptance } from "./release-acceptance.mjs";
+import { readGithubPrerelease, readPublishedNpmPrerelease } from "./published-release.mjs";
+
+export const SOAK_SCHEMA_VERSION = 1;
+const MAX_SOAK_RECORD_BYTES = 64 * 1024;
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const mode = process.argv[2] || "--verify";
+  try {
+    if (mode === "--record") recordCurrentPrereleaseSoak(root, { confirmation: argumentValue("--confirm"), stateRoot: argumentValue("--state-dir") || undefined });
+    else if (mode === "--verify") verifyCurrentStableSoak(root);
+    else if (mode === "--status") printStatus(root);
+    else throw new Error("usage: node scripts/release-soak.mjs [--record --confirm TEXT [--state-dir DIR]|--verify|--status]");
+  } catch (error) {
+    console.error(`release soak failed: ${error?.message || error}`);
+    process.exit(1);
+  }
+}
+
+export function soakRecordPath(repositoryRoot, stableVersion) {
+  const stable = parseReleaseVersion(stableVersion);
+  if (stable.prerelease) throw new Error("soak record path requires a stable version");
+  return join(repositoryRoot, "release-soak", `v${stable.raw}.json`);
+}
+
+export function recordCurrentPrereleaseSoak(repositoryRoot, options = {}) {
+  const pkg = readPackage(repositoryRoot);
+  const prerelease = assertSoakEligiblePrerelease(pkg.version);
+  const acceptance = verifyCurrentReleaseAcceptance(repositoryRoot);
+  if (!acceptance.required) throw new Error("prerelease package is missing local candidate acceptance policy");
+  const activation = readPrereleaseActivation(prerelease.raw, options.stateRoot);
+  if (activation.source !== "npm-prerelease") {
+    throw new Error("formal soak starts only after installing the published npm beta/rc; a local candidate activation is insufficient");
+  }
+  if (activation.integrity !== acceptance.metadata.integrity || activation.shasum !== acceptance.metadata.shasum) {
+    throw new Error("activated prerelease bytes do not match the locally accepted prerelease package");
+  }
+  const promotionDigest = computePromotionContentDigest(repositoryRoot);
+  if (activation.promotion_content_sha256 !== promotionDigest) {
+    throw new Error("activated prerelease promotion digest does not match the current source tree");
+  }
+  const previousStable = options.previousStableVersion || latestStableTag(repositoryRoot, prerelease.baseVersion);
+  const requiredSeconds = minimumSoakSeconds(prerelease.baseVersion, previousStable);
+  const activatedAt = Date.parse(activation.activated_at);
+  const acceptedAt = Number.isFinite(options.now) ? Number(options.now) : Date.now();
+  const observedSeconds = Math.floor((acceptedAt - activatedAt) / 1000);
+  if (observedSeconds < requiredSeconds) {
+    throw new Error(`prerelease soak is incomplete: observed ${formatSoakDuration(Math.max(0, observedSeconds))}, required ${formatSoakDuration(requiredSeconds)}`);
+  }
+  const expected = soakConfirmationPhrase(pkg.name, prerelease.raw, requiredSeconds);
+  if (options.confirmation !== expected) throw new Error(`soak confirmation must exactly match: ${expected}`);
+
+  const published = options.published || readPublishedNpmPrerelease(pkg.name, prerelease.raw, prerelease.npmTag);
+  if (
+    published.version !== prerelease.raw
+    || published.integrity !== acceptance.metadata.integrity
+    || published.shasum !== acceptance.metadata.shasum
+    || published.distTag !== prerelease.npmTag
+    || published.publishedAt !== activation.published_at
+  ) {
+    throw new Error("published npm prerelease metadata does not match the accepted and activated package");
+  }
+  const github = options.github || readGithubPrerelease(prerelease.raw);
+  if (github.tag !== `v${prerelease.raw}` || github.isPrerelease !== true) {
+    throw new Error("GitHub prerelease is missing or not marked as a prerelease");
+  }
+  const record = validateSoakRecord({
+    schema_version: SOAK_SCHEMA_VERSION,
+    result: "passed",
+    confirmation: SOAK_CONFIRMATION,
+    package_name: pkg.name,
+    stable_version: prerelease.baseVersion,
+    prerelease_version: prerelease.raw,
+    prerelease_channel: prerelease.channel,
+    prerelease_shasum: acceptance.metadata.shasum,
+    prerelease_integrity: acceptance.metadata.integrity,
+    promotion_content_sha256: promotionDigest,
+    activated_at: activation.activated_at,
+    published_at: published.publishedAt,
+    accepted_at: new Date(acceptedAt).toISOString(),
+    minimum_soak_seconds: requiredSeconds,
+    observed_soak_seconds: observedSeconds,
+    npm_dist_tag: prerelease.npmTag,
+    github_prerelease_tag: github.tag,
+    previous_stable_version: previousStable,
+    known_blocking_issues: 0,
+  });
+  const file = soakRecordPath(repositoryRoot, prerelease.baseVersion);
+  mkdirSync(dirname(file), { recursive: true });
+  replaceFileAtomicallySync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o644 });
+  console.log(`Published prerelease soak accepted: ${file}`);
+  console.log("Stable promotion may change only synchronized version metadata; any functional package change requires a new prerelease and a new soak window.");
+  return record;
+}
+
+export function verifyCurrentStableSoak(repositoryRoot, options = {}) {
+  const pkg = readPackage(repositoryRoot);
+  if (!requiresSoakForStable(pkg.version)) return { required: false, version: pkg.version };
+  const file = soakRecordPath(repositoryRoot, pkg.version);
+  if (!existsSync(file)) throw new Error(`stable release soak record is missing: ${file}`);
+  let parsed;
+  try { parsed = JSON.parse(readBoundedRegularFileSync(file, MAX_SOAK_RECORD_BYTES, "release soak record", { verifyPathIdentity: true }).toString("utf8")); }
+  catch (error) { throw new Error(`release soak record is unavailable or invalid: ${error.message}`); }
+  const promotionDigest = computePromotionContentDigest(repositoryRoot, options);
+  const record = validateSoakRecord(parsed, { stableVersion: pkg.version, promotionDigest });
+  return { required: true, version: pkg.version, record, promotionDigest };
+}
+
+export function validateSoakRecord(value, options = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("release soak record must be an object");
+  const allowed = new Set([
+    "schema_version", "result", "confirmation", "package_name", "stable_version", "prerelease_version",
+    "prerelease_channel", "prerelease_shasum", "prerelease_integrity", "promotion_content_sha256",
+    "activated_at", "published_at", "accepted_at", "minimum_soak_seconds", "observed_soak_seconds",
+    "npm_dist_tag", "github_prerelease_tag", "previous_stable_version", "known_blocking_issues",
+  ]);
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length) throw new Error(`release soak record contains unsupported fields: ${unknown.join(", ")}`);
+  if (value.schema_version !== SOAK_SCHEMA_VERSION) throw new Error("unsupported release soak schema");
+  if (value.result !== "passed" || value.confirmation !== SOAK_CONFIRMATION) throw new Error("release soak is not accepted");
+  if (value.package_name !== "machine-bridge-mcp") throw new Error("release soak package name is invalid");
+  const { stable, prerelease } = assertStablePromotion(value.stable_version, value.prerelease_version);
+  if (value.prerelease_channel !== prerelease.channel) throw new Error("release soak prerelease channel is inconsistent");
+  if (value.npm_dist_tag !== prerelease.npmTag) throw new Error("release soak npm dist-tag is inconsistent");
+  if (value.github_prerelease_tag !== `v${prerelease.raw}`) throw new Error("release soak GitHub prerelease tag is inconsistent");
+  if (!/^[0-9a-f]{40}$/.test(String(value.prerelease_shasum || ""))) throw new Error("release soak prerelease SHA-1 is invalid");
+  if (!/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(String(value.prerelease_integrity || ""))) throw new Error("release soak prerelease integrity is invalid");
+  if (!/^[0-9a-f]{64}$/.test(String(value.promotion_content_sha256 || ""))) throw new Error("release soak promotion digest is invalid");
+  const activatedAt = Date.parse(String(value.activated_at || ""));
+  const publishedAt = Date.parse(String(value.published_at || ""));
+  const acceptedAt = Date.parse(String(value.accepted_at || ""));
+  if (![activatedAt, publishedAt, acceptedAt].every(Number.isFinite)) throw new Error("release soak timestamps are invalid");
+  if (publishedAt > activatedAt + 5 * 60 * 1000 || activatedAt > acceptedAt) throw new Error("release soak timestamp ordering is invalid");
+  if (!Number.isSafeInteger(value.minimum_soak_seconds) || value.minimum_soak_seconds < 60) throw new Error("release soak minimum duration is invalid");
+  if (!Number.isSafeInteger(value.observed_soak_seconds) || value.observed_soak_seconds < value.minimum_soak_seconds) throw new Error("release soak observed duration is insufficient");
+  const elapsed = Math.floor((acceptedAt - activatedAt) / 1000);
+  if (value.observed_soak_seconds > elapsed + 5 || value.observed_soak_seconds < elapsed - 5) throw new Error("release soak observed duration does not match its timestamps");
+  if (value.known_blocking_issues !== 0) throw new Error("stable release is blocked by known prerelease issues");
+  const previous = parseReleaseVersion(value.previous_stable_version);
+  if (previous.prerelease || compareReleaseVersions(stable, previous) <= 0) throw new Error("release soak previous stable version is invalid");
+  const expectedMinimum = minimumSoakSeconds(stable.raw, previous.raw);
+  if (value.minimum_soak_seconds < expectedMinimum) throw new Error("release soak duration is below the active policy minimum");
+  if (options.stableVersion && stable.raw !== parseReleaseVersion(options.stableVersion).raw) throw new Error("release soak record targets another stable version");
+  if (options.promotionDigest && value.promotion_content_sha256 !== options.promotionDigest) {
+    throw new Error("stable package content differs from the accepted prerelease; publish a new prerelease and restart soak");
+  }
+  return Object.freeze({
+    schema_version: SOAK_SCHEMA_VERSION,
+    result: "passed",
+    confirmation: SOAK_CONFIRMATION,
+    package_name: "machine-bridge-mcp",
+    stable_version: stable.raw,
+    prerelease_version: prerelease.raw,
+    prerelease_channel: prerelease.channel,
+    prerelease_shasum: String(value.prerelease_shasum),
+    prerelease_integrity: String(value.prerelease_integrity),
+    promotion_content_sha256: String(value.promotion_content_sha256),
+    activated_at: new Date(activatedAt).toISOString(),
+    published_at: new Date(publishedAt).toISOString(),
+    accepted_at: new Date(acceptedAt).toISOString(),
+    minimum_soak_seconds: Number(value.minimum_soak_seconds),
+    observed_soak_seconds: Number(value.observed_soak_seconds),
+    npm_dist_tag: prerelease.npmTag,
+    github_prerelease_tag: `v${prerelease.raw}`,
+    previous_stable_version: previous.raw,
+    known_blocking_issues: 0,
+  });
+}
+
+export function soakConfirmationPhrase(name, prereleaseVersion, requiredSeconds) {
+  return `I SOAK-TESTED ${name} ${prereleaseVersion} FOR AT LEAST ${formatSoakDuration(requiredSeconds)} WITH NO BLOCKING ISSUES`;
+}
+
+function latestStableTag(repositoryRoot, targetBaseVersion) {
+  const target = parseReleaseVersion(targetBaseVersion);
+  const result = run("git", ["tag", "--list", "v*"], { cwd: repositoryRoot });
+  const versions = result.stdout.split(/\r?\n/).map((tag) => tag.trim().replace(/^v/, "")).filter(Boolean)
+    .map((value) => { try { return parseReleaseVersion(value); } catch { return null; } })
+    .filter((value) => value && !value.prerelease && compareReleaseVersions(value, target) < 0)
+    .sort(compareReleaseVersions);
+  const previous = versions.at(-1);
+  if (!previous) throw new Error(`could not determine the previous stable version before ${target.raw}`);
+  return previous.raw;
+}
+
+function printStatus(repositoryRoot) {
+  const pkg = readPackage(repositoryRoot);
+  const parsed = parseReleaseVersion(pkg.version);
+  if (parsed.prerelease) {
+    console.log(JSON.stringify({ version: parsed.raw, channel: parsed.channel, stable_target: parsed.baseVersion, soak_record: soakRecordPath(repositoryRoot, parsed.baseVersion) }, null, 2));
+    return;
+  }
+  const result = verifyCurrentStableSoak(repositoryRoot);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function readPackage(repositoryRoot) {
+  const value = JSON.parse(readFileSync(join(repositoryRoot, "package.json"), "utf8"));
+  if (value.name !== "machine-bridge-mcp") throw new Error("unexpected package name");
+  parseReleaseVersion(value.version);
+  return value;
+}
+
+function run(file, args, options = {}) {
+  const result = spawnSync(file, args, { cwd: options.cwd || root, encoding: "utf8", env: process.env, windowsHide: true });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${file} ${args[0] || ""} failed: ${String(result.stderr || result.stdout).trim()}`);
+  return result;
+}
+
+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] : "";
+}