feat: close the browser boundary and add the generic UI host loader

Two gaps stood between the module UI contract and a host that could use
it. ADR 0023 recorded the first honestly but never diagnosed it: a module
UI file compiled with `"types": []` could still typecheck `process.env`.
The second was simply missing — nothing imported a compiled artifact,
checked its identity, mounted it, or tore it down.

The leak was one type-only import, bisected against the real type graph
rather than guessed. `@ekklesia/module-ui-sdk` imported
`type { EkklesiaPrincipal } from "@ekklesia/contracts"`. Importing
contracts/identity alone is clean and importing Zod alone is clean, but
contracts exposes a single barrel entry, so that one import reached
module-database, whose Drizzle types re-introduce Node's globals. The
runtime was never affected — the import was erased and host-context.js is
`export {}` — but a type-graph leak is still a real boundary failure,
because it silently permits code that cannot run in its target
environment.

The fix is not a narrower import path. The SDK now has no dependencies at
all, so there is no graph to leak through and no future contracts change
can reopen this. It owns `ModuleUiPrincipal`: the same shape ADR 0022
chose, with the Zod brand dropped. That brand encodes a server-side
parsing guarantee a browser cannot produce, and it is the same reason
`permissions.has` already took a plain string. An Ekklesia host still
passes its own `EkklesiaPrincipal` straight through — a branded string is
assignable to `string` — while a standalone host builds the literal.
Proven the way an author experiences it: two fixtures compiled under the
exact project a module uses, one supported and one deliberately reaching
for `process`, with the second required to fail on that specific name.

`@ekklesia/module-ui-host` is the generic loader, in its own package
because the SDK is bundled into every module artifact and host-only
loader code has no business shipping there. The boundary checker enforces
both directions: modules may not depend on the loader, and the loader may
depend only on the SDK plus dev-time tooling.

The distinction that shaped the design: Core resolves `entrypoints.ui` to
an absolute path on the server's disk, and a browser needs a URL. A
loader that accepted the path would test green on a server and fail in
every real host, and would quietly own asset publication. So the loader
takes a browser-loadable URL and knows nothing about how one is obtained.
Ekklesia has no route that publishes installed artifacts, so this is
precisely: loader complete, publication deferred. Nothing can mount an
installed module UI yet, and the docs say so rather than implying
otherwise.

Dynamic import is `(url) => import(url)` with a non-analyzable specifier,
kept as a runtime import so a host does not statically bundle every
installed module or need a hardcoded registry. It is injectable for
bundlers needing their own escape hatch, and deliberately not `eval` or
`new Function`, which would cost a host `unsafe-eval` in its CSP.

Identity is validated through the SDK's existing parser before `mount`
runs, so a stale or mismatched bundle never renders. Contract violations
propagate unwrapped; the loader adds only import and mount failure codes,
sanitized, with the cause attached. Unmount is idempotent, safe when a
module returned no cleanup, and marks an instance unmounted before
running cleanup so a throwing cleanup surfaces once and never re-runs. A
failed mount registers no cleanup. Each instance owns its own state, so
two mounts coexist. The loader never mutates the host's container — not
on success, failure, or unmount.

Tests prove all of it against real module URLs (`data:`, which both
browsers and Node import natively) rather than filesystem paths,
including one artifact built by the canonical Pass 2 pipeline and run
under both an Ekklesia-shaped and a standalone-shaped context. Core,
apps/api, and the contracts package are untouched; discovery remains
inert.

Co-Authored-By: Claude Opus 5 <[email protected]>

packages/module-ui-sdk/tests/browser-boundary.test.ts

@@ -0,0 +1,48 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+
+const run = promisify(execFile);
+const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const fixtureDirectory = path.join(packageDirectory, "tests", "browser-boundary");
+const typescript = path.join(packageDirectory, "node_modules", ".bin", "tsc");
+
+async function typecheck(project: string): Promise<{ code: number; output: string }> {
+  try {
+    await run(typescript, ["--noEmit", "--project", path.join(fixtureDirectory, project)]);
+    return { code: 0, output: "" };
+  } catch (error) {
+    const failure = error as { code?: number; stdout?: string; stderr?: string };
+    return { code: failure.code ?? 1, output: `${failure.stdout ?? ""}${failure.stderr ?? ""}` };
+  }
+}
+
+/**
+ * The browser boundary, tested the way a module author experiences it rather than by inspecting the
+ * dependency graph.
+ *
+ * Both fixtures compile under the *exact* project a module uses for UI source —
+ * `browser-react.json` with `"types": []`. Before this package dropped its `@ekklesia/contracts`
+ * dependency, the negative fixture below compiled successfully: that import reached a backend
+ * barrel whose Drizzle types re-introduced Node's global declarations, so `process.env` typechecked
+ * inside browser-only code (ADR 0024).
+ */
+describe("module UI SDK browser boundary", () => {
+  it("compiles supported UI source that imports the public SDK", async () => {
+    const result = await typecheck("tsconfig.supported.json");
+
+    expect(result.output).toBe("");
+    expect(result.code).toBe(0);
+  }, 60_000);
+
+  it("refuses Node globals in UI source that imports the public SDK", async () => {
+    const result = await typecheck("tsconfig.node-global.json");
+
+    expect(result.code).not.toBe(0);
+    // Specifically because `process` does not exist — not because of an unrelated error.
+    expect(result.output).toContain("Cannot find name 'process'");
+    expect(result.output).toContain("node-global.tsx");
+  }, 60_000);
+});

