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(),