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/src/host-context.ts

@@ -1,4 +1,33 @@
-import type { EkklesiaPrincipal } from "@ekklesia/contracts";
+/**
+ * Who is viewing, as a browser sees it.
+ *
+ * This is deliberately **not** Core's `EkklesiaPrincipal`, and the difference is the point. That
+ * type's `userId` is a Zod-branded string whose brand only means something to server-side parsing,
+ * and reaching for it made this package import `@ekklesia/contracts` — a backend barrel whose type
+ * graph pulls Drizzle, and with it Node's global declarations, back into every module UI program
+ * (measured: a UI file importing this package could typecheck `process.env`). A browser contract
+ * that drags a database ORM's types behind it is not a browser contract.
+ *
+ * So the shape is preserved and the brand is dropped: plain, serializable, and exactly what a UI
+ * needs to decide what to render. An Ekklesia host can pass its own `EkklesiaPrincipal` straight in
+ * — a branded string is assignable to `string`, so the two remain structurally compatible without
+ * this package knowing anything about the server's representation. A standalone host builds the
+ * same object literal from whatever identity system it has.
+ *
+ * Nothing server-internal belongs here. A field is added only when module UI provably needs it to
+ * render something.
+ */
+export interface ModuleUiAnonymousPrincipal {
+  readonly kind: "anonymous";
+}
+
+export interface ModuleUiAuthenticatedPrincipal {
+  readonly kind: "authenticated";
+  /** Opaque to module UI: an identifier to correlate with, never to parse or display verbatim. */
+  readonly userId: string;
+}
+
+export type ModuleUiPrincipal = ModuleUiAnonymousPrincipal | ModuleUiAuthenticatedPrincipal;
 
 /**
  * Everything a host hands a module's UI, and the complete list of what module UI may assume exists.
@@ -10,7 +39,8 @@ import type { EkklesiaPrincipal } from "@ekklesia/contracts";
  * than to add. See ADR 0022.
  *
  * Nothing in this object is an Ekklesia implementation. Every member is satisfiable by a standalone
- * host that never runs Core, which is what makes one module UI hostable by both.
+ * host that never runs Core, which is what makes one module UI hostable by both. This package has
+ * no dependencies at all, so importing it cannot pull a backend type graph into a browser program.
  */
 export interface ModuleUiHostContext {
   /** The module this UI belongs to, as the host knows it. Supplied so a module never has to hardcode
@@ -18,9 +48,9 @@ export interface ModuleUiHostContext {
   readonly moduleId: string;
   /** The only supported way for module UI to reach its own backend. See {@link ModuleUiApiClient}. */
   readonly api: ModuleUiApiClient;
-  /** Who is viewing, for presentation decisions only. Reuses Core's own principal type so a host and
-   * a module UI cannot disagree about its shape. */
-  readonly principal: EkklesiaPrincipal;
+  /** Who is viewing, for presentation decisions only. See {@link ModuleUiPrincipal} for why this is
+   * a browser-owned shape rather than Core's server principal type. */
+  readonly principal: ModuleUiPrincipal;
   /** Presentation-only permission hints. See {@link ModuleUiPermissions}. */
   readonly permissions: ModuleUiPermissions;
 }