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

packages/contracts/src/module-manifest.ts

@@ -59,12 +59,26 @@ const moduleStorageSchema = z
   .strict()
   .default(() => ({ buckets: [] }));
 
+/**
+ * The compiled artifacts a module publishes for the platform to resolve. Every entry is a
+ * package-relative path to a build output, never source: Core resolves and validates these
+ * statically during discovery, and the manifest stays inert JSON (ADR 0006, ADR 0021).
+ *
+ * `ui` is a module's optional, host-neutral presentation entrypoint (ADR 0021). It is declared and
+ * statically validated here, exactly like `jobs` already is, but **no runtime consumer exists yet**
+ * — nothing in this repository imports, evaluates, mounts, or renders it. Its name is deliberately
+ * not `dashboard`: a module's UI must be hostable by Ekklesia's own application shell *and* by a
+ * future standalone host, so the contract cannot be named after one of them. It is deliberately not
+ * `surface` either — `surfaces/*` is a separate ownership layer (ADR 0001), and reusing that word
+ * for a module-owned artifact would conflate two different things.
+ */
 const entrypointsSchema = z
   .object({
     server: packageRelativePathSchema,
     schema: packageRelativePathSchema.optional(),
     migrations: packageRelativePathSchema.optional(),
     jobs: packageRelativePathSchema.optional(),
+    ui: packageRelativePathSchema.optional(),
   })
   .strict();
 
@@ -87,9 +101,22 @@ function reportDuplicates(
   });
 }
 