packages/module-ui-sdk/tests/browser-boundary/node-global.tsx

@@ -0,0 +1,6 @@
+// The negative case. Importing the public SDK must NOT make Node globals visible. If this file
+// ever typechecks, the browser boundary has regressed and `browser-boundary.test.ts` fails.
+import type { ModuleUiHostContext } from "../../src/index.js";
+
+export type Context = ModuleUiHostContext;
+export const leaked: string | undefined = process.env.NODE_ENV;

packages/module-ui-sdk/tests/browser-boundary/supported.tsx

@@ -0,0 +1,24 @@
+// A module author's supported UI source: it imports the public SDK and must typecheck cleanly
+// under the exact browser project a module uses (`browser-react.json`, `"types": []`).
+import {
+  defineModuleUi,
+  type ModuleUiHostContext,
+  type ModuleUiPrincipal,
+} from "../../src/index.js";
+
+function describePrincipal(principal: ModuleUiPrincipal): string {
+  return principal.kind === "authenticated" ? principal.userId : "anonymous";
+}
+
+export default defineModuleUi({
+  id: "example",
+  version: "0.1.0",
+  mount(container: Element, context: ModuleUiHostContext) {
+    container.textContent = describePrincipal(context.principal);
+    void context.api.request("records");
+    void context.permissions.has("example.records.read");
+    return () => {
+      container.textContent = "";
+    };
+  },
+});

packages/module-ui-sdk/tests/browser-boundary/tsconfig.node-global.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../typescript-config/browser-react.json",
+  "compilerOptions": { "noEmit": true, "types": [] },
+  "include": ["node-global.tsx"]
+}

packages/module-ui-sdk/tests/browser-boundary/tsconfig.supported.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../typescript-config/browser-react.json",
+  "compilerOptions": { "noEmit": true, "types": [] },
+  "include": ["supported.tsx"]
+}

packages/module-ui-sdk/tests/browser-safety.test.ts

@@ -18,29 +18,30 @@ async function sourceFiles(): Promise<string[]> {
  * way; `import type` is erased at build time, a plain `import` is not.
  */
 describe("module UI SDK stays browser-safe", () => {
-  it("imports nothing from another workspace package at runtime", async () => {
+  it("imports nothing from another package at all, at type level or runtime", async () => {
+    // Stronger than "type-only imports are fine". A type-only import is erased at runtime but still
+    // drags the imported package's *type graph* into every consuming program — which is exactly how
+    // Node globals reached browser-only module UI before ADR 0024. This package now imports nothing
+    // external, so there is no graph to drag.
     for (const file of await sourceFiles()) {
       const source = await readFile(path.join(sourceDirectory, file), "utf8");
-      const workspaceImports = [
-        ...source.matchAll(/^import\s+(.*?)\s+from\s+"(@ekklesia\/[^"]+)"/gmu),
-      ];
+      const externalImports = [...source.matchAll(/^(?:import|export)\s[^;]*?from\s+"([^"]+)"/gmu)]
+        .map(([, specifier]) => specifier)
+        .filter((specifier) => specifier !== undefined && !specifier.startsWith("."));
 
-      for (const [, clause, specifier] of workspaceImports) {
-        expect(
-          clause?.startsWith("type "),
-          `${file} imports ${specifier} at runtime; it must be a type-only import`,
-        ).toBe(true);
-      }
+      expect(externalImports, `${file} imports outside this package`).toEqual([]);
     }
   });
 
-  it("declares no runtime dependency other than the type-only contracts package", async () => {
+  it("declares no dependencies whatsoever", async () => {
     const manifestPath = path.join(sourceDirectory, "..", "package.json");
     const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
       dependencies?: Record<string, string>;
+      peerDependencies?: Record<string, string>;
     };
 
-    expect(Object.keys(manifest.dependencies ?? {})).toEqual(["@ekklesia/contracts"]);
+    expect(Object.keys(manifest.dependencies ?? {})).toEqual([]);
+    expect(Object.keys(manifest.peerDependencies ?? {})).toEqual([]);
   });
 
   it("does not depend on a UI framework, so the contract stays framework-neutral", async () => {
@@ -61,5 +62,9 @@ describe("module UI SDK stays browser-safe", () => {
     for (const framework of ["react", "react-dom", "vue", "svelte", "preact"]) {
       expect(declared).not.toContain(framework);
     }
+    // Backend graphs must not reappear through a development dependency either.
+    for (const backend of ["drizzle-orm", "zod", "semver", "@ekklesia/contracts"]) {
+      expect(declared).not.toContain(backend);
+    }
   });
 });