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

core/tests/authorization-permissions.test.ts

@@ -2,6 +2,7 @@ import { parsePermissionId } from "@ekklesia/contracts";
 import { describe, expect, it } from "vitest";
 import {
   CORE_AUTHORIZATION_GRANTS_MANAGE,
+  CORE_DASHBOARD_NAVIGATION_MANAGE,
   CORE_MODULES_UI_READ,
   CORE_PERMISSION_DECLARATIONS,
   CORE_PERMISSION_REGISTRY,
@@ -100,10 +101,20 @@ describe("CORE_PERMISSION_REGISTRY", () => {
     expect(declaration?.id).toBe("core.modules.ui.read");
   });
 
-  it("contains exactly these two permissions and no others", () => {
+  it("registers core.dashboard.navigation.manage as restricted", () => {
+    const declaration = CORE_PERMISSION_REGISTRY.get(CORE_DASHBOARD_NAVIGATION_MANAGE);
+    expect(declaration).toBeDefined();
+    // Reorganizing the Dashboard is administrative, not something every signed-in user may do —
+    // unlike merely reading which module UIs exist (ADR 0027).
+    expect(declaration?.baseline).toBe("restricted");
+    expect(declaration?.id).toBe("core.dashboard.navigation.manage");
+  });
+
+  it("contains exactly these three permissions and no others", () => {
     expect(CORE_PERMISSION_REGISTRY.declarations.map((declaration) => declaration.id)).toEqual([
       CORE_AUTHORIZATION_GRANTS_MANAGE,
       CORE_MODULES_UI_READ,
+      CORE_DASHBOARD_NAVIGATION_MANAGE,
     ]);
   });
 });
@@ -121,10 +132,16 @@ describe("CORE_PERMISSION_DECLARATIONS", () => {
         description: "List the installed module UIs a browser host may mount.",
         id: CORE_MODULES_UI_READ,
       },
+      {
+        baseline: "restricted",
+        description: "Organize the Dashboard: create, rename, order, and delete navigation groups.",
+        id: CORE_DASHBOARD_NAVIGATION_MANAGE,
+      },
     ]);
     expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS)).toBe(true);
     expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS[0])).toBe(true);
     expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS[1])).toBe(true);