+/**
+ * The one manifest shape Core accepts. Adding `entrypoints.ui` is an incompatible shape change —
+ * version 3's `entrypoints` object is `.strict()` and rejects `ui` outright — so the canonical
+ * manifest moves to `manifestVersion: 4` rather than reinterpreting version 3 (ADR 0021).
+ *
+ * Version 3, and every other version, fails validation: there is no compatibility adapter, no
+ * automatic conversion, and no dual acceptance, exactly as version 1 was rejected by version 2
+ * (ADR 0006) and version 2 by version 3 (ADR 0014). One manifest document can therefore never be
+ * read as two different versions. Upgrading a backend-only version 3 manifest is a one-character
+ * edit: no field added by version 4 is required.
+ */
+export const MODULE_MANIFEST_VERSION = 4;
+
 export const moduleManifestSchema = z
   .object({
-    manifestVersion: z.literal(3),
+    manifestVersion: z.literal(MODULE_MANIFEST_VERSION),
     id: moduleIdSchema,
     name: z.string().trim().min(1).max(120),
     description: z.string().trim().min(1).max(500).optional(),

packages/contracts/tests/module-manifest.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   isVersionCompatible,
   MODULE_LIFECYCLE_STAGES,
+  MODULE_MANIFEST_VERSION,
   packageRelativePathSchema,
   parseModuleManifest,
   parsePermissionId,
@@ -10,7 +11,7 @@ import {
 
 function validManifest(): Record<string, unknown> {
   return {
-    manifestVersion: 3,
+    manifestVersion: 4,
     id: "calendar",
     name: "Calendar",
     version: "0.1.0",
@@ -193,10 +194,10 @@ describe("module manifest contract", () => {
     expect(safeParseModuleManifest({ ...validManifest(), manifestVersion: 1 }).success).toBe(false);
   });
 
-  it("rejects a version 2 manifest rather than silently interpreting it as version 3", () => {
-    // manifestVersion 2's own permissions shape (a bare string array) is also what version 3
-    // must reject — this manifest is invalid twice over, deliberately, since a real version 2
-    // manifest is exactly this shape.
+  it("rejects a version 2 manifest rather than silently interpreting it as a later version", () => {
+    // manifestVersion 2's own permissions shape (a bare string array) is also what every later
+    // version must reject — this manifest is invalid twice over, deliberately, since a real
+    // version 2 manifest is exactly this shape.
     const version2Manifest = {
       ...validManifest(),
       manifestVersion: 2,
@@ -206,6 +207,25 @@ describe("module manifest contract", () => {
     expect(safeParseModuleManifest(version2Manifest).success).toBe(false);
   });
 
+  it("rejects a version 3 manifest rather than silently interpreting it as version 4", () => {
+    // A backend-only version 3 manifest is otherwise byte-identical to a valid version 4 one:
+    // only the version literal separates them, and it is not reinterpreted.
+    const version3Manifest = { ...validManifest(), manifestVersion: 3 };
+
+    expect(safeParseModuleManifest(version3Manifest).success).toBe(false);
+  });
+
+  it("accepts exactly one manifest version, so no document can be read as two versions", () => {
+    expect(MODULE_MANIFEST_VERSION).toBe(4);
+    for (const manifestVersion of [1, 2, 3, 5, "4", 4.5, null]) {
+      expect(safeParseModuleManifest({ ...validManifest(), manifestVersion }).success).toBe(false);
+    }
+    expect(
+      safeParseModuleManifest({ ...validManifest(), manifestVersion: MODULE_MANIFEST_VERSION })
+        .success,
+    ).toBe(true);
+  });
+
   it("rejects a bare permission-id string array instead of complete declarations", () => {
     const manifest = { ...validManifest(), permissions: ["calendar.events.read"] };
 
@@ -325,4 +345,115 @@ describe("module manifest contract", () => {
     expect(MODULE_LIFECYCLE_STAGES).toContain("discovered");
     expect(MODULE_LIFECYCLE_STAGES).toContain("failed");
   });
+
+  describe("module-owned UI entrypoint (ADR 0021)", () => {
+    it("accepts a backend-only module that declares no UI at all", () => {
+      const manifest = parseModuleManifest(validManifest());
+
+      expect(manifest.entrypoints.ui).toBeUndefined();
+      expect(manifest.entrypoints.server).toBe("./dist/server/index.js");
+    });
+
+    it("accepts a declared compiled UI entrypoint alongside the server entrypoint", () => {
+      const manifest = parseModuleManifest({
+        ...validManifest(),
+        entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+      });
+
+      expect(manifest.entrypoints.ui).toBe("./dist/ui/index.js");
+      // Declaring UI never alters the backend contract: a product module is one module, not two.
+      expect(manifest.entrypoints.server).toBe("./dist/server/index.js");
+    });
+
+    it.each([
+      ["../outside/ui.js", "escapes the package boundary"],
+      ["/absolute/ui.js", "is an absolute path"],
+      ["./dist/../../ui.js", "traverses out through a parent segment"],
+      ["file:///dist/ui/index.js", "is a URL rather than a package-relative path"],
+      ["./dist\\ui\\index.js", "uses backslash separators"],
+      ["./dist/ui/index.js?raw", "carries a query string"],
+      ["", "is empty"],
+    ])("rejects a UI entrypoint that %s", (ui) => {
+      const manifest = {
+        ...validManifest(),
+        entrypoints: { server: "./dist/server/index.js", ui },
+      };
+
+      expect(safeParseModuleManifest(manifest).success).toBe(false);
+    });
+
+    it.each([
+      42,
+      null,
+      true,
+      ["./dist/ui/index.js"],
+      { entry: "./dist/ui/index.js" },
+    ])("rejects a non-string UI entrypoint %s", (ui) => {
+      const manifest = {
+        ...validManifest(),
+        entrypoints: { server: "./dist/server/index.js", ui },
+      };
+
+      expect(safeParseModuleManifest(manifest).success).toBe(false);
+    });
+
+    it("still rejects unknown entrypoint keys, so UI is the only new one", () => {
+      for (const unknownEntrypoint of ["dashboard", "surface", "client", "web", "renderers"]) {
+        const manifest = {
+          ...validManifest(),
+          entrypoints: {
+            server: "./dist/server/index.js",
+            [unknownEntrypoint]: "./dist/ui/index.js",
+          },
+        };
+
+        expect(safeParseModuleManifest(manifest).success).toBe(false);
+      }
+    });
+
+    it("declares no grouping, folder, parent, or menu field for a module to own", () => {
+      // Dashboard organization is presentation configuration, never module architecture
+      // (ADR 0021). The manifest must offer no place to encode a hierarchy.
+      for (const presentationField of [
+        "group",
+        "folder",
+        "parent",
+        "menu",
+        "navigation",
+        "icon",
+        "order",
+      ]) {
+        const manifest = { ...validManifest(), [presentationField]: "media" };
+
+        expect(safeParseModuleManifest(manifest).success).toBe(false);
+      }
+    });
+
+    it("keeps the module dependency graph flat: UI adds no parent/child relationship", () => {
+      const manifest = parseModuleManifest({
+        ...validManifest(),
+        entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+      });
+
+      // A module that ships UI still expresses relationships only through genuine module and
+      // capability dependencies — the same two mechanisms a backend-only module uses.
+      expect(Object.keys(manifest.dependencies.modules.required)).toEqual([]);
+      expect(Object.keys(manifest.dependencies.modules.optional)).toEqual([]);
+      expect(Object.keys(manifest)).not.toContain("children");
+    });
+
+    it("still supports a genuine module dependency for a module that ships UI", () => {
+      const manifest = parseModuleManifest({
+        ...validManifest(),
+        dependencies: {
+          modules: { required: { people: "^0.1.0" } },
+          capabilities: { required: { "people.records": "^2.0.0" } },
+        },
+        entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+      });
+
+      expect(manifest.dependencies.modules.required).toEqual({ people: "^0.1.0" });
+      expect(manifest.dependencies.capabilities.required).toEqual({ "people.records": "^2.0.0" });
+    });
+  });
 });