feat: establish the module product contract

Ekklesia's module model has been backend-only since ADR 0001: a module
owns domain behavior and data, and every presentation concern belongs to
a surface. That prevents a module author — the person who knows the
domain — from shipping the screen that makes their module useful, and it
guarantees a module and its own UI drift apart. It also pushes toward two
codebases for one domain the moment a module needs to run standalone.

ADR 0021 replaces that rule. A module is an independently versioned
product that owns its domain behavior, data, permissions, routes,
migrations, and its own UI, hostable inside Ekklesia and — from the same
implementation — by a later standalone host. Core keeps the containing
application shell and every platform policy: authentication,
authorization enforcement, platform context, top-level routing,
navigation, global theme, error boundaries, and trusted-origin/CORS. The
module graph stays flat: modules are peers, genuine module and capability
dependencies remain the only relationships, and Dashboard folders are
presentation configuration an administrator can reorganize, never module
architecture.

This pass implements the static contract only. `manifestVersion` moves to
4 and `entrypoints` gains one optional field, `ui`. Version 3's
`entrypoints` is strict and rejects `ui`, so this is an incompatible
shape change and version 3 is now rejected outright rather than
reinterpreted, exactly as version 1 was by version 2 and version 2 by
version 3. Every field version 4 adds is optional, so upgrading a
backend-only manifest is a one-character edit.

Discovery resolves and validates `ui` under the same rules as `server`
and `schema` — package-relative, inside the package before and after
symlink resolution, a real file, compiled ESM `.js`/`.mjs`, so source
TypeScript is rejected rather than assumed to be compiled later.
Discovery stays inert: nothing imports, evaluates, mounts, or renders a
UI entrypoint, and a test proves a throwing artifact still discovers
successfully. This follows `entrypoints.jobs`, declared and resolved
since ADR 0006 with no runtime consumer.

The name is `ui`, not `dashboard`, because a module's UI must be hostable
by Ekklesia's shell and by a standalone host, so the contract cannot be
named after one of them; and not `surface`, because `surfaces/*` is a
separate ownership layer. No widget, route, icon, folder, menu, layout,
or standalone-metadata field is added, and tests assert the manifest
still rejects every unknown entrypoint key and offers no hierarchy field.

Deliberately unchanged: `scripts/check-boundaries.ts` still enforces
`modules-do-not-own-ui`. Relaxing that guard depends entirely on the UI
authoring model a later pass chooses, and weakening a working protection
before that decision exists would trade real coverage for nothing. A
module may therefore declare `ui` today only for a framework-neutral
compiled artifact, and the docs say so rather than implying otherwise.
Restart-based discovery, explicit operator-invoked migrations, and the
trusted compiled-module model are untouched — a module that ships UI is
exactly as trusted as one that does not.

No Dashboard shell, UI runtime, renderer, framework choice, navigation
registry, grouping system, standalone host, installer, hot-loading, or
feature module is added by this pass.

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

core/src/modules/discovery.ts

@@ -45,6 +45,10 @@ export interface ResolvedModuleEntrypoints {
   readonly schema?: string;
   readonly migrations?: string;
   readonly jobs?: string;
+  /** A module's declared presentation artifact (ADR 0021), resolved and validated exactly like the
+   * other entrypoints. Discovery only proves the file exists, is compiled ESM, and stays inside the
+   * module package — nothing in this repository imports, evaluates, mounts, or renders it yet. */
+  readonly ui?: string;
 }
 
 // Branded primitives (`PermissionId`, `ModuleId`, ...) are `string & {brand}` intersection types,