+    expect(Object.isFrozen(CORE_PERMISSION_DECLARATIONS[2])).toBe(true);
   });
 
   it("matches exactly what CORE_PERMISSION_REGISTRY exposes as its own declarations, so a composer building on top of it never diverges from what Core itself registers", () => {

core/tests/authorization-store.integration.ts

@@ -173,6 +173,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0000_identity_core_tables",
       "core:0001_authorization_core_tables",
       "core:0002_authorization_integrity",
+      "core:0003_dashboard_navigation_tables",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {
@@ -207,7 +208,7 @@ describe.sequential("live Core authorization store", () => {
   const scope: AuthorizationScope = parseAuthorizationScope("calendar-event:123");
   const actor = createUserActor("authz_user_two"); // an operator/admin user distinct from the subject
 
-  it("applies a fresh migration and creates exactly the three authorization tables with their constraints", async () => {
+  it("applies a fresh migration and creates exactly the expected Core tables with their constraints", async () => {
     database = await createDisposableDatabase("fresh");
     await applyCoreMigrations(database.url);
 
@@ -218,9 +219,13 @@ describe.sequential("live Core authorization store", () => {
        where table_schema = 'public' and table_name like 'ekklesia_core_%'
        order by table_name`,
     );
+    // The complete Core schema after every migration, asserted exactly so a new table is a
+    // deliberate change here rather than an unnoticed one.
     expect(tables.map((row) => row.table_name)).toEqual([
       "ekklesia_core_account",
       "ekklesia_core_authorization_audit",
+      "ekklesia_core_dashboard_group",
+      "ekklesia_core_dashboard_placement",
       "ekklesia_core_grant",
       "ekklesia_core_migrations",
       "ekklesia_core_platform_owner",

core/tests/dashboard-flat-modules.test.ts

@@ -0,0 +1,247 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { type DashboardConfiguration, resolveDashboardNavigation } from "../src/dashboard/index.js";
+import {
+  createModuleUiPublicationRegistry,
+  type DiscoveredModule,
+  discoverModules,
+} from "../src/modules/index.js";
+
+/**
+ * The executable form of the architecture's central rule: **Dashboard grouping is presentation
+ * configuration and can never become module structure** (ADR 0021, ADR 0027).
+ *
+ * These run real discovery over real fixtures, including a genuine module dependency, and then
+ * arrange those modules into folders in several different ways. Everything discovery decides —
+ * which modules exist, what depends on what, and the order they must start in — has to come out
+ * byte-identical every time. A future change that let a group influence any of that fails here.
+ */
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+interface ModuleFixture {
+  readonly id: string;
+  readonly name: string;
+  /** A *real* technical dependency — one module calling another's functionality — expressed through
+   * the existing module dependency contract, which is the only kind of module relationship that
+   * exists. */
+  readonly dependsOn?: string;
+}
+
+async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
+  const moduleDirectory = path.join(modulesDirectory, fixture.id);
+  await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
+  await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
+  await writeFile(
+    path.join(moduleDirectory, "package.json"),
+    JSON.stringify({
+      ekklesia: { layer: "module" },
+      name: `@test/module-${fixture.id}`,
+      type: "module",
+      version: "1.0.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "ekklesia.module.json"),
+    JSON.stringify({
+      compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+      ...(fixture.dependsOn
+        ? { dependencies: { modules: { required: { [fixture.dependsOn]: "^1.0.0" } } } }
+        : {}),
+      entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+      id: fixture.id,
+      manifestVersion: 4,
+      name: fixture.name,
+      version: "1.0.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "dist/server/index.js"),
+    `export default { id: ${JSON.stringify(fixture.id)}, version: "1.0.0" };`,
+  );
+  await writeFile(
+    path.join(moduleDirectory, "dist/ui/index.js"),
+    `export default { id: ${JSON.stringify(fixture.id)}, version: "1.0.0", mount() {} };\n`,
+  );
+}
+
+/** Livestream genuinely depends on Video — it calls Video's functionality — so discovery must order
+ * Video first. Calendar depends on nothing. This is the *only* kind of relationship modules have. */
+async function discoverFixtures(): Promise<readonly DiscoveredModule[]> {
+  const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-flat-modules-"));
+  temporaryDirectories.push(modulesDirectory);
+  await createModule(modulesDirectory, { id: "video", name: "Video" });
+  await createModule(modulesDirectory, {
+    dependsOn: "video",
+    id: "livestream",
+    name: "Livestream",
+  });
+  await createModule(modulesDirectory, { id: "calendar", name: "Calendar" });
+  return discoverModules({
+    moduleSdkVersion: "0.1.0",
+    modulesDirectory,
+    platformVersion: "0.1.0",
+  });
+}
+
+/**
+ * Four arrangements of the same three modules, including the one the architecture warns about:
+ * Livestream and Video together under "Media", which must **not** create a Media module or a
+ * dependency between them.
+ */
+const arrangements: ReadonlyArray<readonly [string, DashboardConfiguration]> = [
+  ["nothing configured", { groups: [], placements: [] }],
+  [
+    "Media over Planning",
+    {
+      groups: [
+        { id: "media", label: "Media", sortOrder: 10 },
+        { id: "planning", label: "Planning", sortOrder: 20 },
+      ],
+      placements: [
+        { groupId: "media", moduleId: "livestream", sortOrder: 10 },
+        { groupId: "media", moduleId: "video", sortOrder: 20 },
+        { groupId: "planning", moduleId: "calendar", sortOrder: 10 },
+      ],
+    },
+  ],
+  [
+    "Livestream moved to Sunday Production, away from Video",
+    {
+      groups: [
+        { id: "media", label: "Media", sortOrder: 10 },
+        { id: "sunday-production", label: "Sunday Production", sortOrder: 5 },
+      ],
+      placements: [
+        { groupId: "sunday-production", moduleId: "livestream", sortOrder: 10 },
+        { groupId: "media", moduleId: "video", sortOrder: 10 },
+      ],
+    },
+  ],
+  [
+    "the dependency inverted in presentation: Video grouped under Livestream's folder alone",
+    {
+      groups: [{ id: "streaming", label: "Streaming", sortOrder: 1 }],
+      placements: [{ groupId: "streaming", moduleId: "video", sortOrder: 10 }],
+    },
+  ],
+];
+
+describe("Dashboard grouping never becomes module structure", () => {
+  it("orders discovery by real dependencies, which is the only module relationship", async () => {
+    const discovered = await discoverFixtures();
+
+    // Video before Livestream because Livestream *depends* on it — not because of any folder.
+    expect(discovered.map((module) => module.manifest.id)).toEqual([
+      "calendar",
+      "video",
+      "livestream",
+    ]);
+    expect(
+      discovered.find((module) => module.manifest.id === "livestream")?.manifest.dependencies,
+    ).toMatchObject({ modules: { required: { video: "^1.0.0" } } });
+  });
+
+  it("leaves discovery, dependencies, and start order identical under every arrangement", async () => {
+    const discovered = await discoverFixtures();
+    const registry = createModuleUiPublicationRegistry(discovered);
+    // The exact facts the runtime consumes, captured before any Dashboard configuration exists.
+    const baseline = JSON.stringify(
+      discovered.map((module) => ({
+        capabilities: module.manifest.capabilities,
+        dependencies: module.manifest.dependencies,
+        id: module.manifest.id,
+        permissions: module.manifest.permissions,
+        version: module.manifest.version,
+      })),
+    );
+
+    for (const [label, configuration] of arrangements) {
+      const view = resolveDashboardNavigation(
+        configuration,
+        registry.list().map((entry) => ({ id: entry.moduleId, name: entry.name })),
+      );
+
+      // Discovery order — which is module *startup* order — is untouched by presentation.
+      expect(
+        discovered.map((module) => module.manifest.id),
+        label,
+      ).toEqual(["calendar", "video", "livestream"]);
+      // So is every fact the runtime reads.
+      expect(
+        JSON.stringify(
+          discovered.map((module) => ({
+            capabilities: module.manifest.capabilities,
+            dependencies: module.manifest.dependencies,
+            id: module.manifest.id,
+            permissions: module.manifest.permissions,
+            version: module.manifest.version,
+          })),
+        ),
+        label,
+      ).toBe(baseline);
+      // And every module is still rendered exactly once, whatever the folders say.
+      expect(
+        [...view.groups.flatMap((group) => group.modules), ...view.ungrouped]
+          .map((entry) => entry.id)
+          .sort(),
+        label,
+      ).toEqual(["calendar", "livestream", "video"]);
+    }
+  });
+
+  it("never invents a module for a group, however the group is named", async () => {
+    const discovered = await discoverFixtures();
+    const registry = createModuleUiPublicationRegistry(discovered);
+    const [, mediaArrangement] = arrangements[1] as readonly [string, DashboardConfiguration];
+
+    const view = resolveDashboardNavigation(
+      mediaArrangement,
+      registry.list().map((entry) => ({ id: entry.moduleId, name: entry.name })),
+    );
+
+    // "Media" and "Planning" are group labels. There is no `media` module, no manifest for one, no
+    // artifact, no API root, no permission, and nothing depends on one.
+    const moduleIds = discovered.map((module) => module.manifest.id);
+    expect(moduleIds).toEqual(["calendar", "video", "livestream"]);
+    for (const groupId of view.groups.map((group) => group.id)) {
+      expect(moduleIds).not.toContain(groupId);
+      expect(registry.resolve(groupId, "1.0.0")).toBeUndefined();
+    }
+  });
+
+  it("keeps the publication record free of any grouping, ordering, or navigation field", async () => {
+    const registry = createModuleUiPublicationRegistry(await discoverFixtures());
+
+    const published = registry.resolve("livestream", "1.0.0");
+
+    // The record a host mounts from carries identity, the validated artifact, declared permissions,
+    // and the module's own name — never a group, an order, a parent, or a folder.
+    expect(Object.keys(published ?? {}).sort()).toEqual([
+      "artifactPath",
+      "moduleId",
+      "name",
+      "permissions",
+      "version",
+    ]);
+  });
+
+  it("takes the display name from the module's own manifest, not from any folder", async () => {
+    const registry = createModuleUiPublicationRegistry(await discoverFixtures());
+
+    expect(registry.list().map((entry) => [entry.moduleId, entry.name])).toEqual([
+      ["calendar", "Calendar"],
+      ["video", "Video"],
+      ["livestream", "Livestream"],
+    ]);
+  });
+});

core/tests/dashboard-navigation.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "vitest";
+import {
+  type DashboardConfiguration,
+  type DashboardNavigationModule,
+  resolveDashboardNavigation,
+} from "../src/dashboard/index.js";
+
+function module(id: string, name = id): DashboardNavigationModule {
+  return { id, name };
+}
+
+function configuration(
+  groups: ReadonlyArray<{ id: string; label: string; sortOrder: number }>,
+  placements: ReadonlyArray<{ moduleId: string; groupId: string | null; sortOrder: number }>,
+): DashboardConfiguration {
+  return { groups, placements };
+}
+
+const media = { id: "media", label: "Media", sortOrder: 10 };
+const planning = { id: "planning", label: "Planning", sortOrder: 20 };
+
+describe("resolving Dashboard navigation", () => {
+  it("groups modules exactly where the configuration places them", () => {
+    const view = resolveDashboardNavigation(
+      configuration(
+        [media, planning],
+        [
+          { groupId: "media", moduleId: "livestream", sortOrder: 20 },
+          { groupId: "media", moduleId: "video", sortOrder: 10 },
+          { groupId: "planning", moduleId: "calendar", sortOrder: 10 },
+        ],
+      ),
+      [
+        module("calendar", "Calendar"),
+        module("livestream", "Livestream"),
+        module("video", "Video"),
+      ],
+    );
+
+    expect(
+      view.groups.map((group) => [group.label, group.modules.map((entry) => entry.name)]),
+    ).toEqual([
+      ["Media", ["Video", "Livestream"]],
+      ["Planning", ["Calendar"]],
+    ]);
+    expect(view.ungrouped).toEqual([]);
+  });
+
+  it("shows a newly discovered module without any stored placement", () => {
+    // The rule that makes installing a module sufficient to see it: no initialization write, no
+    // manual database edit, no migration.
+    const view = resolveDashboardNavigation(
+      configuration([media], [{ groupId: "media", moduleId: "video", sortOrder: 10 }]),
+      [module("video", "Video"), module("roster", "Roster")],
+    );
+
+    expect(view.groups[0]?.modules.map((entry) => entry.id)).toEqual(["video"]);
+    expect(view.ungrouped.map((entry) => entry.id)).toEqual(["roster"]);
+  });
+
+  it("keeps a deliberately ungrouped module distinct from an unconfigured one, and orders both", () => {
+    const view = resolveDashboardNavigation(
+      configuration(
+        [],
+        [
+          { groupId: null, moduleId: "video", sortOrder: 20 },
+          { groupId: null, moduleId: "calendar", sortOrder: 10 },
+        ],
+      ),
+      [module("roster"), module("video"), module("calendar")],
+    );
+
+    // Placed-and-ungrouped first, in the administrator's order; never-configured after, by id — so a
+    // newcomer never interrupts an ordering someone chose.
+    expect(view.ungrouped.map((entry) => entry.id)).toEqual(["calendar", "video", "roster"]);
+  });
+
+  it("omits a stored placement whose module is not installed", () => {
+    const view = resolveDashboardNavigation(
+      configuration(
+        [media],
+        [
+          { groupId: "media", moduleId: "video", sortOrder: 10 },
+          { groupId: "media", moduleId: "uninstalled", sortOrder: 20 },
+        ],
+      ),
+      [module("video", "Video")],
+    );
+
+    // No dead entry renders, and the caller's configuration is untouched — the record survives for a
+    // reinstall.
+    expect(view.groups[0]?.modules.map((entry) => entry.id)).toEqual(["video"]);
+    expect(view.ungrouped).toEqual([]);
+  });
+
+  it("restores a reinstalled module to the position its retained placement describes", () => {
+    const stored = configuration(
+      [media],
+      [
+        { groupId: "media", moduleId: "livestream", sortOrder: 5 },
+        { groupId: "media", moduleId: "video", sortOrder: 10 },
+      ],
+    );
+
+    const whileUninstalled = resolveDashboardNavigation(stored, [module("video", "Video")]);
+    const afterReinstall = resolveDashboardNavigation(stored, [
+      module("video", "Video"),
+      module("livestream", "Livestream"),
+    ]);
+
+    expect(whileUninstalled.groups[0]?.modules.map((entry) => entry.id)).toEqual(["video"]);
+    expect(afterReinstall.groups[0]?.modules.map((entry) => entry.id)).toEqual([
+      "livestream",
+      "video",
+    ]);
+  });
+
+  it("keeps an empty group rather than hiding it", () => {
+    const view = resolveDashboardNavigation(configuration([media, planning], []), []);
+
+    expect(view.groups.map((group) => group.id)).toEqual(["media", "planning"]);
+    expect(view.groups.every((group) => group.modules.length === 0)).toBe(true);
+  });
+
+  it("treats a placement naming a missing group as ungrouped rather than losing the module", () => {
+    // The schema's `on delete set null` makes this unreachable in practice; the resolver still
+    // refuses to let a configuration inconsistency make a module invisible.
+    const view = resolveDashboardNavigation(
+      configuration([], [{ groupId: "deleted-group", moduleId: "video", sortOrder: 10 }]),
+      [module("video", "Video")],
+    );
+
+    expect(view.groups).toEqual([]);
+    expect(view.ungrouped.map((entry) => entry.id)).toEqual(["video"]);
+  });
+
+  it("orders deterministically when order values collide", () => {
+    const collided = configuration(
+      [
+        { id: "zebra", label: "Zebra", sortOrder: 10 },
+        { id: "alpha", label: "Alpha", sortOrder: 10 },
+      ],
+      [
+        { groupId: "alpha", moduleId: "video", sortOrder: 0 },
+        { groupId: "alpha", moduleId: "calendar", sortOrder: 0 },
+        { groupId: "alpha", moduleId: "roster", sortOrder: 0 },
+      ],
+    );
+    const modules = [module("roster"), module("video"), module("calendar")];
+
+    const first = resolveDashboardNavigation(collided, modules);
+    // A different input order must not change the output: the tie-break is the identifier, never
+    // arrival order.
+    const second = resolveDashboardNavigation(collided, [...modules].reverse());
+
+    expect(first.groups.map((group) => group.id)).toEqual(["alpha", "zebra"]);
+    expect(first.groups[0]?.modules.map((entry) => entry.id)).toEqual([
+      "calendar",
+      "roster",
+      "video",
+    ]);
+    expect(JSON.stringify(second)).toBe(JSON.stringify(first));
+  });
+
+  it("is empty and usable with no configuration and no modules", () => {
+    const view = resolveDashboardNavigation(configuration([], []), []);
+
+    expect(view.groups).toEqual([]);
+    expect(view.ungrouped).toEqual([]);
+  });
+
+  it("returns a frozen view no caller can mutate", () => {
+    const view = resolveDashboardNavigation(
+      configuration([media], [{ groupId: "media", moduleId: "video", sortOrder: 10 }]),
+      [module("video", "Video")],
+    );
+
+    expect(Object.isFrozen(view)).toBe(true);
+    expect(Object.isFrozen(view.groups)).toBe(true);
+    expect(Object.isFrozen(view.groups[0])).toBe(true);
+    expect(Object.isFrozen(view.ungrouped)).toBe(true);
+  });
+});
+
+describe("Dashboard grouping is presentation and nothing else", () => {
+  const modules = [
+    module("livestream", "Livestream"),
+    module("video", "Video"),
+    module("calendar", "Calendar"),
+  ];
+
+  it("creates no module, no parent, and no relationship from a shared group", () => {
+    const view = resolveDashboardNavigation(
+      configuration(
+        [media],
+        [
+          { groupId: "media", moduleId: "livestream", sortOrder: 10 },
+          { groupId: "media", moduleId: "video", sortOrder: 20 },
+        ],
+      ),
+      modules,
+    );
+
+    // "Media" is a label on a rendering bucket. It is not a module: nothing in the view carries a
+    // module id, version, artifact, or API root for it, and no entry names another module.
+    const rendered = JSON.parse(JSON.stringify(view)) as unknown;
+    expect(view.groups[0]?.modules.map((entry) => entry.id)).toEqual(["livestream", "video"]);
+    expect(modules.map((entry) => entry.id)).not.toContain("media");
+    for (const entry of view.groups.flatMap((group) => group.modules)) {
+      // A navigation entry describes exactly one module and never references a second one.
+      expect(Object.keys(entry).sort()).toEqual(["id", "name"]);
+    }
+    expect(JSON.stringify(rendered)).not.toContain("parent");
+    expect(JSON.stringify(rendered)).not.toContain("depends");
+  });
+
+  it("changes only placement when a module moves to a different group", () => {
+    const before = resolveDashboardNavigation(
+      configuration(
+        [media],
+        [
+          { groupId: "media", moduleId: "livestream", sortOrder: 10 },
+          { groupId: "media", moduleId: "video", sortOrder: 20 },
+        ],
+      ),
+      modules,
+    );
+    const after = resolveDashboardNavigation(
+      configuration(
+        [media, { id: "sunday-production", label: "Sunday Production", sortOrder: 5 }],
+        [
+          { groupId: "sunday-production", moduleId: "livestream", sortOrder: 10 },
+          { groupId: "media", moduleId: "video", sortOrder: 20 },
+        ],
+      ),
+      modules,
+    );
+
+    const findLivestream = (view: typeof before) =>
+      [...view.groups.flatMap((group) => group.modules), ...view.ungrouped].find(
+        (entry) => entry.id === "livestream",
+      );
+
+    // The module object itself is identical across the move: same identity, same name, and — in the
+    // API layer above this — the same embedded mount descriptor.
+    expect(findLivestream(after)).toEqual(findLivestream(before));
+    expect(before.groups.find((group) => group.id === "media")?.modules.map((m) => m.id)).toEqual([
+      "livestream",
+      "video",
+    ]);
+    expect(after.groups.find((group) => group.id === "media")?.modules.map((m) => m.id)).toEqual([
+      "video",
+    ]);
+    expect(
+      after.groups.find((group) => group.id === "sunday-production")?.modules.map((m) => m.id),
+    ).toEqual(["livestream"]);
+  });
+
+  it("renders the same module set whatever the arrangement", () => {
+    const arrangements: readonly DashboardConfiguration[] = [
+      configuration([], []),
+      configuration([media], [{ groupId: "media", moduleId: "livestream", sortOrder: 10 }]),
+      configuration(
+        [media, planning],
+        [
+          { groupId: "planning", moduleId: "livestream", sortOrder: 10 },
+          { groupId: "media", moduleId: "calendar", sortOrder: 10 },
+          { groupId: null, moduleId: "video", sortOrder: 10 },
+        ],
+      ),
+    ];
+
+    for (const arrangement of arrangements) {
+      const view = resolveDashboardNavigation(arrangement, modules);
+      const rendered = [...view.groups.flatMap((group) => group.modules), ...view.ungrouped]
+        .map((entry) => entry.id)
+        .sort();
+      // Every module is rendered exactly once, in every arrangement. Grouping can never add,
+      // remove, duplicate, or hide a module.
+      expect(rendered).toEqual(["calendar", "livestream", "video"]);
+    }
+  });
+});

core/tests/dashboard-store.integration.ts

@@ -0,0 +1,415 @@
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client, type QueryResultRow } from "pg";
+import { afterAll, describe, expect, it } from "vitest";
+import {
+  createDashboardDrizzleView,
+  createDashboardStore,
+  type DashboardStore,
+  DashboardStoreError,
+  resolveDashboardNavigation,
+} from "../src/dashboard/index.js";
+import { createValidatedPostgresPool } from "../src/database/index.js";
+import {
+  applyModuleMigrations,
+  createPostgresMigrationDatabase,
+  discoverAllMigrations,
+} from "../src/migrations/index.js";
+
+/**
+ * The Dashboard navigation store against real PostgreSQL.
+ *
+ * The unit suites prove the resolution rules; this proves the things only a database can: that the
+ * migration really creates these tables, that configuration survives a completely new connection,
+ * that `on delete set null` really ungroups a deleted group's modules, and that a placement can
+ * never point at a group that does not exist. The in-memory double used by the API route tests
+ * deliberately reproduces only two of those behaviours, so this file is where they are actually
+ * established rather than assumed.
+ */
+const integrationDatabaseUrlEnvironment = "EKKLESIA_MIGRATION_TEST_DATABASE_URL";
+const coreMigrationsDirectory = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "drizzle",
+);
+const trackedDatabases = new Set<string>();
+let databaseCounter = 0;
+
+class IntegrationHarnessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrationHarnessError";
+    this.stack = `${this.name}: ${this.message}`;
+  }
+}
+
+function harnessError(message: string): IntegrationHarnessError {
+  return new IntegrationHarnessError(message);
+}
+
+function baseDatabaseUrl(): string {
+  const value = process.env[integrationDatabaseUrlEnvironment];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw harnessError("The Dashboard integration database is not configured.");
+  }
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") {
+      throw new TypeError("Unsupported protocol.");
+    }
+  } catch {
+    throw harnessError("The Dashboard integration database configuration is invalid.");
+  }
+  return value;
+}
+
+function quoteDatabaseName(databaseName: string): string {
+  if (!/^[a-z][a-z0-9_]{0,62}$/u.test(databaseName)) {
+    throw harnessError("The generated integration database name is invalid.");
+  }
+  return `"${databaseName}"`;
+}
+
+function makeDatabaseName(label: string): string {
+  const safeLabel = label
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/gu, "_")
+    .replaceAll(/^_+|_+$/gu, "")
+    .slice(0, 14);
+  databaseCounter += 1;
+  return `ekk_dash_${process.pid}_${databaseCounter}_${safeLabel || "scenario"}_${randomBytes(4).toString("hex")}`;
+}
+
+function databaseUrl(databaseName: string): string {
+  const parsed = new URL(baseDatabaseUrl());
+  parsed.pathname = `/${databaseName}`;
+  parsed.searchParams.delete("application_name");
+  return parsed.toString();
+}
+
+async function openAdministrativeClient(connectionString: string): Promise<Client> {
+  const client = new Client({ connectionString });
+  client.on("error", () => undefined);
+  try {
+    await client.connect();
+    return client;
+  } catch {
+    try {
+      await client.end();
+    } catch {
+      // The public harness failure stays static when connection cleanup also fails.
+    }
+    throw harnessError("The Dashboard integration database connection failed.");
+  }
+}
+
+async function safeQuery<Row extends QueryResultRow>(
+  client: Client,
+  text: string,
+  values: unknown[] = [],
+): Promise<readonly Row[]> {
+  try {
+    const result = await client.query<Row>(text, values);
+    return result.rows;
+  } catch {
+    throw harnessError("An integration database administration operation failed.");
+  }
+}
+
+async function safeEnd(client: Client): Promise<void> {
+  try {
+    await client.end();
+  } catch {
+    throw harnessError("An integration database connection could not be closed.");
+  }
+}
+
+async function dropDatabase(databaseName: string): Promise<void> {
+  const admin = await openAdministrativeClient(baseDatabaseUrl());
+  try {
+    await safeQuery(
+      admin,
+      "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()",
+      [databaseName],
+    );
+    await safeQuery(
+      admin,
+      `DROP DATABASE IF EXISTS ${quoteDatabaseName(databaseName)} WITH (FORCE)`,
+    );
+    trackedDatabases.delete(databaseName);
+  } finally {
+    await safeEnd(admin);
+  }
+}
+
+async function createDisposableDatabase(label: string): Promise<{ name: string; url: string }> {
+  const name = makeDatabaseName(label);
+  const admin = await openAdministrativeClient(baseDatabaseUrl());
+  try {
+    await safeQuery(admin, `CREATE DATABASE ${quoteDatabaseName(name)} TEMPLATE template0`);
+  } finally {
+    await safeEnd(admin);
+  }
+  trackedDatabases.add(name);
+  return { name, url: databaseUrl(name) };
+}
+
+async function applyCoreMigrations(url: string): Promise<void> {
+  const emptyModulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-dash-no-modules-"));
+  try {
+    const aggregate = await discoverAllMigrations({
+      coreMigrationsDirectory,
+      moduleDiscovery: {
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory: emptyModulesDirectory,
+        platformVersion: "0.1.0",
+      },
+    });
+    expect(aggregate.migrations.map((entry) => entry.identity)).toEqual([
+      "core:0000_identity_core_tables",
+      "core:0001_authorization_core_tables",
+      "core:0002_authorization_integrity",
+      "core:0003_dashboard_navigation_tables",
+    ]);
+    await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
+  } finally {
+    await rm(emptyModulesDirectory, { force: true, recursive: true });
+  }
+}
+
+afterAll(async () => {
+  for (const databaseName of [...trackedDatabases]) {
+    await dropDatabase(databaseName).catch(() => undefined);
+  }
+});
+
+describe.sequential("live Core Dashboard navigation store", () => {
+  let database: { name: string; url: string };
+  let admin: Client;
+  let store: DashboardStore;
+  let close: () => Promise<void>;
+
+  it("creates exactly the two Dashboard tables, with their constraints", async () => {
+    database = await createDisposableDatabase("fresh");
+    await applyCoreMigrations(database.url);
+    admin = await openAdministrativeClient(database.url);
+
+    const tables = await safeQuery<{ table_name: string }>(
+      admin,
+      `select table_name from information_schema.tables
+        where table_schema = 'public' and table_name like 'ekklesia_core_dashboard%'
+        order by table_name`,
+    );
+    const constraints = await safeQuery<{ constraint_name: string; delete_rule: string }>(
+      admin,
+      `select rc.constraint_name, rc.delete_rule
+         from information_schema.referential_constraints rc
+         join information_schema.table_constraints tc
+           on tc.constraint_name = rc.constraint_name
+        where tc.table_name = 'ekklesia_core_dashboard_placement'`,
+    );
+
+    expect(tables.map((table) => table.table_name)).toEqual([
+      "ekklesia_core_dashboard_group",
+      "ekklesia_core_dashboard_placement",
+    ]);
+    // The database, not the application, is what guarantees a deleted group leaves no dangling
+    // reference.
+    expect(constraints.map((constraint) => constraint.delete_rule)).toEqual(["SET NULL"]);
+
+    const handle = createValidatedPostgresPool(database.url);
+    close = handle.close;
+    store = createDashboardStore(createDashboardDrizzleView(handle.pool));
+  });
+
+  it("starts empty, so an installation with no configuration is a normal state", async () => {
+    expect(await store.readConfiguration()).toEqual({ groups: [], placements: [] });
+  });
+
+  it("persists groups and placements, and reads them back in deterministic order", async () => {
+    await store.upsertGroup({ id: "planning", label: "Planning", sortOrder: 20 });
+    await store.upsertGroup({ id: "media", label: "Media", sortOrder: 10 });
+    await store.setPlacement({ groupId: "media", moduleId: "livestream", sortOrder: 20 });
+    await store.setPlacement({ groupId: "media", moduleId: "video", sortOrder: 10 });
+    await store.setPlacement({ groupId: "planning", moduleId: "calendar", sortOrder: 10 });
+
+    const configuration = await store.readConfiguration();
+
+    expect(configuration.groups.map((group) => group.id)).toEqual(["media", "planning"]);
+    expect(configuration.placements.map((placement) => placement.moduleId)).toEqual([
+      "calendar",
+      "video",
+      "livestream",
+    ]);
+  });
+
+  it("survives a completely new connection, so a church configures its Dashboard once", async () => {
+    // A different pool, as a restarted process would use — nothing is cached in the old one.
+    const reopened = createValidatedPostgresPool(database.url);
+    try {
+      const configuration = await createDashboardStore(
+        createDashboardDrizzleView(reopened.pool),
+      ).readConfiguration();
+      const view = resolveDashboardNavigation(configuration, [
+        { id: "livestream", name: "Livestream" },
+        { id: "video", name: "Video" },
+        { id: "calendar", name: "Calendar" },
+      ]);
+
+      expect(
+        view.groups.map((group) => [group.label, group.modules.map((entry) => entry.name)]),
+      ).toEqual([
+        ["Media", ["Video", "Livestream"]],
+        ["Planning", ["Calendar"]],
+      ]);
+    } finally {
+      await reopened.close();
+    }
+  });
+
+  it("renames a group without disturbing a single placement", async () => {
+    const before = await store.readConfiguration();
+
+    await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 10 });
+    const after = await store.readConfiguration();
+
+    expect(after.groups.find((group) => group.id === "media")?.label).toBe("Media & Streaming");
+    // The stable id is what placements point at, so a rename can never re-organize the Dashboard.
+    expect(after.placements).toEqual(before.placements);
+  });
+
+  it("re-orders a group and a module in place, without creating duplicates", async () => {
+    await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 30 });
+    await store.setPlacement({ groupId: "media", moduleId: "video", sortOrder: 99 });
+
+    const configuration = await store.readConfiguration();
+
+    expect(configuration.groups).toHaveLength(2);
+    expect(configuration.groups.map((group) => group.id)).toEqual(["planning", "media"]);
+    expect(configuration.placements.filter((entry) => entry.moduleId === "video")).toHaveLength(1);
+    expect(configuration.placements.find((entry) => entry.moduleId === "video")?.sortOrder).toBe(
+      99,
+    );
+  });
+
+  it("moves a module between groups by changing exactly one row", async () => {
+    await store.upsertGroup({ id: "sunday-production", label: "Sunday Production", sortOrder: 5 });
+    await store.setPlacement({
+      groupId: "sunday-production",
+      moduleId: "livestream",
+      sortOrder: 10,
+    });
+
+    const configuration = await store.readConfiguration();
+
+    expect(configuration.placements.find((entry) => entry.moduleId === "livestream")?.groupId).toBe(
+      "sunday-production",
+    );
+    // Video did not move.
+    expect(configuration.placements.find((entry) => entry.moduleId === "video")?.groupId).toBe(
+      "media",
+    );
+  });
+
+  it("ungroups a module deliberately, which is distinct from having no record", async () => {
+    await store.setPlacement({ groupId: null, moduleId: "calendar", sortOrder: 7 });
+
+    const configuration = await store.readConfiguration();
+    const calendar = configuration.placements.find((entry) => entry.moduleId === "calendar");
+
+    expect(calendar).toEqual({ groupId: null, moduleId: "calendar", sortOrder: 7 });
+  });
+
+  it("ungroups a deleted group's modules instead of leaving a dangling reference", async () => {
+    await store.deleteGroup("sunday-production");
+
+    const configuration = await store.readConfiguration();
+    const groupIds = new Set(configuration.groups.map((group) => group.id));
+
+    expect(groupIds.has("sunday-production")).toBe(false);
+    expect(
+      configuration.placements.find((entry) => entry.moduleId === "livestream")?.groupId,
+    ).toBeNull();
+    // No placement anywhere names a group that no longer exists.
+    for (const placement of configuration.placements) {
+      if (placement.groupId !== null) {
+        expect(groupIds.has(placement.groupId)).toBe(true);
+      }
+    }
+  });
+
+  it("refuses a placement naming a group that was never created", async () => {
+    await expect(
+      store.setPlacement({ groupId: "not-a-group", moduleId: "video", sortOrder: 10 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_GROUP_NOT_FOUND" });
+  });
+
+  it("refuses to delete a group that does not exist", async () => {
+    await expect(store.deleteGroup("not-a-group")).rejects.toMatchObject({
+      code: "DASHBOARD_GROUP_NOT_FOUND",
+    });
+  });
+
+  it("stores a placement for a module that is not installed, and renders nothing for it", async () => {
+    await store.upsertGroup({ id: "media", label: "Media & Streaming", sortOrder: 30 });
+    await store.setPlacement({ groupId: "media", moduleId: "uninstalled", sortOrder: 1 });
+
+    const configuration = await store.readConfiguration();
+    const view = resolveDashboardNavigation(configuration, [{ id: "video", name: "Video" }]);
+
+    // Retained, so a reinstall restores the position...
+    expect(configuration.placements.map((entry) => entry.moduleId)).toContain("uninstalled");
+    // ...and never rendered while the module is absent.
+    expect(
+      [...view.groups.flatMap((group) => group.modules), ...view.ungrouped].map(
+        (entry) => entry.id,
+      ),
+    ).toEqual(["video"]);
+  });
+
+  it("rejects malformed input before it reaches the database", async () => {
+    await expect(
+      store.upsertGroup({ id: "Not Kebab Case", label: "Nope", sortOrder: 0 }),
+    ).rejects.toBeInstanceOf(DashboardStoreError);
+    await expect(
+      store.upsertGroup({ id: "media", label: "   ", sortOrder: 0 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_GROUP_LABEL_INVALID" });
+    await expect(
+      store.upsertGroup({ id: "media", label: "x".repeat(121), sortOrder: 0 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_GROUP_LABEL_INVALID" });
+    await expect(
+      store.upsertGroup({ id: "media", label: "Media", sortOrder: -1 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_SORT_ORDER_INVALID" });
+    await expect(
+      store.setPlacement({ groupId: null, moduleId: "Not Valid", sortOrder: 0 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_MODULE_ID_INVALID" });
+    await expect(
+      store.setPlacement({ groupId: null, moduleId: "video", sortOrder: 1.5 }),
+    ).rejects.toMatchObject({ code: "DASHBOARD_SORT_ORDER_INVALID" });
+  });
+
+  it("trims a stored label rather than persisting surrounding whitespace", async () => {
+    await store.upsertGroup({ id: "planning", label: "  Planning  ", sortOrder: 20 });
+
+    const configuration = await store.readConfiguration();
+
+    expect(configuration.groups.find((group) => group.id === "planning")?.label).toBe("Planning");
+  });
+
+  it("leaks no database detail in a sanitized failure", async () => {
+    await close();
+
+    const error = await store.readConfiguration().catch((caught: unknown) => caught);
+    const text = `${String(error)}\n${(error as Error).stack ?? ""}`;
+
+    expect(error).toMatchObject({ code: "DASHBOARD_READ_FAILED" });
+    expect(text).not.toContain(database.name);
+    expect(text).not.toContain("select");
+    expect(text).not.toContain("ekklesia_core_dashboard");
+    await safeEnd(admin);
+    await dropDatabase(database.name);
+  });
+});

core/tests/doctor-report.test.ts

@@ -78,7 +78,7 @@ Modules
   ✓ Dependency graph valid
     Dependency order is empty.
   ✓ Permission registry composed
-    2 permissions registered
+    3 permissions registered
 
 Data definitions
   ✓ Schemas validated

core/tests/module-permissions.test.ts

@@ -2,6 +2,7 @@ import { type PermissionBaseline, parseModuleManifest } from "@ekklesia/contract
 import { describe, expect, it } from "vitest";
 import {
   CORE_AUTHORIZATION_GRANTS_MANAGE,
+  CORE_DASHBOARD_NAVIGATION_MANAGE,
   CORE_MODULES_UI_READ,
   CORE_PERMISSION_DECLARATIONS,
   PermissionRegistryError,
@@ -67,8 +68,9 @@ describe("composePlatformPermissionRegistry", () => {
     expect(registry.has(CORE_MODULES_UI_READ)).toBe(true);
     expect(registry.has("calendar.events.read")).toBe(true);
     expect(registry.has("people.directory.read")).toBe(true);
-    // Core's own two declarations plus one from each module.
-    expect(registry.declarations).toHaveLength(4);
+    expect(registry.has(CORE_DASHBOARD_NAVIGATION_MANAGE)).toBe(true);
+    // Core's own three declarations plus one from each module.
+    expect(registry.declarations).toHaveLength(5);
   });
 
   it("preserves deterministic order: Core first, then modules in the supplied order, then declarations in manifest order", () => {
@@ -85,6 +87,7 @@ describe("composePlatformPermissionRegistry", () => {
     expect(registry.declarations.map((declaration) => declaration.id)).toEqual([
       CORE_AUTHORIZATION_GRANTS_MANAGE,
       CORE_MODULES_UI_READ,
+      CORE_DASHBOARD_NAVIGATION_MANAGE,
       "calendar.events.read",
       "calendar.events.write",
       "people.directory.read",