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/tests/module-ui-host-e2e.test.ts

@@ -28,6 +28,7 @@ import {
   moduleUiSourceUrl,
 } from "@ekklesia/shell";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp } from "../src/app.js";
 
 /**
@@ -73,8 +74,12 @@ afterEach(async () => {
  * already proven end to end by `templates/module`'s own tests, and what this test needs is a byte
  * sequence whose journey through publication, inventory, and the loader can be asserted exactly.
  */
-async function createFixtureModule(modulesDirectory: string): Promise<void> {
-  const moduleDirectory = path.join(modulesDirectory, "example");
+async function createFixtureModule(
+  modulesDirectory: string,
+  id = "example",
+  name = "Example module",
+): Promise<void> {
+  const moduleDirectory = path.join(modulesDirectory, id);
   await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
   await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
 
@@ -82,7 +87,7 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
     path.join(moduleDirectory, "package.json"),
     JSON.stringify({
       ekklesia: { layer: "module" },
-      name: "@test/module-example",
+      name: `@test/module-${id}`,
       type: "module",
       version: "0.1.0",
     }),
@@ -92,14 +97,14 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
     JSON.stringify({
       compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
       entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
-      id: "example",
+      id,
       manifestVersion: 4,
-      name: "Example module",
+      name,
       permissions: [
         {
           baseline: "restricted",
           description: "Read example records.",
-          id: "example.records.read",
+          id: `${id}.records.read`,
         },
       ],
       version: "0.1.0",
@@ -108,13 +113,13 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
   await writeFile(
     path.join(moduleDirectory, "dist/server/index.js"),
     `export default {
-      id: "example",
+      id: ${JSON.stringify(id)},
       version: "0.1.0",
       register({ http }) {
         http.route({
           method: "GET",
           path: "/records",
-          permission: "example.records.read",
+          permission: ${JSON.stringify(`${id}.records.read`)},
           maxBodyBytes: 0,
           async handler() {
             return Response.json([{ id: "a" }, { id: "b" }]);
@@ -128,10 +133,10 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
   await writeFile(
     path.join(moduleDirectory, "dist/ui/index.js"),
     `export default {
-  id: "example",
+  id: ${JSON.stringify(id)},
   version: "0.1.0",
   async mount(container, context) {
-    if (!context.permissions.has("example.records.read")) {
+    if (!context.permissions.has(${JSON.stringify(`${id}.records.read`)})) {
       container.textContent = context.moduleId + ":denied";
       return () => { container.textContent = ""; };
     }
@@ -148,6 +153,10 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
 interface HarnessOptions {
   readonly principal?: EkklesiaPrincipal;
   readonly grants?: readonly string[];
+  /** Extra fixture modules, so grouping can be exercised with more than one — a folder containing a
+   * single module proves very little. */
+  readonly extraModules?: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  readonly platformOwner?: boolean;
 }
 
 interface Harness {
@@ -164,6 +173,9 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
   const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-host-e2e-"));
   temporaryDirectories.push(modulesDirectory);
   await createFixtureModule(modulesDirectory);
+  for (const extra of options.extraModules ?? []) {
+    await createFixtureModule(modulesDirectory, extra.id, extra.name);
+  }
 
   const modules = await discoverModules({
     moduleSdkVersion: "0.1.0",
@@ -180,7 +192,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
   const granted = new Set(options.grants ?? []);
   const evaluator = createAuthorizationEvaluator({
     grants: { hasActiveGrant: async (query) => granted.has(query.permission) },
-    platformOwners: { isPlatformOwner: async () => false },
+    platformOwners: { isPlatformOwner: async () => options.platformOwner === true },
   });
   const runtime: EkklesiaIdentityRuntime = {
     handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
@@ -201,6 +213,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
     moduleRoutes: moduleRuntime.routes,
     moduleServices: services,
     moduleUi: createModuleUiPublicationRegistry(modules),
+    dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: ["https://dashboard.example.test"],
   });
@@ -250,9 +263,12 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
       // 1. The shell's own bootstrap: principal, then inventory.
       const bootstrap = await bootstrapHost(harness.config);
       expect(bootstrap.principal).toEqual({ kind: "authenticated", userId: viewerId });
-      expect(bootstrap.modules).toHaveLength(1);
+      // A module nobody has arranged yet is ungrouped and visible — no initialization write.
+      expect(bootstrap.navigation.groups).toEqual([]);
+      expect(bootstrap.navigation.ungrouped).toHaveLength(1);
+      expect(bootstrap.navigation.ungrouped[0]?.name).toBe("Example module");
 
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -304,7 +320,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -336,7 +352,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -364,13 +380,187 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     }
   });
 
+  it("renders a configured arrangement, and a move changes presentation only", async () => {
+    const harness = await startHarness({
+      extraModules: [
+        { id: "video", name: "Video" },
+        { id: "calendar", name: "Calendar" },
+      ],
+      grants: ["example.records.read"],
+      platformOwner: true,
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    const organize = (url: string, body: unknown) =>
+      (harness.config.fetch as typeof fetch)(`https://ekklesia.example.test${url}`, {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json", origin: "https://dashboard.example.test" },
+        method: "PUT",
+      });
+
+    try {
+      // An administrator organizes the Dashboard, through the real mutation API.
+      await organize("/api/v1/dashboard/navigation/groups/media", { label: "Media", order: 10 });
+      await organize("/api/v1/dashboard/navigation/groups/planning", {
+        label: "Planning",
+        order: 20,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/video", {
+        groupId: "media",
+        order: 10,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/example", {
+        groupId: "media",
+        order: 20,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/calendar", {
+        groupId: "planning",
+        order: 10,
+      });
+
+      // The shell's own bootstrap sees exactly that arrangement.
+      const before = await bootstrapHost(harness.config);
+      expect(
+        before.navigation.groups.map((group) => [
+          group.label,
+          group.modules.map((entry) => entry.name),
+        ]),
+      ).toEqual([
+        ["Media", ["Video", "Example module"]],
+        ["Planning", ["Calendar"]],
+      ]);
+      expect(before.navigation.ungrouped).toEqual([]);
+
+      // Mounting from inside a group uses the descriptor the group carried, untouched.
+      const groupedEntry = before.navigation.groups[0]?.modules[1];
+      if (!groupedEntry) {
+        throw new Error("the arrangement did not contain the expected module");
+      }
+      const container = containerSink();
+      const mounted = await loadModuleUi({
+        container: container as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor: groupedEntry.descriptor,
+          principal: before.principal,
+        }),
+        source: {
+          moduleId: groupedEntry.descriptor.id,
+          url: await publishedArtifactUrl(
+            harness,
+            moduleUiSourceUrl(harness.config, groupedEntry.descriptor),
+          ),
+          version: groupedEntry.descriptor.version,
+        },
+      });
+      expect(container.textContent).toBe("example:200:2");
+      await mounted.unmount();
+
+      // Now move it somewhere else entirely.
+      await organize("/api/v1/dashboard/navigation/groups/sunday-production", {
+        label: "Sunday Production",
+        order: 5,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/example", {
+        groupId: "sunday-production",
+        order: 10,
+      });
+
+      const after = await bootstrapHost(harness.config);
+      expect(
+        after.navigation.groups.map((group) => [
+          group.label,
+          group.modules.map((entry) => entry.name),
+        ]),
+      ).toEqual([
+        ["Sunday Production", ["Example module"]],
+        ["Media", ["Video"]],
+        ["Planning", ["Calendar"]],
+      ]);
+
+      const movedEntry = after.navigation.groups[0]?.modules[0];
+      if (!movedEntry) {
+        throw new Error("the moved module was not found in its new group");
+      }
+      // The whole point of the pass: the module is byte-identical across the move — same artifact
+      // URL, same API root, same permissions, same version, same name.
+      expect(movedEntry).toEqual(groupedEntry);
+
+      // And it still mounts the same artifact and reaches the same API.
+      const callsBeforeRemount = harness.moduleApiCalls.length;
+      const movedContainer = containerSink();
+      const remounted = await loadModuleUi({
+        container: movedContainer as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor: movedEntry.descriptor,
+          principal: after.principal,
+        }),
+        source: {
+          moduleId: movedEntry.descriptor.id,
+          url: await publishedArtifactUrl(
+            harness,
+            moduleUiSourceUrl(harness.config, movedEntry.descriptor),
+          ),
+          version: movedEntry.descriptor.version,
+        },
+      });
+      expect(movedContainer.textContent).toBe("example:200:2");
+      expect(harness.moduleApiCalls.slice(callsBeforeRemount)).toEqual([
+        "GET /api/v1/modules/example/records",
+      ]);
+      await remounted.unmount();
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("keeps a newly installed module visible beside an existing arrangement", async () => {
+    const harness = await startHarness({
+      extraModules: [{ id: "video", name: "Video" }],
+      platformOwner: true,
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      await (harness.config.fetch as typeof fetch)(
+        "https://ekklesia.example.test/api/v1/dashboard/navigation/groups/media",
+        {
+          body: JSON.stringify({ label: "Media", order: 10 }),
+          headers: {
+            "content-type": "application/json",
+            origin: "https://dashboard.example.test",
+          },
+          method: "PUT",
+        },
+      );
+      await (harness.config.fetch as typeof fetch)(
+        "https://ekklesia.example.test/api/v1/dashboard/navigation/placements/video",
+        {
+          body: JSON.stringify({ groupId: "media", order: 10 }),
+          headers: {
+            "content-type": "application/json",
+            origin: "https://dashboard.example.test",
+          },
+          method: "PUT",
+        },
+      );
+
+      const bootstrap = await bootstrapHost(harness.config);
+
+      expect(bootstrap.navigation.groups[0]?.modules.map((entry) => entry.name)).toEqual(["Video"]);
+      // `example` was never placed, and is still reachable rather than invisible.
+      expect(bootstrap.navigation.ungrouped.map((entry) => entry.name)).toEqual(["Example module"]);
+    } finally {
+      await harness.stop();
+    }
+  });
+
   it("gives an anonymous visitor no inventory and therefore nothing to mount", async () => {
     const harness = await startHarness();
     try {
       const bootstrap = await bootstrapHost(harness.config);
 
       expect(bootstrap.principal).toEqual({ kind: "anonymous" });
-      expect(bootstrap.modules).toEqual([]);
+      expect(bootstrap.navigation).toEqual({ groups: [], ungrouped: [] });
     } finally {
       await harness.stop();
     }
@@ -383,7 +573,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }