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

apps/api/src/app.ts

@@ -9,11 +9,13 @@ import type {
   PermissionRegistry,
 } from "@ekklesia/core/authorization";
 import { type EkklesiaIdentityRuntime, IdentityRuntimeError } from "@ekklesia/core/identity";
+import type { DashboardStore } from "@ekklesia/core/dashboard";
 import type { ModuleUiPublicationRegistry } from "@ekklesia/core/modules";
 import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
 import { cors } from "hono/cors";
 import { AUTH_REQUEST_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js";
+import { createDashboardRoutes } from "./dashboard-routes.js";
 import { createGrantsRoutes } from "./grants-routes.js";
 import { canonicalizeVaryHeader, mountModuleHttpRoutes } from "./module-http-routes.js";
 import { createModuleUiInventoryRoutes } from "./module-ui-inventory.js";
@@ -47,6 +49,12 @@ export interface CreateApiAppOptions {
    * is: a caller that publishes no module UI must say so explicitly with an empty registry, never
    * fall through to an implicit one. See `./module-ui-routes.js`. */
   readonly moduleUi: ModuleUiPublicationRegistry;
+  /** Core's persistence for how this Dashboard presents installed modules (ADR 0027). Required
+   * rather than defaulted, like every other module option here: a caller that exercises no
+   * Dashboard says so with an explicit store, never falls through to an implicit one. Grouping is
+   * presentation only — nothing reachable through this store influences discovery, dependency
+   * ordering, module startup, or any authorization decision. */
+  readonly dashboard: DashboardStore;
   readonly runtime: EkklesiaIdentityRuntime;
   /** Exact allowed browser origins. Never a wildcard; combined with `credentials: true`, only an
    * exact, reflected match is ever returned in `Access-Control-Allow-Origin`. Also the trusted set
@@ -193,6 +201,21 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
     }),
   );
 
+  // Layered deliberately on top of the generic inventory above rather than merged into it: the
+  // inventory stays the host-neutral "what is mountable" contract a standalone host could consume,
+  // and this adds Ekklesia's own presentation of those same modules. See `./dashboard-routes.js`.
+  app.route(
+    "/",
+    createDashboardRoutes({
+      evaluator: options.authorization.evaluator,
+      moduleUi: options.moduleUi,
+      registry: options.authorization.registry,
+      runtime,
+      store: options.dashboard,
+      trustedOrigins: allowedOrigins,
+    }),
+  );
+
   mountModuleHttpRoutes(app, options.moduleRoutes, {
     evaluator: options.authorization.evaluator,
     registry: options.authorization.registry,

apps/api/src/dashboard-routes.ts

@@ -0,0 +1,310 @@
+import {
+  CORE_DASHBOARD_NAVIGATION_MANAGE,
+  CORE_MODULES_UI_READ,
+} from "@ekklesia/core/authorization";
+import {
+  DASHBOARD_SORT_ORDER_MAX,
+  DASHBOARD_SORT_ORDER_MIN,
+  type DashboardStore,
+  DashboardStoreError,
+  isValidDashboardIdentifier,
+  normalizeDashboardGroupLabel,
+  resolveDashboardNavigation,
+} from "@ekklesia/core/dashboard";
+import type { ModuleUiPublicationRegistry } from "@ekklesia/core/modules";
+import { Hono } from "hono";
+import type { Context } from "hono";
+import {
+  type AuthorizationMiddlewareOptions,
+  getAuthorizedPrincipal,
+  requirePermission,
+  requireTrustedOrigin,
+} from "./authorization-middleware.js";
+import { CORE_MUTATION_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js";
+import { describeMountableModules, type HostModuleUiDescriptor } from "./module-ui-inventory.js";
+
+export const DASHBOARD_NAVIGATION_PATH = "/api/v1/dashboard/navigation";
+const DASHBOARD_GROUPS_PATH = `${DASHBOARD_NAVIGATION_PATH}/groups`;
+const DASHBOARD_PLACEMENTS_PATH = `${DASHBOARD_NAVIGATION_PATH}/placements`;
+
+/**
+ * One module as the Dashboard presents it: the module's display name, plus the generic mount
+ * descriptor unchanged.
+ *
+ * The descriptor is **embedded rather than flattened**, and that is the layering made visible.
+ * `module` is exactly `HostModuleUiDescriptor` — the host-neutral answer to "what is mountable and
+ * how" (ADR 0026) — and `name` is the Dashboard's presentation concern layered on top. A standalone
+ * host consumes the inner object and never learns that Ekklesia has folders; Ekklesia's shell
+ * consumes the outer one. Neither contract is warped to serve the other, and there is one
+ * construction of the descriptor rather than two that could drift.
+ */
+export interface DashboardNavigationModuleView {
+  readonly name: string;
+  readonly module: HostModuleUiDescriptor;
+}
+
+export interface DashboardNavigationGroupView {
+  /** The stable key, unchanged by a rename. Addresses the group in the mutation API; never displayed. */
+  readonly id: string;
+  readonly label: string;
+  readonly order: number;
+  readonly modules: readonly DashboardNavigationModuleView[];
+}
+
+export interface DashboardNavigationResponse {
+  readonly groups: readonly DashboardNavigationGroupView[];
+  /** Modules an administrator placed outside every group, and modules never configured at all — a
+   * newly installed module most importantly. Never empty merely because nothing has been arranged. */
+  readonly ungrouped: readonly DashboardNavigationModuleView[];
+}
+
+export interface CreateDashboardRoutesOptions extends AuthorizationMiddlewareOptions {
+  /** The same publication registry the artifact route and the generic inventory serve from: the one
+   * accepted, mountable module set. Navigation never rescans, never reads a manifest, and never
+   * discovers anything of its own. */
+  readonly moduleUi: ModuleUiPublicationRegistry;
+  readonly store: DashboardStore;
+  readonly trustedOrigins: ReadonlySet<string>;
+}
+
+function sanitizedFailure(c: Context, status: 400 | 404 | 503, code: string): Response {
+  c.header("Cache-Control", "no-store");
+  return c.json({ code }, status);
+}
+
+/** Maps the store's own sanitized codes onto HTTP without inventing a second vocabulary. A
+ * validation failure the route already rejects can still arrive here from a concurrent change, so
+ * both paths are handled rather than assumed unreachable. */
+function storeFailure(c: Context, error: unknown): Response {
+  if (error instanceof DashboardStoreError) {
+    if (error.code === "DASHBOARD_GROUP_NOT_FOUND") {
+      return sanitizedFailure(c, 404, error.code);
+    }
+    if (error.code === "DASHBOARD_READ_FAILED" || error.code === "DASHBOARD_WRITE_FAILED") {
+      return sanitizedFailure(c, 503, error.code);
+    }
+    return sanitizedFailure(c, 400, "INVALID_REQUEST");
+  }
+  return sanitizedFailure(c, 503, "DASHBOARD_WRITE_FAILED");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parsedSortOrder(value: unknown): number | undefined {
+  if (
+    typeof value !== "number" ||
+    !Number.isSafeInteger(value) ||
+    value < DASHBOARD_SORT_ORDER_MIN ||
+    value > DASHBOARD_SORT_ORDER_MAX
+  ) {
+    return undefined;
+  }
+  return value;
+}
+
+const GROUP_BODY_KEYS = new Set(["label", "order"]);
+const PLACEMENT_BODY_KEYS = new Set(["groupId", "order"]);
+
+/**
+ * Structured, closed validation — never a free-form configuration blob. Any key beyond the declared
+ * ones makes the whole body invalid rather than being silently dropped, so a caller cannot smuggle a
+ * field a future version might interpret, and a typo fails loudly instead of quietly doing nothing.
+ */
+function parseGroupBody(raw: unknown): { label: string; order: number } | undefined {
+  if (!isRecord(raw) || Object.keys(raw).some((key) => !GROUP_BODY_KEYS.has(key))) {
+    return undefined;
+  }
+  const order = parsedSortOrder(raw.order);
+  const label = normalizeDashboardGroupLabel(raw.label);
+  if (label === undefined || order === undefined) {
+    return undefined;
+  }
+  return { label, order };
+}
+
+function parsePlacementBody(raw: unknown): { groupId: string | null; order: number } | undefined {
+  if (!isRecord(raw) || Object.keys(raw).some((key) => !PLACEMENT_BODY_KEYS.has(key))) {
+    return undefined;
+  }
+  const order = parsedSortOrder(raw.order);
+  const groupId = raw.groupId;
+  if (order === undefined || (groupId !== null && !isValidDashboardIdentifier(groupId))) {
+    return undefined;
+  }
+  return { groupId, order };
+}
+
+async function readJsonBody(c: Context): Promise<unknown> {
+  try {
+    return (await c.req.json()) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The Ekklesia Dashboard's navigation: how this installation presents its mountable modules, and the
+ * narrow, structured API for changing that.
+ *
+ * ## Navigation is layered on the inventory, not merged into it
+ *
+ * `GET /api/v1/module-ui` (ADR 0026) answers *what may be mounted* and stays host-neutral — a
+ * standalone host uses it and never learns Ekklesia has folders. This route answers *how this
+ * Dashboard presents those modules*, and embeds each generic descriptor untouched inside a
+ * presentation wrapper. Keeping them separate is what stops Dashboard semantics leaking into the
+ * portable module-host contract.
+ *
+ * ## Grouping is presentation, and structurally cannot be anything else
+ *
+ * The resolved view is computed by `resolveDashboardNavigation`, a pure function of stored
+ * configuration and the current module set. It reads no manifest, no dependency, no capability, and
+ * no entrypoint, and it produces no relationship between two modules. Modules stay flat (ADR 0021,
+ * ADR 0027): two modules in one group are exactly as related as two in different groups, and moving
+ * one changes a single presentation row — never its artifact, its API root, its permissions, its
+ * dependencies, or when it starts.
+ *
+ * ## Reading versus organizing
+ *
+ * Reading requires `core.modules.ui.read`, the same permission the generic inventory requires,
+ * because this response *contains* that inventory and serves the same audience: any signed-in user
+ * needs it to see anything at all. Organizing requires `core.dashboard.navigation.manage`
+ * (restricted) — a platform permission, never a module's — and, like every other Core mutation, an
+ * exact trusted `Origin` and a bounded body before authorization work begins.
+ *
+ * Holding the manage permission grants no module authority. Every module route remains enforced
+ * against its own declared permission, and no arrangement of folders changes a single authorization
+ * decision.
+ */
+export function createDashboardRoutes(options: CreateDashboardRoutesOptions): Hono {
+  const routes = new Hono();
+  const middlewareOptions: AuthorizationMiddlewareOptions = {
+    evaluator: options.evaluator,
+    registry: options.registry,
+    runtime: options.runtime,
+  };
+  const requireRead = requirePermission(middlewareOptions, CORE_MODULES_UI_READ);
+  const requireManage = requirePermission(middlewareOptions, CORE_DASHBOARD_NAVIGATION_MANAGE);
+  const requireOrigin = requireTrustedOrigin(options.trustedOrigins);
+  const mutationBodyLimit = platformBodyLimit(CORE_MUTATION_MAX_BODY_BYTES);
+
+  routes.get(DASHBOARD_NAVIGATION_PATH, requireRead, async (c) => {
+    c.header("Cache-Control", "no-store");
+    // Per-principal: the embedded descriptors carry permission hints evaluated for this caller.
+    c.header("Vary", "Origin, Cookie");
+    const principal = getAuthorizedPrincipal(c);
+    try {
+      const [configuration, descriptors] = await Promise.all([
+        options.store.readConfiguration(),
+        describeMountableModules(options.evaluator, principal, options.moduleUi),
+      ]);
+      const view = resolveDashboardNavigation(
+        configuration,
+        descriptors.map((entry) => ({ id: entry.descriptor.id, ...entry })),
+      );
+      const present = (entry: {
+        readonly descriptor: HostModuleUiDescriptor;
+        readonly name: string;
+      }): DashboardNavigationModuleView => ({ module: entry.descriptor, name: entry.name });
+      return c.json(
+        {
+          groups: view.groups.map((group) => ({
+            id: group.id,
+            label: group.label,
+            modules: group.modules.map(present),
+            order: group.order,
+          })),
+          ungrouped: view.ungrouped.map(present),
+        } satisfies DashboardNavigationResponse,
+        200,
+      );
+    } catch (error) {
+      if (error instanceof DashboardStoreError) {
+        return storeFailure(c, error);
+      }
+      // An authorization-evaluation outage, exactly as the generic inventory reports it: a
+      // permission hint that could not be determined is never rendered as "not granted".
+      return sanitizedFailure(c, 503, "AUTHORIZATION_EVALUATION_FAILED");
+    }
+  });
+
+  routes.put(
+    `${DASHBOARD_GROUPS_PATH}/:groupId`,
+    requireOrigin,
+    mutationBodyLimit,
+    requireManage,
+    async (c) => {
+      c.header("Cache-Control", "no-store");
+      const groupId = c.req.param("groupId");
+      const body = parseGroupBody(await readJsonBody(c));
+      if (!body || !isValidDashboardIdentifier(groupId)) {
+        return sanitizedFailure(c, 400, "INVALID_REQUEST");
+      }
+      try {
+        // Idempotent by design: creating and renaming are the same operation against a
+        // client-chosen, stable id, so a rename can never orphan the placements pointing at it.
+        const group = await options.store.upsertGroup({
+          id: groupId,
+          label: body.label,
+          sortOrder: body.order,
+        });
+        return c.json({ id: group.id, label: group.label, order: group.sortOrder }, 200);
+      } catch (error) {
+        return storeFailure(c, error);
+      }
+    },
+  );
+
+  routes.delete(`${DASHBOARD_GROUPS_PATH}/:groupId`, requireOrigin, requireManage, async (c) => {
+    c.header("Cache-Control", "no-store");
+    const groupId = c.req.param("groupId");
+    if (!isValidDashboardIdentifier(groupId)) {
+      return sanitizedFailure(c, 400, "INVALID_REQUEST");
+    }
+    try {
+      // Modules in the group become ungrouped through the schema's `on delete set null`, so no
+      // module is lost and no placement is left pointing at a group that no longer exists.
+      await options.store.deleteGroup(groupId);
+      return c.body(null, 204);
+    } catch (error) {
+      return storeFailure(c, error);
+    }
+  });
+
+  routes.put(
+    `${DASHBOARD_PLACEMENTS_PATH}/:moduleId`,
+    requireOrigin,
+    mutationBodyLimit,
+    requireManage,
+    async (c) => {
+      c.header("Cache-Control", "no-store");
+      const moduleId = c.req.param("moduleId");
+      const body = parsePlacementBody(await readJsonBody(c));
+      if (!body || !isValidDashboardIdentifier(moduleId)) {
+        return sanitizedFailure(c, 400, "INVALID_REQUEST");
+      }
+      try {
+        // A placement may be stored for a module that is not installed: that is how uninstalling
+        // and reinstalling preserves an arrangement. Nothing renders it until the module is back.
+        const placement = await options.store.setPlacement({
+          groupId: body.groupId,
+          moduleId,
+          sortOrder: body.order,
+        });
+        return c.json(
+          {
+            groupId: placement.groupId,
+            moduleId: placement.moduleId,
+            order: placement.sortOrder,
+          },
+          200,
+        );
+      } catch (error) {
+        return storeFailure(c, error);
+      }
+    },
+  );
+
+  return routes;
+}

apps/api/src/database.ts

@@ -3,12 +3,17 @@ import {
   type AuthorizationDrizzleDatabase,
   createAuthorizationDrizzleView,
 } from "@ekklesia/core/authorization";
+import {
+  createDashboardDrizzleView,
+  type DashboardDrizzleDatabase,
+} from "@ekklesia/core/dashboard";
 import { createValidatedPostgresPool, type PostgresPoolOptions } from "@ekklesia/core/database";
 import { createIdentityDrizzleView, type IdentityDrizzleDatabase } from "@ekklesia/core/identity";
 import { createModuleDatabaseView } from "@ekklesia/core/modules";
 
 export interface ApiDatabaseHandle {
   readonly authorization: AuthorizationDrizzleDatabase;
+  readonly dashboard: DashboardDrizzleDatabase;
   readonly identity: IdentityDrizzleDatabase;
   readonly module: ModuleDatabase;
   /** Closes the one shared pool exactly once, regardless of how many typed views were created
@@ -35,6 +40,7 @@ export function createApiDatabase(
   return Object.freeze({
     authorization: createAuthorizationDrizzleView(pool),
     close,
+    dashboard: createDashboardDrizzleView(pool),
     identity: createIdentityDrizzleView(pool),
     module: createModuleDatabaseView(pool),
   });

apps/api/src/module-ui-inventory.ts

@@ -120,6 +120,38 @@ async function describeModule(
   };
 }
 
+/** One mountable module, described once: the host-neutral mount descriptor plus the module's own
+ * display name, kept beside it rather than inside it. */
+export interface MountableModuleDescription {
+  readonly descriptor: HostModuleUiDescriptor;
+  /** `manifest.name`. Presentation *identity* the module owns — never its placement, which the
+   * Dashboard owns (ADR 0027). Deliberately absent from `HostModuleUiDescriptor`, so the
+   * host-neutral contract a standalone host consumes stays free of presentation concerns. */
+  readonly name: string;
+}
+
+/**
+ * The one composition of the mountable-module set, shared by the generic inventory route and the
+ * Dashboard navigation route (`./dashboard-routes.js`).
+ *
+ * Both derive from the same publication registry and the same evaluator, so the two endpoints can
+ * never disagree about what exists, what its URLs are, or what the caller may do inside it. Sharing
+ * this function rather than duplicating the mapping is what makes that a structural property instead
+ * of a convention.
+ */
+export async function describeMountableModules(
+  evaluator: AuthorizationMiddlewareOptions["evaluator"],
+  principal: EkklesiaPrincipal,
+  registry: ModuleUiPublicationRegistry,
+): Promise<readonly MountableModuleDescription[]> {
+  return Promise.all(
+    registry.list().map(async (published) => ({
+      descriptor: await describeModule(evaluator, principal, published),
+      name: published.name,
+    })),
+  );
+}
+
 /** Mirrors `requirePermission`'s own infrastructure-failure result exactly: a permission hint that
  * could not be determined is never reported as "not granted". Carries no module id, permission id,
  * or caught error. */
@@ -178,11 +210,14 @@ export function createModuleUiInventoryRoutes(options: CreateModuleUiInventoryRo
     // The `authenticated` baseline guarantees this is an authenticated principal.
     const principal = getAuthorizedPrincipal(c);
     try {
-      const modules = await Promise.all(
-        options.moduleUi
-          .list()
-          .map((published) => describeModule(options.evaluator, principal, published)),
+      const described = await describeMountableModules(
+        options.evaluator,
+        principal,
+        options.moduleUi,
       );
+      // Only the host-neutral descriptor reaches this response: the display name stays out of the
+      // portable contract and is carried by the Dashboard navigation view instead.
+      const modules = described.map((entry) => entry.descriptor);
       return c.json({ modules } satisfies HostModuleUiInventory, 200);
     } catch {
       return sanitizedInventoryFailure(c);

apps/api/src/server.ts

@@ -6,6 +6,7 @@ import {
   createAuthorizationEvaluator,
   createAuthorizationStore,
 } from "@ekklesia/core/authorization";
+import { createDashboardStore } from "@ekklesia/core/dashboard";
 import { createIdentityRuntime, type IdentityRateLimitOverride } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
@@ -413,6 +414,8 @@ export async function startApi(
       // module, and a module that failed to load, register, or start never reaches this line at
       // all. Modules declaring no `entrypoints.ui` are simply absent from the registry.
       moduleUi: createModuleUiPublicationRegistry(inventory.modules),
+      // A typed view over the same single pool as identity, authorization, and the module facade.
+      dashboard: createDashboardStore(databaseHandle.dashboard),
       runtime,
       trustedOrigins: config.identity.trustedOrigins,
     });