feat: add Dashboard navigation as presentation configuration

Phase 6D pass 1. The shell's navigation was a flat list of module ids, which
is not a usable experience — and the obvious fix carries an obvious trap.
Letting a module declare its folder, or modelling "Media" as something
Livestream and Video belong to, turns a rendering preference into
architecture: a folder becomes an owner, membership starts to look like a
dependency, and the flat module graph acquires a hierarchy nobody decided on.

So the rule comes first: a Dashboard group is a label on a rendering bucket.
No manifest, no version, no artifact, no API, no lifecycle; nothing depends on
it. Livestream depends on Video because it calls Video's functionality, and
that orders startup. Livestream is shown under Media, and that orders nothing.
No parent module, child module, owning module, or group-derived dependency
appears anywhere in the contracts.

No manifest change and no version 5. `manifest.name` has been required since
version 1 and already is the module's product identity, so the shell renders
"Livestream" instead of `livestream` with nothing added. `suggestedGroup` is
deliberately deferred rather than shipped: it would force a hard
manifest-version cutover for a hint, and its only correct semantics needs
initialization logic that risks a suggestion overwriting an administrator's
decision. Defaulting and ownership are different things.

Two Core tables (migration 0003) hold groups and placements — server-side,
because a church configures its Dashboard rather than one browser;
platform-global, because no organization model exists to scope them to.
`group_id` is `on delete set null`, so deleting a group ungroups its modules
and a dangling reference is impossible. `module_id` carries no foreign key,
because modules are packages rather than rows, so a placement for an
uninstalled module is retained and restores its position on reinstall.

`resolveDashboardNavigation` is a pure function of configuration plus the
mountable set: an unplaced module is ungrouped and visible with no
initialization write, an absent module renders nothing, empty groups are kept,
and ordering is total with the module id as final tie-break.

`GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of
the host-neutral module UI inventory rather than merged into it — each generic
descriptor is embedded untouched, so a standalone host never inherits Dashboard
semantics. Reading needs the permission the inventory already needs; organizing
needs the new platform permission `core.dashboard.navigation.manage` through a
narrow, idempotent, closed-validation mutation contract. No editor UI.

The flatness rule is executable: a test discovers real fixtures with a genuine
dependency, arranges them four ways including both in one folder and the
dependency inverted in presentation, and asserts discovery order, dependency
declarations, and the module set stay byte-identical. The end-to-end test
organizes a real installation through the real API, mounts a module from inside
a group, moves it, and asserts the navigation entry is byte-identical across the
move and still mounts the same artifact.

The shell's client for the generic inventory became dead code and was removed
rather than kept speculatively; the endpoint itself is unchanged.

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

surfaces/shell/src/host-protocol.ts

@@ -17,10 +17,15 @@ export interface EkklesiaHostConfig {
 }
 
 /** Root-relative platform paths. The shell never builds a module UI artifact URL or a module API
- * URL — the server produces both and hands them over in the inventory — so these two are the only
- * URLs it knows, and they are the two that describe the platform itself rather than any module. */
+ * URL — the server produces both and hands them over in the navigation view — so these two are the
+ * only URLs it knows, and they describe the platform itself rather than any module.
+ *
+ * `/api/v1/module-ui` is deliberately absent: that host-neutral inventory (ADR 0026) remains the
+ * endpoint a standalone host would consume, but Ekklesia's own shell needs the arrangement too, so
+ * it reads the navigation view instead. Keeping an unused client for it here would be speculative
+ * code for a consumer that does not exist. */
 const PRINCIPAL_PATH = "/api/v1/principal";
-const MODULE_UI_INVENTORY_PATH = "/api/v1/module-ui";
+const DASHBOARD_NAVIGATION_PATH = "/api/v1/dashboard/navigation";
 
 export type HostProtocolErrorCode =
   /** The caller is not signed in, or lacks `core.modules.ui.read`. */
@@ -112,37 +117,99 @@ function rootRelativePath(value: unknown, key: string): string | undefined {
  * yielding a half-built descriptor, because a descriptor with a missing URL would surface much later
  * as an inexplicable mount failure.
  */
-export function parseHostModuleUiInventory(payload: unknown): readonly HostModuleUiDescriptor[] {
-  const modules = isRecord(payload) ? payload.modules : undefined;
-  if (!Array.isArray(modules)) {
+function parseDescriptor(entry: unknown): HostModuleUiDescriptor {
+  const id = nestedString(entry, "id");
+  const version = nestedString(entry, "version");
+  const uiUrl = isRecord(entry) ? rootRelativePath(entry.ui, "url") : undefined;
+  const apiBaseUrl = isRecord(entry) ? rootRelativePath(entry.api, "baseUrl") : undefined;
+  const permissions = isRecord(entry) ? entry.permissions : undefined;
+  if (
+    id === undefined ||
+    version === undefined ||
+    uiUrl === undefined ||
+    apiBaseUrl === undefined ||
+    !Array.isArray(permissions) ||
+    permissions.some((permission) => typeof permission !== "string")
+  ) {
     throw new HostProtocolError("HOST_RESPONSE_INVALID");
   }
-  return Object.freeze(
-    modules.map((entry): HostModuleUiDescriptor => {
-      const id = nestedString(entry, "id");
-      const version = nestedString(entry, "version");
-      const uiUrl = isRecord(entry) ? rootRelativePath(entry.ui, "url") : undefined;
-      const apiBaseUrl = isRecord(entry) ? rootRelativePath(entry.api, "baseUrl") : undefined;
-      const permissions = isRecord(entry) ? entry.permissions : undefined;
-      if (
-        id === undefined ||
-        version === undefined ||
-        uiUrl === undefined ||
-        apiBaseUrl === undefined ||
-        !Array.isArray(permissions) ||
-        permissions.some((permission) => typeof permission !== "string")
-      ) {
-        throw new HostProtocolError("HOST_RESPONSE_INVALID");
-      }
-      return Object.freeze({
-        apiBaseUrl,
-        id,
-        permissions: Object.freeze([...(permissions as string[])]),
-        uiUrl,
-        version,
-      });
-    }),
-  );
+  return Object.freeze({
+    apiBaseUrl,
+    id,
+    permissions: Object.freeze([...(permissions as string[])]),
+    uiUrl,
+    version,
+  });
+}
+
+/**
+ * One module as the Dashboard presents it.
+ *
+ * The mount descriptor is nested exactly as the server sends it, not flattened into this object.
+ * That keeps the two concerns visibly separate in the browser as well as on the wire: `descriptor`
+ * is the host-neutral "what and how to mount", and `name` is Ekklesia's presentation of it. Nothing
+ * about a group is stored on the module — a module does not know, and must not know, where it has
+ * been placed.
+ */
+export interface DashboardNavigationEntry {
+  readonly name: string;
+  readonly descriptor: HostModuleUiDescriptor;
+}
+
+export interface DashboardNavigationGroup {
+  /** Opaque and stable; the shell uses it as a React key and never displays it. */
+  readonly id: string;
+  readonly label: string;
+  readonly modules: readonly DashboardNavigationEntry[];
+}
+
+/**
+ * The whole navigation the shell renders, already resolved and ordered by the server.
+ *
+ * The browser performs no grouping, no sorting, and no joining of its own: it does not read
+ * manifests, does not know which module belongs where, and could not compute this view if it wanted
+ * to. Ordering arrives as array order, so a change to the server's ordering rules needs no shell
+ * change at all.
+ */
+export interface DashboardNavigation {
+  readonly groups: readonly DashboardNavigationGroup[];
+  readonly ungrouped: readonly DashboardNavigationEntry[];
+}
+
+function parseNavigationEntry(entry: unknown): DashboardNavigationEntry {
+  const name = nestedString(entry, "name");
+  if (name === undefined || !isRecord(entry)) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  return Object.freeze({ descriptor: parseDescriptor(entry.module), name });
+}
+
+/** Strict, total validation, exactly like the inventory parser: a malformed group or entry fails
+ * the whole document rather than rendering a half-built navigation. */
+export function parseDashboardNavigation(payload: unknown): DashboardNavigation {
+  const groups = isRecord(payload) ? payload.groups : undefined;
+  const ungrouped = isRecord(payload) ? payload.ungrouped : undefined;
+  if (!Array.isArray(groups) || !Array.isArray(ungrouped)) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  return Object.freeze({
+    groups: Object.freeze(
+      groups.map((group): DashboardNavigationGroup => {
+        const id = nestedString(group, "id");
+        const label = nestedString(group, "label");
+        const modules = isRecord(group) ? group.modules : undefined;
+        if (id === undefined || label === undefined || !Array.isArray(modules)) {
+          throw new HostProtocolError("HOST_RESPONSE_INVALID");
+        }
+        return Object.freeze({
+          id,
+          label,
+          modules: Object.freeze(modules.map((entry) => parseNavigationEntry(entry))),
+        });
+      }),
+    ),
+    ungrouped: Object.freeze(ungrouped.map((entry) => parseNavigationEntry(entry))),
+  });
 }
 
 /** `/api/v1/principal`'s two documented shapes, narrowed to the browser-owned `ModuleUiPrincipal`
@@ -214,21 +281,27 @@ export async function loadHostPrincipal(
   return parseHostPrincipal(await requestPlatformJson(config, PRINCIPAL_PATH, signal));
 }
 
-/** Which module UIs this viewer may mount, where to fetch each, and what they may do inside it. */
-export async function loadModuleUiInventory(
+/** The resolved Dashboard navigation: the same mountable modules, arranged as this installation has
+ * configured them (ADR 0027). */
+export async function loadDashboardNavigation(
   config: EkklesiaHostConfig,
   signal?: AbortSignal,
-): Promise<readonly HostModuleUiDescriptor[]> {
-  return parseHostModuleUiInventory(
-    await requestPlatformJson(config, MODULE_UI_INVENTORY_PATH, signal),
+): Promise<DashboardNavigation> {
+  return parseDashboardNavigation(
+    await requestPlatformJson(config, DASHBOARD_NAVIGATION_PATH, signal),
   );
 }
 
 export interface HostBootstrap {
   readonly principal: ModuleUiPrincipal;
-  readonly modules: readonly HostModuleUiDescriptor[];
+  readonly navigation: DashboardNavigation;
 }
 
+const EMPTY_NAVIGATION: DashboardNavigation = Object.freeze({
+  groups: Object.freeze([]),
+  ungrouped: Object.freeze([]),
+});
+
 /**
  * The shell's whole startup sequence, in one explicit function: resolve who is viewing, then ask
  * what they may mount. Sequential rather than parallel on purpose — an anonymous viewer is told to
@@ -241,7 +314,7 @@ export async function bootstrapHost(
 ): Promise<HostBootstrap> {
   const principal = await loadHostPrincipal(config, signal);
   if (principal.kind === "anonymous") {
-    return { modules: Object.freeze([]), principal };
+    return { navigation: EMPTY_NAVIGATION, principal };
   }
-  return { modules: await loadModuleUiInventory(config, signal), principal };
+  return { navigation: await loadDashboardNavigation(config, signal), principal };
 }