@@ -243,8 +247,11 @@ async function resolveEntrypoints(
     if (relativeEntrypoint === undefined) {
       continue;
     }
+    // `ui` joins `schema`/`server` here: a presentation entrypoint is a build output like any
+    // other module artifact, so source TypeScript is rejected at discovery rather than relied upon
+    // to be compiled later (ADR 0006's compiled-artifact rule, extended by ADR 0021).
     if (
-      ["schema", "server"].includes(entrypointName) &&
+      ["schema", "server", "ui"].includes(entrypointName) &&
       ![".js", ".mjs"].includes(path.extname(relativeEntrypoint).toLowerCase())
     ) {
       issues.push({
@@ -323,6 +330,7 @@ async function resolveEntrypoints(
     ...(resolved.schema ? { schema: resolved.schema } : {}),
     ...(resolved.migrations ? { migrations: resolved.migrations } : {}),
     ...(resolved.jobs ? { jobs: resolved.jobs } : {}),
+    ...(resolved.ui ? { ui: resolved.ui } : {}),
   };
 }
 

core/tests/core-migration-discovery.test.ts

@@ -91,7 +91,7 @@ async function createModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        manifestVersion: 3,
+        manifestVersion: 4,
         id,
         name: `${id} module`,
         version: "0.1.0",

core/tests/doctor.test.ts

@@ -41,7 +41,7 @@ function discoveredModule(id: string, version = "0.1.0"): DiscoveredModule {
       },
       entrypoints: { server: "./dist/server.js" },
       id,
-      manifestVersion: 3,
+      manifestVersion: 4,
       name: `${id} module`,
       permissions: [],
       storage: { buckets: [] },

core/tests/fixtures/module-database-integration/db-facade/ekklesia.module.json

@@ -1,5 +1,5 @@
 {
-  "manifestVersion": 3,
+  "manifestVersion": 4,
   "id": "db-facade",
   "name": "Database Facade Integration Test Module",
   "description": "Test-only installed module fixture proving ModuleDatabase against real PostgreSQL. Never discovered by production startup, Doctor, or normal migration aggregation — only apps/api/tests/module-database.integration.ts points discovery at it explicitly.",

core/tests/module-discovery.test.ts

@@ -13,6 +13,9 @@ interface ModuleFixtureOptions {
   manifest?: Record<string, unknown>;
   packageJson?: Record<string, unknown>;
   serverSource?: string;
+  /** Extra package-relative files to write before discovery runs, so a fixture can publish a
+   * compiled UI artifact (or a deliberately uncompiled one) alongside its server entrypoint. */
+  extraFiles?: Record<string, string>;
 }
 
 const temporaryDirectories: string[] = [];
@@ -31,7 +34,7 @@ async function createModulesDirectory(): Promise<string> {
 
 function manifestFor(id: string): Record<string, unknown> {
   return {
-    manifestVersion: 3,
+    manifestVersion: 4,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -73,6 +76,12 @@ async function createModule(
       options.serverSource ?? `export default { id: ${JSON.stringify(id)}, version: "0.1.0" };`,
     ),
   ]);
+
+  for (const [relativePath, contents] of Object.entries(options.extraFiles ?? {})) {
+    const target = path.join(moduleDirectory, relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, contents);
+  }
 }
 
 async function discoveryError(
@@ -585,4 +594,115 @@ describe("module discovery", () => {
 
     expect(firstError.issues).toEqual(secondError.issues);
   });
+
+  describe("module-owned UI entrypoint (ADR 0021)", () => {
+    function manifestWithUi(id: string, ui: string): Record<string, unknown> {
+      const manifest = manifestFor(id);
+      manifest.entrypoints = { server: "./dist/server/index.js", ui };
+      return manifest;
+    }
+
+    it("resolves a declared compiled UI entrypoint to a canonical path inside the package", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "announcements", {
+        manifest: manifestWithUi("announcements", "./dist/ui/index.js"),
+        extraFiles: { "dist/ui/index.js": "export default {};" },
+      });
+
+      const [discovered] = await discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      });
+
+      expect(discovered?.entrypoints.ui).toBe(
+        path.join(discovered?.directory ?? "", "dist/ui/index.js"),
+      );
+      expect(discovered?.entrypoints.server).toBeDefined();
+    });
+
+    it("omits the resolved UI entrypoint entirely for a backend-only module", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "roster");
+
+      const [discovered] = await discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      });
+
+      expect(discovered?.entrypoints.ui).toBeUndefined();
+      expect(Object.hasOwn(discovered?.entrypoints ?? {}, "ui")).toBe(false);
+    });
+
+    it("rejects a source TypeScript UI entrypoint where compiled output is required", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "signage", {
+        manifest: manifestWithUi("signage", "./src/ui/index.ts"),
+        extraFiles: { "src/ui/index.ts": "export default {};" },
+      });
+
+      const error = await discoveryError(modulesDirectory);
+      expect(issueCodes(error)).toContain("MODULE_ENTRYPOINT_INVALID");
+      expect(error.issues.map((issue) => issue.path)).toContain("entrypoints.ui");
+    });
+
+    it("rejects a missing UI artifact rather than silently ignoring the declaration", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "video", {
+        manifest: manifestWithUi("video", "./dist/ui/index.js"),
+      });
+
+      const error = await discoveryError(modulesDirectory);
+      expect(issueCodes(error)).toContain("MODULE_ENTRYPOINT_MISSING");
+    });
+
+    it("rejects a UI entrypoint that resolves to a directory instead of a file", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "livestream", {
+        manifest: manifestWithUi("livestream", "./dist/ui.js"),
+        extraFiles: { "dist/ui.js/placeholder.txt": "not a file entrypoint" },
+      });
+
+      const error = await discoveryError(modulesDirectory);
+      expect(issueCodes(error)).toContain("MODULE_ENTRYPOINT_INVALID");
+    });
+
+    it("rejects a UI entrypoint linked outside its own module package", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      const externalDirectory = await createModulesDirectory();
+      const externalArtifact = path.join(externalDirectory, "foreign-ui.js");
+      await writeFile(externalArtifact, "export default {};");
+      await createModule(modulesDirectory, "calendar", {
+        manifest: manifestWithUi("calendar", "./dist/ui/index.js"),
+      });
+      await mkdir(path.join(modulesDirectory, "calendar/dist/ui"), { recursive: true });
+      await symlink(externalArtifact, path.join(modulesDirectory, "calendar/dist/ui/index.js"));
+
+      const error = await discoveryError(modulesDirectory);
+      expect(issueCodes(error)).toContain("MODULE_ENTRYPOINT_INVALID");
+    });
+
+    it("never imports a UI artifact merely to discover it", async () => {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, "announcements", {
+        manifest: manifestWithUi("announcements", "./dist/ui/index.js"),
+        // Discovery is inert: a throwing artifact must not be evaluated. If discovery ever
+        // imported a UI entrypoint, this would surface as a rejected promise rather than a
+        // successfully discovered module.
+        extraFiles: {
+          "dist/ui/index.js": "throw new Error('a UI entrypoint must never be evaluated');",
+        },
+      });
+
+      const discovered = await discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      });
+
+      expect(discovered).toHaveLength(1);
+      expect(discovered[0]?.entrypoints.ui).toContain("dist/ui/index.js");
+    });
+  });
 });

core/tests/module-migration-discovery.test.ts

@@ -65,7 +65,7 @@ function manifestFor(
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 3,
+    manifestVersion: 4,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-permissions.test.ts

@@ -23,7 +23,7 @@ interface PermissionInput {
  * is read by `composePlatformPermissionRegistry`; the rest exist only to satisfy the type. */
 function fakeModule(id: string, permissions: readonly PermissionInput[] = []): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 3,
+    manifestVersion: 4,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-runtime.test.ts

@@ -52,7 +52,7 @@ function manifestFor(
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 3,
+    manifestVersion: 4,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-schema-discovery.test.ts

@@ -41,7 +41,7 @@ function manifestFor(
   options: { dependencies?: Record<string, unknown>; schema?: string | false } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 3,
+    manifestVersion: 4,
     id,
     name: `${id} module`,
     version: "0.1.0",