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/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"],
+    ]);
+  });
+});