fix(runtime): guard import-time side effects

src/plugins/contracts/runtime-import-side-effects.contract.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { assertNoImportTimeSideEffects } from "./testkit.js";
+
+const listBootstrapChannelPlugins = vi.hoisted(() =>
+  vi.fn(() => [
+    {
+      id: "signal",
+      messaging: {
+        defaultMarkdownTableMode: "bullets",
+      },
+    },
+  ]),
+);
+
+const BOOTSTRAP_SEAM = "listBootstrapChannelPlugins()";
+const BOOTSTRAP_WHY =
+  "it boots bundled channel metadata on hot runtime/config import paths and turns cheap module evaluation into channel bootstrap work.";
+const BOOTSTRAP_FIX =
+  "keep the seam behind a lazy getter/runtime boundary so import stays cold and the first real lookup loads once.";
+
+function mockBootstrapRegistry() {
+  vi.doMock("../../channels/plugins/bootstrap-registry.js", async () => {
+    const actual =
+      await vi.importActual<typeof import("../../channels/plugins/bootstrap-registry.js")>(
+        "../../channels/plugins/bootstrap-registry.js",
+      );
+    return {
+      ...actual,
+      listBootstrapChannelPlugins,
+    };
+  });
+}
+
+function expectNoBootstrapDuringImport(moduleId: string) {
+  assertNoImportTimeSideEffects({
+    moduleId,
+    forbiddenSeam: BOOTSTRAP_SEAM,
+    calls: listBootstrapChannelPlugins.mock.calls,
+    why: BOOTSTRAP_WHY,
+    fixHint: BOOTSTRAP_FIX,
+  });
+}
+
+afterEach(() => {
+  vi.resetModules();
+  vi.restoreAllMocks();
+  vi.doUnmock("../../channels/plugins/bootstrap-registry.js");
+});
+
+describe("runtime import side-effect contracts", () => {
+  beforeEach(() => {
+    listBootstrapChannelPlugins.mockClear();
+  });
+
+  it("keeps config/markdown-tables cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../../config/markdown-tables.js");
+
+    expectNoBootstrapDuringImport("src/config/markdown-tables.ts");
+  });
+
+  it("keeps markdown table defaults lazy and memoized after import", async () => {
+    mockBootstrapRegistry();
+    const markdownTables = await import("../../config/markdown-tables.js");
+
+    expectNoBootstrapDuringImport("src/config/markdown-tables.ts");
+
+    expect(markdownTables.DEFAULT_TABLE_MODES.get("signal")).toBe("bullets");
+    expect(listBootstrapChannelPlugins).toHaveBeenCalledTimes(1);
+    expect(markdownTables.DEFAULT_TABLE_MODES.has("signal")).toBe(true);
+    expect(listBootstrapChannelPlugins).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps plugins/runtime/runtime-channel cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../runtime/runtime-channel.js");
+
+    expectNoBootstrapDuringImport("src/plugins/runtime/runtime-channel.ts");
+  });
+
+  it("keeps plugins/runtime/runtime-system cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../runtime/runtime-system.js");
+
+    expectNoBootstrapDuringImport("src/plugins/runtime/runtime-system.ts");
+  });
+
+  it("keeps web-search/runtime cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../../web-search/runtime.js");
+
+    expectNoBootstrapDuringImport("src/web-search/runtime.ts");
+  });
+
+  it("keeps web-fetch/runtime cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../../web-fetch/runtime.js");
+
+    expectNoBootstrapDuringImport("src/web-fetch/runtime.ts");
+  });
+
+  it("keeps plugins/runtime/index cold on import", async () => {
+    mockBootstrapRegistry();
+    await import("../runtime/index.js");
+
+    expectNoBootstrapDuringImport("src/plugins/runtime/index.ts");
+  });
+});

src/plugins/contracts/testkit.ts

@@ -13,6 +13,46 @@ export function uniqueSortedStrings(values: readonly string[]) {
   return [...new Set(values)].toSorted((left, right) => left.localeCompare(right));
 }
 
+function formatImportSideEffectCall(args: readonly unknown[]): string {
+  if (args.length === 0) {
+    return "(no args)";
+  }
+  return args
+    .map((arg) => {
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return String(arg);
+      }
+    })
+    .join(", ");
+}
+
+export function assertNoImportTimeSideEffects(params: {
+  moduleId: string;
+  forbiddenSeam: string;
+  calls: readonly (readonly unknown[])[];
+  why: string;
+  fixHint: string;
+}) {
+  if (params.calls.length === 0) {
+    return;
+  }
+  const observedCalls = params.calls
+    .slice(0, 3)
+    .map((call, index) => `  ${index + 1}. ${formatImportSideEffectCall(call)}`)
+    .join("\n");
+  throw new Error(
+    [
+      `[runtime contract] ${params.moduleId} touched ${params.forbiddenSeam} during module import.`,
+      `why this is banned: ${params.why}`,
+      `expected fix: ${params.fixHint}`,
+      `observed calls (${params.calls.length}):`,
+      observedCalls,
+    ].join("\n"),
+  );
+}
+
 export function createPluginRegistryFixture(config = {} as OpenClawConfig) {
   return {
     config,