@powerhousedao/switchboard 6.2.3-dev.32 → 6.2.3-dev.34

package/dist/server.d.mts

@@ -1,5 +1,5 @@
 import { ILogger } from "document-model";
-import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig } from "@powerhousedao/reactor";
+import { ChannelScheme, IDocumentModelLoader, IReactorClient, InProcessReactorClientModule, JwtHandler, ReactorBuilder, ReactorClientBuilder, ReactorFeatureFlags, SignerConfig, UnsupportedStoredDocuments, UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
 import { AttachmentReferenceProjectionCapability } from "@powerhousedao/reactor-api";
 import { IAttachmentService } from "@powerhousedao/reactor-attachments";
 import { IRenown } from "@renown/sdk/node";
@@ -108,6 +108,8 @@ export type StartServerOptions = {
   identity?: IdentityOptions;
   /** Base URL for the attachment service; defaults to `PH_SWITCHBOARD_PUBLIC_URL` then `http(s)://localhost:${port}`. */
   attachmentServiceUrl?: string;
+  /** Mount the MCP server at `/mcp`. On by default; `false` wins over
+   * MCP_ENABLED, which can turn it off but never on. */
   mcp?: boolean;
   /** Powerhouse workflows: the runtime, its subgraph, its webhooks and its
    * document models. Wins over PH_WORKFLOWS_ENABLED and the config file. */
@@ -170,6 +172,14 @@ export type StartServerOptions = {
     enabled?: boolean;
     dbPoolSize?: number;
   };
+  /**
+   * Stored documents at protocol versions this build does not run: "refuse"
+   * (the default) fails the boot with a StoredDocumentsRefusedError;
+   * "read-only" starts with a warning and keeps those documents read-only.
+   * Unset falls back to the REACTOR_UNSUPPORTED_STORED_DOCUMENTS env var.
+   * Ignored when `reactor` is passed.
+   */
+  unsupportedStoredDocuments?: UnsupportedStoredDocuments;
 };
 export type SwitchboardReactor = {
   defaultDriveUrl: string | undefined;
@@ -183,6 +193,8 @@ export type SwitchboardReactor = {
   workflowTriggers?: WorkflowTriggersCapability;
   /** Whether workflows are on, after the option, PH_WORKFLOWS_ENABLED and the config file. */
   workflowsEnabled: boolean;
+  /** Whether `/mcp` is mounted, after the option and MCP_ENABLED. */
+  mcpEnabled: boolean;
   /** The Renown instance if identity was initialized */
   renown: IRenown$1 | null;
   /**
@@ -244,6 +256,20 @@ type SwitchboardReactorDefaultsOptions = {
 };
 export declare function applySwitchboardReactorDefaults(reactorBuilder: ReactorBuilder, clientBuilder: ReactorClientBuilder, options?: SwitchboardReactorDefaultsOptions): void;
 //#endregion
+//#region src/unsupported-stored-documents.d.mts
+/** From REACTOR_UNSUPPORTED_STORED_DOCUMENTS; `input` wins when defined. */
+export declare function resolveUnsupportedStoredDocuments(input: UnsupportedStoredDocuments | undefined, env: NodeJS.ProcessEnv): UnsupportedStoredDocuments;
+/** The reactor refused to start over documents this build does not run. */
+export declare class StoredDocumentsRefusedError extends Error {
+  readonly versions: readonly {
+    protocol: string;
+    version: number;
+  }[];
+  readonly documents: number;
+  constructor(cause: UnsupportedStoredProtocolError);
+  static isError(error: unknown): error is StoredDocumentsRefusedError;
+}
+//#endregion
 //#region src/server.d.mts
 /**
  * Attempt to bind a throwaway TCP server to the given port. Resolves true if

package/dist/server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;;KA2DY;EACN;;EAEA;EACA;;;;;;;;;;YC7CM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;EACA;;;EAGA;IACE;;EAEF,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;YAIQ;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KCzLN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;;;;;wBC6DK,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAu5BvB,mBAAgB,UAClB,uBACR,QAAQ"}
+{"version":3,"file":"server.d.mts","names":[],"sources":["../src/workflow-runtime.mts","../src/types.ts","../src/builder-defaults.mts","../src/unsupported-stored-documents.mts","../src/server.mts"],"mappings":";;;;;;;;;;;;;KA2DY;EACN;;EAEA;EACA;;;;;;;;;;YC5CM;;YAKA,wBAAwB;EAClC,eAAe;;YAGL;EACV;EACA;EACA;;YAGU;;EAEV;;;;;EAKA;;EAGA;;YAGU;;;;;;;;;;;;;;;;;;;;;EAqBV,UAAU;;;;;;;;EAQV;;;;;;;EAOA;EACA;EACA;;;;;;EAMA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA;IAEM;IACA;;;;;;;EASN,WAAW;;EAEX;;;EAGA;;;EAGA;IACE;;EAEF,kBAAkB;EAClB;EACA;;;;;;EAMA;EACA,SAAS;;;;;;;;;;EAUT;;;;;;;;;;EAUA;;;;;;;;;EASA;IACE;IACA;IACA;;;;;;;;;;;EAWF;IACE;IACA;;;;;;;;;EASF,6BAA6B;;YAGnB;EACV;EACA,SAAS;;EAET,mBAAmB;;EAEnB,+BAA+B;;;EAG/B,mBAAmB;;EAEnB;;EAEA;;EAEA,QAAQ;;;;;EAKR;;;;;;;;;;;;;EAaA,gBAAgB;;;;KCtMN;EAIV,iBAAiB;;EAEjB,mBAAmB;;EAEnB;;;;;;EAMA,gBAAgB;;EAEhB;;EAEA;IACE;IACA,eAAe,QAAQ;;;EAGzB,sBAAsB;EACtB,SAAS;;;;;;EAMT,SAAS;;;;;EAKT,cAAc,KAAK;;EAEnB,wBAAwB;;wBAsBV,gCACd,gBAAgB,gBAChB,eAAe,sBACf,UAAS;;;;wBC3EK,kCACd,OAAO,wCACP,KAAK,OAAO,aACX;;qBAaU,oCAAoC;WACtC;IAAqB;IAAkB;;WACvC;EAET,YAAY,OAAO;SAcZ,QAAQ,iBAAiB,SAAS;;;;;;;;;wBC4G3B,gBAAgB,eAAe;;wBAoI/B,8BACd,SAAS,KAAK,uDACd,oBACA,QAAQ;EACL;EAAmB,YAAY;;;;;;;;;;;;;;;;;;;qBAk7BvB,mBAAgB,UAClB,uBACR,QAAQ"}

package/dist/server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as applySwitchboardReactorDefaults, n as isPortAvailable, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-CKKn0aXV.mjs";
-export { applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, startSwitchboard };
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fe3a107a-4dd4-530b-b8d9-ef36656e688e")}catch(e){}}();
-//# debugId=fe3a107a-4dd4-530b-b8d9-ef36656e688e
+import { a as resolveUnsupportedStoredDocuments, i as StoredDocumentsRefusedError, n as isPortAvailable, o as applySwitchboardReactorDefaults, r as startSwitchboard, t as deriveAttachmentServiceConfig } from "./server-sQoWp21G.mjs";
+export { StoredDocumentsRefusedError, applySwitchboardReactorDefaults, deriveAttachmentServiceConfig, isPortAvailable, resolveUnsupportedStoredDocuments, startSwitchboard };
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1396e5c4-5148-5e73-aaff-79e70b5910cc")}catch(e){}}();
+//# debugId=1396e5c4-5148-5e73-aaff-79e70b5910cc

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powerhousedao/switchboard",
   "type": "module",
-  "version": "6.2.3-dev.32",
+  "version": "6.2.3-dev.34",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "@openfeature/core": "1.9.1",
     "@openfeature/env-var-provider": "0.3.1",
     "@openfeature/server-sdk": "1.19.0",
-    "@powerhousedao/config": "6.2.3-dev.32",
+    "@powerhousedao/config": "6.2.3-dev.34",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
@@ -55,22 +55,22 @@
     "@opentelemetry/sdk-node": "^0.218.0",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.32",
-    "@powerhousedao/reactor": "6.2.3-dev.32",
-    "@powerhousedao/shared": "6.2.3-dev.32",
-    "@powerhousedao/vetra": "6.2.3-dev.32",
-    "@powerhousedao/reactor-api": "6.2.3-dev.32",
-    "@powerhousedao/reactor-attachments": "6.2.3-dev.32",
-    "@powerhousedao/reactor-drive": "6.2.3-dev.32",
-    "@powerhousedao/reactor-group": "6.2.3-dev.32",
-    "@powerhousedao/reactor-workflow": "6.2.3-dev.32",
-    "@powerhousedao/workflow": "6.2.3-dev.32",
-    "@powerhousedao/pglite-fs": "6.2.3-dev.32",
+    "@powerhousedao/opentelemetry-instrumentation-reactor": "6.2.3-dev.34",
+    "@powerhousedao/reactor": "6.2.3-dev.34",
+    "@powerhousedao/shared": "6.2.3-dev.34",
+    "@powerhousedao/vetra": "6.2.3-dev.34",
+    "@powerhousedao/reactor-api": "6.2.3-dev.34",
+    "@powerhousedao/reactor-attachments": "6.2.3-dev.34",
+    "@powerhousedao/reactor-drive": "6.2.3-dev.34",
+    "@powerhousedao/reactor-group": "6.2.3-dev.34",
+    "@powerhousedao/reactor-workflow": "6.2.3-dev.34",
+    "@powerhousedao/workflow": "6.2.3-dev.34",
+    "@powerhousedao/pglite-fs": "6.2.3-dev.34",
     "@pyroscope/nodejs": "^0.4.5",
-    "@renown/sdk": "6.2.3-dev.32",
+    "@renown/sdk": "6.2.3-dev.34",
     "@sentry/node": "^10.53.1",
     "@sentry/opentelemetry": "^10.53.1",
-    "document-model": "6.2.3-dev.32",
+    "document-model": "6.2.3-dev.34",
     "dotenv": "^16.4.7",
     "express": "^4.22.1",
     "graphql": "^16",

package/test/boot-mcp-enabled.test.ts

@@ -0,0 +1,121 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ILogger } from "document-model";
+import { describe, expect, it, vi } from "vitest";
+import { startSwitchboard } from "../src/server.mjs";
+
+// `port: 0` would bind a random port the switchboard does not report back, so
+// the test picks a free one and pins it.
+async function freePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  if (!address || typeof address === "string") throw new Error("no port");
+  return address.port;
+}
+
+function stubLogger(): ILogger {
+  const logger = {
+    verbose: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(),
+  };
+  logger.child.mockReturnValue(logger);
+  return logger as unknown as ILogger;
+}
+
+async function withSwitchboard(
+  env: Record<string, string>,
+  mcp: boolean | undefined,
+  run: (
+    switchboard: Awaited<ReturnType<typeof startSwitchboard>>,
+  ) => Promise<void>,
+): Promise<void> {
+  const tempRoot = await mkdtemp(join(tmpdir(), "switchboard-mcp-enabled-"));
+  const names = ["PH_REACTOR_DATABASE_URL", "MCP_ENABLED", ...Object.keys(env)];
+  const previous = names.map((name) => [name, process.env[name]] as const);
+  process.env.PH_REACTOR_DATABASE_URL = join(tempRoot, "reactor-storage");
+  delete process.env.MCP_ENABLED;
+  Object.assign(process.env, env);
+  let switchboard: Awaited<ReturnType<typeof startSwitchboard>> | undefined;
+
+  try {
+    switchboard = await startSwitchboard({
+      workflows: { enabled: false },
+      dbPath: join(tempRoot, "read-model"),
+      port: await freePort(),
+      strictPort: true,
+      mcp,
+      disableLocalPackages: true,
+      identity: { keypairPath: join(tempRoot, "identity.json") },
+      drive: {
+        slug: "default-drive",
+        global: { name: "Default Drive" },
+      },
+      logger: stubLogger(),
+    });
+    await run(switchboard);
+    await switchboard.shutdown();
+    switchboard = undefined;
+  } finally {
+    await switchboard?.shutdown();
+    for (const [name, value] of previous) {
+      if (value === undefined) {
+        delete process.env[name];
+      } else {
+        process.env[name] = value;
+      }
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function postMcp(port: number): Promise<number> {
+  const response = await fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+  });
+  await response.body?.cancel();
+  return response.status;
+}
+
+describe("booting Switchboard", () => {
+  it("mounts /mcp by default", async () => {
+    await withSwitchboard({}, undefined, async ({ mcpEnabled, port }) => {
+      expect(mcpEnabled).toBe(true);
+      expect(await postMcp(port)).not.toBe(404);
+    });
+  }, 60_000);
+
+  it('leaves /mcp unmounted under MCP_ENABLED="false"', async () => {
+    await withSwitchboard(
+      { MCP_ENABLED: "false" },
+      undefined,
+      async ({ mcpEnabled, port }) => {
+        expect(mcpEnabled).toBe(false);
+        expect(await postMcp(port)).toBe(404);
+      },
+    );
+  }, 60_000);
+
+  it("keeps a host's mcp: false over MCP_ENABLED=true", async () => {
+    await withSwitchboard(
+      { MCP_ENABLED: "true" },
+      false,
+      async ({ mcpEnabled, port }) => {
+        expect(mcpEnabled).toBe(false);
+        expect(await postMcp(port)).toBe(404);
+      },
+    );
+  }, 60_000);
+});

package/test/boot-unsupported-stored-documents.test.ts

@@ -0,0 +1,210 @@
+import { PGlite } from "@electric-sql/pglite";
+import { AtomicNodeFs } from "@powerhousedao/pglite-fs";
+import {
+  JobStatus,
+  ReactorBuilder,
+  type Database,
+} from "@powerhousedao/reactor";
+import { driveDocumentModelModule } from "@powerhousedao/shared/document-drive";
+import {
+  withSignaturePolicy,
+  type PeerCapability,
+} from "@powerhousedao/shared/document-model";
+import type { ILogger } from "document-model";
+import { Kysely } from "kysely";
+import { cp, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { ClosablePGliteDialect } from "../src/pglite-dialect.js";
+import { startSwitchboard } from "../src/server.mjs";
+import { StoredDocumentsRefusedError } from "../src/unsupported-stored-documents.mjs";
+
+const ENV_KEYS = [
+  "PH_REACTOR_DATABASE_URL",
+  "DATABASE_URL",
+  "REACTOR_UNSUPPORTED_STORED_DOCUMENTS",
+] as const;
+
+const BASE_REDUCER_7: PeerCapability = {
+  kind: "protocol",
+  name: "base-reducer",
+  baseline: [1, 2],
+  supported: () => [1, 2, 7],
+  preferred: () => 2,
+  optional: false,
+};
+
+type StubLogger = ILogger & {
+  warn: ReturnType<typeof vi.fn>;
+  error: ReturnType<typeof vi.fn>;
+};
+
+function stubLogger(): StubLogger {
+  const logger = {
+    verbose: vi.fn(),
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(),
+  };
+  logger.child.mockReturnValue(logger);
+  return logger as unknown as StubLogger;
+}
+
+/** A reactor store holding one drive created at base-reducer 7. */
+async function seedStore(dir: string): Promise<void> {
+  const db = new Kysely<Database>({
+    dialect: new ClosablePGliteDialect(
+      new PGlite({ fs: new AtomicNodeFs(dir) }),
+    ),
+  });
+  const module = await new ReactorBuilder()
+    .withKysely(db)
+    .withDocumentModelSources([driveDocumentModelModule as never])
+    .withPeerCapabilities([BASE_REDUCER_7])
+    .buildModule();
+  const created = await module.reactor.create(
+    withSignaturePolicy(
+      driveDocumentModelModule.utils.createDocument(),
+      "legacy",
+      {
+        id: "br7-stored",
+        protocolVersions: { "base-reducer": 7 },
+      },
+    ),
+  );
+  await vi.waitUntil(
+    async () => {
+      const { status } = await module.reactor.getJobStatus(created.id);
+      return status === JobStatus.READ_READY || status === JobStatus.FAILED;
+    },
+    { timeout: 10_000, interval: 5 },
+  );
+  expect((await module.reactor.getJobStatus(created.id)).status).toBe(
+    JobStatus.READ_READY,
+  );
+  await module.reactor.kill().completed;
+  await db.destroy();
+}
+
+// PGlite boots are several times slower on Windows runners.
+const BOOT_TIMEOUT = 120_000;
+
+describe("booting over documents this build does not run", () => {
+  let seeded: string;
+  let tempRoot: string;
+  let previous: Partial<Record<(typeof ENV_KEYS)[number], string>>;
+
+  beforeAll(async () => {
+    seeded = await mkdtemp(join(tmpdir(), "switchboard-stored-protocol-seed-"));
+    await seedStore(join(seeded, "reactor-storage"));
+  }, BOOT_TIMEOUT);
+
+  afterAll(async () => {
+    await rm(seeded, { recursive: true, force: true });
+  });
+
+  beforeEach(async () => {
+    tempRoot = await mkdtemp(join(tmpdir(), "switchboard-stored-protocol-"));
+    previous = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+    process.env.PH_REACTOR_DATABASE_URL = join(tempRoot, "reactor-storage");
+    process.env.DATABASE_URL = join(tempRoot, "read-model");
+    delete process.env.REACTOR_UNSUPPORTED_STORED_DOCUMENTS;
+    await cp(
+      join(seeded, "reactor-storage"),
+      process.env.PH_REACTOR_DATABASE_URL,
+      { recursive: true },
+    );
+  });
+
+  afterEach(async () => {
+    for (const key of ENV_KEYS) {
+      if (previous[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = previous[key];
+      }
+    }
+    await rm(tempRoot, { recursive: true, force: true });
+  });
+
+  function boot(logger: ILogger) {
+    return startSwitchboard({
+      workflows: { enabled: false },
+      port: 0,
+      mcp: false,
+      disableLocalPackages: true,
+      identity: { keypairPath: join(tempRoot, "identity.json") },
+      logger,
+    });
+  }
+
+  it(
+    "refuses by default and tells the operator both ways forward",
+    async () => {
+      const logger = stubLogger();
+
+      const booted = boot(logger);
+
+      await expect(booted).rejects.toSatisfy(
+        (error) =>
+          StoredDocumentsRefusedError.isError(error) &&
+          error.documents === 1 &&
+          error.versions.some(
+            ({ protocol, version }) =>
+              protocol === "base-reducer" && version === 7,
+          ),
+      );
+      const message = (await booted.catch((error: Error) => error)) as Error;
+      expect(message.message).toMatch(
+        /1 stored document\(s\) require base-reducer 7/,
+      );
+      expect(message.message).toMatch(
+        /switchboard build that runs base-reducer 7/,
+      );
+      expect(message.message).toMatch(
+        /REACTOR_UNSUPPORTED_STORED_DOCUMENTS=read-only/,
+      );
+      expect(logger.error).toHaveBeenCalledWith(message.message);
+      expect(logger.error).not.toHaveBeenCalledWith(
+        "App crashed: @error",
+        expect.anything(),
+      );
+    },
+    BOOT_TIMEOUT,
+  );
+
+  it(
+    "starts read-only when REACTOR_UNSUPPORTED_STORED_DOCUMENTS says so",
+    async () => {
+      process.env.REACTOR_UNSUPPORTED_STORED_DOCUMENTS = "read-only";
+      const logger = stubLogger();
+
+      const switchboard = await boot(logger);
+      try {
+        expect(logger.warn).toHaveBeenCalledWith(
+          expect.stringContaining("read-only"),
+          expect.stringContaining(
+            "1 stored document(s) require base-reducer 7",
+          ),
+        );
+        const stored = await switchboard.reactor.get("br7-stored");
+        expect(stored.header.id).toBe("br7-stored");
+      } finally {
+        await switchboard.shutdown();
+      }
+    },
+    BOOT_TIMEOUT,
+  );
+});

package/test/mcp-flag.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { initFeatureFlags } from "../src/feature-flags.js";
+import { MCP_ENABLED, resolveMcpEnabled } from "../src/mcp-flag.mjs";
+import type { BooleanFlagSource } from "../src/workflow-runtime.mjs";
+
+describe("resolveMcpEnabled", () => {
+  let featureFlags: BooleanFlagSource;
+
+  beforeAll(async () => {
+    featureFlags = await initFeatureFlags();
+  });
+
+  afterEach(() => {
+    delete process.env[MCP_ENABLED];
+  });
+
+  it("defaults to on", async () => {
+    await expect(resolveMcpEnabled({ featureFlags })).resolves.toBe(true);
+    await expect(
+      resolveMcpEnabled({ featureFlags, option: true }),
+    ).resolves.toBe(true);
+  });
+
+  it('is turned off by MCP_ENABLED="false"', async () => {
+    process.env[MCP_ENABLED] = "false";
+
+    await expect(resolveMcpEnabled({ featureFlags })).resolves.toBe(false);
+  });
+
+  // `ph vetra` passes `mcp: true` explicitly; the env var still wins.
+  it("turns off a host that asked for MCP", async () => {
+    process.env[MCP_ENABLED] = "false";
+
+    await expect(
+      resolveMcpEnabled({ featureFlags, option: true }),
+    ).resolves.toBe(false);
+  });
+
+  it("never turns on a host that switched MCP off", async () => {
+    process.env[MCP_ENABLED] = "true";
+
+    await expect(
+      resolveMcpEnabled({ featureFlags, option: false }),
+    ).resolves.toBe(false);
+  });
+
+  it("leaves MCP on for any value but the string false", async () => {
+    for (const raw of ["true", "0", "no", ""]) {
+      process.env[MCP_ENABLED] = raw;
+      await expect(
+        resolveMcpEnabled({ featureFlags }),
+        `MCP_ENABLED=${JSON.stringify(raw)}`,
+      ).resolves.toBe(true);
+    }
+  });
+});

package/test/unsupported-stored-documents.test.ts

@@ -0,0 +1,72 @@
+import { UnsupportedStoredProtocolError } from "@powerhousedao/reactor";
+import { describe, expect, it } from "vitest";
+import {
+  StoredDocumentsRefusedError,
+  resolveUnsupportedStoredDocuments,
+} from "../src/unsupported-stored-documents.mjs";
+
+describe("resolveUnsupportedStoredDocuments", () => {
+  it("refuses by default", () => {
+    expect(resolveUnsupportedStoredDocuments(undefined, {})).toBe("refuse");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " ",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("reads REACTOR_UNSUPPORTED_STORED_DOCUMENTS", () => {
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: " read-only ",
+      }),
+    ).toBe("read-only");
+    expect(
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "refuse",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("lets the option win over the env var", () => {
+    expect(
+      resolveUnsupportedStoredDocuments("refuse", {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "read-only",
+      }),
+    ).toBe("refuse");
+  });
+
+  it("refuses an unknown value", () => {
+    expect(() =>
+      resolveUnsupportedStoredDocuments(undefined, {
+        REACTOR_UNSUPPORTED_STORED_DOCUMENTS: "readonly",
+      }),
+    ).toThrow(
+      'REACTOR_UNSUPPORTED_STORED_DOCUMENTS must be "refuse" or "read-only", got "readonly"',
+    );
+  });
+});
+
+describe("StoredDocumentsRefusedError", () => {
+  it("names the versions, the count and both ways forward", () => {
+    const cause = new UnsupportedStoredProtocolError(
+      [
+        { protocol: "base-reducer", version: 3 },
+        { protocol: "base-reducer", version: 7 },
+      ],
+      4,
+    );
+
+    const error = new StoredDocumentsRefusedError(cause);
+
+    expect(error.message).toBe(
+      "Refusing to start: 4 stored document(s) require base-reducer 3, base-reducer 7, which this switchboard does not run. " +
+        "Either start a switchboard build that runs base-reducer 3, base-reducer 7, or set REACTOR_UNSUPPORTED_STORED_DOCUMENTS=read-only to start with those documents read-only.",
+    );
+    expect(error.documents).toBe(4);
+    expect(error.versions).toBe(cause.versions);
+    expect(error.cause).toBe(cause);
+    expect(StoredDocumentsRefusedError.isError(error)).toBe(true);
+    expect(StoredDocumentsRefusedError.isError(cause)).toBe(false);
+  });
+});