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]>

docs/module-development/README.md

@@ -231,7 +231,7 @@ independent.
 | --- | --- |
 | `moduleId` | Your module's id, so you never re-derive it from a URL |
 | `api` | `request(path, init)` against **your own** module API — see below |
-| `principal` | Who is viewing (`anonymous` or `authenticated`), for presentation |
+| `principal` | Who is viewing: `ModuleUiPrincipal`, either `{ kind: "anonymous" }` or `{ kind: "authenticated", userId }` |
 | `permissions` | `has(permissionId)` — a presentation hint, never a security check |
 
 Navigation, host theme and design tokens, module configuration, organization context, and
@@ -332,12 +332,13 @@ not match `.tsx`, and a UI project covers the browser half:
 }
 ```
 
-`"types": []` is deliberate: UI source should not reach for Node globals. Be aware this is a
-convention rather than an airtight guard — TypeScript still pulls global declarations in
-transitively through dependency type graphs, so `process.env` currently typechecks in a UI file that
-imports `@ekklesia/module-ui-sdk`. Nothing catches it at build time either: only
-`process.env.NODE_ENV` is substituted, so any other Node global reaches the browser and fails there.
-Treat "no Node globals in UI source" as a rule you keep, not one the compiler keeps for you.
+`"types": []` is deliberate, and as of
+[ADR 0024](../architecture/decisions/0024-browser-safe-ui-sdk-and-host-loader.md) it actually holds:
+`process.env` in a UI file fails to compile even though the file imports `@ekklesia/module-ui-sdk`.
+It did not hold previously — the SDK imported `@ekklesia/contracts`, whose barrel pulled Drizzle's
+types and with them Node's globals into every module UI program. The SDK now has **no dependencies at
+all**, so importing it cannot drag a backend type graph into your browser code, and a compile test in
+that package proves both directions.
 
 `noEmit` is also deliberate — TypeScript only checks types here; esbuild produces the artifact.
 
@@ -382,9 +383,11 @@ Layer rules are unchanged: module UI source may not import Core, an app, a surfa
 another module. An unsupported framework aliased behind an allowed name — `"react": "npm:vue@3"` —
 is resolved and rejected by its real target.
 
-> **Still no host.** You can now author, build, and test a module UI end to end. **Nothing serves it
-> to a user yet** — the Dashboard shell does not exist, and neither does the standalone host. Your
-> artifact is proven by your own tests, not mounted in production.
+> **Still no host.** You can author, build, and test a module UI end to end, and
+> `@ekklesia/module-ui-host` can load and mount a built artifact from a browser URL. **Nothing serves
+> your artifact at such a URL yet** — Ekklesia has no module-asset publication route, and the
+> Dashboard shell and standalone host do not exist. Your artifact is proven by tests, not mounted in
+> production. See [How a host loads your UI](#how-a-host-loads-your-ui).
 
 ### What this does and does not do today
 
@@ -398,6 +401,49 @@ Core also never *builds* anything. Building is an authoring and packaging step y
 discovers the compiled artifact you shipped and validates it. Installing a module does not trigger a
 build, and neither does starting the API.
 
+### How a host loads your UI
+
+You do not write this — a host does — but knowing the shape explains what your artifact must satisfy.
+`@ekklesia/module-ui-host` is the generic loader both Ekklesia and a future standalone host use
+([ADR 0024](../architecture/decisions/0024-browser-safe-ui-sdk-and-host-loader.md)):
+
+```text
+compiled artifact (dist/ui/index.js)
+        ↓  asset publication — host-specific, NOT YET IMPLEMENTED for Ekklesia
+browser-loadable module URL
+        ↓  loadModuleUi({ source, container, context })
+dynamic import → parseModuleUiExport → identity checked against the manifest
+        ↓
+mount(container, context)
+        ↓
+MountedModuleUi.unmount()   // idempotent
+```
+
+```ts
+const mounted = await loadModuleUi({
+  source: { moduleId: "example", version: "0.1.0", url: publishedUrl },
+  container,
+  context,
+});
+await mounted.unmount();
+```
+
+What that means for you as a module author:
+
+- **Your `id` and `version` must match your manifest.** They are checked *before* `mount` runs, so a
+  stale artifact is rejected rather than rendered.
+- **Return an unmount function if you acquire anything.** The host calls it once; calling it again is
+  a no-op. Returning nothing is fine if you acquired nothing.
+- **If your `mount` throws, nothing is registered as mounted** and the host is told the mount failed.
+  The loader does not clear your container — the host owns it and decides what a failure looks like.
+- **Your UI may be mounted more than once**, into different containers, if your implementation
+  supports it. Each mount gets its own cleanup.
+
+> **Asset publication is the missing piece.** Core resolves `entrypoints.ui` to a path on the
+> *server's filesystem*; a browser cannot import that. Something must serve your compiled artifact at
+> a URL first, and Ekklesia has no such route yet. Until it does, no host can mount an installed
+> module's UI — the loader is ready, the plumbing to reach it is not.
+
 ### What a module UI will never own
 
 A module UI consumes platform policy and never redefines it.