Merge pull request 'feat(shell): Settings hierarchy, Discover, and /settings/<module-id> (Stage 1, ADR 0061)' (#108) from feat/settings-shell into main

Reviewed-on: #108
Reviewed-by: Zayin_Admin <[email protected]>

.gitattributes

@@ -6,3 +6,7 @@
 *.gif binary
 *.webp binary
 *.woff2 binary
+
+# Reviewed license supplements are named by the SHA-256 of their exact bytes (ADR 0052), so Git must
+# never rewrite their line endings.
+packages/module-pack/license-supplements/** -text

.github/workflows/ci.yml

@@ -128,6 +128,129 @@ jobs:
         if: always()
         run: bash scripts/ci-sweep.sh --job
 
+  package-release:
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # What the gate proved, for the job that consumes its artifact to check it received exactly that.
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      revision: ${{ steps.release.outputs.revision }}
+      manifest_sha256: ${{ steps.release.outputs.manifest_sha256 }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # `actions/checkout` defaults to leaving the job token in `.git/config`, where any later
+          # step — including one a pull request added to this file — could read or reuse it. Nothing
+          # in this workflow pushes, so the credential is never needed after checkout.
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # ADR 0053's package release gate: build the public package train from this commit, build it
+      # again from a second checkout and require byte-identical artifacts, then install exactly those
+      # tarballs (offline, no registry) into a module outside this repository and prove it builds,
+      # packages, and verifies. Nothing is published and no credential exists here. A future publish
+      # job must depend on this job and publish only the artifacts it proved.
+      - name: Build, reproduce, and consume the public package train
+        run: pnpm test:package-release --keep package-train
+
+      - name: Describe the proven release train
+        id: release
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          manifest="$release/ekklesia-package-train.json"
+          {
+            echo "version=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).version' "$manifest")"
+            echo "revision=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).source.revision' "$manifest")"
+            echo "manifest_sha256=$(sha256sum "$manifest" | cut -d' ' -f1)"
+          } >>"$GITHUB_OUTPUT"
+          cat "$manifest"
+
+      # The exact release artifacts, for the jobs that consume them, from a directory whose name does
+      # not start with a dot: the artifact actions leave hidden files out. Version 3 of the artifact
+      # actions: version 4 refuses any server that is not github.com, which this Gitea is not, while
+      # Gitea implements the protocol version 3 uses. A consumer checks the files, not the wrapper.
+      - name: Hand the release train on
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train
+          path: package-train/
+          if-no-files-found: error
+          retention-days: 7
+
+  # The publication tool, given exactly the artifact the package-release job proved, against a
+  # disposable Gitea 1.27.2 (scripts/test-package-publication.sh). Never the real registry, and no
+  # credential: the disposable registry's accounts are created and discarded inside the job.
+  package-publication:
+    needs: package-release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # Names this job's stacks, so its final step removes exactly these (scripts/lib/ci-project.sh).
+      EKKLESIA_CI_JOB_KEY: package-publication
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      # A job the runner killed (cancelled, or past the runner's own time limit) never ran its
+      # cleanup. Anything a CI job left on this shared daemon more than three hours ago goes first.
+      - name: Sweep stale CI stacks from the runner
+        run: bash scripts/ci-sweep.sh --stale
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Receive the release train the gate proved
+        uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
+        with:
+          name: package-train
+          path: package-train/
+
+      - name: Check it is exactly that train
+        env:
+          EXPECTED_MANIFEST_SHA256: ${{ needs.package-release.outputs.manifest_sha256 }}
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          actual="$(sha256sum "$release/ekklesia-package-train.json" | cut -d' ' -f1)"
+          if [[ -z "$EXPECTED_MANIFEST_SHA256" || "$actual" != "$EXPECTED_MANIFEST_SHA256" ]]; then
+            echo "The received release manifest is not the one the package-release job proved." >&2
+            exit 1
+          fi
+          (cd "$release" && sha256sum --check --strict SHA256SUMS)
+
+      - name: Publish it to a disposable Gitea, and prove the round trip and recovery
+        run: bash scripts/test-package-publication.sh --release "$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+
+      # Whatever happened above, this job's own stacks do not outlive it.
+      - name: Remove this job's CI stacks
+        if: always()
+        run: bash scripts/ci-sweep.sh --job
+
   image-build:
     needs: verify
     runs-on: ubuntu-latest

.github/workflows/publish-packages.yml

@@ -0,0 +1,133 @@
+name: Publish packages
+
+# Publishes one public @ekklesia/* package train (ADR 0053, docs/development/releases.md) to the
+# npm registry: exactly the artifacts this run's package-release gate proves, and nothing else.
+#
+# Only ever started by hand, on `main`, by someone with write access to this repository: no pull
+# request or push can start it. It needs the version-set commit of a release (`version` must equal
+# the platform version there), and the repository secret EKKLESIA_PACKAGES_PUBLISH_TOKEN, a token of
+# the dedicated publisher account with only the `write:package` scope. Packages are publicly
+# readable (ADR 0054); publishing is what this protects.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: The package train version to publish, equal to the platform version on main.
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# Never cancel a publication part way, and never run two at once. A rerun resumes safely.
+concurrency:
+  group: publish-packages
+  cancel-in-progress: false
+
+env:
+  # The only registry-specific setting: where the train is published.
+  EKKLESIA_PACKAGES_REGISTRY: https://git.zayin.net/api/packages/Zayin/npm/
+
+jobs:
+  package-release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      revision: ${{ steps.release.outputs.revision }}
+      manifest_sha256: ${{ steps.release.outputs.manifest_sha256 }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # The same credential-free gate as CI: build, reproduce, and consume the train.
+      - name: Build, reproduce, and consume the public package train
+        run: pnpm test:package-release --keep package-train
+
+      - name: Describe the proven release train
+        id: release
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          manifest="$release/ekklesia-package-train.json"
+          {
+            echo "version=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).version' "$manifest")"
+            echo "revision=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).source.revision' "$manifest")"
+            echo "manifest_sha256=$(sha256sum "$manifest" | cut -d' ' -f1)"
+          } >>"$GITHUB_OUTPUT"
+
+      # Artifact actions version 3: version 4 refuses any server that is not github.com. The directory
+      # name must not start with a dot: the artifact actions leave hidden files out.
+      - name: Hand the release train on
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train
+          path: package-train/
+          if-no-files-found: error
+          retention-days: 90
+
+  publish:
+    needs: package-release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      # Only for the publication tool itself: nothing is built or installed in this job.
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Receive the release train the gate proved
+        uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
+        with:
+          name: package-train
+          path: package-train/
+
+      # The tool validates the whole train against its manifest, that manifest against the gate's,
+      # its version against the request, and its revision against this commit, before it sends
+      # anything; then publishes, verifies every package byte for byte, and moves `latest` last.
+      - name: Publish the exact release train
+        env:
+          EKKLESIA_PACKAGES_PUBLISH_TOKEN: ${{ secrets.EKKLESIA_PACKAGES_PUBLISH_TOKEN }}
+          TRAIN_VERSION: ${{ inputs.version }}
+          TRAIN_REVISION: ${{ github.sha }}
+          MANIFEST_SHA256: ${{ needs.package-release.outputs.manifest_sha256 }}
+        run: |
+          node scripts/publish-package-train.ts \
+            --release "$(find package-train -mindepth 1 -maxdepth 1 -type d)" \
+            --registry "$EKKLESIA_PACKAGES_REGISTRY" \
+            --version "$TRAIN_VERSION" \
+            --revision "$TRAIN_REVISION" \
+            --manifest-sha256 "$MANIFEST_SHA256" \
+            --record publication-record.json \
+            --require-public-read
+
+      - name: Keep the publication record
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train-publication-record
+          path: publication-record.json
+          if-no-files-found: error
+          retention-days: 90

.gitignore

@@ -1,4 +1,8 @@
 node_modules/
+# pnpm's content-addressed package store. pnpm keeps it beside node_modules on the same file system,
+# so when the checkout is its own mount (a CI runner's workspace volume, a bind-mounted container),
+# `pnpm install` creates it here, at the checkout's root. A package cache, never source.
+.pnpm-store/
 .turbo/
 coverage/
 dist/
@@ -16,3 +20,11 @@ generated/*
 
 core/.identity-schema-reference.ts
 core/.identity-schema-check-*
+
+# The packager tests copy fixture modules here (packages/module-pack/tests/support/fixture-module.ts).
+packages/module-pack/.fixtures/
+
+# `pnpm packages:release` writes package release trains here (scripts/package-release.ts).
+.package-release/
+# CI keeps the proven release here to hand it on as a workflow artifact (scripts/test-package-release.sh --keep).
+/package-train/

CLAUDE.md

@@ -6,27 +6,60 @@ contents, because restated details drift.
 
 ## What this repository is
 
-Ekklesia is a modular, self-hosted church platform built as a strictly layered pnpm/TypeScript
+Ekklesia is a modular, self-hosted church platform. **This repository is the platform** — Core, the
-monorepo:
+API, the Dashboard and display shell, and the public `@ekklesia/*` module-development packages — built
+as a strictly layered pnpm/TypeScript monorepo:
 
 - **Core** (`core/`) owns platform infrastructure: identity, database connectivity, migration
-  execution, module discovery/lifecycle, and other feature-agnostic services. Core never imports a
+  execution, module discovery/lifecycle, devices, and other feature-agnostic services. Core never
-  feature module, a surface, or an app.
+  imports a feature module, a surface, or an app.
-- **Modules** (`modules/*`, template at `templates/module`) are independently versioned product
+- **Modules** are independently versioned product packages. First-party modules live in **their own
-  packages. They own their own data and migrations, declare capabilities/permissions through
+  repositories** (Signage is `Zayin/Signage`), build against the published `@ekklesia/*` packages
-  `@ekklesia/contracts` and `@ekklesia/module-sdk`, and must never import Core, another module, or a
+  (ADR 0053), and reach an installation as a Module Package (ADR 0049) installed into module storage
-  surface directly. Per ADR 0021 a module owns its UI; manifest v7 permits independently optional
+  outside the image (ADR 0048). No module source lives in this repository; `templates/module` is the
-  primary and full-viewport display artifacts, authored in React against the same role-neutral
+  example, and `modules/` is only an optional, ignored local installed-modules directory. A module owns
-  `@ekklesia/module-ui-sdk` ABI. Ekklesia mounts each through a separate surface role, while
+  its data, migrations, and **its own domain UI** (ADR 0021), declares capabilities/permissions through
-  `pnpm boundaries` still rejects every non-React UI framework and non-`.tsx` presentation source.
+  `@ekklesia/contracts` and `@ekklesia/module-sdk`, and never imports Core, another module, or a
+  surface. Manifest v8 permits independently optional primary and full-viewport display artifacts,
+  authored in React against the role-neutral `@ekklesia/module-ui-sdk` ABI; database access is the
+  Module Database ABI v1 (ADR 0050).
 - **Surfaces** (`surfaces/*`) own the containing application shell, navigation, and every
-  presentation concern a module does not. They consume public API/client contracts only, never Core
+  presentation concern a module does not. The shell **hosts** module UI through the generic loader;
-  or module internals directly.
+  it never rebuilds a module's domain screens. Surfaces consume public API/client contracts only.
 
 These boundaries are enforced by `pnpm boundaries` (`scripts/check-boundaries.ts`), not just
 documented. Read `docs/architecture/repository-boundaries.md` and
 `docs/architecture/platform-architecture.md` before proposing any change that crosses a layer.
 
+## Product direction lives beside this repository
+
+The current roadmap and product/interface design contract are `ROADMAP.md` and `DESIGN.md` in the
+parent development directory (`../ROADMAP.md` and `../DESIGN.md` from a checkout in the standard
+`~/development/ekklesia/` layout). They are deliberately **not** committed here; do not copy them into
+this repository to make them available. They are authoritative for product direction: read the
+relevant stages and sections before designing a change. If this repository's documentation disagrees
+with them, flag the conflict, correct the repository-local documentation where appropriate, and never
+silently follow the stale text. Architectural decisions still change only through ADRs (below).
+
+Rules from those documents that every change here must respect:
+
+- **Ownership.** Modules own their domain data, behaviour, and UI. Shared resources — displays and
+  devices, accounts and identity, roles and authorization, branding, mail, push, storage providers,
+  and module installation/lifecycle — belong to the platform, and modules consume them.
+- **Branding.** Normal user-facing UI never hard-codes "Ekklesia"; product identity comes from
+  installation branding (ADR 0046). Package names, diagnostics, logs, and developer tooling may.
+  Existing hard-coded shell strings are known debt for Stage 1, not a pattern to copy.
+- **Visual direction.** Simple, minimal, and calm; responsive for phone, tablet, and desktop; light,
+  dark, and system modes. Normal UI colours come only from the shared design tokens
+  (`@ekklesia/design-tokens`, ADR 0039) — never a hard-coded colour.
+- **No browser-native dialogs.** `window.alert`, `window.confirm`, and `window.prompt` are prohibited
+  in product UI. Destructive actions use in-product confirmation proportional to their impact.
+- **Displays are transitional.** Displays are platform-owned. Today's device pairing (the Dashboard
+  sidebar's *Display devices* panel) and Signage's own display roster are a transitional
+  implementation that Stage 1 migrates to **Settings → Displays**. Fix defects in them, but do not
+  build the Stage 1 Settings, global Displays, theme editor, module installer, or responsive shell
+  redesign early, and keep existing paired displays working across any change.
+
 ## ADRs are authoritative
 
 `docs/architecture/decisions/` records durable architectural decisions. **Accepted ADRs are
@@ -43,6 +76,7 @@ At minimum, read the current versions of:
 - `docs/architecture/decisions/README.md` and every ADR relevant to your change
 - `docs/architecture/platform-architecture.md` and `docs/architecture/repository-boundaries.md`
 - `README.md` (current platform status — what is and is not implemented)
+- `../ROADMAP.md` and `../DESIGN.md` (current product direction; see above)
 - `docs/development/repository-workflow.md` and `docs/development/testing.md`
 - `CONTRIBUTING.md`
 
@@ -52,8 +86,16 @@ your own memory of a prior session** — treat stale assumptions as a bug to cat
 
 ## Working conventions
 
-- Work on a clean branch off an up-to-date `main`; never commit or push directly to `main`; never
+- The canonical repositories are on the church Gitea under the `Zayin` organization:
-  change branch-protection settings.
+  `ssh://[email protected]:2222/Zayin/Ekklesia.git` (this one), `Zayin/Signage.git`, and
+  `Zayin/Classroom_Desktop.git`. A local clone may be behind the server: `git fetch --prune --tags`
+  and branch from `origin/main`, never from whatever is checked out.
+- One branch per PR, off an up-to-date `origin/main`. Never commit or push directly to `main`, never
+  merge your own PR, and never change branch-protection settings.
+- Never create or push a release tag. Release tags belong to the human maintainer.
+- A change that needs both a platform contract change and a module change is two PRs: Core first, on
+  its own branch, with the compatibility boundary stated explicitly; then the module. Do not copy
+  platform logic into a module to avoid making the correct Core change.
 - Keep PRs focused on one bounded slice. Record major architectural changes in an ADR rather than
   burying them in an implementation.
 - Add or update tests when you change a contract or architectural rule. New behavior needs new
@@ -66,6 +108,13 @@ your own memory of a prior session** — treat stale assumptions as a bug to cat
 - Never run a database migration automatically (on import, on startup, in a test that isn't
   explicitly a migration test, or as a side effect of an unrelated command). Migrations are always
   an explicit, operator-invoked action.
+- Report what you find. A defect, flaky test, documentation/ADR conflict, or CI problem outside the
+  task at hand gets an issue in the repository it belongs to, as soon as you find it. Search for an
+  existing issue first; something fixed in the same PR goes in that PR's description instead. Be
+  descriptive: what you saw, the evidence (run and job links, commit, file and line), how to
+  reproduce it, the impact, and options, and never a secret. Label it `found-by-claude` (an agent
+  that cannot apply labels ends the body with a line saying so), leave it unassigned, and list what
+  you filed when you report back.
 
 ## Canonical verification commands
 
@@ -78,6 +127,13 @@ ever disagree:
 - `pnpm test:migrations:integration` — live, disposable-PostgreSQL evidence: migration discovery,
   planning, and execution, plus the `apps/api` HTTP transport (signup, sign-in, principal
   resolution, sign-out). Requires Docker. Run this for any change touching either area.
+- `pnpm test:package-release` — builds the public `@ekklesia/*` package train, proves it
+  reproducible, and proves a standalone module consumes exactly those tarballs. Publishes nothing.
+  Run it for any change to the public packages or their release tooling.
+- `pnpm test:package-publication` — publishes a release train to a disposable Gitea (Docker) and
+  proves the publication tool. Never the real registry. The real publication is the manual
+  `Publish packages` workflow only; never run `scripts/publish-package-train.ts` against the real
+  registry without the user's explicit intent.
 - `pnpm doctor` — read-only local readiness report. Never treat it as a substitute for `pnpm
   verify` or the integration suite.
 - `pnpm migrations:plan` / `pnpm migrations:apply` — read-only planning vs. mutating execution

README.md

@@ -48,8 +48,34 @@ migration history is retained and reported, and blocks no other migration. A mod
 as one **Ekklesia Module Package v1**
 ([ADR 0049](docs/architecture/decisions/0049-module-package-v1.md)): a deterministic `.tar.gz` and
 its SHA-256, produced by the canonical packager (`@ekklesia/module-pack`) with the module's backend
-bundled, and checked by Core's verifier before it is installed. Only the portable `any` target exists
+bundled, and checked by Core's verifier before it is installed. Two targets exist:
-so far. Purge, native-target packages, signing, and any installer or marketplace do not exist yet.
+- the portable `any` target, for pure-JavaScript modules;
+- `linux-x64-glibc`, for modules with a native dependency such as `sharp`. Its native runtime
+  packages are carried as real files under the package's `node_modules`, and the verifier checks the
+  host before anything is loaded.
+
+Every package records the module's validated SPDX expression and carries its explicitly
+supplied `LICENSE` bytes; dependency material remains separate in `THIRD_PARTY_NOTICES`. ABI-v1
+packages may bundle a module-owned Drizzle version without coupling it to Core;
+legacy-v8 packages retain their transitional exact-version check. Where a redistributed dependency
+omits licence material, the packager may add reviewed licence supplements
+([ADR 0052](docs/architecture/decisions/0052-reviewed-license-supplements.md)). A native package that
+redistributes LGPL or MPL code is distributed publicly only with its corresponding-source artifact,
+which `ekklesia-corresponding-source` builds and gates
+([ADR 0055](docs/architecture/decisions/0055-corresponding-source-artifacts.md)). Purge, other
+operating-system or CPU targets, signing, and any installer or marketplace do not exist yet.
+
+A module can be built in its own repository from Ekklesia's public module-development packages
+([ADR 0053](docs/architecture/decisions/0053-standalone-module-development-packages.md)):
+a curated `@ekklesia/module-sdk`, `@ekklesia/module-database`, the UI packages, and the build and
+packaging tools. They are released as one coordinated train of tarballs with a release manifest,
+and CI proves on every run that two builds of a commit are byte-identical and that a module outside
+the repository installs, builds, packages, and verifies from those artifacts alone. A manual
+workflow, the only way to publish, publishes exactly those artifacts to the npm registry and
+verifies every package byte for byte. Anyone may read and install the packages before launch
+([ADR 0054](docs/architecture/decisions/0054-public-package-reads-before-launch.md)). The first train
+published will be the next platform release
+([Releases and the public package train](docs/development/releases.md)).
 
 Phase 4A added Core-owned identity foundations: a Core-owned Better Auth database schema
 (`ekklesia_core_user`, `ekklesia_core_session`, `ekklesia_core_account`,
@@ -506,8 +532,8 @@ reported `blocked · configuration_missing · bucket` — never imported, never
 from inside its own `start` hook — and its required dependents block behind it through ADR 0028's
 existing mechanism. Doctor and `pnpm modules:validate` report the same thing while still importing no
 module code. That change introduced `manifestVersion: 5` as a hard cutover; the current strict
-manifest is version 7 after ADR 0033 added the optional display declaration and ADR 0041 added
+manifest is version 8 after ADR 0050 added the optional database ABI declaration. Version 8 is a
-browser contributions.
+hard cutover; a version 7 source module or package must be updated and rebuilt.
 
 **Ekklesia does not store secrets, and does not pretend to.** There is no encryption at rest here and
 no key management, so a `secret` key's value is supplied by the deployment
@@ -796,7 +822,8 @@ hosting are deployment work, not guarantees added by this pass. Display device i
 public Website remain separate future designs.
 
 **Still not the finished Dashboard.** There is no navigation editor or drag and drop, no nested
-folders, no icons or colors, no Dashboard Home or widgets, no design system, no client-side routing,
+folders, no icons or colors, no Dashboard Home or widgets, no design system, no client-side routing
+(since added; see the Stage 1 paragraph below),
 and no module-management, settings, or storage UI — module enablement and configuration are an API and
 a CLI, not a screen, and object storage is deployment configuration. A production CSP and
 deployment for the built shells, general sidecar asset publication, React runtime sharing, the
@@ -841,7 +868,7 @@ is versioned with no dual acceptance; migrating is one `pnpm build`.
 
 Phase 8 pass 3 lets one module contribute a browser renderer to a capability another module provides
 ([ADR 0041](docs/architecture/decisions/0041-module-browser-contributions.md)) — the browser half of
-the capability system Core has had since Phase 1. `manifestVersion: 7` declares a namespaced id, its
+the capability system Core has had since Phase 1. `manifestVersion: 8` declares a namespaced id, its
 own version, a target capability, a compatible range, and one artifact, and nothing else: there is no
 payload schema, slot, ordering, or rendering hint anywhere, so Core cannot learn what any of it
 means. Publication requires that another eligible module provides the capability inside the declared
@@ -879,6 +906,52 @@ the module's responsibility and do not exist yet.**
 Ekklesia Lite, a theme editor, a module store or installer, a standalone host, and every feature
 module — Signage included — still do not exist, and nothing in Phase 8 claims otherwise.
 
+Stage 1 begins with **real Dashboard URLs**
+([ADR 0057](docs/architecture/decisions/0057-dashboard-urls-are-host-owned-routes.md)). The
+Dashboard opens on an **Overview** at `/`, and each module is a top-level destination with its own
+address, `/<module-id>` (`/signage`), beside `/settings` and `/account`, so a refresh, a bookmark,
+and a shared link land on the page that was open and Back and Forward walk the Dashboard's own pages.
+The API serves the same Dashboard page at `/`, throughout `/settings` and `/account`, and throughout
+each installed module's `/<module-id>`; any other top-level path is its sanitized `404`. Core reserves
+the platform's own top-level names (`account`, `api`, `assets`, `display`, `settings`), and
+discovery refuses a module that uses one. An installed module that is disabled shows a host-owned
+*This page isn't available* rather than loading anything. A module's own
+sub-pages, Settings and Account pages, and returning to the workflow a Settings link came from are
+later Stage 1 work.
+
+The Dashboard's **shell** follows DESIGN.md §4
+([ADR 0058](docs/architecture/decisions/0058-dashboard-shell-navigation-and-lucide-icons.md)): a
+collapsible left sidebar — icons and labels expanded, icons with accessible tooltips collapsed, the
+choice remembered in this browser — with the Overview first, the server's groups and modules below it,
+and an account menu anchored at the bottom (Sign out, for now). There is no top bar. On a phone the
+same navigation opens in a modal drawer with focus trapped inside it, Escape and the backdrop closing
+it, and focus returned to the menu button. Lucide is Ekklesia's icon vocabulary; until modules can
+declare their own icon (manifest v9), every module shows one generic icon. Church branding in the
+sidebar's identity slot is still to come.
+
+`@ekklesia/ui` now carries the interactions every later screen shares
+([ADR 0059](docs/architecture/decisions/0059-shared-interaction-primitives.md)): a product-owned
+`ConfirmationDialog` (simple, destructive, or typed-phrase, chosen by the caller), a per-tree
+top-center toast system, `ErrorState` with collapsed technical detail and remedies, skeleton loading,
+and `PageHeader` with a Back action that returns only to a validated Dashboard page. Every dialog
+traps and restores focus, and `pnpm lint` refuses `window.alert`, `confirm`, and `prompt`
+repository-wide.
+
+The Dashboard follows the operating system's **Light or Dark** appearance and **reduced-motion**
+setting, live and without a reload, and so does every module's UI, through the same design tokens
+([ADR 0060](docs/architecture/decisions/0060-light-dark-system-theme-and-motion.md)). The dark theme is
+designed rather than inverted, every text and focus pairing is contrast-tested to WCAG AA in both
+schemes, corners scale from one `radius.scale` token, and an explicit Light or Dark choice is one call
+away once account preferences exist. Displays stay light.
+
+**Settings** has its own place in the sidebar
+([ADR 0061](docs/architecture/decisions/0061-settings-hierarchy-and-module-settings-routes.md)): a
+landing page at `/settings`; the platform's General, Branding, Displays, Discover, and System; and each
+module's settings at `/settings/<module-id>`. Discover is where modules are found, installed, managed,
+and updated (`/settings/discover/browse`, `/installed`, `/updates`); configuring a module is its own
+Settings page. A person sees only what the server says they may administer, and no Settings link at all
+when that is nothing. The pages are placeholders until each section is built.
+
 ## Quick start
 
 Prerequisites: Node.js 24 LTS, pnpm 11.12, and Docker with Compose.

apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/api",
-  "version": "0.1.2",
+  "version": "0.2.5",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",

apps/api/src/app.ts

@@ -1,6 +1,5 @@
 import {
   isAuthenticatedPrincipal,
-  type ModuleRuntimeServices,
   type ModuleSecretSource,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -13,6 +12,7 @@ import type { DashboardStore } from "@ekklesia/core/dashboard";
 import type { DeviceStore } from "@ekklesia/core/devices";
 import { type EkklesiaIdentityRuntime, IdentityRuntimeError } from "@ekklesia/core/identity";
 import type {
+  AnyModuleRuntimeServices,
   DiscoveredModule,
   ModuleConfigurationLookup,
   ModuleConfigurationSettings,
@@ -20,6 +20,7 @@ import type {
   ModuleLifecycleSnapshot,
   ModuleLifecycleStore,
   ModuleRealtimeRegistry,
+  ModuleRuntimeServicesLookup,
   ModuleStorageLookup,
   ModuleUiPublicationRegistry,
 } from "@ekklesia/core/modules";
@@ -30,7 +31,8 @@ import { AUTH_REQUEST_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js
 import type { DashboardHostAssets } from "./dashboard-host-assets.js";
 import { createDashboardHostRoutes } from "./dashboard-host-routes.js";
 import { createDashboardRoutes } from "./dashboard-routes.js";
-import { createDeviceRoutes } from "./device-routes.js";
+import { createDashboardSettingsRoutes } from "./dashboard-settings-routes.js";
+import { createDeviceRoutes, renewDeviceSessionCookie } from "./device-routes.js";
 import type { DisplayHostAssets } from "./display-host-assets.js";
 import { createGrantsRoutes } from "./grants-routes.js";
 import { type ApiHealthOptions, createHealthRoutes } from "./health-routes.js";
@@ -62,11 +64,10 @@ export interface CreateApiAppOptions {
   /** The started runtime's immutable module-owned realtime registry. Required explicitly even when
    * empty, for the same reason as module routes: application composition never guesses what ran. */
   readonly moduleRealtime: ModuleRealtimeRegistry;
-  /** The same frozen services object the caller's started module runtime already passed to every
+  /** The same per-module service lookup the caller's started module runtime used for every
-   * module's `start`/`stop` hooks (`apps/api/src/server.ts`) — reference-identical, never a fresh
+   * module's `start`/`stop` hooks (`apps/api/src/server.ts`) — each handler receives its module's
-   * object built here, so a module's HTTP handlers and lifecycle hooks share exactly one
+   * reference-identical service object, never a fresh facade or executor built per request. */
-   * `ModuleDatabase` for the lifetime of this API runtime. */
+  readonly moduleServices: ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
-  readonly moduleServices: ModuleRuntimeServices;
   /** The platform's module UI publication policy — always the one Core builds from the exact
    * discovered inventory this runtime started (`createModuleUiPublicationRegistry`,
    * `apps/api/src/server.ts`). Required rather than defaulted, for the same reason `moduleRoutes`
@@ -363,10 +364,18 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
   // own entirely. See `./health-routes.js`.
   app.route("/", createHealthRoutes(options.health));
 
-  // The Dashboard page and its one script, at exact literal paths outside `/api/` (ADR 0044). They
+  // The Dashboard page and its one script, at fixed paths outside `/api/` (ADR 0044, ADR 0057): the
-  // grant no authority and resolve no principal; the page asks `/api/v1/principal` itself. See
+  // page at `/`, the Dashboard's platform pages, and every discovered module with a Dashboard UI at
-  // `./dashboard-host-routes.js`.
+  // `/<module-id>`. They grant no authority and resolve no principal; the page asks
-  app.route("/", createDashboardHostRoutes(options.dashboardHostAssets));
+  // `/api/v1/principal` itself. See `./dashboard-host-routes.js`.
+  app.route(
+    "/",
+    createDashboardHostRoutes(options.dashboardHostAssets, {
+      modulePages: options.moduleLifecycle.snapshot.discoveredModules
+        .filter((module) => module.entrypoints.ui !== undefined)
+        .map((module) => module.manifest.id),
+    }),
+  );
 
   app.route(
     "/",
@@ -407,6 +416,12 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
     registry: options.authorization.registry,
     runtime,
     ...(options.displayHostAssets ? { assets: options.displayHostAssets } : {}),
+    ...(options.devices
+      ? {
+          renewDeviceCredential: (c: Context) =>
+            renewDeviceSessionCookie(c, options.devices?.secureCookies ?? true),
+        }
+      : {}),
   });
 
   if (options.devices) {
@@ -441,6 +456,19 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
     }),
   );
 
+  // Which Settings destinations the viewer may see (ADR 0061): server-evaluated presentation hints
+  // beside the navigation, never authority. See `./dashboard-settings-routes.js`.
+  app.route(
+    "/",
+    createDashboardSettingsRoutes({
+      evaluator: options.authorization.evaluator,
+      platformOwners: options.authorization.store,
+      registry: options.authorization.registry,
+      runtime,
+      snapshot: options.moduleLifecycle.snapshot,
+    }),
+  );
+
   // Mounted before module routes and, critically, under its own sibling prefix: `/api/v1/modules/`
   // belongs entirely to installed modules, so the platform's own lifecycle resource lives beside it
   // rather than inside it. See `./module-lifecycle-routes.js`.

apps/api/src/dashboard-host-routes.ts

@@ -1,13 +1,19 @@
+import { moduleIdSchema } from "@ekklesia/contracts";
+import { isReservedModuleId } from "@ekklesia/core/modules";
+import { DASHBOARD_PLATFORM_PAGES } from "@ekklesia/shell/dashboard-routes";
 import { Hono } from "hono";
 import { etagMatches } from "./conditional-request.js";
 import { createDashboardHostAssets, type DashboardHostAssets } from "./dashboard-host-assets.js";
 
 /**
- * The Dashboard's two host-owned routes (ADR 0044). Neither can collide with anything else the API
+ * The Dashboard's host-owned routes (ADR 0044, ADR 0057). None can collide with anything else the API
- * serves: `/` is the only page the Dashboard has — it has no client router, and every emailed
+ * serves: the page answers at `/`, at the Dashboard's own platform pages (which the shell exports, so
- * verification or reset link lands on `/` with a query (ADR 0038) — and the script lives beside, never
+ * this server and the shell's router read one list), and at each installed module's `/<module-id>`.
- * inside, the display host's `/assets/ekklesia-display/` namespace. Module routes all live under
+ * Every one of those first segments is either a reserved platform name or a module id Core accepted,
- * `/api/v1/modules/<module-id>`.
+ * and Core refuses a module id that is a reserved name, so no module page can shadow `/api`,
+ * `/assets`, `/display`, or a platform page. The script lives beside, never inside, the display
+ * host's `/assets/ekklesia-display/` namespace, and every emailed verification or reset link still
+ * lands on `/` with a query (ADR 0038).
  */
 export const DASHBOARD_HOST_PAGE_PATH = "/";
 export const DASHBOARD_HOST_SCRIPT_PATH = "/assets/ekklesia-dashboard/app.js";
@@ -85,30 +91,74 @@ function fixedAsset(
   });
 }
 
+export interface DashboardHostRouteOptions {
+  /**
+   * The id of every module this process discovered that declares a Dashboard UI — enabled or not,
+   * since a disabled module's bookmark should open the Dashboard and say the module is unavailable
+   * rather than fail as an unknown address. Fixed at startup, like the rest of the module set.
+   */
+  readonly modulePages: readonly string[];
+}
+
+/** Each module page must be a real module id that names no platform namespace, exactly once.
+ * Discovery already guarantees this; the routes refuse to compose rather than trust it. */
+function validatedModulePages(modulePages: readonly string[]): readonly string[] {
+  const seen = new Set<string>();
+  for (const moduleId of modulePages) {
+    if (
+      !moduleIdSchema.safeParse(moduleId).success ||
+      isReservedModuleId(moduleId) ||
+      DASHBOARD_PLATFORM_PAGES.some((page) => page === moduleId) ||
+      seen.has(moduleId)
+    ) {
+      throw new DashboardHostConfigurationError();
+    }
+    seen.add(moduleId);
+  }
+  return [...seen];
+}
+
 /**
  * Serves the built Dashboard from the same origin as `/api`, so the identity system keeps its
  * default same-origin shape.
  *
- * Two exact literal routes over one frozen snapshot: never a static directory, never a path or file
+ * Fixed routes over one frozen snapshot: never a static directory, never a path or file name taken
- * name taken from the request, and never the source map. Any other path — `/index.html`, `/app.js`,
+ * from the request, and never the source map. The page answers at `/`, anywhere inside a Dashboard
- * the `.map`, a traversal spelling — has no route and falls through to the application's ordinary
+ * platform page (`/settings/displays/add` as much as `/settings`), and anywhere inside an installed
- * sanitized `404`. Like the display host's code, these bytes grant no authority: the page renders
+ * module's page (`/signage/timelines` as much as `/signage`, so the module's own sub-pages need no
- * the sign-in form until `/api/v1/principal` says otherwise.
+ * server change later) — always with the **same** bytes and the same validator, because the path
+ * selects a page inside the shell rather than a file here; that is what lets a refreshed or
+ * bookmarked deep link stay where it was.
+ *
+ * A top-level name that is neither — `/definitely-not-a-real-module`, a module that is not
+ * installed or has no Dashboard UI, a look-alike such as `/settings-old` — has no route, nor does
+ * `/index.html`, `/app.js`, the `.map`, or a traversal spelling: all fall through to the
+ * application's ordinary sanitized `404`. Like the display host's code, these bytes grant no
+ * authority: the page renders the sign-in form until `/api/v1/principal` says otherwise.
  */
-export function createDashboardHostRoutes(assets: DashboardHostAssets): Hono {
+export function createDashboardHostRoutes(
+  assets: DashboardHostAssets,
+  options: DashboardHostRouteOptions,
+): Hono {
   const snapshot = snapshotAssets(assets);
+  const modulePages = validatedModulePages(options.modulePages);
   const routes = new Hono();
 
-  routes.get(DASHBOARD_HOST_PAGE_PATH, (c) =>
+  const page = (ifNoneMatch: string | undefined): Response =>
     fixedAsset(
-      c.req.header("if-none-match"),
+      ifNoneMatch,
       snapshot.html,
       snapshot.htmlEtag,
       "text/html; charset=utf-8",
       DASHBOARD_PAGE_SECURITY_HEADERS,
-    ),
     );
 
+  routes.get(DASHBOARD_HOST_PAGE_PATH, (c) => page(c.req.header("if-none-match")));
+  for (const name of [...DASHBOARD_PLATFORM_PAGES, ...modulePages]) {
+    routes.get(`/${name}`, (c) => page(c.req.header("if-none-match")));
+    routes.get(`/${name}/*`, (c) => page(c.req.header("if-none-match")));
+  }
+
   routes.get(DASHBOARD_HOST_SCRIPT_PATH, (c) =>
     fixedAsset(
       c.req.header("if-none-match"),

apps/api/src/dashboard-settings-routes.ts

@@ -0,0 +1,133 @@
+import type { EkklesiaPrincipal, PermissionId } from "@ekklesia/contracts";
+import {
+  type AuthorizationPlatformOwnerPort,
+  CORE_DEVICES_MANAGE,
+  CORE_MODULES_CONFIGURATION_MANAGE,
+  CORE_MODULES_LIFECYCLE_MANAGE,
+  CORE_MODULES_UI_READ,
+} from "@ekklesia/core/authorization";
+import type { ModuleLifecycleSnapshot } from "@ekklesia/core/modules";
+import { SETTINGS_SECTIONS, type SettingsSection } from "@ekklesia/shell/dashboard-routes";
+import { Hono } from "hono";
+import {
+  type AuthorizationMiddlewareOptions,
+  getAuthorizedPrincipal,
+  requirePermission,
+} from "./authorization-middleware.js";
+
+export const DASHBOARD_SETTINGS_PATH = "/api/v1/dashboard/settings";
+
+/** One module's settings destination: its id (the `/settings/<module-id>` segment), its display
+ * name, and whether it is running. A disabled or blocked module is listed so its address can say it
+ * is unavailable, and flagged so the Dashboard never offers it in navigation. */
+export interface DashboardSettingsModuleView {
+  readonly id: string;
+  readonly name: string;
+  readonly available: boolean;
+}
+
+export interface DashboardSettingsResponse {
+  /** The platform sections this viewer may see, in navigation order. */
+  readonly sections: readonly SettingsSection[];
+  /** Modules whose settings this viewer may see, by name. */
+  readonly modules: readonly DashboardSettingsModuleView[];
+}
+
+/**
+ * Who may see each platform section (ADR 0061).
+ *
+ * A section whose administration already has a Core permission uses it, so it is delegable today.
+ * General, Branding, and System have no permission yet — nothing in them exists to authorize — so
+ * they are shown only to the **platform owner**, the one principal who already holds every
+ * permission; each gains its own delegable permission in the work that builds it.
+ */
+const SECTION_ACCESS: Readonly<Record<SettingsSection, PermissionId | "platform-owner">> =
+  Object.freeze({
+    branding: "platform-owner",
+    // Finding, installing, turning on and off, and updating modules: deciding which modules run.
+    discover: CORE_MODULES_LIFECYCLE_MANAGE,
+    displays: CORE_DEVICES_MANAGE,
+    general: "platform-owner",
+    system: "platform-owner",
+  });
+
+export interface CreateDashboardSettingsRoutesOptions extends AuthorizationMiddlewareOptions {
+  /** The boot snapshot: every module this process discovered, and which it started. A module's
+   * settings exist when its manifest declares configuration (ADR 0029). */
+  readonly snapshot: ModuleLifecycleSnapshot;
+  readonly platformOwners: AuthorizationPlatformOwnerPort;
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/**
+ * The Dashboard's Settings navigation, evaluated for the viewer.
+ *
+ * Like the module permission hints in the navigation (ADR 0026), these are **presentation hints,
+ * not authority**: they decide which Settings destinations the Dashboard offers, so nobody is shown
+ * administration they cannot carry out (DESIGN.md §9.2). Every route behind a section keeps its own
+ * enforcement, unchanged. Each answer goes through Core's one evaluator — baselines, grants, expiry,
+ * and the owner bypass behave exactly as on a real request — and an evaluation failure is a `503`,
+ * never an empty answer that would look like a permissions problem.
+ *
+ * Reading requires `core.modules.ui.read`, the same permission the navigation it sits beside
+ * requires: any signed-in person may ask, and most will be told there is nothing for them.
+ */
+export function createDashboardSettingsRoutes(options: CreateDashboardSettingsRoutesOptions): Hono {
+  const routes = new Hono();
+  const requireRead = requirePermission(options, CORE_MODULES_UI_READ);
+  const started = new Set(options.snapshot.startedModuleIds);
+  const modulesWithSettings = options.snapshot.discoveredModules
+    .filter((module) => module.manifest.configuration.length > 0)
+    .map((module) => ({ id: module.manifest.id, name: module.manifest.name }))
+    .sort((left, right) => compareText(left.name, right.name) || compareText(left.id, right.id));
+
+  const holds = async (
+    principal: EkklesiaPrincipal,
+    permission: PermissionId,
+  ): Promise<boolean> => {
+    const declaration = options.registry.get(permission);
+    if (!declaration) {
+      return false;
+    }
+    return (
+      await options.evaluator.authorize({
+        baseline: declaration.baseline,
+        permission,
+        principal,
+      })
+    ).allowed;
+  };
+
+  routes.get(DASHBOARD_SETTINGS_PATH, requireRead, async (c) => {
+    c.header("Cache-Control", "no-store");
+    c.header("Vary", "Origin, Cookie");
+    const principal = getAuthorizedPrincipal(c);
+    try {
+      let owner: boolean | undefined;
+      const isOwner = async (): Promise<boolean> => {
+        owner ??=
+          principal.kind === "authenticated" &&
+          (await options.platformOwners.isPlatformOwner(principal.userId));
+        return owner;
+      };
+      const sections: SettingsSection[] = [];
+      for (const section of SETTINGS_SECTIONS) {
+        const access = SECTION_ACCESS[section];
+        if (access === "platform-owner" ? await isOwner() : await holds(principal, access)) {
+          sections.push(section);
+        }
+      }
+      const modules = (await holds(principal, CORE_MODULES_CONFIGURATION_MANAGE))
+        ? modulesWithSettings.map((module) => ({ ...module, available: started.has(module.id) }))
+        : [];
+      return c.json({ modules, sections } satisfies DashboardSettingsResponse, 200);
+    } catch {
+      return c.json({ code: "AUTHORIZATION_EVALUATION_FAILED" }, 503);
+    }
+  });
+
+  return routes;
+}

apps/api/src/database.ts

@@ -1,4 +1,4 @@
-import type { ModuleDatabase } from "@ekklesia/contracts";
+import type { ModuleDatabaseExecutor, ModuleId } from "@ekklesia/contracts";
 import {
   type AuthorizationDrizzleDatabase,
   createAuthorizationDrizzleView,
@@ -12,9 +12,11 @@ import { createDeviceDrizzleView, type DeviceDrizzleDatabase } from "@ekklesia/c
 import { createIdentityDrizzleView, type IdentityDrizzleDatabase } from "@ekklesia/core/identity";
 import {
   createModuleConfigurationView,
+  createModuleDatabaseExecutor,
   createModuleDatabaseView,
   createModuleLifecycleView,
   type ModuleConfigurationDrizzleDatabase,
+  type ModuleDatabase,
   type ModuleLifecycleDrizzleDatabase,
 } from "@ekklesia/core/modules";
 
@@ -24,6 +26,8 @@ export interface ApiDatabaseHandle {
   readonly dashboard: DashboardDrizzleDatabase;
   readonly identity: IdentityDrizzleDatabase;
   readonly module: ModuleDatabase;
+  /** Builds one ABI-v1 executor attributed to exactly one module, over this handle's shared pool. */
+  readonly moduleExecutor: (moduleId: ModuleId) => ModuleDatabaseExecutor;
   readonly moduleConfiguration: ModuleConfigurationDrizzleDatabase;
   readonly moduleLifecycle: ModuleLifecycleDrizzleDatabase;
   /**
@@ -76,6 +80,7 @@ export function createApiDatabase(
     dashboard: createDashboardDrizzleView(pool),
     identity: createIdentityDrizzleView(pool),
     module: createModuleDatabaseView(pool),
+    moduleExecutor: (moduleId: ModuleId) => createModuleDatabaseExecutor(pool, { moduleId }),
     moduleConfiguration: createModuleConfigurationView(pool),
     moduleLifecycle: createModuleLifecycleView(pool),
     ping: async (statementTimeoutMs: number) => {

apps/api/src/device-routes.ts

@@ -92,7 +92,7 @@ function readString(body: Record<string, unknown>, key: string, max: number): st
  */
 function writeDeviceCookie(
   c: Context,
-  options: DeviceRoutesOptions,
+  options: Pick<DeviceRoutesOptions, "secureCookies">,
   name: string,
   value: string,
   maxAgeSeconds: number,
@@ -106,6 +106,27 @@ function writeDeviceCookie(
   });
 }
 
+/**
+ * Re-issues the device cookie a request just authenticated with, with a fresh lifetime (ADR 0056).
+ *
+ * The value is unchanged — no rotation — so a renewal lost in transit costs nothing: the screen still
+ * holds a working credential. Only the browser's own expiry is pushed forward, matching the
+ * server's sliding window. Called only after the request resolved to a live, unrevoked device.
+ */
+export function renewDeviceSessionCookie(c: Context, secureCookies: boolean): void {
+  const credential = getCookie(c, DEVICE_SESSION_COOKIE);
+  if (credential === undefined || credential.length === 0) {
+    return;
+  }
+  writeDeviceCookie(
+    c,
+    { secureCookies },
+    DEVICE_SESSION_COOKIE,
+    credential,
+    Math.floor(DEVICE_CREDENTIAL_TTL_MS / 1000),
+  );
+}
+
 export function createDeviceRoutes(options: DeviceRoutesOptions): Hono {
   const routes = new HonoApp();
   const now = options.now ?? ((): Date => new Date());

apps/api/src/module-display-routes.ts

@@ -83,6 +83,9 @@ export interface ModuleDisplayRoutesOptions extends AuthorizationMiddlewareOptio
   /** Omitted only when the registry contains no display entrypoints. Production reads the exact
    * surface-owned files before binding and supplies their frozen contents here. */
   readonly assets?: DisplayHostAssets;
+  /** Re-issues a paired device's cookie with a fresh lifetime (ADR 0056). Composed only when the
+   * deployment has device support; called only for a request that resolved to a device. */
+  readonly renewDeviceCredential?: (c: Context) => void;
 }
 
 /** A composition error, detected before any display route is registered. Carries no module id,
@@ -199,6 +202,11 @@ function mountDisplay(
       if (!viewer) {
         return displayFailure(c);
       }
+      // Every screen asks for this on start, on reconnect, and periodically while running, so it
+      // is where an in-use credential's browser expiry is pushed forward.
+      if (principal.kind === "device") {
+        options.renewDeviceCredential?.(c);
+      }
       return c.json(await describeDisplay(options, principal, display, viewer), 200);
     } catch {
       return displayFailure(c);

apps/api/src/module-http-routes.ts

@@ -1,14 +1,17 @@
 import {
   EMPTY_MODULE_CONFIGURATION,
   EMPTY_MODULE_STORAGE,
+  type ModuleDatabaseExecutor,
   type ModuleId,
   type ModuleRouteHandlerContext,
-  type ModuleRuntimeServices,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
 import type {
+  AnyModuleRuntimeServices,
   ModuleConfigurationLookup,
+  ModuleDatabase,
   ModuleRealtimeRegistry,
+  ModuleRuntimeServicesLookup,
   ModuleStorageLookup,
 } from "@ekklesia/core/modules";
 import type { Context, Hono } from "hono";
@@ -37,14 +40,14 @@ export interface ModuleHttpRoutesOptions extends AuthorizationMiddlewareOptions
    * received for this API runtime — never a fresh one built per request, and never touched for a
    * denied, trusted-origin-rejected, or `OPTIONS` request, since a handler is only ever invoked
    * after authorization succeeds. */
-  readonly services: ModuleRuntimeServices;
+  readonly services: ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
   /**
    * Per-module frozen configuration snapshots — the exact map the module runtime started from
    * (ADR 0029), so a handler and that module's `start`/`stop` hooks receive the identical object
    * rather than two independently resolved values. A module with no entry receives
    * `EMPTY_MODULE_CONFIGURATION`, so `context.config` is always present.
    *
-   * Unlike `services`, which is one shared object, this is keyed by module id: a handler can only
+   * Like `services`, this is keyed by module id: a handler can only
    * ever reach its own module's configuration, because that is the only entry looked up for it.
    */
   readonly configurations: ModuleConfigurationLookup;
@@ -232,6 +235,11 @@ export function mountModuleHttpRoutes(
     if (!options.registry.has(route.permission)) {
       throw new ModuleRouteConfigurationError();
     }
+    const services =
+      "get" in options.services ? options.services.get(route.moduleId) : options.services;
+    if (!services) {
+      throw new ModuleRouteConfigurationError();
+    }
 
     const requireRoutePermission = requirePermission(middlewareOptions, route.permission);
     // The route's own conscious body contract (`route.maxBodyBytes` — 0 means no body accepted at
@@ -243,19 +251,24 @@ export function mountModuleHttpRoutes(
     const routeBodyLimit = platformBodyLimit(route.maxBodyBytes, route.bodyMode);
     const path = moduleRoutePath(route.moduleId, route.path);
     const finalHandler = async (c: Context): Promise<Response> => {
-      const context: ModuleRouteHandlerContext = Object.freeze({
+      const context = Object.freeze({
         config: options.configurations.get(route.moduleId) ?? EMPTY_MODULE_CONFIGURATION,
         moduleId: route.moduleId,
         storage: options.storages.get(route.moduleId) ?? EMPTY_MODULE_STORAGE,
         params: Object.freeze({ ...c.req.param() }),
         principal: getAuthorizedPrincipal(c),
         realtime: options.realtime.publisherFor(route.moduleId),
-        services: options.services,
+        services,
-      });
+      }) as ModuleRouteHandlerContext<ModuleDatabase | ModuleDatabaseExecutor>;
 
       let response: Response;
       try {
-        response = await route.handler(c.req.raw, context);
+        response = await (
+          route.handler as (
+            request: Request,
+            context: ModuleRouteHandlerContext<ModuleDatabase | ModuleDatabaseExecutor>,
+          ) => PromiseLike<Response> | Response
+        )(c.req.raw, context);
       } catch {
         return sanitizedModuleHandlerFailure(c);
       }

apps/api/src/server.ts

@@ -1,11 +1,7 @@
 import type { Socket } from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import {
+import { EMPTY_MODULE_SECRET_SOURCE, type ModuleSecretSource } from "@ekklesia/contracts";
-  EMPTY_MODULE_SECRET_SOURCE,
-  type ModuleRuntimeServices,
-  type ModuleSecretSource,
-} from "@ekklesia/contracts";
 import {
   createAuthorizationEvaluator,
   createAuthorizationStore,
@@ -21,12 +17,14 @@ import {
 } from "@ekklesia/core/identity";
 import { createSmtpMailProvider, type MailProvider } from "@ekklesia/core/mail";
 import {
+  type AnyModuleRuntimeServices,
   createModuleConfigurationStore,
   createModuleLifecycleStore,
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
   type ModuleConfigurationSettings,
   type ModuleEligibilityResolution,
+  type ModuleRuntimeServicesLookup,
   resolveModuleEligibility,
   type StartedModuleRuntime,
   startDiscoveredModuleRuntime,
@@ -393,16 +391,13 @@ function bindServer(
  *    (`prepareStartupModuleInventory`, `./platform-permissions.js`).
  * 2. Construct the one shared PostgreSQL pool (identity, authorization, and the module database
  *    facade each get a typed Drizzle view over it — see `./database.js`).
- * 3. Construct the frozen `ModuleRuntimeServices` (currently just `database`) from that same pool,
+ * 3. Construct the Core identity runtime, authorization store, and evaluator from that pool.
- *    then the Core identity runtime, authorization store, and evaluator.
  * 4. Read the stored module enablement configuration and resolve, from that exact same discovered
  *    inventory, which modules are eligible to run (`resolveModuleEligibility`).
  * 5. Start the module runtime from the eligible subset (`startDiscoveredModuleRuntime`) — never
- *    rediscovering modules a second time — passing it the same services object every module's
+ *    rediscovering modules a second time — passing the manifest-selected service map.
- *    `start`/`stop` hook receives.
  * 6. Create the Hono application, mounting the started module runtime's published routes, publishing
- *    UI for that same eligible set, and passing the exact same services object to every module HTTP
+ *    UI for that same eligible set, and passing the same per-module service map to HTTP handlers.
- *    handler.
  * 7. Bind the Node HTTP server.
  *
  * Discovery and permission composition happen before any pool, Better Auth instance, module
@@ -459,12 +454,10 @@ export async function startApi(
   const storageProvider = config.storage ? createS3StorageProvider(config.storage) : undefined;
   const mailProvider = config.mail ? createSmtpMailProvider(config.mail) : undefined;
 
-  let services: ModuleRuntimeServices;
   let runtime: ReturnType<typeof createIdentityRuntime>;
   let authorizationStore: ReturnType<typeof createAuthorizationStore>;
   let deviceStore: ReturnType<typeof createDeviceStore>;
   try {
-    services = Object.freeze({ database: databaseHandle.module });
     runtime = createIdentityRuntime({
       config: config.identity,
       db: databaseHandle.identity,
@@ -532,6 +525,15 @@ export async function startApi(
     throw error;
   }
 
+  const services: ModuleRuntimeServicesLookup = new Map<string, AnyModuleRuntimeServices>(
+    eligibility.eligibleModules.map((module) => [
+      module.manifest.id,
+      module.manifest.database?.abi === 1
+        ? Object.freeze({ database: databaseHandle.moduleExecutor(module.manifest.id) })
+        : Object.freeze({ database: databaseHandle.module }),
+    ]),
+  );
+
   // One scoped facade per eligible module, over the exact buckets that module's own manifest
   // declares. Built from the eligible set so a blocked module never receives storage at all.
   const moduleStorages = createModuleStorageLookup(

apps/api/tests/api-http.integration.ts

@@ -208,6 +208,29 @@ async function activeConnectionCount(databaseName: string): Promise<number> {
   }
 }
 
+/** How long a shutdown's closed connections may take to leave `pg_stat_activity`. Far below pg's
+ * 10 s idle timeout, so a connection that is genuinely still open is still caught. */
+const SHUTDOWN_SETTLE_MS = 3_000;
+
+/**
+ * The connections left on `databaseName` once a shutdown has had a moment to land.
+ *
+ * PostgreSQL ends a backend asynchronously: `pool.end()` resolves once the client side has closed,
+ * and the server can still list that backend for a moment afterwards. On a loaded CI runner that
+ * moment was long enough for an immediate count to see one. So this waits, briefly, for the count to
+ * reach zero; a leaked pooled client would stay idle and listed far past the deadline.
+ */
+async function connectionsLeftAfterShutdown(databaseName: string): Promise<number> {
+  const deadline = Date.now() + SHUTDOWN_SETTLE_MS;
+  for (;;) {
+    const count = await activeConnectionCount(databaseName);
+    if (count === 0 || Date.now() >= deadline) {
+      return count;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
 async function createDisposableDatabase(label: string): Promise<{ name: string; url: string }> {
   const name = makeDatabaseName(label);
   await createDatabase(name);
@@ -221,9 +244,9 @@ async function applyCoreMigrations(url: string): Promise<void> {
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory: emptyModulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     // Phase 4A's and Phase 4C pass 1's committed migrations must not have drifted while building
@@ -339,10 +362,10 @@ async function createGatedRouteModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: { server: "./dist/server/index.js" },
         id,
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: `${id} module`,
         permissions: [{ baseline: "public", description: "Gated drain probe.", id: permissionId }],
         version: "0.1.0",
@@ -386,11 +409,11 @@ async function createFixtureModule(
 ): Promise<void> {
   const moduleDirectory = path.join(modulesDirectory, id);
   const manifest = {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     permissions: [],
     entrypoints: { server: "./dist/server/index.js" },
     ...manifestOverrides,
@@ -521,10 +544,10 @@ async function createUiModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
         id,
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: `${id} module`,
         version,
       }),
@@ -1349,7 +1372,7 @@ describe.sequential("live API — signup, sign-in, principal, sign-out", () => {
     await running.shutdown();
 
     await expect(fetch(origin, { signal: AbortSignal.timeout(1_000) })).rejects.toBeTruthy();
-    const remainingConnections = await activeConnectionCount(database.name);
+    const remainingConnections = await connectionsLeftAfterShutdown(database.name);
     expect(remainingConnections).toBe(0);
 
     await dropDatabase(database.name);
@@ -2230,7 +2253,7 @@ describe.sequential("live API — platform owner and delegated grant management"
 
   it("shuts down cleanly, closing the one shared pool", async () => {
     await running.shutdown();
-    const remainingConnections = await activeConnectionCount(database.name);
+    const remainingConnections = await connectionsLeftAfterShutdown(database.name);
     expect(remainingConnections).toBe(0);
     await dropDatabase(database.name);
   });
@@ -2592,9 +2615,9 @@ describe.sequential("live API — installed module permission end-to-end", () =>
     const report = await diagnoseEkklesia({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
       runtimeRange: ">=0.0.0",
       runtimeVersion: process.versions.node,
@@ -2837,7 +2860,7 @@ describe.sequential("live API — installed module permission end-to-end", () =>
 
   it("shuts down cleanly, then restarting with the module absent rejects new grants for its former permission, returns NOT_FOUND for its former route, while the historical grant remains listable", async () => {
     await running.shutdown();
-    const remainingConnections = await activeConnectionCount(database.name);
+    const remainingConnections = await connectionsLeftAfterShutdown(database.name);
     expect(remainingConnections).toBe(0);
     // Exactly one stop, matching the exactly-one register/start already asserted above.
     expect(recorder.events.filter((event) => event === "calendar:stop")).toHaveLength(1);
@@ -3906,9 +3929,9 @@ describe.sequential("live API — module lifecycle governs what actually runs",
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     expect(aggregate.discoveredModules.map((module) => module.manifest.id)).toEqual(["calendar"]);

apps/api/tests/app.test.ts

@@ -1,8 +1,6 @@
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   moduleIdSchema,
   parseEkklesiaUserId,
   parsePermissionId,
@@ -20,6 +18,8 @@ import { IdentityRuntimeError } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleUiPublicationRegistry,
   StagedModuleRealtimeRegistry,
 } from "@ekklesia/core/modules";
@@ -48,9 +48,9 @@ function fakeRuntime(overrides: Partial<EkklesiaIdentityRuntime> = {}): Ekklesia
   };
 }
 
-/** A small typed fake `ModuleRuntimeServices` — these tests exercise `createApiApp`'s own wiring,
+/** A small typed fake `LegacyModuleRuntimeServices` — these tests exercise `createApiApp`'s own wiring,
  * never real database behavior, so no PostgreSQL is required. */
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   const database = Object.freeze({
     delete: vi.fn(),
     execute: vi.fn(),

apps/api/tests/dashboard-host-routes.test.ts

@@ -1,9 +1,8 @@
 import { createHash } from "node:crypto";
 import {
   ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
   type ModuleRouteHandler,
-  type ModuleRuntimeServices,
+  parseModuleManifest,
   parsePermissionId,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -15,7 +14,15 @@ import {
 import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
+  type DiscoveredModule,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  isReservedModuleId,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
+  type ModuleLifecycleConfiguration,
+  RESERVED_MODULE_IDS,
+  RESERVED_SETTINGS_NAMES,
+  RESERVED_TOP_LEVEL_NAMES,
 } from "@ekklesia/core/modules";
 import { describe, expect, it, vi } from "vitest";
 
@@ -33,11 +40,23 @@ import {
   DASHBOARD_HOST_PAGE_PATH,
   DASHBOARD_HOST_SCRIPT_PATH,
   DashboardHostConfigurationError,
+  createDashboardHostRoutes,
 } from "../src/dashboard-host-routes.js";
-import { DISPLAY_HOST_SCRIPT_PATH } from "../src/module-display-routes.js";
+import { DASHBOARD_PLATFORM_PAGES, SETTINGS_SECTIONS } from "@ekklesia/shell/dashboard-routes";
+import {
+  MODULE_DISPLAY_DESCRIPTOR_PREFIX,
+  MODULE_DISPLAY_PAGE_PREFIX,
+} from "../src/module-display-path.js";
+import {
+  DISPLAY_HOST_SCRIPT_PATH,
+  DISPLAY_SERVICE_WORKER_PATH,
+} from "../src/module-display-routes.js";
 import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
-import { emptyModuleLifecycle } from "./support/in-memory-module-lifecycle.js";
+import {
+  createInMemoryModuleLifecycleStore,
+  moduleLifecycleSnapshotFor,
+} from "./support/in-memory-module-lifecycle.js";
 import { emptyModuleStorage } from "./support/in-memory-module-storage.js";
 import { readyHealth } from "./support/ready-health.js";
 
@@ -74,13 +93,44 @@ function fakeStore(): AuthorizationStore {
   };
 }
 
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 
+/** A discovered module as the boot snapshot records it, from a real validated manifest. Only its id
+ * and whether it declares a Dashboard UI matter to these routes; nothing is ever loaded. */
+function discoveredModule(id: string, options: { readonly ui: boolean }): DiscoveredModule {
+  const manifest = parseModuleManifest({
+    capabilities: [],
+    compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
+    entrypoints: {
+      server: "./dist/server/index.js",
+      ...(options.ui ? { ui: "./dist/ui/index.js" } : {}),
+    },
+    id,
+    manifestVersion: 8,
+    name: `${id} module`,
+    permissions: [],
+    version: "0.1.0",
+  });
+  return {
+    contributions: [],
+    directory: `/modules/${id}`,
+    entrypoints: {
+      server: `/modules/${id}/dist/server/index.js`,
+      ...(options.ui ? { ui: `/modules/${id}/dist/ui/index.js` } : {}),
+    },
+    manifest,
+    manifestPath: `/modules/${id}/ekklesia.module.json`,
+    packageName: `@test/${id}`,
+  };
+}
+
 function buildApp(
   options: {
     readonly assets?: DashboardHostAssets;
+    readonly configuration?: ModuleLifecycleConfiguration;
+    readonly discovered?: readonly DiscoveredModule[];
     readonly moduleRoutes?: readonly RegisteredModuleHttpRoute[];
   } = {},
 ) {
@@ -100,7 +150,10 @@ function buildApp(
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: fakeModuleServices(),
     moduleUi: createModuleUiPublicationRegistry([]),
-    moduleLifecycle: emptyModuleLifecycle(),
+    moduleLifecycle: {
+      snapshot: moduleLifecycleSnapshotFor(options.discovered ?? [], options.configuration),
+      store: createInMemoryModuleLifecycleStore(),
+    },
     moduleConfiguration: emptyModuleConfiguration(),
     moduleStorage: emptyModuleStorage(),
     dashboard: createInMemoryDashboardStore(),
@@ -193,6 +246,179 @@ describe("GET / (the Dashboard page)", () => {
   });
 });
 
+describe("Dashboard deep links (ADR 0057)", () => {
+  const installed = () => [
+    discoveredModule("signage", { ui: true }),
+    discoveredModule("calendar", { ui: true }),
+    discoveredModule("retired", { ui: true }),
+    // A display-only module has no Dashboard page (ADR 0033).
+    discoveredModule("lobby-screen", { ui: false }),
+  ];
+  // Installed but disabled: its address still opens the Dashboard, which says it is unavailable.
+  const configuration = { modules: [{ enabled: false, moduleId: "retired" }] };
+
+  const deepLinks = [
+    "/settings",
+    "/settings/",
+    "/settings/displays/add",
+    "/account",
+    "/account/appearance",
+    "/signage",
+    "/signage/",
+    // Reserved for the module's own pages, which the shell will interpret (ADR 0057).
+    "/signage/timelines",
+    "/signage/timelines/a1b2",
+    "/calendar",
+    "/retired",
+  ];
+
+  it("serves the shell's own platform pages, from the shell's own list", () => {
+    expect(DASHBOARD_PLATFORM_PAGES).toEqual(["settings", "account"]);
+  });
+
+  it("serves the identical page, validator, and security headers at every Dashboard page, so a refresh stays put", async () => {
+    const { app } = buildApp({ configuration, discovered: installed() });
+
+    for (const path of deepLinks) {
+      const response = await app.request(path);
+      expect(response.status, path).toBe(200);
+      expect(await response.text(), path).toBe(PAGE_HTML);
+      expect(response.headers.get("content-type"), path).toBe("text/html; charset=utf-8");
+      expect(response.headers.get("cache-control"), path).toBe("no-cache");
+      expect(response.headers.get("etag"), path).toBe(PAGE_ETAG);
+      expectPageSecurityHeaders(response);
+    }
+    expect(readFileMock).not.toHaveBeenCalled();
+  });
+
+  it("revalidates a deep link with the page's one validator", async () => {
+    const { app } = buildApp({ discovered: installed() });
+
+    for (const path of ["/settings/displays", "/signage"]) {
+      const response = await app.request(path, { headers: { "If-None-Match": PAGE_ETAG } });
+      expect(response.status, path).toBe(304);
+      expect(await response.text(), path).toBe("");
+      expectPageSecurityHeaders(response);
+    }
+  });
+
+  it("never turns an arbitrary top-level path into a Dashboard page", async () => {
+    const { app } = buildApp({ configuration, discovered: installed() });
+
+    for (const path of [
+      "/definitely-not-a-real-module",
+      "/definitely-not-a-real-module/timelines",
+      // Installed, but with no Dashboard UI.
+      "/lobby-screen",
+      // Look-alikes of real pages.
+      "/signages",
+      "/signage-old",
+      "/Signage",
+      "/settings-old",
+      "/accounts",
+      // The former implementation prefix is not a namespace at all.
+      "/modules",
+      "/modules/signage",
+    ]) {
+      await expectSanitizedNotFound(await app.request(path), path);
+    }
+  });
+
+  it("serves a module's page only while that module is installed", async () => {
+    const { app } = buildApp({ discovered: [] });
+
+    await expectSanitizedNotFound(await app.request("/signage"), "/signage");
+    expect((await app.request("/settings")).status).toBe(200);
+  });
+
+  it("serves the page and never the script, whatever a deep link's last segment looks like", async () => {
+    const { app } = buildApp({ discovered: installed() });
+
+    for (const path of [
+      "/signage/app.js",
+      "/settings/assets/ekklesia-dashboard/app.js",
+      "/account/index.html",
+    ]) {
+      expect(await (await app.request(path)).text(), path).toBe(PAGE_HTML);
+    }
+  });
+
+  it("answers no other method at a Dashboard page", async () => {
+    const { app } = buildApp({ discovered: installed() });
+
+    for (const path of ["/settings/displays", "/signage"]) {
+      for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
+        await expectSanitizedNotFound(await app.request(path, { method }), `${method} ${path}`);
+      }
+    }
+  });
+
+  it("refuses at composition a module page that would shadow a platform namespace", () => {
+    for (const modulePages of [["api"], ["settings"], ["display"], ["Not-An-Id"], ["a", "a"]]) {
+      expect(
+        () =>
+          createDashboardHostRoutes(createDashboardHostAssets(PAGE_HTML, SCRIPT), { modulePages }),
+        JSON.stringify(modulePages),
+      ).toThrow(DashboardHostConfigurationError);
+    }
+  });
+});
+
+describe("the platform's reserved top-level names (ADR 0057)", () => {
+  it("cover every top-level namespace the API registers, so a module page can never shadow one", () => {
+    const { app } = buildApp({ discovered: [discoveredModule("signage", { ui: true })] });
+
+    const topLevel = new Set(
+      app.routes
+        .map((route) => route.path.split("/")[1] ?? "")
+        .filter((segment) => segment !== "" && segment !== "*"),
+    );
+    topLevel.delete("signage");
+
+    // This composition publishes no display, so the display host's routes are absent here; they
+    // are checked through their own path constants below.
+    expect([...topLevel].sort()).toEqual(["account", "api", "assets", "settings"]);
+    for (const segment of topLevel) {
+      expect(isReservedModuleId(segment), segment).toBe(true);
+    }
+  });
+
+  it("cover the display host's pages, service worker, and script, and the Dashboard's script", () => {
+    for (const path of [
+      MODULE_DISPLAY_PAGE_PREFIX,
+      DISPLAY_SERVICE_WORKER_PATH,
+      DISPLAY_HOST_SCRIPT_PATH,
+      DASHBOARD_HOST_SCRIPT_PATH,
+      MODULE_DISPLAY_DESCRIPTOR_PREFIX,
+    ]) {
+      expect(isReservedModuleId(path.split("/")[1] ?? ""), path).toBe(true);
+    }
+    expect([...RESERVED_TOP_LEVEL_NAMES].sort()).toEqual([
+      "account",
+      "api",
+      "assets",
+      "display",
+      "settings",
+    ]);
+  });
+
+  it("include every Dashboard platform page the shell interprets", () => {
+    for (const page of DASHBOARD_PLATFORM_PAGES) {
+      expect(RESERVED_TOP_LEVEL_NAMES, page).toContain(page);
+    }
+  });
+
+  it("include exactly the Settings sections the shell interprets, so /settings/<module-id> never collides (ADR 0061)", () => {
+    expect([...SETTINGS_SECTIONS].sort()).toEqual([...RESERVED_SETTINGS_NAMES]);
+    for (const section of SETTINGS_SECTIONS) {
+      expect(isReservedModuleId(section), section).toBe(true);
+    }
+    expect(RESERVED_MODULE_IDS).toEqual(
+      [...RESERVED_TOP_LEVEL_NAMES, ...RESERVED_SETTINGS_NAMES].sort(),
+    );
+  });
+});
+
 describe("GET /assets/ekklesia-dashboard/app.js (the Dashboard script)", () => {
   it("serves the exact startup script bytes as JavaScript with revalidation and a strong ETag", async () => {
     const { app } = buildApp();

apps/api/tests/dashboard-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -20,6 +18,8 @@ import {
   createModuleUiPublicationRegistry,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -77,7 +77,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         ...(fixture.withUi === false ? {} : { ui: "./dist/ui/index.js" }),
       },
       id: fixture.id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: fixture.name,
       version: "1.0.0",
     }),
@@ -147,7 +147,7 @@ async function install(options: InstallOptions = {}): Promise<{ app: Hono }> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(modules),
     moduleLifecycle: {
       snapshot: moduleLifecycleSnapshotFor(modules),

apps/api/tests/dashboard-settings-routes.test.ts

@@ -0,0 +1,248 @@
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  type EkklesiaPrincipal,
+  parseEkklesiaUserId,
+  parseModuleManifest,
+} from "@ekklesia/contracts";
+import {
+  type AuthorizationStore,
+  CORE_DEVICES_MANAGE,
+  CORE_MODULES_CONFIGURATION_MANAGE,
+  CORE_MODULES_LIFECYCLE_MANAGE,
+  createAuthorizationEvaluator,
+} from "@ekklesia/core/authorization";
+import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
+import {
+  composePlatformPermissionRegistry,
+  createModuleUiPublicationRegistry,
+  type DiscoveredModule,
+  EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
+  type ModuleLifecycleConfiguration,
+} from "@ekklesia/core/modules";
+import { describe, expect, it, vi } from "vitest";
+import { createApiApp } from "../src/app.js";
+import {
+  DASHBOARD_SETTINGS_PATH,
+  type DashboardSettingsResponse,
+} from "../src/dashboard-settings-routes.js";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
+import { testDashboardHostAssets } from "./support/dashboard-host-assets.js";
+import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
+import {
+  createInMemoryModuleLifecycleStore,
+  moduleLifecycleSnapshotFor,
+} from "./support/in-memory-module-lifecycle.js";
+import { emptyModuleStorage } from "./support/in-memory-module-storage.js";
+import { readyHealth } from "./support/ready-health.js";
+
+/**
+ * `GET /api/v1/dashboard/settings` (ADR 0061): which Settings destinations the viewer may see,
+ * evaluated by the server through Core's one authorization evaluator. Presentation hints, never
+ * authority: every Settings data route keeps its own enforcement.
+ */
+
+const viewerId = parseEkklesiaUserId("44444444-4444-4444-8444-444444444444");
+const viewer = createAuthenticatedPrincipal(viewerId);
+
+function discovered(
+  id: string,
+  options: { readonly name?: string; readonly settings: boolean },
+): DiscoveredModule {
+  const manifest = parseModuleManifest({
+    capabilities: [],
+    compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
+    configuration: options.settings
+      ? [
+          {
+            default: "Hello",
+            description: "A greeting.",
+            key: "greeting",
+            maxLength: 40,
+            type: "string",
+          },
+        ]
+      : [],
+    entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
+    id,
+    manifestVersion: 8,
+    name: options.name ?? `${id} module`,
+    permissions: [],
+    version: "0.1.0",
+  });
+  return {
+    contributions: [],
+    directory: `/modules/${id}`,
+    entrypoints: {
+      server: `/modules/${id}/dist/server/index.js`,
+      ui: `/modules/${id}/dist/ui/index.js`,
+    },
+    manifest,
+    manifestPath: `/modules/${id}/ekklesia.module.json`,
+    packageName: `@test/${id}`,
+  };
+}
+
+interface Options {
+  readonly principal?: EkklesiaPrincipal;
+  readonly owner?: boolean;
+  readonly grants?: readonly string[];
+  readonly modules?: readonly DiscoveredModule[];
+  readonly configuration?: ModuleLifecycleConfiguration;
+  readonly ownerLookupFails?: boolean;
+}
+
+function build(options: Options = {}) {
+  const modules = options.modules ?? [
+    discovered("signage", { name: "Signage", settings: true }),
+    discovered("calendar", { name: "Calendar", settings: true }),
+    discovered("retired", { name: "Archive", settings: true }),
+    discovered("plain", { name: "Plain", settings: false }),
+  ];
+  const isPlatformOwner = vi.fn(async () => {
+    if (options.ownerLookupFails) {
+      throw new Error("database down");
+    }
+    return options.owner === true;
+  });
+  const grants = new Set(options.grants ?? []);
+  const evaluator = createAuthorizationEvaluator({
+    grants: { hasActiveGrant: async ({ permission }) => grants.has(String(permission)) },
+    platformOwners: { isPlatformOwner },
+  });
+  const runtime: EkklesiaIdentityRuntime = {
+    handleAuthRequest: vi.fn(),
+    resolvePrincipal: vi.fn().mockResolvedValue(options.principal ?? viewer),
+  };
+  const store = {
+    createGrant: vi.fn(),
+    grantPlatformOwner: vi.fn(),
+    hasActiveGrant: vi.fn(),
+    isPlatformOwner,
+    listGrantsForUser: vi.fn(),
+    revokeGrant: vi.fn(),
+    revokePlatformOwner: vi.fn(),
+  } as unknown as AuthorizationStore;
+  const app = createApiApp({
+    authorization: { evaluator, registry: composePlatformPermissionRegistry(modules), store },
+    dashboard: createInMemoryDashboardStore(),
+    dashboardHostAssets: testDashboardHostAssets(),
+    health: readyHealth(),
+    moduleConfiguration: emptyModuleConfiguration(),
+    moduleLifecycle: {
+      snapshot: moduleLifecycleSnapshotFor(
+        modules,
+        options.configuration ?? { modules: [{ enabled: false, moduleId: "retired" }] },
+      ),
+      store: createInMemoryModuleLifecycleStore(),
+    },
+    moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
+    moduleRoutes: Object.freeze([]),
+    moduleServices: Object.freeze({
+      database: Object.freeze({}) as unknown as ModuleDatabase,
+    }) as LegacyModuleRuntimeServices,
+    moduleStorage: emptyModuleStorage(),
+    moduleUi: createModuleUiPublicationRegistry([]),
+    runtime,
+    trustedOrigins: ["https://dashboard.example.test"],
+  });
+  return { app, isPlatformOwner };
+}
+
+async function settings(options: Options = {}) {
+  const { app } = build(options);
+  const response = await app.request(DASHBOARD_SETTINGS_PATH);
+  const body =
+    response.status === 200 ? ((await response.json()) as DashboardSettingsResponse) : undefined;
+  return { body, response };
+}
+
+describe("GET /api/v1/dashboard/settings", () => {
+  it("shows a signed-in person with no administrative permission nothing at all", async () => {
+    const { body, response } = await settings();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(body).toEqual({ modules: [], sections: [] });
+  });
+
+  it("refuses an anonymous viewer, like the navigation it sits beside", async () => {
+    const { response } = await settings({ principal: ANONYMOUS_PRINCIPAL });
+
+    expect(response.status).toBe(403);
+  });
+
+  it("shows the platform owner every section, in order, and every module with settings", async () => {
+    const { body } = await settings({ owner: true });
+
+    expect(body).toEqual({
+      modules: [
+        { available: false, id: "retired", name: "Archive" },
+        { available: true, id: "calendar", name: "Calendar" },
+        { available: true, id: "signage", name: "Signage" },
+      ],
+      sections: ["general", "branding", "displays", "discover", "system"],
+    });
+  });
+
+  it("shows Displays exactly to whoever may manage devices", async () => {
+    const { body } = await settings({ grants: [String(CORE_DEVICES_MANAGE)] });
+
+    expect(body).toEqual({ modules: [], sections: ["displays"] });
+  });
+
+  it("shows Discover — module lifecycle — exactly to whoever may manage which modules run", async () => {
+    const { body } = await settings({ grants: [String(CORE_MODULES_LIFECYCLE_MANAGE)] });
+
+    expect(body).toEqual({ modules: [], sections: ["discover"] });
+  });
+
+  it("lists modules' settings exactly to whoever may configure modules, flagging disabled ones", async () => {
+    const { body } = await settings({ grants: [String(CORE_MODULES_CONFIGURATION_MANAGE)] });
+
+    // A module that declares no configuration has no settings page; a disabled module is listed so
+    // its address can say it is unavailable, but marked so the Dashboard does not navigate to it.
+    expect(body).toEqual({
+      modules: [
+        { available: false, id: "retired", name: "Archive" },
+        { available: true, id: "calendar", name: "Calendar" },
+        { available: true, id: "signage", name: "Signage" },
+      ],
+      sections: [],
+    });
+  });
+
+  it("keeps General, Branding, and System to the platform owner until each has a permission of its own", async () => {
+    const { body } = await settings({
+      grants: [
+        String(CORE_DEVICES_MANAGE),
+        String(CORE_MODULES_LIFECYCLE_MANAGE),
+        String(CORE_MODULES_CONFIGURATION_MANAGE),
+      ],
+    });
+
+    expect(body?.sections).toEqual(["displays", "discover"]);
+  });
+
+  it("is a 503, never an empty answer, when authorization cannot be evaluated", async () => {
+    const { response } = await settings({ ownerLookupFails: true });
+
+    expect(response.status).toBe(503);
+    expect(await response.json()).toEqual({ code: "AUTHORIZATION_EVALUATION_FAILED" });
+  });
+
+  it("is a hint, not authority: the data behind a section stays refused without its permission", async () => {
+    const { app } = build({ grants: [] });
+
+    for (const path of [
+      "/api/v1/module-lifecycle",
+      "/api/v1/module-configuration/signage",
+      "/api/v1/grants",
+    ]) {
+      const response = await app.request(path);
+      expect(response.status, path).toBe(403);
+    }
+  });
+});

apps/api/tests/device-pairing.integration.ts

@@ -118,13 +118,13 @@ async function createDisplayModuleDirectory(): Promise<string> {
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: {
           display: { artifact: "./dist/ui/display.js", permission: displayPermission },
           server: "./dist/server/index.js",
         },
         id: "announcements",
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: "Announcements fixture",
         permissions: [
           {
@@ -782,6 +782,127 @@ describe.sequential("display device pairing, end to end", () => {
     }
   });
 
+  /**
+   * ADR 0056: a credential lasts while the screen is in use, and dies 180 days after it was last
+   * seen. Ages are set directly in the database, exactly as months of real use would leave them.
+   */
+  describe("credential lifetime", () => {
+    const ttlSeconds = 180 * 24 * 60 * 60;
+    const descriptor = "/api/v1/module-displays/announcements";
+
+    function renewal(response: Response): string | undefined {
+      return setCookieFor(response, "ekklesia_device_session");
+    }
+
+    it("keeps a screen that is in use paired long past 180 days, renewing its cookie", async () => {
+      const running = await platform("renewal");
+      const device = new DeviceBrowser(running.origin);
+      try {
+        await pairDevice(running, device);
+        const credential = device.header().replace(/^.*ekklesia_device_session=/u, "");
+        // Paired 200 days ago, and seen yesterday: a screen that has simply been working.
+        await query(
+          running.url,
+          `update ekklesia_core_device set created_at = now() - interval '200 days', last_seen_at = now() - interval '1 day'`,
+        );
+
+        const response = await device.request(descriptor);
+        expect(response.status).toBe(200);
+        // The same credential, re-issued with a full lifetime and the same protections.
+        const header = renewal(response);
+        expect(header).toBeDefined();
+        expect(header).toContain(`ekklesia_device_session=${credential};`);
+        expect(header).toMatch(new RegExp(`Max-Age=${ttlSeconds}(;|$)`, "u"));
+        expect(header).toMatch(/HttpOnly/u);
+        expect(header).toMatch(/SameSite=Strict/u);
+        expect(header).toMatch(/Path=\//u);
+        expect(header).not.toMatch(/Domain=/iu);
+
+        // Using it moved the server's window forward too.
+        const [row] = await query<{ recent: boolean }>(
+          running.url,
+          `select last_seen_at > now() - interval '1 minute' as recent from ekklesia_core_device`,
+        );
+        expect(row?.recent).toBe(true);
+      } finally {
+        await running.close();
+      }
+    });
+
+    it("keeps a credential paired under the fixed 180-day rule working once it is renewed", async () => {
+      const running = await platform("legacy");
+      const device = new DeviceBrowser(running.origin);
+      try {
+        await pairDevice(running, device);
+        // A production screen paired 179 days ago that checked in this morning: under the old
+        // rule it had one day left. It must carry straight on.
+        await query(
+          running.url,
+          `update ekklesia_core_device set created_at = now() - interval '179 days', last_seen_at = now() - interval '2 hours'`,
+        );
+        expect((await device.request(descriptor)).status).toBe(200);
+        await query(
+          running.url,
+          `update ekklesia_core_device set created_at = now() - interval '190 days'`,
+        );
+        expect((await device.request(descriptor)).status).toBe(200);
+      } finally {
+        await running.close();
+      }
+    });
+
+    it("lets an abandoned screen stop being an identity 180 days after it was last seen", async () => {
+      const running = await platform("abandoned");
+      const device = new DeviceBrowser(running.origin);
+      try {
+        await pairDevice(running, device);
+        await query(
+          running.url,
+          `update ekklesia_core_device set created_at = now() - interval '400 days', last_seen_at = now() - interval '181 days'`,
+        );
+        const response = await device.request(descriptor);
+        // Anonymous, exactly as revoked or wrong credentials are: the screen shows a pairing code.
+        expect(response.status).toBe(403);
+        expect(renewal(response)).toBeUndefined();
+      } finally {
+        await running.close();
+      }
+    });
+
+    it("never renews a revoked screen", async () => {
+      const running = await platform("revoked-renewal");
+      const device = new DeviceBrowser(running.origin);
+      try {
+        await pairDevice(running, device);
+        const listed = (await (
+          await adminRequest(running.origin, running.ownerCookie, "/api/v1/devices")
+        ).json()) as { devices: Array<{ id: string }> };
+        await adminRequest(
+          running.origin,
+          running.ownerCookie,
+          `/api/v1/devices/${listed.devices[0]?.id}/revoke`,
+          {},
+        );
+        const response = await device.request(descriptor);
+        expect(response.status).toBe(403);
+        expect(renewal(response)).toBeUndefined();
+      } finally {
+        await running.close();
+      }
+    });
+
+    it("does not hand a device cookie to a person viewing the display", async () => {
+      const running = await platform("human-renewal");
+      try {
+        const response = await adminRequest(running.origin, running.ownerCookie, descriptor);
+        expect(response.status).toBe(200);
+        expect(renewal(response)).toBeUndefined();
+      } finally {
+        await running.close();
+      }
+    });
+  });
+
   it("keeps a human administrator's own session unaffected by a device cookie", async () => {
     const running = await platform("mixed");
     const device = new DeviceBrowser(running.origin);

apps/api/tests/health-routes.test.ts

@@ -1,8 +1,6 @@
 import {
   ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
   type ModuleRouteHandler,
-  type ModuleRuntimeServices,
   parsePermissionId,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -15,6 +13,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApiApp } from "../src/app.js";
@@ -56,7 +56,7 @@ function fakeStore(): AuthorizationStore {
   };
 }
 
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 

apps/api/tests/lifecycle.test.ts

@@ -104,11 +104,11 @@ async function createFixtureModule(
 ): Promise<void> {
   const moduleDirectory = path.join(modulesDirectory, id);
   const manifest = {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     permissions: [],
     entrypoints: { server: "./dist/server/index.js" },
     ...manifestOverrides,
@@ -267,10 +267,10 @@ function fakeDiscoveredModule(
 ): DiscoveredModule {
   const manifest = parseModuleManifest({
     capabilities: [],
-    compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+    compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
     entrypoints: { server: "./dist/does-not-exist/index.js" },
     id,
-    manifestVersion: 7,
+    manifestVersion: 8,
     name: `${id} module`,
     permissions,
     version: "0.1.0",
@@ -1435,9 +1435,9 @@ describe("Ekklesia API module runtime startup and shutdown", () => {
     const recorder = createEventRecorder();
     await createWorkingFixtureModule(modulesDirectory, "calendar", recorder, { withRoute: true });
     const discovered = await (await import("@ekklesia/core/modules")).discoverModules({
-      moduleSdkVersion: "0.1.0",
+      moduleSdkVersion: "0.2.0",
       modulesDirectory,
-      platformVersion: "0.1.0",
+      platformVersion: "0.2.0",
     });
     mockPoolAndAuth();
     mockSuccessfulServe();

apps/api/tests/module-configuration-routes.test.ts

@@ -6,8 +6,6 @@ import {
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
   type ModuleConfigurationDeclarationInput,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -22,10 +20,12 @@ import {
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
   discoverModules,
+  type LegacyModuleRuntimeServices,
   type ModuleConfigurationRecord,
   type ModuleConfigurationStore,
   ModuleConfigurationStoreError,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type ModuleDatabase,
   resolveModuleEligibility,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
@@ -108,7 +108,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         configuration: fixture.configuration ?? [],
         entrypoints: { server: "./dist/server/index.js" },
         id: fixture.id,
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: `${fixture.id} module`,
         version: "1.0.0",
       }),
@@ -213,7 +213,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(eligibility.eligibleModules),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/module-database.integration.ts

@@ -8,6 +8,7 @@ import {
   createPostgresMigrationDatabase,
   discoverAllMigrations,
 } from "@ekklesia/core/migrations";
+import { moduleDatabaseExecutorModuleId } from "@ekklesia/core/modules";
 import { Client, type QueryResultRow } from "pg";
 import { afterAll, describe, expect, it } from "vitest";
 import { createApiRuntimeConfig } from "../src/config.js";
@@ -194,6 +195,29 @@ async function activeConnectionCount(databaseName: string): Promise<number> {
   }
 }
 
+/** How long a shutdown's closed connections may take to leave `pg_stat_activity`. Far below pg's
+ * 10 s idle timeout, so a connection that is genuinely still open is still caught. */
+const SHUTDOWN_SETTLE_MS = 3_000;
+
+/**
+ * The connections left on `databaseName` once a shutdown has had a moment to land.
+ *
+ * PostgreSQL ends a backend asynchronously: `pool.end()` resolves once the client side has closed,
+ * and the server can still list that backend for a moment afterwards. On a loaded CI runner that
+ * moment was long enough for an immediate count to see one. So this waits, briefly, for the count to
+ * reach zero; a leaked pooled client would stay idle and listed far past the deadline.
+ */
+async function connectionsLeftAfterShutdown(databaseName: string): Promise<number> {
+  const deadline = Date.now() + SHUTDOWN_SETTLE_MS;
+  for (;;) {
+    const count = await activeConnectionCount(databaseName);
+    if (count === 0 || Date.now() >= deadline) {
+      return count;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
 async function createDisposableDatabase(label: string): Promise<{ name: string; url: string }> {
   const name = makeDatabaseName(label);
   await createDatabase(name);
@@ -211,9 +235,9 @@ async function applyCoreMigrations(url: string): Promise<void> {
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory: emptyModulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     expect(aggregate.migrations.map((entry) => entry.identity)).toEqual([
@@ -240,9 +264,9 @@ async function applyMigrationsWithModule(url: string): Promise<void> {
   const aggregate = await discoverAllMigrations({
     coreMigrationsDirectory,
     moduleDiscovery: {
-      moduleSdkVersion: "0.1.0",
+      moduleSdkVersion: "0.2.0",
       modulesDirectory: fixtureModulesDirectory,
-      platformVersion: "0.1.0",
+      platformVersion: "0.2.0",
     },
   });
   // Core migrations aggregate first, exactly once each, and always before any module migration.
@@ -441,6 +465,11 @@ describe.sequential("live API — module database explicit migration ownership",
 
       const handle = createApiDatabase(database.url);
       expect(handle.module).toBeDefined();
+      const alpha = handle.moduleExecutor("alpha");
+      const beta = handle.moduleExecutor("beta");
+      expect(alpha).not.toBe(beta);
+      expect(moduleDatabaseExecutorModuleId(alpha)).toBe("alpha");
+      expect(moduleDatabaseExecutorModuleId(beta)).toBe("beta");
       await handle.close();
       expect(await tableExists(database.url)).toBe(false);
 
@@ -754,7 +783,7 @@ describe.sequential("live API — module database access through ModuleRuntimeSe
 
     await running.shutdown();
 
-    const remainingConnections = await activeConnectionCount(database.name);
+    const remainingConnections = await connectionsLeftAfterShutdown(database.name);
     expect(remainingConnections).toBe(0);
 
     const eventsAfterShutdown = readRecorder();

apps/api/tests/module-display-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -21,6 +19,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -105,7 +105,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture = {
           : {}),
       },
       id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${id} module`,
       permissions: fixture.display
         ? [
@@ -155,7 +155,7 @@ interface Installation {
   readonly modules: readonly DiscoveredModule[];
 }
 
-function fakeServices(): ModuleRuntimeServices {
+function fakeServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 

apps/api/tests/module-http-routes.test.ts

@@ -1,13 +1,11 @@
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
   type ModuleRouteHandler,
   type ModuleRouteHandlerContext,
-  type ModuleRuntimeServices,
   moduleRoutesOverlap,
-  parsePermissionId,
   type PermissionId,
+  parsePermissionId,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
 import {
@@ -20,20 +18,23 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
+  type ModuleRuntimeServicesLookup,
 } from "@ekklesia/core/modules";
 import { describe, expect, it, vi } from "vitest";
-import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
-import { testDashboardHostAssets } from "./support/dashboard-host-assets.js";
-import { readyHealth } from "./support/ready-health.js";
 import { createApiApp } from "../src/app.js";
 import {
   canonicalizeVaryHeader,
-  mergedVaryHeader,
   ModuleRouteConfigurationError,
+  mergedVaryHeader,
 } from "../src/module-http-routes.js";
-import { emptyModuleLifecycle } from "./support/in-memory-module-lifecycle.js";
+import { testDashboardHostAssets } from "./support/dashboard-host-assets.js";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
+import { emptyModuleLifecycle } from "./support/in-memory-module-lifecycle.js";
 import { emptyModuleStorage } from "./support/in-memory-module-storage.js";
+import { readyHealth } from "./support/ready-health.js";
 
 const trustedOrigin = "https://dashboard.example.test";
 const untrustedOrigin = "https://evil.example.test";
@@ -73,11 +74,11 @@ function moduleRoute(
   return Object.freeze({ bodyMode: "buffered", maxBodyBytes: 1024, ...fields });
 }
 
-/** A small typed fake `ModuleRuntimeServices` — these tests exercise route mounting,
+/** A small typed fake `LegacyModuleRuntimeServices` — these tests exercise route mounting,
  * authorization, and response sanitization, never real database behavior, so no PostgreSQL is
  * required. Each `database` method stays a distinct spy so a test can assert none of them were
  * ever called (denied, trusted-origin-rejected, and `OPTIONS` requests never reach a handler). */
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   const database = Object.freeze({
     delete: vi.fn(),
     execute: vi.fn(),
@@ -91,7 +92,7 @@ function fakeModuleServices(): ModuleRuntimeServices {
   return Object.freeze({ database });
 }
 
-function expectDatabaseFakeUntouched(services: ModuleRuntimeServices): void {
+function expectDatabaseFakeUntouched(services: LegacyModuleRuntimeServices): void {
   expect(vi.mocked(services.database.select)).not.toHaveBeenCalled();
   expect(vi.mocked(services.database.selectDistinct)).not.toHaveBeenCalled();
   expect(vi.mocked(services.database.selectDistinctOn)).not.toHaveBeenCalled();
@@ -107,7 +108,7 @@ function buildModuleApp(options: {
   readonly registry: PermissionRegistry;
   readonly routes: readonly RegisteredModuleHttpRoute[];
   readonly runtime?: EkklesiaIdentityRuntime;
-  readonly services?: ModuleRuntimeServices;
+  readonly services?: LegacyModuleRuntimeServices | ModuleRuntimeServicesLookup;
   readonly trustedOrigins?: readonly string[];
 }) {
   const evaluator = options.evaluator ?? {
@@ -145,6 +146,36 @@ function permissionRegistry(
 }
 
 describe("module HTTP route mounting", () => {
+  it("selects the owning module's stable service entry for its handler", async () => {
+    const calendar = fakeModuleServices();
+    const people = fakeModuleServices();
+    const services: ModuleRuntimeServicesLookup = new Map([
+      ["calendar", calendar],
+      ["people", people],
+    ]);
+    let received: unknown;
+    const { app } = buildModuleApp({
+      registry: permissionRegistry([{ id: readPermission, baseline: "public" }]),
+      routes: [
+        moduleRoute({
+          handler: (_request, context) => {
+            received = context.services;
+            return Response.json({ ok: true });
+          },
+          method: "GET",
+          moduleId: "calendar",
+          path: "/services",
+          permission: readPermission,
+        }),
+      ],
+      services,
+    });
+
+    expect((await app.request("/api/v1/modules/calendar/services")).status).toBe(200);
+    expect(received).toBe(calendar);
+    expect(received).not.toBe(people);
+  });
+
   it('mounts a "/" route at exactly the module root, never with an added trailing slash', async () => {
     const handler = vi.fn<ModuleRouteHandler>(async () => new Response("root", { status: 200 }));
     const { app } = buildModuleApp({
@@ -508,7 +539,7 @@ describe("module route authorization", () => {
     expect(response.status).toBe(403);
     expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
     expect(handler).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("does not invoke the handler when principal resolution fails", async () => {
@@ -637,7 +668,7 @@ describe("module route trusted-origin enforcement", () => {
     }
     expect(handler).not.toHaveBeenCalled();
     expect(evaluator.authorize).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("allows a trusted-origin state-changing request through to the handler", async () => {
@@ -766,7 +797,7 @@ describe("module route CORS", () => {
 
     expect(handler).not.toHaveBeenCalled();
     expect(evaluator.authorize).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("never reflects an untrusted origin for a module route", async () => {

apps/api/tests/module-lifecycle-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -20,6 +18,8 @@ import {
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleLifecycleStore,
   ModuleLifecycleStoreError,
   EMPTY_MODULE_REALTIME_REGISTRY,
@@ -79,7 +79,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         ...(fixture.dependencies ? { dependencies: fixture.dependencies } : {}),
         entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
         id: fixture.id,
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: `${fixture.id} module`,
         version: "1.0.0",
       }),
@@ -189,7 +189,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(eligibility.eligibleModules),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/module-realtime-live.test.ts

@@ -4,9 +4,7 @@ import path from "node:path";
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
   type ModuleRealtimePublisher,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -18,6 +16,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   composePlatformPermissionRegistry,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleRealtimeRegistry,
   type ModuleRealtimeSubscription,
   startDiscoveredModuleRuntime,
@@ -188,7 +188,7 @@ async function createFixtureModule(control: FixtureControl): Promise<{
         compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
         entrypoints: { server: "./dist/server/index.js" },
         id: "announcements",
-        manifestVersion: 7,
+        manifestVersion: 8,
         name: "Announcements fixture",
         permissions: [
           {
@@ -226,7 +226,7 @@ async function createFixtureModule(control: FixtureControl): Promise<{
   return { directory, symbol };
 }
 
-function services(): ModuleRuntimeServices {
+function services(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as ModuleDatabase });
 }
 

apps/api/tests/module-ui-host-e2e.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -18,6 +16,8 @@ import {
   composePlatformPermissionRegistry,
   createModuleUiPublicationRegistry,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   startDiscoveredModuleRuntime,
 } from "@ekklesia/core/modules";
 import {
@@ -129,7 +129,7 @@ async function createFixtureModule(
           : {}),
       },
       id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name,
       permissions: [
         {
@@ -241,7 +241,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
     modulesDirectory,
     platformVersion: "0.1.0",
   });
-  const services: ModuleRuntimeServices = Object.freeze({
+  const services: LegacyModuleRuntimeServices = Object.freeze({
     database: Object.freeze({}) as unknown as ModuleDatabase,
   });
   // The module's real runtime: its server entrypoint is imported, registered, and started, and the

apps/api/tests/module-ui-inventory.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -21,6 +19,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -99,7 +99,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         version: "1.0.0",
       })),
       id: fixture.id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${fixture.id} module`,
       permissions: (fixture.permissions ?? []).map((permission) => ({
         ...permission,
@@ -192,7 +192,7 @@ async function install(options: InstallOptions): Promise<Installation> {
     revokeGrant: vi.fn(),
     revokePlatformOwner: vi.fn(),
   } as unknown as AuthorizationStore;
-  const services: ModuleRuntimeServices = Object.freeze({
+  const services: LegacyModuleRuntimeServices = Object.freeze({
     database: Object.freeze({}) as unknown as ModuleDatabase,
   });
   const permissionRegistry = composePlatformPermissionRegistry(modules);

apps/api/tests/module-ui-routes.test.ts

@@ -1,11 +1,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import {
+import { ANONYMOUS_PRINCIPAL } from "@ekklesia/contracts";
-  ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
-} from "@ekklesia/contracts";
 import type { AuthorizationEvaluator, AuthorizationStore } from "@ekklesia/core/authorization";
 import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
@@ -14,6 +10,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import { loadModuleUi } from "@ekklesia/module-ui-host";
 import { MODULE_UI_ABI_VERSION, NO_MODULE_UI_CONTRIBUTIONS } from "@ekklesia/module-ui-sdk";
@@ -139,7 +137,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         version: "1.0.0",
       })),
       id: fixture.id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${fixture.id} module`,
       permissions:
         fixture.display === undefined
@@ -215,7 +213,7 @@ async function install(
       : modules.filter((module) => publicationModuleIds.includes(module.manifest.id));
 
   const database = Object.freeze({}) as unknown as ModuleDatabase;
-  const services: ModuleRuntimeServices = Object.freeze({ database });
+  const services: LegacyModuleRuntimeServices = Object.freeze({ database });
   const runtime: EkklesiaIdentityRuntime = {
     handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
     // Anonymous, and every authorization decision denied: whatever this route does, it does it

biome.json

@@ -19,7 +19,10 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "preset": "recommended"
+      "preset": "recommended",
+      "suspicious": {
+        "noAlert": "error"
+      }
     }
   },
   "javascript": {

core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/core",
-  "version": "0.1.2",
+  "version": "0.2.5",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",

core/src/cli/verify-module-package.ts

@@ -25,6 +25,7 @@ class VerifyArgumentsError extends Error {}
 
 const USAGE =
   "Usage: verify-module-package <archive> [--sha256 <hex> | --sha256-file <file>] [--extract-to <new directory>]";
+export const MODULE_VERIFIER_SCRATCH_ENV = "EKKLESIA_MODULE_VERIFIER_SCRATCH_DIR";
 
 export interface VerifyModulePackageArguments {
   readonly archivePath: string;
@@ -90,6 +91,16 @@ export function parseSha256File(contents: string): string {
   return match[1].toLowerCase();
 }
 
+/** The CLI's operator-facing bridge to Core's otherwise explicit verifier option. */
+export function moduleVerifierScratchDirectory(environment: NodeJS.ProcessEnv): string | undefined {
+  const configured = environment[MODULE_VERIFIER_SCRATCH_ENV];
+  if (configured === undefined) return undefined;
+  if (configured === "" || !path.isAbsolute(configured)) {
+    throw new VerifyArgumentsError(`${MODULE_VERIFIER_SCRATCH_ENV} must be an absolute path.`);
+  }
+  return configured;
+}
+
 async function readJson(file: string): Promise<Record<string, unknown>> {
   return JSON.parse(await readFile(file, "utf8")) as Record<string, unknown>;
 }
@@ -121,6 +132,7 @@ export async function readModulePackagePlatform(
 
 async function main(): Promise<void> {
   const parsed = parseVerifyModulePackageArguments(process.argv.slice(2));
+  const executionScratchDirectory = moduleVerifierScratchDirectory(process.env);
   let expectedSha256 = parsed.expectedSha256;
   if (parsed.sha256File !== undefined) {
     let contents: string;
@@ -137,6 +149,7 @@ async function main(): Promise<void> {
   const result = await verifyModulePackage({
     archivePath: parsed.archivePath,
     platform,
+    ...(executionScratchDirectory === undefined ? {} : { executionScratchDirectory }),
     ...(expectedSha256 === undefined ? {} : { expectedSha256 }),
     ...(parsed.extractTo === undefined ? {} : { extractTo: parsed.extractTo }),
   });

core/src/devices/store.ts

@@ -44,17 +44,26 @@ export class DeviceStoreError extends Error {
 export const DEVICE_PAIRING_REQUEST_TTL_MS = 10 * 60_000;
 
 /**
- * How long a device credential is accepted before the device must pair again.
+ * How long a device credential may go **unused** before the device must pair again (ADR 0056).
  *
- * A display runs unattended for months; forcing a signage player to be re-paired every fortnight
+ * The window slides: every request from the device moves `lastSeenAt` forward, and the host
- * because human sessions expire that fast would mean someone climbing to a ceiling-mounted screen
+ * re-issues the cookie with a fresh lifetime, so a screen that is in use stays paired until an
- * on a schedule. What makes a long horizon safe is that it is not the security boundary: the server
+ * administrator revokes it. Revocation, not expiry, is the security boundary — the server checks it
- * decides on every single request whether the device is still revoked, so an administrator's revoke
+ * on every single request. The window exists only so an abandoned, forgotten screen eventually stops
- * takes effect immediately regardless of how long the credential would otherwise have lived. The
+ * being an identity at all: 180 days after it was last seen, its credential is dead.
- * expiry exists so an abandoned, forgotten screen eventually stops being an identity at all.
  */
 export const DEVICE_CREDENTIAL_TTL_MS = 180 * 24 * 60 * 60_000;
 
+/** When a device credential expires: the idle window, measured from the last time the device was
+ * seen, or from pairing if it never has been. */
+export function deviceCredentialExpiresAt(input: {
+  readonly createdAt: Date;
+  readonly lastSeenAt?: Date | null | undefined;
+}): Date {
+  const anchor = Math.max(input.createdAt.getTime(), input.lastSeenAt?.getTime() ?? 0);
+  return new Date(anchor + DEVICE_CREDENTIAL_TTL_MS);
+}
+
 /** How stale `lastSeenAt` may become before the resolver spends a write on it. A display polling
  * realtime and assets would otherwise turn an operational nicety into a continuous write load. */
 export const DEVICE_LAST_SEEN_THROTTLE_MS = 15 * 60_000;
@@ -475,7 +484,8 @@ export function createDeviceStore(db: DeviceDrizzleDatabase): DeviceStore {
         }
         // The credential's own horizon, measured from when the device was paired. Revocation is
         // checked above and is what makes a long horizon acceptable.
-        if (row.createdAt.getTime() + DEVICE_CREDENTIAL_TTL_MS <= now.getTime()) {
+        // Expiry is measured from last use, not from pairing, so a screen in use never ages out.
+        if (deviceCredentialExpiresAt(row).getTime() <= now.getTime()) {
           return undefined;
         }
         return Object.freeze({

core/src/modules/database.ts

@@ -1,7 +1,54 @@
-import type { ModuleDatabase } from "@ekklesia/contracts";
+import type { ModuleDatabaseAbiRuntimeServices, ModuleRuntimeServices } from "@ekklesia/contracts";
-import { drizzle } from "drizzle-orm/node-postgres";
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { Pool } from "pg";
 
+/**
+ * A trusted backend module's typed Drizzle query surface — the same query-building methods a
+ * platform-owned Drizzle instance exposes, restricted to exactly the operations a module needs to
+ * read and write its own tables. Derived with `Pick` from the real `drizzle-orm/node-postgres`
+ * database type rather than hand-declared, so every method keeps Drizzle's own table-aware
+ * argument and result inference exactly as-is — a module calling `database.select().from(table)`
+ * or `database.insert(table).values(...)` gets the identical typed builder a direct Drizzle caller
+ * would, with no `any`/`unknown` erasure anywhere in the chain.
+ *
+ * Deliberately excludes everything `NodePgDatabase` or the `drizzle(...)` factory otherwise
+ * exposes: `$client` (the raw `pg` client/pool), `_` (internal session/dialect/schema state),
+ * `query` (a relational-query builder tied to one schema, which would have to span every
+ * installed module's tables to exist here at all), `$cache`, `$count`, `$with`, `with`, and
+ * `refreshMaterializedView`. There is no connection string, pool, session, or dialect object
+ * reachable through this type. Carries no schema generic — a module brings its own Drizzle table
+ * objects to each call, so there is no global relational schema spanning every installed module for
+ * this type to leak.
+ *
+ * Core's own, private type (ADR 0053): it moved here from `@ekklesia/contracts` so no published
+ * package references Drizzle. New modules use the Module Database ABI v1 instead (ADR 0050), and
+ * the Module SDK never exposes this facade's type.
+ *
+ * This is an integration boundary, not a security sandbox: modules are trusted, compiled backend
+ * plugins that already run arbitrary code in this process, exactly like every other lifecycle hook
+ * and HTTP handler they define. `ModuleDatabase` exists to keep a module's code Drizzle-typed and
+ * decoupled from how the platform physically connects to PostgreSQL — not to defend against a
+ * malicious module, which this facade cannot do and does not attempt to do.
+ */
+export type ModuleDatabase = Pick<
+  NodePgDatabase,
+  | "select"
+  | "selectDistinct"
+  | "selectDistinctOn"
+  | "insert"
+  | "update"
+  | "delete"
+  | "execute"
+  | "transaction"
+>;
+
+/** The services a legacy module's hooks and handlers receive: the legacy facade. */
+export type LegacyModuleRuntimeServices = ModuleRuntimeServices<ModuleDatabase>;
+/** The services Core hands any started module: the legacy facade or the ABI v1 executor. */
+export type AnyModuleRuntimeServices =
+  | LegacyModuleRuntimeServices
+  | ModuleDatabaseAbiRuntimeServices;
+
 /**
  * A typed `ModuleDatabase` view over an externally owned pool — the module-facing counterpart to
  * `createIdentityDrizzleView` (`core/src/identity/database.ts`) and

core/src/modules/discovery.ts

@@ -9,6 +9,7 @@ import {
   safeParseModuleManifest,
   semanticVersionSchema,
 } from "@ekklesia/contracts";
+import { isReservedModuleId } from "./reserved-ids.js";
 
 export const MODULE_MANIFEST_FILENAME = "ekklesia.module.json";
 
@@ -39,6 +40,7 @@ export type ModuleDiscoveryIssueCode =
   | "MODULE_ENTRYPOINT_INVALID"
   | "MODULE_ENTRYPOINT_MISSING"
   | "MODULE_ID_DUPLICATE"
+  | "MODULE_ID_RESERVED"
   | "MODULE_MANIFEST_INVALID"
   | "MODULE_MANIFEST_MISSING"
   | "MODULE_PACKAGE_INVALID"
@@ -614,6 +616,18 @@ async function scanModuleDirectory(
     });
   }
 
+  if (isReservedModuleId(manifest.id)) {
+    // A module's id is a stable URL identifier: its page is `/<module-id>` (ADR 0057) and its
+    // settings `/settings/<module-id>` (ADR 0061), beside the platform's own pages in both.
+    issues.push({
+      code: "MODULE_ID_RESERVED",
+      message: `Module ID ${manifest.id} is reserved for the platform's own pages and routes.`,
+      moduleDirectory: directoryName,
+      moduleId: manifest.id,
+      path: "id",
+    });
+  }
+
   const artifacts = await resolveEntrypoints(moduleDirectory, directoryName, manifest, issues);
   if (!artifacts) {
     return undefined;

core/src/modules/index.ts

@@ -9,9 +9,11 @@ export * from "./lifecycle-schema.js";
 export * from "./lifecycle-store.js";
 export * from "./migration-discovery.js";
 export * from "./modules-directory.js";
+export * from "./module-package-host.js";
 export * from "./module-package-verification.js";
 export * from "./permissions.js";
 export * from "./realtime.js";
+export * from "./reserved-ids.js";
 export * from "./runtime.js";
 export * from "./schema-discovery.js";
 export * from "./ui-publication.js";

core/src/modules/legacy-schema-definition.ts

@@ -1,19 +1,15 @@
+/**
+ * The legacy module schema definition (ADR 0007): a v8 module that declares no `database` default-
+ * exports `{ moduleId, tables }` with its Drizzle table objects themselves. Core alone validates it,
+ * for the legacy facade's deprecation window (ADR 0050). It lives here, beside Core's own Drizzle
+ * dependency, so that no package a module installs needs Drizzle at run time (ADR 0053).
+ *
+ * Erasable TypeScript with no relative imports: the verifier's probe imports this source file
+ * directly in tests (`module-package-probe.ts`).
+ */
 import { is } from "drizzle-orm";
 import { type AnyPgTable, PgTable } from "drizzle-orm/pg-core";
-import { z } from "zod";
+import { type ModuleId, moduleIdSchema } from "@ekklesia/contracts";
-import { type ModuleId, moduleIdSchema } from "./identifiers.js";
-
-export const POSTGRES_IDENTIFIER_MAX_LENGTH = 63;
-
-export const moduleTableLocalNameSchema = z
-  .string()
-  .min(1)
-  .regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/u, "Must be a lowercase snake-case table name.");
-
-export const physicalModuleTableNameSchema = moduleTableLocalNameSchema.max(
-  POSTGRES_IDENTIFIER_MAX_LENGTH,
-  `Must not exceed ${POSTGRES_IDENTIFIER_MAX_LENGTH} characters.`,
-);
 
 export interface ModuleSchemaDefinition<
   Tables extends Readonly<Record<string, AnyPgTable>> = Readonly<Record<string, AnyPgTable>>,
@@ -35,23 +31,6 @@ function hasOnlyStringKeys(value: object, allowedKeys?: ReadonlySet<string>): bo
   );
 }
 
-export function moduleTableNamespace(moduleId: ModuleId): string {
-  return moduleIdSchema.parse(moduleId).replaceAll("-", "_");
-}
-
-export function moduleTablePrefix(moduleId: ModuleId): string {
-  return `${moduleTableNamespace(moduleId)}_`;
-}
-
-export function moduleTableName(moduleId: ModuleId, localName: string): string {
-  const parsedLocalName = moduleTableLocalNameSchema.parse(localName);
-  const tableName = `${moduleTablePrefix(moduleId)}${parsedLocalName}`;
-  if (!physicalModuleTableNameSchema.safeParse(tableName).success) {
-    throw new RangeError("The namespaced PostgreSQL table name is invalid or too long.");
-  }
-  return tableName;
-}
-
 export function isModuleSchemaDefinition(value: unknown): value is ModuleSchemaDefinition {
   try {
     if (

core/src/modules/module-package-host.ts

@@ -0,0 +1,59 @@
+/**
+ * The facts about this host that decide whether a native Module Package v1 can run on it
+ * (ADR 0049): operating system, CPU, C library family and version, and Node-API version.
+ *
+ * Everything comes from Node.js itself (`process.platform`, `process.arch`, `process.versions`, and
+ * the diagnostic report's `glibcVersionRuntime`), never from running a system command. A fact Node
+ * cannot report is left undefined, and every check that needs it fails closed.
+ */
+export interface ModulePackageHost {
+  readonly platform: string;
+  readonly arch: string;
+  /** The C library on Linux: glibc with its runtime version, or undefined when it cannot be proven
+   * to be glibc (musl reports none). */
+  readonly libc?: { readonly family: "glibc"; readonly version: string };
+  /** `process.versions.napi`: the highest Node-API version this Node.js provides. */
+  readonly nodeApi?: number;
+  /** `process.versions.modules`: the ABI an ABI-specific addon must have been built for. */
+  readonly nodeAbi?: string;
+}
+
+function glibcVersion(): string | undefined {
+  try {
+    const header = (process.report?.getReport() as { header?: { glibcVersionRuntime?: unknown } })
+      ?.header;
+    const version = header?.glibcVersionRuntime;
+    return typeof version === "string" && /^\d+\.\d+(?:\.\d+)?$/u.test(version)
+      ? version
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function currentModulePackageHost(): ModulePackageHost {
+  const libc = process.platform === "linux" ? glibcVersion() : undefined;
+  const nodeApi = Number(process.versions.napi);
+  return Object.freeze({
+    arch: process.arch,
+    ...(libc === undefined
+      ? {}
+      : { libc: Object.freeze({ family: "glibc" as const, version: libc }) }),
+    ...(Number.isInteger(nodeApi) && nodeApi > 0 ? { nodeApi } : {}),
+    ...(typeof process.versions.modules === "string" ? { nodeAbi: process.versions.modules } : {}),
+    platform: process.platform,
+  });
+}
+
+/** The native targets this platform can verify, with what each requires of a host. */
+export const MODULE_PACKAGE_NATIVE_TARGETS: ReadonlyMap<
+  string,
+  {
+    readonly platform: string;
+    readonly arch: string;
+    readonly libc: "glibc";
+    readonly elfMachine: number;
+  }
+> = new Map([
+  ["linux-x64-glibc", { arch: "x64", elfMachine: 62, libc: "glibc", platform: "linux" }],
+]);

core/src/modules/module-package-probe.ts

@@ -9,12 +9,18 @@
 // The result travels over the IPC channel, never stdout, so nothing a module prints can forge it.
 // It carries fixed role and reason names only: never an error message, a path, or module output.
 //
-// Written as erasable TypeScript with no relative imports, so Node can run the source file directly
+// Written as erasable TypeScript, so Node can run the source file directly in tests as well as the
-// in tests as well as the compiled file in the image.
+// compiled file in the image. Its one relative import names the source file's own extension, which
+// the build rewrites to `.js` (`rewriteRelativeImportExtensions`); that file follows the same rules.
 import { pathToFileURL } from "node:url";
-import { parseModuleRuntimeDefinition, parseModuleSchemaDefinition } from "@ekklesia/contracts";
+import {
+  parseModuleRuntimeDefinition,
+  parseModuleSchemaMetadataDefinition,
+} from "@ekklesia/contracts";
+import { parseModuleSchemaDefinition } from "./legacy-schema-definition.ts";
 
 interface ProbeRequest {
+  readonly databaseAbi?: 1;
   readonly moduleId: string;
   readonly version: string;
   readonly entrypoints: Readonly<Record<string, string>>;
@@ -22,7 +28,7 @@ interface ProbeRequest {
 
 interface ProbeFailure {
   readonly role: string;
-  readonly reason: "export" | "identity" | "load";
+  readonly reason: "contract" | "export" | "identity" | "load";
 }
 
 function defaultExport(namespace: unknown): unknown {
@@ -51,8 +57,14 @@ async function probe(request: ProbeRequest): Promise<readonly ProbeFailure[]> {
         if (definition.id !== request.moduleId || definition.version !== request.version) {
           failures.push({ reason: "identity", role });
         }
+        if ((definition.database?.abi === 1) !== (request.databaseAbi === 1)) {
+          failures.push({ reason: "contract", role });
+        }
       } else if (role === "schema") {
-        const definition = parseModuleSchemaDefinition(defaultExport(namespace));
+        const definition =
+          request.databaseAbi === 1
+            ? parseModuleSchemaMetadataDefinition(defaultExport(namespace))
+            : parseModuleSchemaDefinition(defaultExport(namespace));
         if (definition.moduleId !== request.moduleId) {
           failures.push({ reason: "identity", role });
         }

core/src/modules/module-package-verification.ts

@@ -1,21 +1,28 @@
 import { fork } from "node:child_process";
 import { createHash } from "node:crypto";
-import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   isVersionCompatible,
+  type ModuleManifest,
+  safeParseModuleManifest,
+} from "@ekklesia/contracts";
+import {
   MODULE_PACKAGE_ANY_TARGET,
   MODULE_PACKAGE_FORMAT,
   MODULE_PACKAGE_METADATA_FILENAME,
-  type ModuleManifest,
   type ModulePackageMetadata,
-  safeParseModuleManifest,
   safeParseModulePackageMetadata,
   safeParseModulePackageRuntimePackage,
-} from "@ekklesia/contracts";
+} from "@ekklesia/contracts/module-package";
 import { discoverModules, MODULE_MANIFEST_FILENAME, ModuleDiscoveryError } from "./discovery.js";
+import {
+  currentModulePackageHost,
+  MODULE_PACKAGE_NATIVE_TARGETS,
+  type ModulePackageHost,
+} from "./module-package-host.js";
 import { discoverModuleMigrations, ModuleMigrationDiscoveryError } from "./migration-discovery.js";
 import {
   type ModulePackageArchive,
@@ -45,6 +52,7 @@ import { discoverModuleSchemas, ModuleSchemaDiscoveryError } from "./schema-disc
 export type ModulePackageVerificationErrorCode =
   | ModulePackageArchiveErrorCode
   | "MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE"
+  | "MODULE_PACKAGE_DATABASE_RUNTIME_UNEXPECTED"
   | "MODULE_PACKAGE_DIGEST_MISMATCH"
   | "MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED"
   | "MODULE_PACKAGE_EXTRACTION_FAILED"
@@ -53,20 +61,26 @@ export type ModulePackageVerificationErrorCode =
   | "MODULE_PACKAGE_FILE_UNLISTED"
   | "MODULE_PACKAGE_FORMAT_UNSUPPORTED"
   | "MODULE_PACKAGE_IDENTITY_MISMATCH"
+  | "MODULE_PACKAGE_LIBC_INCOMPATIBLE"
   | "MODULE_PACKAGE_MANIFEST_INVALID"
   | "MODULE_PACKAGE_METADATA_INVALID"
   | "MODULE_PACKAGE_METADATA_MISSING"
   | "MODULE_PACKAGE_MODULE_INVALID"
   | "MODULE_PACKAGE_NATIVE_FILE"
+  | "MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE"
+  | "MODULE_PACKAGE_NODE_API_INCOMPATIBLE"
   | "MODULE_PACKAGE_RUNTIME_INCOMPATIBLE"
   | "MODULE_PACKAGE_RUNTIME_PACKAGE_INVALID"
   | "MODULE_PACKAGE_SDK_INCOMPATIBLE"
   | "MODULE_PACKAGE_TARGET_INCOMPATIBLE"
-  | "MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED";
+  | "MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED"
+  | "MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE";
 
 const messages: Readonly<Record<ModulePackageVerificationErrorCode, string>> = Object.freeze({
   MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE:
     "The package's bundled database runtime does not match this platform's (a transitional constraint).",
+  MODULE_PACKAGE_DATABASE_RUNTIME_UNEXPECTED:
+    "A Module Database ABI package must not carry a transitional database runtime.",
   MODULE_PACKAGE_DIGEST_MISMATCH: "The archive does not match the SHA-256 it was given.",
   MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED:
     "A backend entrypoint could not be loaded from the package alone.",
@@ -80,12 +94,19 @@ const messages: Readonly<Record<ModulePackageVerificationErrorCode, string>> = O
     "The package metadata, runtime package.json, and manifest disagree about the module's identity.",
   MODULE_PACKAGE_LAYOUT_INVALID:
     "The archive must contain exactly one top-level module directory, with each path once.",
+  MODULE_PACKAGE_LIBC_INCOMPATIBLE:
+    "The package needs a newer C library than this host provides, or one it cannot establish.",
   MODULE_PACKAGE_LINK: "The archive contains a link; module packages may contain none.",
   MODULE_PACKAGE_MANIFEST_INVALID: "The package's module manifest is missing or invalid.",
   MODULE_PACKAGE_METADATA_INVALID: "The package metadata is invalid.",
   MODULE_PACKAGE_METADATA_MISSING: "The archive contains no package metadata.",
   MODULE_PACKAGE_MODULE_INVALID: "The packaged module failed module validation.",
-  MODULE_PACKAGE_NATIVE_FILE: "An any-target package contains a native file.",
+  MODULE_PACKAGE_NATIVE_FILE:
+    "An any-target package contains a native file or a node_modules directory.",
+  MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE:
+    "A native file in the package is not built for the package's target.",
+  MODULE_PACKAGE_NODE_API_INCOMPATIBLE:
+    "The package's addons need a Node-API version or Node.js ABI this host does not provide.",
   MODULE_PACKAGE_RUNTIME_INCOMPATIBLE:
     "The package needs a Node.js version this host does not run.",
   MODULE_PACKAGE_RUNTIME_PACKAGE_INVALID:
@@ -98,6 +119,8 @@ const messages: Readonly<Record<ModulePackageVerificationErrorCode, string>> = O
   MODULE_PACKAGE_TOO_LARGE: "The archive exceeds the module package size limits.",
   MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED:
     "The package metadata contains transitional facts this platform does not understand.",
+  MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE:
+    "The verifier execution scratch directory is missing, not writable, or mounted noexec.",
   MODULE_PACKAGE_UNREADABLE: "The file is not a readable gzip-compressed ustar archive.",
   MODULE_PACKAGE_UNSAFE_MODE: "The archive contains a setuid, setgid, or sticky entry.",
   MODULE_PACKAGE_UNSAFE_PATH: "The archive contains an absolute, escaping, or non-portable path.",
@@ -126,6 +149,8 @@ export interface ModulePackagePlatform {
   readonly databaseRuntime: Readonly<Record<string, string>>;
   /** Defaults to the running process's Node.js version. */
   readonly nodeVersion?: string;
+  /** Defaults to this process's own host (`currentModulePackageHost`). */
+  readonly host?: ModulePackageHost;
 }
 
 export interface VerifyModulePackageOptions {
@@ -135,6 +160,12 @@ export interface VerifyModulePackageOptions {
   readonly platform: ModulePackagePlatform;
   /** A directory that must not exist yet; the verified module directory is written there. */
   readonly extractTo?: string;
+  /**
+   * Existing writable directory where backend candidates may execute. Defaults to `os.tmpdir()`.
+   * A hardened caller whose system temporary directory is `noexec` must provide a dedicated
+   * executable scratch mount; each verification creates and removes its own child directory.
+   */
+  readonly executionScratchDirectory?: string;
   readonly loadTimeoutMs?: number;
 }
 
@@ -261,13 +292,20 @@ function checkCompatibility(
   files: ReadonlyMap<string, Buffer>,
   platform: ModulePackagePlatform,
 ): void {
-  // This verifier implements the portable target only. Native targets are a later slice.
+  if (metadata.target === MODULE_PACKAGE_ANY_TARGET) {
-  if (metadata.target !== MODULE_PACKAGE_ANY_TARGET) {
+    // An any-target package bundles everything: no addon, no ELF object, no node_modules.
-    fail("MODULE_PACKAGE_TARGET_INCOMPATIBLE");
+    for (const [filePath, data] of files) {
-  }
+      if (
-  if ([...files.keys()].some((filePath) => filePath.toLowerCase().endsWith(".node"))) {
+        filePath.toLowerCase().endsWith(".node") ||
+        filePath.startsWith("node_modules/") ||
+        isElf(data)
+      ) {
         fail("MODULE_PACKAGE_NATIVE_FILE");
       }
+    }
+  } else {
+    checkNativeTarget(metadata, files, platform.host ?? currentModulePackageHost());
+  }
   if (!isVersionCompatible(platform.nodeVersion ?? process.versions.node, metadata.runtime.node)) {
     fail("MODULE_PACKAGE_RUNTIME_INCOMPATIBLE");
   }
@@ -275,9 +313,15 @@ function checkCompatibility(
   if (sdk !== undefined && !isVersionCompatible(sdk, manifest.compatibility.moduleSdk)) {
     fail("MODULE_PACKAGE_SDK_INCOMPATIBLE");
   }
-  // Transitional (ADR 0049): today a module's Drizzle copy must be interchangeable with the
+  if (manifest.database?.abi === 1) {
-  // platform's, because Core queries the module's tables with its own Drizzle instance. This is an
+    if (metadata.transitional?.databaseRuntime !== undefined) {
-  // implementation constraint pending a Module Database ABI, not that ABI.
+      fail("MODULE_PACKAGE_DATABASE_RUNTIME_UNEXPECTED");
+    }
+    return;
+  }
+  // Transitional legacy-v8 path (ADR 0049): Core queries the module's Drizzle tables with its own
+  // Drizzle instance, so a recorded module runtime must match. ABI-v1 packages return above: their
+  // bundled ORM is a private implementation detail and is never compared with Core's.
   for (const [runtime, version] of Object.entries(metadata.transitional?.databaseRuntime ?? {})) {
     if (platform.databaseRuntime[runtime] !== version) {
       fail("MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE");
@@ -285,6 +329,74 @@ function checkCompatibility(
   }
 }
 
+function isElf(data: Uint8Array): boolean {
+  return (
+    data.length >= 4 && data[0] === 0x7f && data[1] === 0x45 && data[2] === 0x4c && data[3] === 0x46
+  );
+}
+
+/** `2.41` → `2.41.0`, for comparison against a semantic-version range. */
+function asSemver(version: string): string {
+  const parts = version.split(".");
+  return [...parts, "0", "0"].slice(0, 3).join(".");
+}
+
+/**
+ * A native target (ADR 0049): accepted only for a target this platform implements, on a host that
+ * provably matches it. Platform, CPU, C library family and minimum version, and the Node-API version
+ * or ABI the addons need are all checked; a fact the host cannot establish fails closed. Every ELF
+ * object in the package must be built for the target's machine, and every `.node` addon must be one.
+ */
+function checkNativeTarget(
+  metadata: ModulePackageMetadata,
+  files: ReadonlyMap<string, Buffer>,
+  host: ModulePackageHost,
+): void {
+  const target = MODULE_PACKAGE_NATIVE_TARGETS.get(metadata.target);
+  if (
+    target === undefined ||
+    host.platform !== target.platform ||
+    host.arch !== target.arch ||
+    host.libc?.family !== target.libc
+  ) {
+    fail("MODULE_PACKAGE_TARGET_INCOMPATIBLE");
+  }
+  const required = metadata.runtime.libcVersion;
+  if (
+    required === undefined ||
+    host.libc === undefined ||
+    !isVersionCompatible(asSemver(host.libc.version), required)
+  ) {
+    fail("MODULE_PACKAGE_LIBC_INCOMPATIBLE");
+  }
+  const { nodeAbi, nodeApi } = metadata.runtime;
+  if (
+    (nodeApi === undefined && nodeAbi === undefined) ||
+    (nodeApi !== undefined && (host.nodeApi === undefined || host.nodeApi < nodeApi)) ||
+    (nodeAbi !== undefined && host.nodeAbi !== nodeAbi)
+  ) {
+    fail("MODULE_PACKAGE_NODE_API_INCOMPATIBLE");
+  }
+  for (const [filePath, data] of files) {
+    const addon = filePath.toLowerCase().endsWith(".node");
+    if (!isElf(data)) {
+      if (addon) {
+        fail("MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE");
+      }
+      continue;
+    }
+    // ELF64, little-endian, for the target's machine (e_machine at offset 18).
+    if (
+      data.length < 20 ||
+      data[4] !== 2 ||
+      data[5] !== 1 ||
+      data.readUInt16LE(18) !== target.elfMachine
+    ) {
+      fail("MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE");
+    }
+  }
+}
+
 /** Writes the archive's directories (`0755`) and files (`0644`) under `root`, which must not exist.
  * Safe by construction: every path was validated as relative and non-escaping, and only directories
  * and regular files exist. Ownership is the writing process's, never the archive's. */
@@ -311,13 +423,66 @@ function probeEntrypointPath(): string {
   return path.join(path.dirname(self), `module-package-probe${path.extname(self)}`);
 }
 
+function decodedMountPath(value: string): string {
+  return value.replace(/\\([0-7]{3})/gu, (_match, octal: string) =>
+    String.fromCharCode(Number.parseInt(octal, 8)),
+  );
+}
+
+/** Linux exposes the effective options of every mount, including a container's tmpfs mounts. A
+ * verifier cannot infer `noexec` from file permissions: native addons are mapped executable rather
+ * than invoked as files. On systems without mountinfo, the load remains the final authority. */
+async function isNoExecMount(directory: string): Promise<boolean> {
+  if (process.platform !== "linux") return false;
+  let mountinfo: string;
+  let canonicalDirectory: string;
+  try {
+    [mountinfo, canonicalDirectory] = await Promise.all([
+      readFile("/proc/self/mountinfo", "utf8"),
+      realpath(directory),
+    ]);
+  } catch {
+    return false;
+  }
+  const mounts = mountinfo
+    .split("\n")
+    .map((line) => line.split(" "))
+    .filter((fields) => fields.length > 6 && fields.includes("-"))
+    .map((fields) => ({
+      mountPoint: decodedMountPath(fields[4] ?? ""),
+      options: (fields[5] ?? "").split(","),
+    }))
+    .filter(
+      ({ mountPoint }) =>
+        canonicalDirectory === mountPoint ||
+        canonicalDirectory.startsWith(mountPoint === "/" ? "/" : `${mountPoint}/`),
+    )
+    .sort((left, right) => right.mountPoint.length - left.mountPoint.length);
+  return mounts[0]?.options.includes("noexec") ?? false;
+}
+
+async function createExecutionScratch(baseDirectory: string): Promise<string> {
+  if (!path.isAbsolute(baseDirectory)) {
+    fail("MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE");
+  }
+  try {
+    if (await isNoExecMount(baseDirectory)) {
+      fail("MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE");
+    }
+    return await mkdtemp(path.join(baseDirectory, "ekklesia-package-verify-"));
+  } catch (error) {
+    if (error instanceof ModulePackageVerificationError) throw error;
+    fail("MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE");
+  }
+}
+
 /** Loads every backend entrypoint in a short-lived child with an empty environment, and reports
  * only whether each loaded and exported a definition naming this module. */
 async function loadEntrypoints(
-  moduleId: string,
+  manifest: Pick<ModuleManifest, "database" | "id" | "version">,
-  version: string,
   entrypoints: Readonly<Record<string, string>>,
   timeoutMs: number,
+  executionDirectory: string,
 ): Promise<void> {
   const outcome = await new Promise<"ok" | "failed">((resolve) => {
     let settled = false;
@@ -332,13 +497,24 @@ async function loadEntrypoints(
       }
     };
     try {
-      child = fork(probeEntrypointPath(), [JSON.stringify({ entrypoints, moduleId, version })], {
+      child = fork(
-        cwd: tmpdir(),
+        probeEntrypointPath(),
+        [
+          JSON.stringify({
+            ...(manifest.database?.abi === 1 ? { databaseAbi: 1 } : {}),
+            entrypoints,
+            moduleId: manifest.id,
+            version: manifest.version,
+          }),
+        ],
+        {
+          cwd: executionDirectory,
           env: {},
           execArgv: [],
           serialization: "json",
           stdio: ["ignore", "ignore", "ignore", "ipc"],
-      });
+        },
+      );
     } catch {
       finish("failed");
       return;
@@ -401,7 +577,7 @@ export async function verifyModulePackage(
   const manifest = checkIdentity(archive, metadata, files);
   checkCompatibility(metadata, manifest, files, options.platform);
 
-  const scratch = await mkdtemp(path.join(tmpdir(), "ekklesia-package-verify-"));
+  const scratch = await createExecutionScratch(options.executionScratchDirectory ?? tmpdir());
   try {
     // The candidate alone, in a scratch inventory of its own: never module storage.
     const modulesDirectory = path.join(scratch, "candidates");
@@ -437,12 +613,7 @@ export async function verifyModulePackage(
 
     // Executed only now, and first in isolation: a schema is imported in this process below only
     // after the probe proved it loads on its own.
-    await loadEntrypoints(
+    await loadEntrypoints(manifest, entrypoints, options.loadTimeoutMs ?? 30_000, scratch);
-      metadata.module.id,
-      metadata.module.version,
-      entrypoints,
-      options.loadTimeoutMs ?? 30_000,
-    );
     try {
       await discoverModuleSchemas(discoveryOptions);
     } catch (error) {

core/src/modules/reserved-ids.ts

@@ -0,0 +1,56 @@
+/**
+ * Names the platform owns, which therefore can never be a module id (ADR 0057, ADR 0061).
+ *
+ * A module id is a **stable URL identifier**. Every module with a Dashboard UI is addressed at
+ * `/<module-id>`, and every module with settings at `/settings/<module-id>`, beside the platform's
+ * own pages in the same two namespaces. A module called `settings` would collide with the
+ * Dashboard's Settings, and one called `discover` with Settings → Discover. This is the complete set
+ * the platform serves today, not a guess at what it might want later.
+ */
+
+/**
+ * Top-level namespaces (`/<name>`):
+ *
+ * - `api` — the API: identity, principal, health, Core resources, module routes, module UI artifacts,
+ *   display descriptors, and realtime (`/api/…`);
+ * - `assets` — the Dashboard's and display host's scripts (`/assets/…`);
+ * - `display` — the display host's pages and service worker (`/display/…`);
+ * - `settings` and `account` — the Dashboard's own Settings and account areas.
+ */
+export const RESERVED_TOP_LEVEL_NAMES = Object.freeze([
+  "account",
+  "api",
+  "assets",
+  "display",
+  "settings",
+] as const);
+
+/**
+ * The platform's own Settings sections (`/settings/<name>`): General, Branding, Displays, Discover
+ * (finding, installing, and managing modules), and System. Every other `/settings/<name>` is a
+ * module's settings. Discover's own pages live beneath it (`/settings/discover/…`), so they cannot
+ * collide with a module and need no reservation of their own.
+ */
+export const RESERVED_SETTINGS_NAMES = Object.freeze([
+  "branding",
+  "discover",
+  "displays",
+  "general",
+  "system",
+] as const);
+
+/**
+ * Every reserved name, sorted. `apps/api` holds this list to the routes it actually registers and to
+ * the pages and Settings sections the shell interprets, so a new platform route or Settings section
+ * cannot be added without reserving it here. Reserving a name is a breaking change for any
+ * installation with a module of that id, so the set grows only deliberately.
+ */
+export const RESERVED_MODULE_IDS = Object.freeze(
+  [...RESERVED_TOP_LEVEL_NAMES, ...RESERVED_SETTINGS_NAMES].sort(),
+);
+
+const reserved: ReadonlySet<string> = new Set(RESERVED_MODULE_IDS);
+
+export function isReservedModuleId(moduleId: string): boolean {
+  return reserved.has(moduleId);
+}

core/src/modules/runtime.ts

@@ -7,15 +7,16 @@ import {
   EMPTY_MODULE_CONFIGURATION,
   EMPTY_MODULE_STORAGE,
   type ModuleConfiguration,
+  type ModuleDatabaseExecutor,
   type ModuleHttpRouteRegistrar,
   type ModuleId,
   ModuleRealtimeError,
   type ModuleRealtimePublisher,
   type ModuleRegistrationContext,
   type ModuleRouteDefinitionInput,
+  type ModuleRouteHandler,
   type ModuleRuntimeContext,
   type ModuleRuntimeDefinition,
-  type ModuleRuntimeServices,
   type ModuleStorage,
   moduleRouteShapeKey,
   moduleRoutesOverlap,
@@ -24,6 +25,7 @@ import {
   type RegisteredModuleHttpRoute,
   safeParseModuleRouteDefinition,
 } from "@ekklesia/contracts";
+import type { AnyModuleRuntimeServices, ModuleDatabase } from "./database.js";
 import {
   type DiscoveredModule,
   discoverModules,
@@ -68,6 +70,7 @@ export type ModuleRuntimeIssueCode =
   | "MODULE_ROUTE_PERMISSION_INVALID"
   | "MODULE_ROUTE_PERMISSION_UNDECLARED"
   | "MODULE_RUNTIME_EXPORT_INVALID"
+  | "MODULE_RUNTIME_DATABASE_MISMATCH"
   | "MODULE_RUNTIME_ID_MISMATCH"
   | "MODULE_RUNTIME_IMPORT_FAILED"
   | "MODULE_RUNTIME_VERSION_MISMATCH"
@@ -105,9 +108,8 @@ export interface StartedModuleRuntime {
 /**
  * Per-module frozen configuration snapshots, keyed by module id (ADR 0029).
  *
- * A lookup rather than a field on `ModuleRuntimeServices`, because `services` is deliberately **one
+ * A lookup rather than a field on `ModuleRuntimeServices`, because configuration is resolved and
- * shared object identity every module receives** — a property this runtime has a test for — while
+ * frozen per module independently of its live service object. A module with no entry receives
- * configuration is per-module by definition. A module with no entry receives
  * `EMPTY_MODULE_CONFIGURATION` rather than `undefined`, so `context.config` is always present and
  * module code never branches on whether the platform supplied one.
  */
@@ -124,12 +126,33 @@ function configurationFor(
  * Per-module scoped object storage, keyed by module id (ADR 0030).
  *
  * A lookup for the same reason configuration is one, and emphatically **not** a field on
- * `ModuleRuntimeServices`: `services` is one shared object identity every module receives, while a
+ * `ModuleRuntimeServices`: a storage facade is scoped to exactly the buckets one module declared.
- * storage facade is scoped to exactly the buckets one module declared. Sharing it would hand every
+ * Sharing it would hand every
  * module every other module's storage.
  */
 export type ModuleStorageLookup = ReadonlyMap<string, ModuleStorage>;
 
+/** One frozen service object per module id. Legacy modules may point at objects wrapping the same
+ * facade; ABI-v1 modules each point at their own attributed executor. */
+export type ModuleRuntimeServicesLookup = ReadonlyMap<string, AnyModuleRuntimeServices>;
+export type ModuleRuntimeServicesSource = ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
+
+function servicesFor(
+  services: ModuleRuntimeServicesSource,
+  module: DiscoveredModule,
+): AnyModuleRuntimeServices {
+  const selected = "get" in services ? services.get(module.manifest.id) : services;
+  if (!selected) {
+    throw new TypeError(`Module ${module.manifest.id} has no runtime services.`);
+  }
+  const expectsAbi = module.manifest.database?.abi === 1;
+  const isAbi = "abiVersion" in selected.database && selected.database.abiVersion === 1;
+  if (expectsAbi !== isAbi) {
+    throw new TypeError(`Module ${module.manifest.id} has the wrong database service.`);
+  }
+  return selected;
+}
+
 function storageFor(storages: ModuleStorageLookup, moduleId: string): ModuleStorage {
   return storages.get(moduleId) ?? EMPTY_MODULE_STORAGE;
 }
@@ -164,10 +187,9 @@ export interface ModuleRuntimeCompositionOptions extends ModuleRuntimeTimeoutOpt
 export interface StartModuleRuntimeOptions
   extends ModuleDiscoveryOptions,
     ModuleRuntimeCompositionOptions {
-  /** The same frozen services object every started module's `start`/`stop` hooks and (once
+  /** The manifest-selected service object for each module. One module's `start`/`stop` hooks and
-   * `apps/api` mounts routes) HTTP handlers receive for this runtime — a required production
+   * handlers receive its same entry; ABI-v1 entries carry distinct attributed executors. */
-   * dependency, never an optional test-only global. See `ModuleRuntimeServices`. */
+  readonly services: ModuleRuntimeServicesSource;
-  readonly services: ModuleRuntimeServices;
 }
 
 interface LoadedModule {
@@ -175,6 +197,13 @@ interface LoadedModule {
   readonly discovered: DiscoveredModule;
 }
 
+type AnyRegistrationHook = (
+  context: ModuleRegistrationContext<ModuleDatabase | ModuleDatabaseExecutor>,
+) => unknown;
+type AnyRuntimeHook = (
+  context: ModuleRuntimeContext<ModuleDatabase | ModuleDatabaseExecutor>,
+) => unknown;
+
 interface CapabilityRegistrationStage {
   readonly capabilities: CapabilityRegistrar;
   commit(): readonly ModuleRuntimeIssue[];
@@ -316,11 +345,11 @@ class StagedCapabilityRegistry {
   createRuntimeContext(
     module: DiscoveredModule,
     phase: "rollback" | "start" | "stop",
-    services: ModuleRuntimeServices,
+    services: AnyModuleRuntimeServices,
     config: ModuleConfiguration,
     storage: ModuleStorage,
     realtime: ModuleRealtimePublisher,
-  ): ModuleRuntimeContext {
+  ): ModuleRuntimeContext<ModuleDatabase | ModuleDatabaseExecutor> {
     const capabilities: CapabilityResolver = Object.freeze({
       resolve: (capabilityId: CapabilityId): RegisteredCapability | undefined => {
         this.#assertAccess(module, capabilityId, phase);
@@ -469,7 +498,7 @@ class StagedModuleHttpRoutes {
         local.push(
           Object.freeze({
             bodyMode: parsed.data.bodyMode,
-            handler: parsed.data.handler,
+            handler: parsed.data.handler as ModuleRouteHandler,
             maxBodyBytes: parsed.data.maxBodyBytes,
             method: parsed.data.method,
             moduleId: module.manifest.id,
@@ -555,6 +584,19 @@ async function loadRuntimeDefinitions(
         ),
       );
     }
+    const runtimeDeclaresAbi = definition.database?.abi === 1;
+    const manifestDeclaresAbi = discovered.manifest.database?.abi === 1;
+    if (runtimeDeclaresAbi !== manifestDeclaresAbi) {
+      matchesManifest = false;
+      issues.push(
+        runtimeIssue(
+          "MODULE_RUNTIME_DATABASE_MISMATCH",
+          "load",
+          discovered.manifest.id,
+          `Module runtime database declaration does not match manifest ${discovered.manifest.id}.`,
+        ),
+      );
+    }
     if (matchesManifest) {
       loaded.push({ definition, discovered });
     }
@@ -580,15 +622,15 @@ async function registerModules(
       module.discovered.manifest.id,
       new Set(module.discovered.manifest.permissions.map((declaration) => declaration.id)),
     );
-    const context: ModuleRegistrationContext = Object.freeze({
+    const context = Object.freeze({
       capabilities: capabilityStage.capabilities,
       config: configurationFor(configurations, module.discovered.manifest.id),
       http: routeStage.http,
       moduleId: module.discovered.manifest.id,
       realtime: realtimeStage.realtime,
-    });
+    }) as ModuleRegistrationContext<ModuleDatabase | ModuleDatabaseExecutor>;
     try {
-      await module.definition.register?.(context);
+      await (module.definition.register as AnyRegistrationHook | undefined)?.(context);
     } catch (error) {
       if (error instanceof ModuleRuntimeSignal) {
         throw new ModuleRuntimeError([error.issue]);
@@ -685,7 +727,7 @@ async function stopModules(
   modules: readonly LoadedModule[],
   registry: StagedCapabilityRegistry,
   phase: "rollback" | "stop",
-  services: ModuleRuntimeServices,
+  services: ModuleRuntimeServicesSource,
   configurations: ModuleConfigurationLookup,
   storages: ModuleStorageLookup,
   realtimeRegistry: StagedModuleRealtimeRegistry,
@@ -698,7 +740,7 @@ async function stopModules(
     // A dependency may keep doing ordinary work while its dependents stop. Deactivate only the
     // module whose stop hook is about to run, not every publisher at the beginning of the sequence.
     realtimeRegistry.deactivateModule(moduleId);
-    const stop = module.definition.stop;
+    const stop = module.definition.stop as AnyRuntimeHook | undefined;
     if (!stop) {
       // No synthetic callback and no timer for a module that declares no stop hook.
       continue;
@@ -710,13 +752,13 @@ async function stopModules(
             registry.createRuntimeContext(
               module.discovered,
               phase,
-              services,
+              servicesFor(services, module.discovered),
               configurationFor(configurations, moduleId),
               storageFor(storages, moduleId),
               realtimeRegistry.publisherFor(moduleId),
+            ) as ModuleRuntimeContext<ModuleDatabase | ModuleDatabaseExecutor>,
           ),
-          ),
+        ).then(() => undefined),
-        ),
         timeoutMs,
       );
       if (outcome === "timed-out") {
@@ -750,7 +792,7 @@ async function stopModules(
 async function startModules(
   modules: readonly LoadedModule[],
   registry: StagedCapabilityRegistry,
-  services: ModuleRuntimeServices,
+  services: ModuleRuntimeServicesSource,
   configurations: ModuleConfigurationLookup,
   storages: ModuleStorageLookup,
   realtimeRegistry: StagedModuleRealtimeRegistry,
@@ -766,15 +808,15 @@ async function startModules(
   for (const module of modules) {
     rollbackCandidates.push(module);
     try {
-      await module.definition.start?.(
+      await (module.definition.start as AnyRuntimeHook | undefined)?.(
         registry.createRuntimeContext(
           module.discovered,
           "start",
-          services,
+          servicesFor(services, module.discovered),
           configurationFor(configurations, module.discovered.manifest.id),
           storageFor(storages, module.discovered.manifest.id),
           realtimeRegistry.publisherFor(module.discovered.manifest.id),
-        ),
+        ) as ModuleRuntimeContext<ModuleDatabase | ModuleDatabaseExecutor>,
       );
       const missingSnapshots = realtimeRegistry.missingSnapshots(module.discovered.manifest.id);
       if (missingSnapshots.length > 0) {
@@ -831,7 +873,7 @@ async function startModules(
  */
 export async function startDiscoveredModuleRuntime(
   discoveredModules: readonly DiscoveredModule[],
-  services: ModuleRuntimeServices,
+  services: ModuleRuntimeServicesSource,
   timeouts: ModuleRuntimeCompositionOptions = {},
 ): Promise<StartedModuleRuntime> {
   const modules = await loadRuntimeDefinitions(discoveredModules);

core/src/modules/schema-discovery.ts

@@ -1,12 +1,16 @@
 import { pathToFileURL } from "node:url";
 import {
   type ModuleId,
-  type ModuleSchemaDefinition,
+  type ModuleSchemaMetadataDefinition,
   moduleTableLocalNameSchema,
   moduleTablePrefix,
-  parseModuleSchemaDefinition,
+  parseModuleSchemaMetadataDefinition,
   physicalModuleTableNameSchema,
 } from "@ekklesia/contracts";
+import {
+  type ModuleSchemaDefinition,
+  parseModuleSchemaDefinition,
+} from "./legacy-schema-definition.js";
 import { is } from "drizzle-orm";
 import { type AnyPgTable, getTableConfig, PgColumn, PgTable } from "drizzle-orm/pg-core";
 import {
@@ -40,7 +44,9 @@ export interface DiscoveredModuleTable {
   readonly exportName: string;
   readonly moduleId: ModuleId;
   readonly name: string;
-  readonly table: AnyPgTable;
+  /** Present only for a temporary legacy-facade module. ABI-v1 schema discovery publishes no ORM
+   * object and contributes nothing to the legacy aggregate below. */
+  readonly table?: AnyPgTable;
 }
 
 export interface DiscoveredModuleSchema {
@@ -55,21 +61,40 @@ export interface ModuleSchemaAggregate {
   readonly tables: readonly DiscoveredModuleTable[];
 }
 
-interface LoadedModuleSchema {
+interface LoadedLegacyModuleSchema {
   readonly definition: ModuleSchemaDefinition;
   readonly discovered: DiscoveredModule;
+  readonly mode: "legacy";
 }
 
+interface LoadedAbiModuleSchema {
+  readonly definition: ModuleSchemaMetadataDefinition;
+  readonly discovered: DiscoveredModule;
+  readonly mode: "abi-v1";
+}
+
+type LoadedModuleSchema = LoadedLegacyModuleSchema | LoadedAbiModuleSchema;
+
 interface InspectedModuleSchema {
   readonly discovered: DiscoveredModule;
   readonly tables: ModuleTableCandidate[];
 }
 
-interface ModuleTableCandidate extends DiscoveredModuleTable {
+interface LegacyModuleTableCandidate extends DiscoveredModuleTable {
+  readonly mode: "legacy";
   readonly foreignKeys: ReturnType<typeof getTableConfig>["foreignKeys"];
   readonly path: string;
+  readonly table: AnyPgTable;
 }
 
+interface AbiModuleTableCandidate extends DiscoveredModuleTable {
+  readonly mode: "abi-v1";
+  readonly foreignKeys: ModuleSchemaMetadataDefinition["tables"][number]["foreignKeys"];
+  readonly path: string;
+}
+
+type ModuleTableCandidate = LegacyModuleTableCandidate | AbiModuleTableCandidate;
+
 const drizzleTableIsAlias = Symbol.for("drizzle:IsAlias");
 
 export class ModuleSchemaDiscoveryError extends Error {
@@ -156,9 +181,13 @@ async function loadSchemaDefinitions(discoveredModules: readonly DiscoveredModul
       continue;
     }
 
-    let definition: ModuleSchemaDefinition;
+    let definition: ModuleSchemaDefinition | ModuleSchemaMetadataDefinition;
+    const mode = discovered.manifest.database?.abi === 1 ? "abi-v1" : "legacy";
     try {
-      definition = parseModuleSchemaDefinition(defaultExport(moduleNamespace));
+      definition =
+        mode === "abi-v1"
+          ? parseModuleSchemaMetadataDefinition(defaultExport(moduleNamespace))
+          : parseModuleSchemaDefinition(defaultExport(moduleNamespace));
     } catch {
       issues.push(
         issue(
@@ -182,7 +211,11 @@ async function loadSchemaDefinitions(discoveredModules: readonly DiscoveredModul
       continue;
     }
 
-    loaded.push({ definition, discovered });
+    loaded.push(
+      mode === "abi-v1"
+        ? { definition: definition as ModuleSchemaMetadataDefinition, discovered, mode }
+        : { definition: definition as ModuleSchemaDefinition, discovered, mode },
+    );
   }
 
   return { issues, loaded };
@@ -197,6 +230,58 @@ function inspectTables(
 
   for (const loaded of loadedSchemas) {
     const moduleId = loaded.discovered.manifest.id;
+    if (loaded.mode === "abi-v1") {
+      const candidates: AbiModuleTableCandidate[] = [];
+      loaded.definition.tables.forEach((table, index) => {
+        const path = `tables.${index}`;
+        const candidate: AbiModuleTableCandidate = {
+          exportName: table.name,
+          foreignKeys: table.foreignKeys,
+          mode: "abi-v1",
+          moduleId,
+          name: table.name,
+          path,
+        };
+        const tablePrefix = moduleTablePrefix(moduleId);
+        if (!table.name.startsWith(tablePrefix)) {
+          issues.push(
+            issue(
+              "MODULE_SCHEMA_TABLE_NAMESPACE_INVALID",
+              moduleId,
+              `Table ${table.name} is not namespaced for module ${moduleId}.`,
+              { path, tableName: table.name },
+            ),
+          );
+        } else if (
+          !moduleTableLocalNameSchema.safeParse(table.name.slice(tablePrefix.length)).success
+        ) {
+          issues.push(
+            issue(
+              "MODULE_SCHEMA_TABLE_NAME_INVALID",
+              moduleId,
+              `Module ${moduleId} has an invalid local table name.`,
+              { path },
+            ),
+          );
+        }
+        const existing = firstTableByName.get(table.name);
+        if (existing) {
+          issues.push(
+            issue(
+              "MODULE_SCHEMA_TABLE_DUPLICATE",
+              moduleId,
+              `Table ${table.name} is declared more than once.`,
+              { path, tableName: table.name },
+            ),
+          );
+        } else {
+          firstTableByName.set(table.name, candidate);
+        }
+        candidates.push(candidate);
+      });
+      inspectedModules.push({ discovered: loaded.discovered, tables: candidates });
+      continue;
+    }
     const seenTables = new Set<AnyPgTable>();
     const candidates: ModuleTableCandidate[] = [];
     const entries = Object.entries(loaded.definition.tables).sort(([left], [right]) =>
@@ -293,6 +378,7 @@ function inspectTables(
       const candidate: ModuleTableCandidate = {
         exportName,
         foreignKeys: config.foreignKeys,
+        mode: "legacy",
         moduleId,
         name: config.name,
         path,
@@ -321,8 +407,8 @@ function inspectTables(
 }
 
 function validForeignKeyTarget(
-  foreignKey: ModuleTableCandidate["foreignKeys"][number],
+  foreignKey: LegacyModuleTableCandidate["foreignKeys"][number],
-  candidate: ModuleTableCandidate,
+  candidate: LegacyModuleTableCandidate,
 ): AnyPgTable | undefined {
   try {
     const reference = foreignKey.reference();
@@ -356,14 +442,42 @@ function inspectForeignKeys(
   const ownerByTable = new Map<AnyPgTable, ModuleId>();
   for (const inspected of inspectedModules) {
     for (const candidate of inspected.tables) {
+      if (candidate.mode === "legacy") {
         ownerByTable.set(candidate.table, candidate.moduleId);
       }
     }
+  }
 
   for (const inspected of inspectedModules) {
     const moduleId = inspected.discovered.manifest.id;
     const ownedTables = new Set(inspected.tables.map((candidate) => candidate.table));
     for (const candidate of inspected.tables) {
+      if (candidate.mode === "abi-v1") {
+        const ownedNames = new Set(inspected.tables.map((table) => table.name));
+        candidate.foreignKeys.forEach((foreignKey, foreignKeyIndex) => {
+          const path = `${candidate.path}.foreignKeys.${foreignKeyIndex}`;
+          if (!foreignKey.table.startsWith(moduleTablePrefix(moduleId))) {
+            issues.push(
+              issue(
+                "MODULE_SCHEMA_CROSS_MODULE_FOREIGN_KEY",
+                moduleId,
+                `Table ${candidate.name} has a foreign key outside module ${moduleId}.`,
+                { path, tableName: candidate.name },
+              ),
+            );
+          } else if (!ownedNames.has(foreignKey.table)) {
+            issues.push(
+              issue(
+                "MODULE_SCHEMA_FOREIGN_KEY_TARGET_MISSING",
+                moduleId,
+                `Table ${candidate.name} references a table not exported by module ${moduleId}.`,
+                { path, tableName: candidate.name },
+              ),
+            );
+          }
+        });
+        continue;
+      }
       candidate.foreignKeys.forEach((foreignKey, foreignKeyIndex) => {
         const path = `${candidate.path}.foreignKeys.${foreignKeyIndex}`;
         const foreignTable = validForeignKeyTarget(foreignKey, candidate);
@@ -446,7 +560,9 @@ function publishAggregate(
         moduleId: inspected.discovered.manifest.id,
         tables: Object.freeze(
           inspected.tables
-            .map(({ foreignKeys: _foreignKeys, path: _path, ...table }) => Object.freeze(table))
+            .map(({ foreignKeys: _foreignKeys, mode: _mode, path: _path, ...table }) =>
+              Object.freeze(table),
+            )
             .sort((left, right) => compareText(left.exportName, right.exportName)),
         ),
       }),
@@ -458,7 +574,11 @@ function publishAggregate(
       .sort((left, right) => compareText(left.name, right.name)),
   );
   const drizzleSchema = Object.freeze(
-    Object.fromEntries(tables.map((table) => [table.name, table.table] as const)),
+    Object.fromEntries(
+      tables.flatMap((table) =>
+        table.table === undefined ? [] : [[table.name, table.table] as const],
+      ),
+    ),
   );
 
   return Object.freeze({ discoveredModules, drizzleSchema, modules, tables });

core/tests/cli-bootstrap-platform-owner.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { IMPORT_SAFETY_TEST_TIMEOUT_MS } from "./support/import-safety.js";
 
 const poolConstructor = vi.hoisted(() => vi.fn());
 
@@ -7,7 +8,9 @@ vi.mock("pg", () => ({ Pool: poolConstructor }));
 describe("bootstrap-platform-owner CLI import safety", () => {
   const originalEnv = { ...process.env };
 
-  it("does not read DATABASE_URL, connect to PostgreSQL, or run bootstrap merely by importing the module", async () => {
+  it(
+    "does not read DATABASE_URL, connect to PostgreSQL, or run bootstrap merely by importing the module",
+    async () => {
       delete process.env.DATABASE_URL;
 
       // Under Vitest, process.argv[1] is never this file's own path, so isDirectExecution() is
@@ -18,5 +21,7 @@ describe("bootstrap-platform-owner CLI import safety", () => {
       expect(poolConstructor).not.toHaveBeenCalled();
 
       process.env = originalEnv;
-  });
+    },
+    IMPORT_SAFETY_TEST_TIMEOUT_MS,
+  );
 });

core/tests/cli-create-initial-owner.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { IMPORT_SAFETY_TEST_TIMEOUT_MS } from "./support/import-safety.js";
 
 const poolConstructor = vi.hoisted(() => vi.fn());
 
@@ -7,7 +8,9 @@ vi.mock("pg", () => ({ Pool: poolConstructor }));
 describe("create-initial-owner CLI import safety", () => {
   const originalEnv = { ...process.env };
 
-  it("does not read DATABASE_URL, connect to PostgreSQL, or create anything merely by importing the module", async () => {
+  it(
+    "does not read DATABASE_URL, connect to PostgreSQL, or create anything merely by importing the module",
+    async () => {
       delete process.env.DATABASE_URL;
 
       // Under Vitest, process.argv[1] is never this file's own path, so isDirectExecution() is false
@@ -18,7 +21,9 @@ describe("create-initial-owner CLI import safety", () => {
       expect(poolConstructor).not.toHaveBeenCalled();
 
       process.env = originalEnv;
-  });
+    },
+    IMPORT_SAFETY_TEST_TIMEOUT_MS,
+  );
 
   it("reads no environment variable for the password", async () => {
     // The password is prompted for or read from standard input; it is deliberately never taken from

core/tests/core-migration-discovery.test.ts

@@ -91,7 +91,7 @@ async function createModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        manifestVersion: 7,
+        manifestVersion: 8,
         id,
         name: `${id} module`,
         version: "0.1.0",

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

@@ -59,7 +59,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         : {}),
       entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
       id: fixture.id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: fixture.name,
       version: "1.0.0",
     }),

core/tests/doctor-host-configuration.test.ts

@@ -83,7 +83,7 @@ function discoveredModule(id: string, overrides: Record<string, unknown> = {}):
       },
       entrypoints: { server: "./dist/server.js" },
       id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${id} module`,
       permissions: [],
       storage: { buckets: [] },

core/tests/doctor-import.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { IMPORT_SAFETY_TEST_TIMEOUT_MS } from "./support/import-safety.js";
 
 const discoverModules = vi.fn();
 const discoverModuleSchemas = vi.fn();
@@ -22,7 +23,9 @@ vi.mock("../src/migrations/index.js", async (importOriginal) => ({
 }));
 
 describe("Doctor import safety", () => {
-  it("does not discover, connect, plan, or print when imported", async () => {
+  it(
+    "does not discover, connect, plan, or print when imported",
+    async () => {
       const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
       const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
 
@@ -41,5 +44,7 @@ describe("Doctor import safety", () => {
 
       log.mockRestore();
       error.mockRestore();
-  });
+    },
+    IMPORT_SAFETY_TEST_TIMEOUT_MS,
+  );
 });

core/tests/doctor.test.ts

@@ -1,8 +1,8 @@
-import { type ModuleManifest, parsePermissionId } from "@ekklesia/contracts";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { type ModuleManifest, parsePermissionId } from "@ekklesia/contracts";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createPermissionRegistry, PermissionRegistryError } from "../src/authorization/index.js";
 import {
@@ -32,7 +32,11 @@ const checksumA = "a".repeat(64);
 const checksumB = "b".repeat(64);
 const checksumC = "c".repeat(64);
 
-function discoveredModule(id: string, version = "0.1.0"): DiscoveredModule {
+function discoveredModule(
+  id: string,
+  version = "0.1.0",
+  database?: { readonly abi: 1 },
+): DiscoveredModule {
   return {
     contributions: [],
     directory: `/unpublished/${id}`,
@@ -41,13 +45,14 @@ function discoveredModule(id: string, version = "0.1.0"): DiscoveredModule {
       capabilities: [],
       compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
       configuration: [],
+      ...(database ? { database } : {}),
       dependencies: {
         capabilities: { optional: {}, required: {} },
         modules: { optional: {}, required: {} },
       },
       entrypoints: { server: "./dist/server.js" },
       id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${id} module`,
       permissions: [],
       storage: { buckets: [] },
@@ -294,7 +299,7 @@ describe("Ekklesia Doctor outbound email reporting", () => {
 describe("Ekklesia Doctor diagnostics", () => {
   it("publishes a healthy deterministic static report without database configuration", async () => {
     const people = discoveredModule("people");
-    const calendar = discoveredModule("calendar", "0.2.0");
+    const calendar = discoveredModule("calendar", "0.2.0", { abi: 1 });
     const inventory = migrationAggregate(
       [migration("people", "0000_initial", checksumA)],
       [people, calendar],
@@ -327,6 +332,7 @@ describe("Ekklesia Doctor diagnostics", () => {
     ]);
     expect(check(report, "modules.discovery").details).toEqual(["people 0.1.0", "calendar 0.2.0"]);
     expect(check(report, "modules.dependencies").details).toEqual(["Order: people → calendar"]);
+    expect(check(report, "schemas.discovery")).toMatchObject({ status: "pass" });
     expect(check(report, "modules.permissions")).toMatchObject({
       details: ["0 permissions registered"],
       status: "pass",

core/tests/fixtures/module-database-integration/db-facade/ekklesia.module.json

@@ -1,12 +1,12 @@
 {
-  "manifestVersion": 7,
+  "manifestVersion": 8,
   "id": "db-facade",
   "name": "Database Facade Integration Test Module",
   "description": "Test-only installed module fixture proving ModuleDatabase against real PostgreSQL. Never discovered by production startup, Doctor, or normal migration aggregation — only apps/api/tests/module-database.integration.ts points discovery at it explicitly.",
   "version": "0.1.0",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
   },
   "permissions": [
     {

core/tests/identity-verification-boundaries.test.ts

@@ -169,13 +169,41 @@ describe("the browser shell reaches none of it", () => {
   });
 
   it("never puts a reset token in browser storage", async () => {
-    for (const file of await readTypeScriptFiles(path.join("surfaces", "shell", "src"))) {
-      const code = withoutComments(file.text);
     // A reset token is a bearer credential for one account; the shell holds it in React state for
-      // the life of one form and nowhere else.
+    // the life of one form and nowhere else. The shell's one use of browser storage is the desktop
-      expect(code, file.path).not.toContain("localStorage");
+    // sidebar's expanded/collapsed mode (ADR 0058), so that use is pinned exactly: `localStorage` is
+    // named only by the entry point, and only to hand it to the sidebar preference, whose one write
+    // is its own fixed key and a validated mode.
+    const files = await readTypeScriptFiles(path.join("surfaces", "shell", "src"));
+    const writes: string[] = [];
+    for (const file of files) {
+      const code = withoutComments(file.text);
       expect(code, file.path).not.toContain("sessionStorage");
       expect(code, file.path).not.toContain("document.cookie");
+      writes.push(
+        ...[...code.matchAll(/\.setItem\(([^)]*)\)/gu)].map(
+          (match) => `${path.relative(repositoryRoot, file.path)}: ${match[1]}`,
+        ),
+      );
+      if (file.path.endsWith(path.join("browser", "main.tsx"))) {
+        expect(code.match(/localStorage/gu), file.path).toHaveLength(1);
+        expect(code).toMatch(
+          /createLocalSidebarPreference\(\s*\(\(\) => \{\s*try \{\s*return window\.localStorage;/u,
+        );
+      } else {
+        expect(code, file.path).not.toContain("localStorage");
+      }
+    }
+    expect(writes).toEqual([
+      `${path.join("surfaces", "shell", "src", "browser", "sidebar-preference.ts")}: SIDEBAR_PREFERENCE_KEY, mode`,
+    ]);
+    // The files that ever hold the token touch no storage API at all.
+    for (const file of files.filter((candidate) =>
+      ["auth-protocol.ts", "ResetPasswordForm.tsx", "HostApp.tsx"].some((name) =>
+        candidate.path.endsWith(name),
+      ),
+    )) {
+      expect(withoutComments(file.text), file.path).not.toMatch(/\b(?:setItem|getItem|Storage)\b/u);
     }
   });
 });

core/tests/legacy-schema-definition.test.ts

@@ -0,0 +1,34 @@
+import { alias, getTableConfig, integer, pgTable } from "drizzle-orm/pg-core";
+import { describe, expect, it } from "vitest";
+import { parseModuleSchemaDefinition } from "../src/modules/legacy-schema-definition.js";
+
+describe("the legacy module schema definition", () => {
+  it("normalizes and freezes a typed schema definition without freezing its tables", () => {
+    const records = pgTable("example_records", { id: integer().primaryKey() });
+    const definition = parseModuleSchemaDefinition({
+      moduleId: "example",
+      tables: { records },
+    });
+
+    expect(definition.tables.records).toBe(records);
+    expect(getTableConfig(records).name).toBe("example_records");
+    expect(Object.isFrozen(definition)).toBe(true);
+    expect(Object.isFrozen(definition.tables)).toBe(true);
+    expect(Object.isFrozen(records)).toBe(false);
+  });
+
+  it("rejects malformed, empty, unknown, and non-PostgreSQL table definitions", () => {
+    const records = pgTable("example_records", { id: integer() });
+    const disguisedRecords = alias(records, "example_disguised_records");
+    expect(() => parseModuleSchemaDefinition({ moduleId: "example", tables: {} })).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { records: {} } }),
+    ).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { records }, extra: true }),
+    ).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { disguisedRecords } }),
+    ).toThrow();
+  });
+});

core/tests/module-configuration-lifecycle.test.ts

@@ -17,7 +17,7 @@ function fakeModule(
   } = {},
 ): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "1.0.0",

core/tests/module-configuration-store.integration.ts

@@ -194,7 +194,7 @@ afterAll(async () => {
 
 function manifestWith(configuration: readonly Record<string, unknown>[], id = "announcements") {
   return parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "1.0.0",

core/tests/module-configuration.test.ts

@@ -21,7 +21,7 @@ function manifestWith(
   id = "announcements",
 ) {
   return parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "1.0.0",
@@ -92,7 +92,7 @@ describe("module configuration declarations", () => {
 
   it("rejects two declarations of the same key, so an ordinary key and a secret can never collide", () => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -114,7 +114,7 @@ describe("module configuration declarations", () => {
 
   it("rejects a default on a secret, because a checked-in default credential is a leaked one", () => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -130,7 +130,7 @@ describe("module configuration declarations", () => {
 
   it("rejects a key that is both required and defaulted, which states an intent nothing can honour", () => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -169,7 +169,7 @@ describe("module configuration declarations", () => {
     ],
   ])("rejects %s", (_label, declaration) => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -189,7 +189,7 @@ describe("module configuration declarations", () => {
     "valueOf",
   ])("rejects the reserved object property name %s as a configuration key", (key) => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -210,7 +210,7 @@ describe("module configuration declarations", () => {
     "",
   ])("rejects the malformed configuration key %s", (key) => {
     const result = safeParseModuleManifest({
-      manifestVersion: 7,
+      manifestVersion: 8,
       id: "announcements",
       name: "announcements module",
       version: "1.0.0",
@@ -591,7 +591,7 @@ describe("configuration over a real discovered inventory", () => {
       writeFile(
         path.join(moduleDirectory, "ekklesia.module.json"),
         JSON.stringify({
-          manifestVersion: 7,
+          manifestVersion: 8,
           id,
           name: `${id} module`,
           version: "1.0.0",

core/tests/module-database-type.test.ts

@@ -1,8 +1,8 @@
 import { integer, pgTable, text } from "drizzle-orm/pg-core";
 import { describe, expect, it } from "vitest";
-import type { ModuleDatabase, ModuleRuntimeServices } from "../src/index.js";
+import type { LegacyModuleRuntimeServices, ModuleDatabase } from "../src/modules/database.js";
 
-const testTable = pgTable("contracts_module_database_test", {
+const testTable = pgTable("core_module_database_type_test", {
   id: integer("id").primaryKey(),
   name: text("name").notNull(),
 });
@@ -68,16 +68,17 @@ function typeOnlyExclusions(database: ModuleDatabase): void {
 }
 void typeOnlyExclusions;
 
-/** Never invoked — proves `ModuleRuntimeServices` has exactly one field, `database`, typed as
+/** Never invoked — proves a legacy module's `ModuleRuntimeServices` has exactly one field,
- * `ModuleDatabase`, with no storage/jobs/configuration/secrets/authorization field this phase. */
+ * `database`, typed as `ModuleDatabase`, with no storage/jobs/configuration/secrets/authorization
-function typeOnlyServicesShape(services: ModuleRuntimeServices): void {
+ * field this phase. */
+function typeOnlyServicesShape(services: LegacyModuleRuntimeServices): void {
   const database: ModuleDatabase = services.database;
   void database;
-  // @ts-expect-error `storage` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `storage` does not exist on the services yet.
   void services.storage;
-  // @ts-expect-error `jobs` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `jobs` does not exist on the services yet.
   void services.jobs;
-  // @ts-expect-error `authorization` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `authorization` does not exist on the services yet.
   void services.authorization;
 }
 void typeOnlyServicesShape;

core/tests/module-discovery.test.ts

@@ -4,8 +4,12 @@ import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
   discoverModules,
+  isReservedModuleId,
   ModuleDiscoveryError,
   type ModuleDiscoveryIssueCode,
+  RESERVED_MODULE_IDS,
+  RESERVED_SETTINGS_NAMES,
+  RESERVED_TOP_LEVEL_NAMES,
 } from "../src/modules/index.js";
 
 interface ModuleFixtureOptions {
@@ -34,7 +38,7 @@ async function createModulesDirectory(): Promise<string> {
 
 function manifestFor(id: string): Record<string, unknown> {
   return {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -271,6 +275,89 @@ describe("module discovery", () => {
     );
   });
 
+  it("rejects a module whose id is one of the platform's reserved top-level names (ADR 0057)", async () => {
+    // Every module with a Dashboard UI is addressed at `/<module-id>`, so an id equal to a
+    // platform-owned top-level namespace would collide with the API, the display host, a host
+    // script, or a Dashboard page.
+    expect(RESERVED_TOP_LEVEL_NAMES).toEqual(["account", "api", "assets", "display", "settings"]);
+    // A module's settings live at `/settings/<module-id>` (ADR 0061), beside the platform's own
+    // Settings sections, so their names are reserved too.
+    expect(RESERVED_SETTINGS_NAMES).toEqual([
+      "branding",
+      "discover",
+      "displays",
+      "general",
+      "system",
+    ]);
+    expect(RESERVED_MODULE_IDS).toEqual([
+      "account",
+      "api",
+      "assets",
+      "branding",
+      "discover",
+      "display",
+      "displays",
+      "general",
+      "settings",
+      "system",
+    ]);
+    for (const list of [RESERVED_MODULE_IDS, RESERVED_TOP_LEVEL_NAMES, RESERVED_SETTINGS_NAMES]) {
+      expect(Object.isFrozen(list)).toBe(true);
+    }
+
+    for (const id of RESERVED_MODULE_IDS) {
+      const modulesDirectory = await createModulesDirectory();
+      await createModule(modulesDirectory, id);
+
+      const error = await discoveryError(modulesDirectory);
+
+      expect(error.issues, id).toEqual([
+        expect.objectContaining({
+          code: "MODULE_ID_RESERVED",
+          moduleDirectory: id,
+          moduleId: id,
+          path: "id",
+        }),
+      ]);
+    }
+  });
+
+  it("accepts ids that merely resemble a reserved name", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    // `modules` is an ordinary id again: module management is Settings → Discover.
+    for (const id of [
+      "settings-sync",
+      "my-account",
+      "display-board",
+      "api-docs",
+      "general-info",
+      "modules",
+      "discovery",
+      "systems",
+    ]) {
+      await createModule(modulesDirectory, id);
+    }
+
+    const modules = await discoverModules({
+      moduleSdkVersion: "0.1.0",
+      modulesDirectory,
+      platformVersion: "0.1.0",
+    });
+
+    expect(modules.map((module) => module.manifest.id).sort()).toEqual([
+      "api-docs",
+      "discovery",
+      "display-board",
+      "general-info",
+      "modules",
+      "my-account",
+      "settings-sync",
+      "systems",
+    ]);
+    expect(isReservedModuleId("settings")).toBe(true);
+    expect(isReservedModuleId("settings-sync")).toBe(false);
+  });
+
   it("enforces platform and Module SDK compatibility", async () => {
     const modulesDirectory = await createModulesDirectory();
     await createModule(modulesDirectory, "future", {

core/tests/module-http-import.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { IMPORT_SAFETY_TEST_TIMEOUT_MS } from "./support/import-safety.js";
 
 const readdir = vi.fn();
 const readFile = vi.fn();
@@ -14,7 +15,9 @@ vi.mock("node:fs/promises", async (importOriginal) => ({
 }));
 
 describe("module HTTP contract and runtime import safety", () => {
-  it("performs no filesystem I/O merely by importing the module runtime or the module-http contract", async () => {
+  it(
+    "performs no filesystem I/O merely by importing the module runtime or the module-http contract",
+    async () => {
       await import("../src/modules/index.js");
       await import("@ekklesia/contracts");
 
@@ -22,5 +25,7 @@ describe("module HTTP contract and runtime import safety", () => {
       expect(readFile).not.toHaveBeenCalled();
       expect(realpath).not.toHaveBeenCalled();
       expect(stat).not.toHaveBeenCalled();
-  });
+    },
+    IMPORT_SAFETY_TEST_TIMEOUT_MS,
+  );
 });

core/tests/module-lifecycle-store.integration.ts

@@ -200,7 +200,7 @@ afterAll(async () => {
  * by eligibility resolution. */
 function fakeModule(id: string, dependencies?: Record<string, unknown>): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "1.0.0",

core/tests/module-lifecycle.test.ts

@@ -22,7 +22,7 @@ function fakeModule(
   } = {},
 ): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -344,7 +344,7 @@ describe("resolveModuleEligibility — over a real discovered inventory", () =>
       writeFile(
         path.join(moduleDirectory, "ekklesia.module.json"),
         JSON.stringify({
-          manifestVersion: 7,
+          manifestVersion: 8,
           id,
           name: `${id} module`,
           version: "0.1.0",

core/tests/module-migration-discovery.test.ts

@@ -35,9 +35,9 @@ async function createModulesDirectory(): Promise<string> {
 
 function discoveryOptions(modulesDirectory: string) {
   return {
-    moduleSdkVersion: "0.1.0",
+    moduleSdkVersion: "0.2.0",
     modulesDirectory,
-    platformVersion: "0.1.0",
+    platformVersion: "0.2.0",
   };
 }
 

core/tests/module-package-verification.test.ts

@@ -1,10 +1,12 @@
-import { mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import {
-  type ModulePackageVerificationErrorCode,
+  currentModulePackageHost,
+  type ModulePackageHost,
   ModulePackageVerificationError,
+  type ModulePackageVerificationErrorCode,
   verifyModulePackage,
 } from "../src/modules/index.js";
 import {
@@ -16,8 +18,8 @@ import {
 
 const platform = {
   databaseRuntime: { "drizzle-orm": "0.45.2" },
-  moduleSdkVersion: "0.1.2",
+  moduleSdkVersion: "0.2.0",
-  platformVersion: "0.1.2",
+  platformVersion: "0.2.0",
 } as const;
 
 const temporaryDirectories: string[] = [];
@@ -46,6 +48,12 @@ async function archiveFile(options: PackageFixtureOptions = {}): Promise<{
   return { archivePath, sha256: fixture.sha256 };
 }
 
+async function executionScratch(): Promise<string> {
+  const directory = path.join(await scratch(), "execution");
+  await mkdir(directory);
+  return directory;
+}
+
 async function rejection(
   options: PackageFixtureOptions,
   code: ModulePackageVerificationErrorCode,
@@ -72,25 +80,85 @@ function withEntry(entry: FixtureEntry): PackageFixtureOptions {
   return { extraEntries: [entry] };
 }
 
+function abiPackage(overrides: PackageFixtureOptions = {}): PackageFixtureOptions {
+  return {
+    manifest: (manifest) => ({ ...manifest, database: { abi: 1 } }),
+    schemaSource: `export default {
+      moduleId: "example",
+      tables: [{ name: "example_records", foreignKeys: [] }]
+    };\n`,
+    serverSource:
+      'export default { database: { abi: 1 }, id: "example", version: "0.1.0", register() {} };\n',
+    ...overrides,
+  };
+}
+
 describe("Module Package v1 verification (ADR 0049)", () => {
   it("verifies a valid any-target package, its digest, and its module", async () => {
     const { archivePath, sha256: digest } = await archiveFile();
     const result = await verifyModulePackage({ archivePath, expectedSha256: digest, platform });
     expect(result).toEqual({
       archiveSha256: digest,
-      fileCount: 8,
+      fileCount: 9,
       moduleId: "example",
       target: "any",
       version: "0.1.0",
     });
   });
 
+  it("uses an explicit execution scratch for pure JavaScript and cleans concurrent runs", async () => {
+    const { archivePath } = await archiveFile();
+    const executionScratchDirectory = await executionScratch();
+    const runs = Array.from({ length: 4 }, () =>
+      verifyModulePackage({ archivePath, executionScratchDirectory, platform }),
+    );
+    await expect(Promise.all(runs)).resolves.toHaveLength(4);
+    expect(await readdir(executionScratchDirectory)).toEqual([]);
+  });
+
+  it("cleans its execution scratch after a backend load failure", async () => {
+    const { archivePath } = await archiveFile({
+      serverSource:
+        'import "dependency-not-in-this-package";\nexport default { id: "example", version: "0.1.0" };\n',
+    });
+    const executionScratchDirectory = await executionScratch();
+    await expect(
+      verifyModulePackage({ archivePath, executionScratchDirectory, platform }),
+    ).rejects.toMatchObject({ code: "MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED" });
+    expect(await readdir(executionScratchDirectory)).toEqual([]);
+  });
+
+  it("reports a missing execution scratch as a verifier environment error", async () => {
+    const { archivePath } = await archiveFile();
+    const executionScratchDirectory = path.join(await scratch(), "missing");
+    await expect(
+      verifyModulePackage({ archivePath, executionScratchDirectory, platform }),
+    ).rejects.toMatchObject({
+      code: "MODULE_PACKAGE_VERIFIER_SCRATCH_UNAVAILABLE",
+      message:
+        "The verifier execution scratch directory is missing, not writable, or mounted noexec.",
+    });
+    await expect(stat(executionScratchDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("rejects an unsafe archive before consulting the execution scratch", async () => {
+    const { archivePath } = await archiveFile(
+      withEntry({ path: "example/../attacker-chosen", data: "x" }),
+    );
+    const executionScratchDirectory = path.join(await scratch(), "missing");
+    await expect(
+      verifyModulePackage({ archivePath, executionScratchDirectory, platform }),
+    ).rejects.toMatchObject({ code: "MODULE_PACKAGE_UNSAFE_PATH" });
+    await expect(stat(executionScratchDirectory)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
   it("extracts only a verified package, with normalized modes, into a new directory", async () => {
     const { archivePath } = await archiveFile();
     const target = path.join(await scratch(), "example");
     await verifyModulePackage({ archivePath, extractTo: target, platform });
     const names = (await readdir(target, { recursive: true })).sort();
     expect(names).toContain("ekklesia.package.json");
+    expect(names).toContain("LICENSE");
     expect(names).toContain("dist/server/index.js");
     expect((await stat(target)).mode & 0o7777).toBe(0o755);
     expect((await stat(path.join(target, "dist", "server", "index.js"))).mode & 0o7777).toBe(0o644);
@@ -140,6 +208,88 @@ describe("Module Package v1 verification (ADR 0049)", () => {
     );
   });
 
+  it.each([
+    ["a missing license declaration", undefined],
+    ["an empty license declaration", ""],
+    ["UNLICENSED", "UNLICENSED"],
+    ["a malformed SPDX expression", "MIT OR"],
+  ])("fails package metadata with %s", async (_label, license) => {
+    await rejection(
+      {
+        metadata: (metadata) => {
+          const changed: Record<string, unknown> = { ...metadata, license };
+          if (license === undefined) {
+            delete changed.license;
+          }
+          return changed;
+        },
+      },
+      "MODULE_PACKAGE_METADATA_INVALID",
+    );
+  });
+
+  it("fails closed on pre-ADR-0051 metadata", async () => {
+    await rejection(
+      {
+        metadata: (metadata) => {
+          const old: Record<string, unknown> = { ...metadata };
+          delete old.license;
+          return old;
+        },
+      },
+      "MODULE_PACKAGE_METADATA_INVALID",
+    );
+  });
+
+  it("requires LICENSE at the canonical path in both payload and inventory", async () => {
+    await rejection(
+      { tamper: (files) => void files.delete("LICENSE") },
+      "MODULE_PACKAGE_FILE_MISSING",
+    );
+    await rejection(
+      {
+        metadata: (metadata) => ({
+          ...metadata,
+          files: (metadata.files as { path: string }[]).filter((file) => file.path !== "LICENSE"),
+        }),
+      },
+      "MODULE_PACKAGE_METADATA_INVALID",
+    );
+    await rejection(
+      withEntry({ path: "example/licenses/LICENSE", data: "attacker-chosen" }),
+      "MODULE_PACKAGE_FILE_UNLISTED",
+    );
+    await rejection(
+      withEntry({ path: "example/COPYING", data: "attacker-chosen" }),
+      "MODULE_PACKAGE_FILE_UNLISTED",
+    );
+  });
+
+  it("checks the listed LICENSE bytes, size, and digest", async () => {
+    await rejection(
+      { tamper: (files) => files.set("LICENSE", Buffer.from("attacker-chosen")) },
+      "MODULE_PACKAGE_FILE_MISMATCH",
+    );
+    await rejection(
+      {
+        metadata: (metadata) => ({
+          ...metadata,
+          files: (metadata.files as { path: string; size: number; sha256: string }[]).map((file) =>
+            file.path === "LICENSE" ? { ...file, size: file.size + 1 } : file,
+          ),
+        }),
+      },
+      "MODULE_PACKAGE_FILE_MISMATCH",
+    );
+  });
+
+  it("rejects a duplicate LICENSE archive entry", async () => {
+    await rejection(
+      withEntry({ path: "example/LICENSE", data: "attacker-chosen" }),
+      "MODULE_PACKAGE_LAYOUT_INVALID",
+    );
+  });
+
   it("fails when the manifest and the package disagree about the version", async () => {
     await rejection(
       { manifest: (manifest) => ({ ...manifest, version: "0.2.0" }) },
@@ -214,13 +364,51 @@ describe("Module Package v1 verification (ADR 0049)", () => {
     });
   });
 
+  it("verifies ABI-v1 plain schema metadata without comparing Drizzle with Core", async () => {
+    const { archivePath } = await archiveFile(abiPackage());
+
+    await expect(
+      verifyModulePackage({
+        archivePath,
+        platform: { ...platform, databaseRuntime: { "drizzle-orm": "99.0.0" } },
+      }),
+    ).resolves.toMatchObject({ moduleId: "example" });
+  });
+
+  it("rejects transitional database runtime metadata from an ABI-v1 package", async () => {
+    await rejection(
+      abiPackage({
+        metadata: (metadata) => ({
+          ...metadata,
+          transitional: { databaseRuntime: { "drizzle-orm": "0.45.2" } },
+        }),
+      }),
+      "MODULE_PACKAGE_DATABASE_RUNTIME_UNEXPECTED",
+    );
+  });
+
+  it("rejects an unsupported database ABI and malformed ABI-v1 schema metadata", async () => {
+    await rejection(
+      abiPackage({ manifest: (manifest) => ({ ...manifest, database: { abi: 2 } }) }),
+      "MODULE_PACKAGE_MANIFEST_INVALID",
+    );
+    const schemaError = await rejection(
+      abiPackage({
+        schemaSource:
+          'export default { moduleId: "example", tables: { records: "attacker-chosen" } };\n',
+      }),
+      "MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED",
+    );
+    expect(schemaError.message).not.toContain("attacker-chosen");
+  });
+
   it("fails a target this platform cannot run", async () => {
     await rejection(
       {
         metadata: (metadata) => ({
           ...metadata,
           target: "linux-arm64-musl",
-          runtime: { node: ">=20", nodeApi: 9 },
+          runtime: { libcVersion: ">=1.2.0", node: ">=20", nodeApi: 9 },
         }),
       },
       "MODULE_PACKAGE_TARGET_INCOMPATIBLE",
@@ -359,6 +547,179 @@ describe("Module Package v1 verification (ADR 0049)", () => {
     });
   });
 
+  describe("native targets (ADR 0049)", () => {
+    /** The first bytes of a 64-bit little-endian ELF object for `machine` (62 is x86-64). The
+     * verifier reads only the identification and machine fields. */
+    function elfHeader(machine = 62): Buffer {
+      const header = Buffer.alloc(64);
+      Buffer.from([0x7f, 0x45, 0x4c, 0x46, 2, 1, 1]).copy(header);
+      header.writeUInt16LE(3, 16);
+      header.writeUInt16LE(machine, 18);
+      return header;
+    }
+
+    const linuxHost = {
+      arch: "x64",
+      libc: { family: "glibc", version: "2.41" },
+      nodeApi: 10,
+      nodeAbi: "137",
+      platform: "linux",
+    } as const;
+
+    function nativePackage(
+      overrides: {
+        readonly files?: Record<string, Uint8Array | string>;
+        readonly target?: string;
+        readonly runtime?: Record<string, unknown>;
+      } = {},
+    ): PackageFixtureOptions {
+      return {
+        files: overrides.files ?? {
+          "node_modules/native-thing/index.js": "module.exports = {};\n",
+          "node_modules/native-thing/lib/native-thing.node": elfHeader(),
+          "node_modules/native-thing/package.json": '{"name":"native-thing","version":"1.0.0"}\n',
+        },
+        metadata: (metadata) => ({
+          ...metadata,
+          runtime: overrides.runtime ?? {
+            libcVersion: ">=2.28.0",
+            node: ">=20",
+            nodeApi: 9,
+          },
+          target: overrides.target ?? "linux-x64-glibc",
+        }),
+      };
+    }
+
+    async function verifyOn(
+      options: PackageFixtureOptions,
+      host: ModulePackageHost,
+    ): Promise<unknown> {
+      const { archivePath } = await archiveFile(options);
+      return verifyModulePackage({ archivePath, platform: { ...platform, host } });
+    }
+
+    async function refusedOn(
+      options: PackageFixtureOptions,
+      host: ModulePackageHost,
+      code: ModulePackageVerificationErrorCode,
+    ): Promise<void> {
+      await expect(verifyOn(options, host)).rejects.toMatchObject({ code });
+    }
+
+    it("accepts linux-x64-glibc on a matching host, native node_modules and addon included", async () => {
+      await expect(verifyOn(nativePackage(), linuxHost)).resolves.toMatchObject({
+        moduleId: "example",
+        target: "linux-x64-glibc",
+      });
+    });
+
+    it("refuses another operating system, CPU, or C library family", async () => {
+      await refusedOn(
+        nativePackage(),
+        { ...linuxHost, platform: "darwin" },
+        "MODULE_PACKAGE_TARGET_INCOMPATIBLE",
+      );
+      await refusedOn(
+        nativePackage(),
+        { ...linuxHost, arch: "arm64" },
+        "MODULE_PACKAGE_TARGET_INCOMPATIBLE",
+      );
+      // musl reports no glibc version, so the host cannot be proven glibc.
+      const { libc: _libc, ...musl } = linuxHost;
+      await refusedOn(nativePackage(), musl, "MODULE_PACKAGE_TARGET_INCOMPATIBLE");
+    });
+
+    it("refuses a target this platform does not implement", async () => {
+      await refusedOn(
+        nativePackage({ target: "linux-arm64-glibc" }),
+        { ...linuxHost, arch: "arm64" },
+        "MODULE_PACKAGE_TARGET_INCOMPATIBLE",
+      );
+    });
+
+    it("refuses a C library older than the package needs", async () => {
+      await refusedOn(
+        nativePackage(),
+        { ...linuxHost, libc: { family: "glibc", version: "2.17" } },
+        "MODULE_PACKAGE_LIBC_INCOMPATIBLE",
+      );
+      await expect(
+        verifyOn(nativePackage(), { ...linuxHost, libc: { family: "glibc", version: "2.28" } }),
+      ).resolves.toMatchObject({ target: "linux-x64-glibc" });
+    });
+
+    it("refuses a Node-API version or Node.js ABI the host does not provide", async () => {
+      await refusedOn(
+        nativePackage(),
+        { ...linuxHost, nodeApi: 8 },
+        "MODULE_PACKAGE_NODE_API_INCOMPATIBLE",
+      );
+      const { nodeApi: _nodeApi, ...unknownApi } = linuxHost;
+      await refusedOn(nativePackage(), unknownApi, "MODULE_PACKAGE_NODE_API_INCOMPATIBLE");
+      await refusedOn(
+        nativePackage({ runtime: { libcVersion: ">=2.28.0", node: ">=20", nodeAbi: "115" } }),
+        linuxHost,
+        "MODULE_PACKAGE_NODE_API_INCOMPATIBLE",
+      );
+    });
+
+    it("refuses a native file built for another machine, or an addon that is not one", async () => {
+      await refusedOn(
+        nativePackage({
+          files: { "node_modules/native-thing/lib/native-thing.node": elfHeader(183) },
+        }),
+        linuxHost,
+        "MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE",
+      );
+      await refusedOn(
+        nativePackage({
+          files: { "node_modules/native-thing/lib/libthing.so": elfHeader(183) },
+        }),
+        linuxHost,
+        "MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE",
+      );
+      await refusedOn(
+        nativePackage({
+          files: { "node_modules/native-thing/lib/native-thing.node": "not an ELF object" },
+        }),
+        linuxHost,
+        "MODULE_PACKAGE_NATIVE_FILE_INCOMPATIBLE",
+      );
+    });
+
+    it("requires a native package to state its Node.js interface and, on Linux, its C library", async () => {
+      await rejection(
+        nativePackage({ runtime: { libcVersion: ">=2.28.0", node: ">=20" } }),
+        "MODULE_PACKAGE_METADATA_INVALID",
+      );
+      await rejection(
+        nativePackage({ runtime: { node: ">=20", nodeApi: 9 } }),
+        "MODULE_PACKAGE_METADATA_INVALID",
+      );
+    });
+
+    it("keeps any-target packages free of node_modules, addons, and ELF objects", async () => {
+      await rejection(
+        { files: { "node_modules/thing/index.js": "module.exports = {};\n" } },
+        "MODULE_PACKAGE_NATIVE_FILE",
+      );
+      await rejection({ files: { "dist/thing.node": elfHeader() } }, "MODULE_PACKAGE_NATIVE_FILE");
+      await rejection({ files: { "dist/libthing.so": elfHeader() } }, "MODULE_PACKAGE_NATIVE_FILE");
+    });
+
+    it("establishes this host's facts from Node.js alone", () => {
+      const host = currentModulePackageHost();
+      expect(host.platform).toBe(process.platform);
+      expect(host.arch).toBe(process.arch);
+      expect(host.nodeApi).toBe(Number(process.versions.napi));
+      if (process.platform === "linux") {
+        const report = process.report.getReport() as { header?: { glibcVersionRuntime?: string } };
+        expect(host.libc?.version).toBe(report.header?.glibcVersionRuntime);
+      }
+    });
+  });
+
   it("fails an archive without package metadata", async () => {
     const fixture = await modulePackageFixture();
     const { gunzipSync, gzipSync } = await import("node:zlib");

core/tests/module-permissions.test.ts

@@ -28,7 +28,7 @@ interface PermissionInput {
  * is read by `composePlatformPermissionRegistry`; the rest exist only to satisfy the type. */
 function fakeModule(id: string, permissions: readonly PermissionInput[] = []): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-realtime-runtime.test.ts

@@ -1,11 +1,8 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import type {
+import type { ModuleRealtimePublisher } from "@ekklesia/contracts";
-  ModuleDatabase,
+import type { LegacyModuleRuntimeServices, ModuleDatabase } from "../src/modules/database.js";
-  ModuleRealtimePublisher,
-  ModuleRuntimeServices,
-} from "@ekklesia/contracts";
 import { afterEach, describe, expect, it } from "vitest";
 import { ModuleRuntimeError, startModuleRuntime } from "../src/modules/runtime.js";
 
@@ -22,7 +19,7 @@ afterEach(async () => {
   );
 });
 
-function fakeServices(): ModuleRuntimeServices {
+function fakeServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as ModuleDatabase });
 }
 
@@ -31,7 +28,7 @@ function manifest(
   permissions: readonly Record<string, string>[] = [],
 ): Record<string, unknown> {
   return {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",

core/tests/module-runtime.test.ts

@@ -1,21 +1,23 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import type { ModuleConfiguration, ModuleDatabaseExecutor } from "@ekklesia/contracts";
 import type {
-  ModuleConfiguration,
+  AnyModuleRuntimeServices,
+  LegacyModuleRuntimeServices,
   ModuleDatabase,
-  ModuleRuntimeServices,
+} from "../src/modules/database.js";
-} from "@ekklesia/contracts";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { discoverModules } from "../src/modules/discovery.js";
-import { resolveModuleEligibility } from "../src/modules/lifecycle.js";
 import {
   ModuleDiscoveryError,
   ModuleRuntimeError,
   type ModuleRuntimeIssueCode,
+  type ModuleRuntimeServicesLookup,
   startDiscoveredModuleRuntime,
   startModuleRuntime,
 } from "../src/modules/index.js";
+import { resolveModuleEligibility } from "../src/modules/lifecycle.js";
 
 vi.mock("../src/modules/discovery.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../src/modules/discovery.js")>();
@@ -52,12 +54,13 @@ function manifestFor(
   id: string,
   options: {
     capabilities?: Array<{ id: string; version: string }>;
+    database?: { abi: 1 };
     dependencies?: Record<string, unknown>;
     permissions?: Array<{ id: string; baseline: string; description: string }>;
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -67,6 +70,7 @@ function manifestFor(
     },
     capabilities: options.capabilities ?? [],
     permissions: options.permissions ?? [],
+    ...(options.database ? { database: options.database } : {}),
     ...(options.dependencies ? { dependencies: options.dependencies } : {}),
     entrypoints: {
       server: "./dist/server/index.js",
@@ -145,13 +149,29 @@ function fakeModuleDatabase(): ModuleDatabase {
   }) as unknown as ModuleDatabase;
 }
 
-function fakeModuleRuntimeServices(): ModuleRuntimeServices {
+function fakeModuleRuntimeServices(): ModuleRuntimeServicesLookup {
-  return Object.freeze({ database: fakeModuleDatabase() });
+  const services = new Map<string, LegacyModuleRuntimeServices>();
+  const database = fakeModuleDatabase();
+  return new Proxy(services, {
+    get(target, property, receiver) {
+      if (property === "get") {
+        return (moduleId: string) => {
+          let value = target.get(moduleId);
+          if (!value) {
+            value = Object.freeze({ database });
+            target.set(moduleId, value);
+          }
+          return value;
+        };
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
 }
 
 function runtimeOptions(
   modulesDirectory: string,
-  services: ModuleRuntimeServices = fakeModuleRuntimeServices(),
+  services: ModuleRuntimeServicesLookup = fakeModuleRuntimeServices(),
 ) {
   return {
     moduleSdkVersion: "0.1.0",
@@ -1067,6 +1087,54 @@ describe("already-discovered module runtime", () => {
 });
 
 describe("module runtime services", () => {
+  it("delivers only the manifest-selected database mode and distinct ABI executors", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    const recorder = createReferenceRecorder();
+    const legacyDatabase = fakeModuleDatabase();
+    const alphaExecutor = Object.freeze({
+      abiVersion: 1,
+      query: vi.fn(),
+      transaction: vi.fn(),
+    }) as unknown as ModuleDatabaseExecutor;
+    const betaExecutor = Object.freeze({
+      abiVersion: 1,
+      query: vi.fn(),
+      transaction: vi.fn(),
+    }) as unknown as ModuleDatabaseExecutor;
+    const services: ModuleRuntimeServicesLookup = new Map<string, AnyModuleRuntimeServices>([
+      ["legacy", Object.freeze({ database: legacyDatabase })],
+      ["alpha", Object.freeze({ database: alphaExecutor })],
+      ["beta", Object.freeze({ database: betaExecutor })],
+    ]);
+    await createRuntimeModule(modulesDirectory, "legacy", {
+      serverSource: `export default { id: "legacy", version: "0.1.0", start({ services }) { ${recorder.expression}.push(services.database); } };`,
+    });
+    for (const id of ["alpha", "beta"]) {
+      await createRuntimeModule(modulesDirectory, id, {
+        manifest: manifestFor(id, { database: { abi: 1 } }),
+        serverSource: `export default { database: { abi: 1 }, id: ${JSON.stringify(id)}, version: "0.1.0", start({ services }) { ${recorder.expression}.push(services.database); } };`,
+      });
+    }
+
+    const runtime = await startModuleRuntime(runtimeOptions(modulesDirectory, services));
+
+    expect(recorder.values).toEqual([alphaExecutor, betaExecutor, legacyDatabase]);
+    expect("select" in alphaExecutor).toBe(false);
+    expect(alphaExecutor).not.toBe(betaExecutor);
+    await runtime.stop();
+  });
+
+  it("rejects a runtime database declaration that disagrees with its manifest", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createRuntimeModule(modulesDirectory, "mismatch", {
+      manifest: manifestFor("mismatch", { database: { abi: 1 } }),
+      serverSource: `export default { id: "mismatch", version: "0.1.0" };`,
+    });
+
+    const error = await captureRuntimeError(modulesDirectory);
+    expect(runtimeIssueCodes(error)).toContain("MODULE_RUNTIME_DATABASE_MISMATCH");
+  });
+
   it("never gives register a services field, and gives start and stop the exact same services object", async () => {
     const modulesDirectory = await createModulesDirectory();
     const services = fakeModuleRuntimeServices();
@@ -1086,11 +1154,11 @@ describe("module runtime services", () => {
 
     expect(registerServices.values).toEqual([undefined]);
     expect(lifecycleServices.values).toHaveLength(2);
-    expect(lifecycleServices.values[0]).toBe(services);
+    expect(lifecycleServices.values[0]).toBe(services.get("wired"));
-    expect(lifecycleServices.values[1]).toBe(services);
+    expect(lifecycleServices.values[1]).toBe(services.get("wired"));
   });
 
-  it("shares the exact same services object identity across every module's start hook", async () => {
+  it("selects a stable services object per module rather than sharing one across modules", async () => {
     const modulesDirectory = await createModulesDirectory();
     const services = fakeModuleRuntimeServices();
     const recorder = createReferenceRecorder();
@@ -1112,7 +1180,8 @@ describe("module runtime services", () => {
 
     const runtime = await startModuleRuntime(runtimeOptions(modulesDirectory, services));
 
-    expect(recorder.values).toEqual([services, services]);
+    expect(recorder.values).toEqual([services.get("alpha"), services.get("beta")]);
+    expect(recorder.values[0]).not.toBe(recorder.values[1]);
     await runtime.stop();
   });
 
@@ -1141,23 +1210,26 @@ describe("module runtime services", () => {
       startModuleRuntime(runtimeOptions(modulesDirectory, services)),
     ).rejects.toBeInstanceOf(ModuleRuntimeError);
 
-    expect(recorder.values).toEqual([services, services]);
+    expect(recorder.values).toEqual([services.get("started"), services.get("started")]);
   });
 
   it("starts and stops a zero-module runtime without ever touching the provided services", async () => {
     const modulesDirectory = await createModulesDirectory();
-    const services = fakeModuleRuntimeServices();
+    const database = fakeModuleDatabase();
+    const services: ModuleRuntimeServicesLookup = new Map([
+      ["unused", Object.freeze({ database })],
+    ]);
 
     const runtime = await startModuleRuntime(runtimeOptions(modulesDirectory, services));
     await runtime.stop();
 
     expect(runtime.modules).toEqual([]);
-    expect(vi.mocked(services.database.select)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.select)).not.toHaveBeenCalled();
-    expect(vi.mocked(services.database.insert)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.insert)).not.toHaveBeenCalled();
-    expect(vi.mocked(services.database.update)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.update)).not.toHaveBeenCalled();
-    expect(vi.mocked(services.database.delete)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.delete)).not.toHaveBeenCalled();
-    expect(vi.mocked(services.database.execute)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.execute)).not.toHaveBeenCalled();
-    expect(vi.mocked(services.database.transaction)).not.toHaveBeenCalled();
+    expect(vi.mocked(database.transaction)).not.toHaveBeenCalled();
   });
 });
 
@@ -1463,7 +1535,7 @@ describe("module configuration delivery (ADR 0029)", () => {
     expect(recorder.values).toEqual([["object", []]]);
   });
 
-  it("keeps the services object one shared identity even though configuration is per-module", async () => {
+  it("keeps each module's services object stable while configuration remains per-module", async () => {
     const modulesDirectory = await createModulesDirectory();
     const services = fakeModuleRuntimeServices();
     const recorder = createReferenceRecorder();
@@ -1492,11 +1564,11 @@ describe("module configuration delivery (ADR 0029)", () => {
     await runtime.stop();
 
     const [alphaServices, alphaConfig, bravoServices, bravoConfig] = recorder.values;
-    // This is the reason configuration is a sibling of `services` rather than a field inside it:
+    // Configuration remains a sibling of `services`: both are selected per module, but they are
-    // `services` is deliberately one shared object for the whole runtime, while configuration must
+    // independently composed snapshots with separate contracts and lifetimes.
-    // differ per module. Both properties hold simultaneously.
+    expect(alphaServices).toBe(services.get("alpha"));
-    expect(alphaServices).toBe(services);
+    expect(bravoServices).toBe(services.get("bravo"));
-    expect(bravoServices).toBe(services);
+    expect(alphaServices).not.toBe(bravoServices);
     expect(alphaConfig).not.toBe(bravoConfig);
     expect((alphaConfig as ModuleConfiguration).getString("label")).toBe("alpha");
     expect((bravoConfig as ModuleConfiguration).getString("label")).toBe("bravo");

core/tests/module-schema-discovery.test.ts

@@ -38,10 +38,14 @@ async function createModulesDirectory(): Promise<string> {
 
 function manifestFor(
   id: string,
-  options: { dependencies?: Record<string, unknown>; schema?: string | false } = {},
+  options: {
+    database?: { abi: 1 };
+    dependencies?: Record<string, unknown>;
+    schema?: string | false;
+  } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
@@ -49,6 +53,7 @@ function manifestFor(
     ...(options.dependencies ? { dependencies: options.dependencies } : {}),
     capabilities: [],
     permissions: [],
+    ...(options.database ? { database: options.database } : {}),
     entrypoints: {
       server: "./dist/server/index.js",
       ...(options.schema === false ? {} : { schema: options.schema ?? "./dist/schema/index.js" }),
@@ -126,6 +131,62 @@ function issueCodes(error: ModuleSchemaDiscoveryError): ModuleSchemaDiscoveryIss
 }
 
 describe("module schema discovery", () => {
+  it("loads ABI-v1 schema entrypoints as plain metadata without importing an ORM", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createSchemaModule(modulesDirectory, "calendar", {
+      manifest: manifestFor("calendar", { database: { abi: 1 } }),
+      schemaSource: `
+        export default {
+          moduleId: "calendar",
+          tables: [
+            { name: "calendar_events", foreignKeys: [] },
+            { name: "calendar_attendees", foreignKeys: [{ table: "calendar_events" }] }
+          ]
+        };
+      `,
+    });
+
+    const aggregate = await discoverModuleSchemas(discoveryOptions(modulesDirectory));
+
+    expect(aggregate.tables.map((table) => table.name)).toEqual([
+      "calendar_attendees",
+      "calendar_events",
+    ]);
+    expect(aggregate.tables.every((table) => table.table === undefined)).toBe(true);
+    expect(aggregate.drizzleSchema).toEqual({});
+  });
+
+  it("aggregates ABI-v1 prefix, duplicate, cross-module FK, missing target, and malformed errors", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createSchemaModule(modulesDirectory, "alpha", {
+      manifest: manifestFor("alpha", { database: { abi: 1 } }),
+      schemaSource: `export default {
+        moduleId: "alpha",
+        tables: [
+          { name: "wrong_records", foreignKeys: [] },
+          { name: "alpha_records", foreignKeys: [{ table: "beta_records" }] },
+          { name: "alpha_records", foreignKeys: [{ table: "alpha_missing" }] }
+        ]
+      };`,
+    });
+    await createSchemaModule(modulesDirectory, "malformed", {
+      manifest: manifestFor("malformed", { database: { abi: 1 } }),
+      schemaSource: `export default { moduleId: "malformed", tables: [{ name: "malformed_rows", unknown: true }] };`,
+    });
+
+    const error = await captureSchemaError(modulesDirectory);
+
+    expect(issueCodes(error)).toEqual(
+      expect.arrayContaining([
+        "MODULE_SCHEMA_CROSS_MODULE_FOREIGN_KEY",
+        "MODULE_SCHEMA_EXPORT_INVALID",
+        "MODULE_SCHEMA_FOREIGN_KEY_TARGET_MISSING",
+        "MODULE_SCHEMA_TABLE_DUPLICATE",
+        "MODULE_SCHEMA_TABLE_NAMESPACE_INVALID",
+      ]),
+    );
+  });
+
   it("returns a frozen empty aggregate without importing module servers", async () => {
     const modulesDirectory = await createModulesDirectory();
     const recorder = createGlobalEventRecorder();

core/tests/module-storage-lifecycle.test.ts

@@ -18,7 +18,7 @@ function fakeModule(
   } = {},
 ): DiscoveredModule {
   const manifest = parseModuleManifest({
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "1.0.0",

core/tests/module-storage.test.ts

@@ -1,5 +1,6 @@
 import {
   EMPTY_MODULE_STORAGE,
+  isModuleStorageError,
   isValidModuleStorageKey,
   MODULE_STORAGE_KEY_MAX_BYTES,
   MODULE_STORAGE_READ_URL_DEFAULT_SECONDS,
@@ -322,6 +323,17 @@ describe("module storage scoping", () => {
     }
   });
 
+  it("recognizes a storage error from an installed module's separate package copy", () => {
+    const external = Object.assign(new Error("The storage service could not be reached."), {
+      code: "STORAGE_PROVIDER_UNAVAILABLE",
+      name: "ModuleStorageError",
+    });
+
+    expect(external).not.toBeInstanceOf(ModuleStorageError);
+    expect(isModuleStorageError(external)).toBe(true);
+    expect(isModuleStorageError(Object.assign(new Error("no"), { code: "UNKNOWN" }))).toBe(false);
+  });
+
   it("gives a module no way to reach another module's storage by knowing its name", async () => {
     const shared = fakeProvider();
     const announcements = createModuleStorage({

core/tests/module-ui-publication.test.ts

@@ -79,7 +79,7 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         version: contribution.version,
       })),
       id: fixture.id,
-      manifestVersion: 7,
+      manifestVersion: 8,
       name: `${fixture.id} module`,
       permissions:
         fixture.display === undefined

core/tests/postgres-migration.integration.ts

@@ -1905,7 +1905,7 @@ describe.sequential("live PostgreSQL migration timeout precedence", () => {
 describe.sequential("live PostgreSQL retained history for an uninstalled module", () => {
   const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
   const templateModule = path.join(repositoryRoot, "templates", "module");
-  const versions = { moduleSdkVersion: "0.1.0", platformVersion: "0.1.0" } as const;
+  const versions = { moduleSdkVersion: "0.2.0", platformVersion: "0.2.0" } as const;
 
   async function coreWithoutNewestMigration(directory: string): Promise<string> {
     const target = path.join(directory, "core-drizzle");

core/tests/support/import-safety.ts

@@ -0,0 +1,19 @@
+/**
+ * The per-test timeout for Core's import-safety tests, and only those.
+ *
+ * Each of these tests proves that importing a module does nothing (no I/O, no connection, no output)
+ * by performing a cold dynamic `import()` of a large Core source graph inside the test body. Vitest
+ * transforms and evaluates that whole graph on demand, and that work is CPU-bound. An ordinary test
+ * file's own top-level imports run before its tests start and fall under no per-test timeout; these
+ * deliberately do not, so the cost lands inside Vitest's default 5-second test timeout.
+ *
+ * Alone they take about 0.7–1.2 s. During a full `pnpm verify`, Turbo runs every package's suite at
+ * once and the CPU is saturated. Reproduced locally (six cores, Core's suite alongside five other
+ * packages' suites), the same tests took 3.0–5.4 s, and so timed out intermittently.
+ *
+ * 30 seconds is about five times the slowest time measured under load, which leaves room for slower
+ * shared CI runners. It matches the repository's integration-test timeout. It is still bounded, so a
+ * module that genuinely hangs while being imported, for example on a network call, still fails. The
+ * assertions themselves are unchanged: these tests fail on what an import does, never on speed.
+ */
+export const IMPORT_SAFETY_TEST_TIMEOUT_MS = 30_000;

core/tests/support/migration-module-fixture.ts

@@ -50,11 +50,11 @@ export function manifestFor(
   } = {},
 ): Record<string, unknown> {
   return {
-    manifestVersion: 7,
+    manifestVersion: 8,
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     ...(options.dependencies ? { dependencies: options.dependencies } : {}),
     capabilities: [],
     permissions: [],

core/tests/support/module-package-fixture.ts

@@ -86,6 +86,7 @@ export interface PackageFixtureOptions {
   readonly id?: string;
   readonly version?: string;
   readonly serverSource?: string;
+  readonly schemaSource?: string;
   readonly manifest?: (manifest: Record<string, unknown>) => Record<string, unknown>;
   readonly runtimePackage?: Record<string, unknown>;
   readonly metadata?: (metadata: Record<string, unknown>) => Record<string, unknown>;
@@ -93,6 +94,8 @@ export interface PackageFixtureOptions {
   readonly tamper?: (files: Map<string, Buffer>) => void;
   /** Entries appended after the package's own, under any path. */
   readonly extraEntries?: readonly FixtureEntry[];
+  /** Extra payload files, listed in the metadata like every other file. */
+  readonly files?: Readonly<Record<string, Uint8Array | string>>;
 }
 
 export interface PackageFixture {
@@ -125,6 +128,7 @@ export async function modulePackageFixture(
   let files: Map<string, Buffer>;
   try {
     const created = await createMigrationModule(scratch, id, {
+      ...(options.schemaSource === undefined ? {} : { schemaSource: options.schemaSource }),
       serverSource:
         options.serverSource ??
         `export default { id: ${JSON.stringify(id)}, version: ${JSON.stringify(version)}, register() {} };\n`,
@@ -160,6 +164,10 @@ export async function modulePackageFixture(
     ),
   );
   files.set("THIRD_PARTY_NOTICES", Buffer.from("No third-party software is included.\n"));
+  files.set("LICENSE", Buffer.from("Example module license text.\n"));
+  for (const [filePath, data] of Object.entries(options.files ?? {})) {
+    files.set(filePath, Buffer.from(data));
+  }
 
   const listed = [...files.entries()]
     .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
@@ -167,13 +175,14 @@ export async function modulePackageFixture(
   const baseMetadata: Record<string, unknown> = {
     packageFormat: 1,
     module: { id, version },
+    license: "MIT",
     target: "any",
     runtime: { node: ">=20" },
     provenance: {
       revision: "86ae907f59458508e3277666cdd214f5bd7c1078",
-      packager: { name: "@ekklesia/module-pack", version: "0.1.2" },
+      packager: { name: "@ekklesia/module-pack", version: "0.2.0" },
     },
-    incorporates: { "@ekklesia/module-sdk": "0.1.2" },
+    incorporates: { "@ekklesia/module-sdk": "0.2.0" },
     files: listed,
   };
   const metadata = options.metadata ? options.metadata(baseMetadata) : baseMetadata;

core/tests/verify-module-package-cli.test.ts

@@ -3,6 +3,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import {
+  MODULE_VERIFIER_SCRATCH_ENV,
+  moduleVerifierScratchDirectory,
   parseSha256File,
   parseVerifyModulePackageArguments,
   readModulePackagePlatform,
@@ -57,6 +59,21 @@ describe("verify-module-package digest files", () => {
   });
 });
 
+describe("verify-module-package execution scratch", () => {
+  it("accepts an absolute operator-configured directory and otherwise leaves the library default", () => {
+    expect(moduleVerifierScratchDirectory({})).toBeUndefined();
+    expect(
+      moduleVerifierScratchDirectory({ [MODULE_VERIFIER_SCRATCH_ENV]: "/run/ekklesia-verifier" }),
+    ).toBe("/run/ekklesia-verifier");
+  });
+
+  it.each(["", "relative/path"])("refuses the invalid configured path %j", (configured) => {
+    expect(() =>
+      moduleVerifierScratchDirectory({ [MODULE_VERIFIER_SCRATCH_ENV]: configured }),
+    ).toThrow(`${MODULE_VERIFIER_SCRATCH_ENV} must be an absolute path.`);
+  });
+});
+
 describe("verify-module-package platform facts", () => {
   it("reads this platform's versions and its transitional database runtime from the repository", async () => {
     const root = JSON.parse(await readFile(path.join(repositoryRoot, "package.json"), "utf8"));

core/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../packages/typescript-config/node.json",
   "compilerOptions": {
     "noEmit": true,
-    "types": ["node", "vitest/globals"]
+    "types": ["node", "vitest/globals"],
+    "rewriteRelativeImportExtensions": true
   },
   "include": [
     "drizzle.config.ts",

deploy/Caddyfile.example

@@ -42,9 +42,16 @@
 
 {$EKKLESIA_HOSTNAME} {
 	# Everything the API serves: the Dashboard at /, the API, display pages and their service
-	# worker, and the Dashboard and display host scripts. Any other path is refused here.
+	# worker, and the Dashboard and display host scripts.
 	@ekklesia path / /api/* /display/* /assets/*
 
+	# The Dashboard's other pages (ADR 0057): its own Settings and account pages, and each installed
+	# module's page at /<module-id> (/signage, and later /signage/timelines), so a refreshed deep link
+	# stays put. Module ids are installation-specific, so this forwards every top-level name shaped
+	# like one and the API decides: the Dashboard page where one exists, its sanitized 404 elsewhere.
+	# Any other path is refused here.
+	@dashboardPage path_regexp dashboardPage ^/[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:/.*)?$
+
 	# Module realtime is Server-Sent Events: flush every event immediately.
 	@realtime path /api/v1/module-realtime/*
 
@@ -63,6 +70,12 @@
 		}
 	}
 
+	handle @dashboardPage {
+		reverse_proxy api:3000 {
+			import ekklesia_forwarding
+		}
+	}
+
 	handle {
 		respond 404
 	}

deploy/Caddyfile.split.example

@@ -51,12 +51,28 @@
 {$EKKLESIA_DASHBOARD_HOSTNAME} {
 	@dashboard path / /assets/ekklesia-dashboard/*
 
+	# The Dashboard's other pages (ADR 0057): its own Settings and account pages, and each installed
+	# module's page at /<module-id> (/signage, and later /signage/timelines), so a refreshed deep link
+	# stays put. Module ids are installation-specific, so this forwards every top-level name shaped
+	# like one and the API decides: the Dashboard page where one exists, its sanitized 404 elsewhere.
+	# The API's own namespaces stay refused on this hostname.
+	@dashboardPage {
+		path_regexp dashboardPage ^/[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:/.*)?$
+		not path /api /api/* /display /display/* /assets /assets/*
+	}
+
 	handle @dashboard {
 		reverse_proxy api:3000 {
 			import ekklesia_forwarding
 		}
 	}
 
+	handle @dashboardPage {
+		reverse_proxy api:3000 {
+			import ekklesia_forwarding
+		}
+	}
+
 	handle {
 		respond 404
 	}

deploy/README.md

@@ -17,6 +17,7 @@ specific to one organization.
 | [`scripts/init-tls.sh`](scripts/init-tls.sh) | Creates the installation-private CA and the `postgres` and `object-storage` server certificates. |
 | [`scripts/gen-secrets.sh`](scripts/gen-secrets.sh) | Prints freshly generated secrets to paste into the env files. Writes nothing. |
 | [`Dockerfile`](Dockerfile) | The one production image, for the API and every operator command ([The production image](#the-production-image)). |
+| [`display-kiosk.md`](display-kiosk.md) | Setting up an unattended display screen: launch, pairing, and recovery. |
 
 ## The reference deployment
 
@@ -170,9 +171,20 @@ identity, target, and Node.js range against this platform, runs the platform's m
 validation, and loads the backend once in a short-lived process with no environment. Only then does
 it write the verified module directory, to a new directory outside module storage:
 
+The backend probe executes the package's server-side code; the verifier container is its isolation
+boundary. Keep the general-purpose `/tmp` mount `noexec`, and give only this one-shot verifier a
+separate executable scratch tmpfs. The mount below is ephemeral, bounded at 1100 MiB (just above the
+package format's 1 GiB expanded limit), `nodev`, `nosuid`, and writable only by the image's
+unprivileged `node` user. `EKKLESIA_MODULE_VERIFIER_SCRATCH_DIR` tells the CLI where that mount is;
+the verifier creates a unique child for each run and removes it on success or failure.
+
 ```sh
 mkdir -m 777 staging        # writable by the image's unprivileged user; nothing else is
-docker run --rm --network none --read-only --tmpfs /tmp \
+docker run --rm --network none --read-only \
+  --tmpfs /tmp:rw,nosuid,nodev,noexec,size=64m \
+  --tmpfs /run/ekklesia-verifier:rw,nosuid,nodev,exec,size=1100m,mode=0700,uid=1000,gid=1000 \
+  --cap-drop ALL --security-opt no-new-privileges \
+  -e EKKLESIA_MODULE_VERIFIER_SCRATCH_DIR=/run/ekklesia-verifier \
   -v "$PWD:/package:ro" -v "$PWD/staging:/staging" \
   --entrypoint node "$EKKLESIA_IMAGE" core/dist/cli/verify-module-package.js \
   /package/<id>-<version>-any.tar.gz --sha256-file /package/<id>-<version>-any.tar.gz.sha256 \
@@ -229,6 +241,14 @@ Module storage is installation state: back it up with the database and the bucke
    `docker compose run --rm migrate node core/dist/cli/apply-migrations.js`.
 5. **Restart on the new image:** `docker compose -f compose.yaml -f compose.proxy.yaml up -d --wait`.
 
+**Upgrading to a release with Dashboard page addresses (ADR 0057):** compare your `Caddyfile` with
+the new `Caddyfile.example` (or `Caddyfile.split.example`). Each gains a `@dashboardPage` matcher
+and `handle` block that forward every top-level path shaped like a module id — `/settings`,
+`/account`, and each installed module's page such as `/signage` — to the API, which answers with
+the Dashboard page where one exists and its sanitized `404` elsewhere. Without it the Dashboard still
+opens at `/`, but refreshing or bookmarking any other Dashboard page is the proxy's `404`. Reload the
+proxy after editing it. Installing or removing a module needs no proxy change.
+
 ### Rolling back
 
 Set `EKKLESIA_IMAGE` back to the previous tag and run `up -d --wait` again. That is enough only when
@@ -251,7 +271,7 @@ The same image serves both; only configuration differs.
 
 | Hostname | Serves | Refuses (`404`) |
 | --- | --- | --- |
-| Dashboard (`EKKLESIA_DASHBOARD_HOSTNAME`) | `/` and `/assets/ekklesia-dashboard/*` | everything else, including `/api/*` |
+| Dashboard (`EKKLESIA_DASHBOARD_HOSTNAME`) | `/`, `/assets/ekklesia-dashboard/*`, and every module-shaped top-level path (the Dashboard's pages, such as `/settings` and `/signage`; the API answers the rest with its `404`) | everything else, including `/api/*`, `/display/*`, and `/assets/*` |
 | API (`EKKLESIA_HOSTNAME`) | `/api/*`, `/display/*`, `/assets/ekklesia-display/*` | everything else, including `/` |
 | Storage (`EKKLESIA_STORAGE_HOSTNAME`) | signed object URLs, unchanged | |
 
@@ -327,7 +347,11 @@ networks:
 
 Then make your proxy do what `Caddyfile.example` does:
 
-- forward `/`, `/api/*`, `/display/*`, and `/assets/*` on the Ekklesia hostname to `api:3000`;
+- forward `/`, `/api/*`, `/display/*`, and `/assets/*` on the Ekklesia hostname to `api:3000`,
+  and every path whose first segment is shaped like a module id, `^/[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:/.*)?$` (ADR 0057): that is
+  `/settings`, `/account`, and each installed module's page such as `/signage`, and the API answers
+  anything that is not a real page with its sanitized `404`. Without it, refreshing any Dashboard page
+  other than `/` is your proxy's `404`. Do not list module ids: they change as modules are installed;
 - **overwrite** `X-Forwarded-For` with the one client address it resolved, and strip
   `CF-Connecting-IP`, `X-Real-IP`, `Forwarded`, and `True-Client-IP`;
 - stream responses on `/api/v1/module-realtime/*` without buffering (Server-Sent Events);
@@ -393,7 +417,7 @@ deployment:
 
 | # | Item | Where it is met |
 | --- | --- | --- |
-| 1 | The proxy forwards the Dashboard and `/api` on the intended origin | `Caddyfile.example` routes `/`, `/api/*`, `/display/*`, `/assets/*` on one hostname to `api`; the API serves the Dashboard itself. In the split topology, `Caddyfile.split.example` gives each hostname exactly its own paths and the exact trusted-origin CORS of ADR 0045 covers the rest. |
+| 1 | The proxy forwards the Dashboard and `/api` on the intended origin | `Caddyfile.example` routes `/`, `/api/*`, `/display/*`, `/assets/*`, and every module-shaped top-level path (the Dashboard's pages) on one hostname to `api`; the API serves the Dashboard itself. In the split topology, `Caddyfile.split.example` gives each hostname exactly its own paths and the exact trusted-origin CORS of ADR 0045 covers the rest. |
 | 2 | The origin port is unreachable from the Internet | The base publishes no port; only `proxy` publishes 80 and 443. |
 | 3 | The origin port is unreachable from untrusted networks | `api` is reachable only on Docker networks; `EKKLESIA_PUBLISH_ADDRESS` limits the proxy to one interface. Firewall the host itself. |
 | 4 | The proxy overwrites the trusted client-IP header | `header_up X-Forwarded-For {client_ip}` in `Caddyfile.example`. |
@@ -500,10 +524,10 @@ finds its files:
 ```sh
 docker build \
   --file deploy/Dockerfile \
-  --build-arg VERSION=0.1.2 \
+  --build-arg VERSION=0.2.5 \
   --build-arg REVISION="$(git rev-parse HEAD)" \
   --build-arg SOURCE=https://git.example.org/your-org/ekklesia \
-  --tag ekklesia:0.1.2 \
+  --tag ekklesia:0.2.5 \
   .
 ```
 

deploy/compose.yaml

@@ -132,6 +132,10 @@ services:
     command:
       - mini
       - -dir=/data
+      # A bucket is a SeaweedFS collection and claims a block of volumes. The ~1 GB automatic
+      # volume size leaves modest hosts with room for only a few collections; after that, writes
+      # stall instead of failing. This changes allocation granularity, not object or total capacity.
+      - -master.volumeSizeLimitMB=32
       - -s3.port.https=8443
       - -s3.cert.file=/run/ekklesia/tls/object-storage.crt
       - -s3.key.file=/run/ekklesia/tls/object-storage.key

deploy/display-kiosk.md

@@ -0,0 +1,130 @@
+# Setting up a display kiosk
+
+A display is a screen — a television with a small computer, or a mini PC on a wall — that opens one
+module's display page full screen and keeps it open unattended. This guide sets one up so it starts
+on boot, stays paired, recovers from network and server outages on its own, and never opens a second
+copy of itself.
+
+Pairing and display identity belong to the platform (ADR 0036). Today an administrator approves a
+screen in the Dashboard sidebar's **Display devices** panel; a later release moves this to
+**Settings → Displays**. Nothing below changes when that happens.
+
+## What the screen needs
+
+- Chromium or Google Chrome, current stable. The display page is tested against Chromium.
+- A **dedicated, persistent browser profile directory**. The device credential is an HttpOnly cookie
+  in that profile; it is what keeps the screen paired across reboots. Never use a guest, incognito, or
+  "clear data on exit" profile, and never share the profile with a person's browsing.
+- Network access to the installation's **API hostname** (the display page, its realtime stream, and
+  its module requests) and to the storage hostname that serves images.
+- A clock that is roughly right. Playback follows the server's clock, but TLS does not tolerate a
+  wildly wrong one.
+
+## The address
+
+Every display-capable module has one display page on the API hostname:
+
+```text
+https://<api-hostname>/display/<module-id>
+```
+
+For Signage that is `https://<api-hostname>/display/signage`. The Signage **Displays** tab shows the
+exact address under **Copy setup address**. Open it on the screen itself; opening it on an
+administrator's own computer only previews the display (and that browser appears in the roster as a
+*Signed-in browser*, which can be removed once it is offline).
+
+## Launching the browser
+
+Run exactly **one** launcher, and launch the page as an app window with a fixed profile:
+
+```bash
+chromium \
+  --user-data-dir=/var/lib/display-kiosk/profile \
+  --app=https://<api-hostname>/display/signage \
+  --kiosk \
+  --no-first-run \
+  --noerrdialogs \
+  --disable-session-crashed-bubble \
+  --hide-crash-restore-bubble \
+  --disable-features=Translate \
+  --autoplay-policy=no-user-gesture-required \
+  --check-for-update-interval=31536000
+```
+
+- `--app` opens the page with no tab strip and no address bar. `--kiosk` makes it full screen.
+- `--user-data-dir` is the persistent profile that holds the pairing. Keep it on persistent storage
+  and back it up with nothing: if it is lost, the screen simply shows a new pairing code.
+- Do **not** add `--restore-last-session`, and do not also start the browser from a desktop autostart
+  entry. Chromium allows one process per profile; a second launch hands its URL to the running
+  process, which opens a **second window or tab** of the display. That is the usual cause of
+  "duplicate" displays. One launcher, one profile, one window.
+
+### Start on boot and restart on exit (systemd)
+
+Run the browser as an unprivileged user in that user's graphical session, from a single user unit:
+
+```ini
+# ~/.config/systemd/user/display-kiosk.service
+[Unit]
+Description=Display kiosk
+After=graphical-session.target network-online.target
+Wants=network-online.target
+PartOf=graphical-session.target
+
+[Service]
+ExecStart=/usr/bin/chromium --user-data-dir=%h/.local/share/display-kiosk --app=https://<api-hostname>/display/signage --kiosk --no-first-run --noerrdialogs --disable-session-crashed-bubble --hide-crash-restore-bubble --disable-features=Translate --autoplay-policy=no-user-gesture-required --check-for-update-interval=31536000
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=graphical-session.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now display-kiosk.service
+loginctl enable-linger <kiosk-user>   # with the desktop set to log this user in automatically
+```
+
+`systemctl --user stop display-kiosk` closes the browser cleanly, which is what keeps its profile —
+and the pairing cookie — intact. Avoid cutting power to a running kiosk when you can: a clean shutdown
+is always safer for a browser profile.
+
+## Pairing
+
+1. Start the kiosk. With no credential it shows a **six-digit pairing code**.
+2. In the Dashboard, enter the code under **Display devices**, give the screen a name, and approve.
+3. Within a few seconds the screen collects its credential and starts showing content.
+4. In Signage → **Displays**, name the display and choose its group and audience.
+
+A paired screen stays paired across browser restarts and reboots, and for as long as it is in use:
+its credential is renewed each time it checks in, and only expires after **180 days without being
+used** (ADR 0056). A screen that is switched off and stored for longer than that, or that is revoked,
+returns to its pairing code and is paired again the same way.
+
+## What happens when things go wrong
+
+| Event | What the screen does |
+| --- | --- |
+| Network drops for seconds | Nothing visible. The display keeps running; the realtime stream reconnects. |
+| Network or API down for longer | Keeps playing what it has cached, with a small corner note; recovers by itself when the server is back. No remount, no reload. |
+| API restarted or upgraded | Reconnects by itself. A new module version is picked up within five minutes and swapped in. |
+| Browser crashes or is restarted | systemd restarts it; the same profile is still paired. |
+| Machine reboots | Starts on boot and resumes. If the server is not up yet, the screen retries on its own (every few seconds, backing off to once a minute) until it is. |
+| Display revoked in the Dashboard | Stops showing content within seconds and returns to its pairing code. |
+| Display moved to another group or audience | Switches content within about one heartbeat (≈12 s), no reload. |
+
+**Offline cold start is not supported yet.** A screen that is already showing content survives an
+outage. A screen that *boots* while the server is completely unreachable can load its cached page but
+cannot mount the module until the server answers, because the authorization it needs is never cached
+(ADR 0043, Signage ADR 0006). It shows a short message and retries on its own until the server is
+reachable — nobody needs to touch it.
+
+## Checklist for a new kiosk
+
+- [ ] One systemd unit, no desktop autostart entry, no second launcher.
+- [ ] `--user-data-dir` on persistent storage, not shared, not cleared on exit.
+- [ ] Automatic login of the kiosk user, and screen blanking/power saving disabled.
+- [ ] Paired and named; assigned in Signage.
+- [ ] Unplug the network for a minute: content keeps playing, then the note clears on reconnect.
+- [ ] Reboot: the screen comes back paired without anyone touching it.

docs/architecture/decisions/0026-minimal-ekklesia-module-ui-host.md

@@ -267,6 +267,8 @@ to follow — and the API never builds frontend source at run time.
   and its only allowed build script, and a second toolchain buys HMR that a proof does not need.
 - **A client router.** Rejected: a selected-module state is sufficient, and host routing versus
   module routing is a design this pass should not settle by accident.
+  > **Cross-reference — see [ADR 0057](0057-dashboard-urls-are-host-owned-routes.md).** The Dashboard
+  > now has host-owned URL routing; module routing remains a separate, deferred decision.
 - **`react-router-dom`.** Rejected outright — modules are denied it precisely because routing belongs
   to the host, and adopting it here for a two-item selector would prejudge that design.
 - **Clearing the container between selections instead of keying the frame.** Rejected: it leaves one

docs/architecture/decisions/0027-dashboard-navigation-and-flat-modules.md

@@ -255,6 +255,10 @@ that is unremarkable, and it is measured work rather than hidden.
 
 ## Deferred
 
+> **Cross-reference — see [ADR 0057](0057-dashboard-urls-are-host-owned-routes.md).** Client-side
+> routing and deep links to a selected module, deferred below, have landed; the rest of this list is
+> unchanged.
+
 Not implemented or promised here: the navigation **editor** — drag and drop, a management UI, and any
 administrator-facing affordance beyond the API; nested folders and subgroups; icons, colors, badges,
 and module descriptions in navigation; `suggestedGroup` and any configuration-initialization or

docs/architecture/decisions/0034-host-owned-browser-authentication.md

@@ -165,6 +165,10 @@ redirect target.
 A future client router may define an internal return-location contract, but it must be a separately
 validated, same-origin route decision. This pass does not create one speculatively.
 
+> **Cross-reference — see [ADR 0057](0057-dashboard-urls-are-host-owned-routes.md).** The Dashboard
+> now has a host-owned router. It adds no return-location contract: sign-in still happens in place at
+> the current URL, which is now a real page address.
+
 ### Cookie and origin policy does not broaden for the Dashboard
 
 The session cookie keeps the identity platform's existing properties: HttpOnly, SameSite=Lax,

docs/architecture/decisions/0036-managed-device-identity-and-pairing.md

@@ -2,6 +2,7 @@
 
 - Status: Accepted
 - Date: 2026-08-24
+- Session lifetime superseded by: [0056](0056-device-credentials-last-while-in-use.md)
 - Extends: [0013](0013-core-authorization-and-owner-bootstrap.md),
   [0032](0032-native-module-realtime-transport.md),
   [0033](0033-display-kiosk-host-contract.md),

docs/architecture/decisions/0039-shared-design-tokens-and-elements.md

@@ -151,6 +151,10 @@ reaching into the artifact or the artifact importing the host.
 
 ## Deferred
 
+> **Cross-reference — see [ADR 0060](0060-light-dark-system-theme-and-motion.md).** A dark theme,
+> System appearance, reduced motion, and a radius scale have landed; ADR 0059 added the focus-trap
+> utility. The rest of this list is unchanged.
+
 A theme editor, a brand builder, per-installation persisted overrides, a dark theme or any second
 theme, density modes, an icon set, charting, layout primitives beyond what the elements need, a
 documentation site, and a focus-trap utility.

docs/architecture/decisions/0051-module-package-license-material.md

@@ -0,0 +1,207 @@
+# 0051: Module packages declare their own license and carry its text
+
+- Status: Accepted
+- Date: 2026-10-07
+- Amends: [0049](0049-module-package-v1.md) — every Module Package v1 artifact gains an
+  authoritative package-level license declaration and a `LICENSE` payload. `packageFormat` stays 1.
+- Related: [the repository license](../../../README.md#license),
+  [ADR 0048](0048-generic-image-and-installed-module-storage.md),
+  [ADR 0050](0050-module-database-abi-v1.md)
+
+## Context
+
+ADR 0049 makes a module release one immutable, self-contained package and already requires
+`THIRD_PARTY_NOTICES` for code bundled from third-party dependencies. It deliberately says that no
+package is a distributable release until license and notice collection is proven. The implemented
+packager now generates those notices from the dependency code it actually bundles, but Module
+Package v1 still does not declare the module's own license or carry the module's license text.
+
+Those are different obligations. `THIRD_PARTY_NOTICES` excludes both the module itself and bundled
+Ekklesia-owned packages. The source module's development `package.json` is not copied into the
+package: the packager generates a minimal runtime `package.json` instead. Consequently, an archive
+can preserve every third-party notice and still lose the authoritative declaration and text for the
+work being distributed.
+
+The repository and its workspace packages declare `AGPL-3.0-or-later`, and the repository carries
+the GNU AGPL version 3 text in `LICENSE`. The canonical module template also declares
+`AGPL-3.0-or-later` in its source `package.json`. Official Ekklesia modules use that license today,
+but a packager cannot assume that every module has the platform's license. A module release must say
+what license its own publisher actually declared and must carry the corresponding material.
+
+The current `ekklesia.package.json` contract is strict: a reader refuses unknown fields. Adding a
+required field therefore makes pre-change and post-change readers reject one another's artifacts.
+That is intentional here, not a reason for `packageFormat: 2`. ADR 0049 has not admitted a
+distributable v1 release without proven license handling; this decision completes that still-open v1
+requirement before real modules are distributed. The packager and verifier must adopt the tightening
+together, and strict readers fail closed during that cutover rather than silently misreading a
+package.
+
+## Decision
+
+### The package declares the module's own license once
+
+Every Module Package v1 `ekklesia.package.json` has a required top-level `license` field containing
+the module's SPDX license expression:
+
+```json
+{
+  "packageFormat": 1,
+  "module": { "id": "example", "version": "0.1.0" },
+  "license": "AGPL-3.0-or-later"
+}
+```
+
+`ekklesia.package.json.license` is the authoritative package-release declaration. The expression is
+not repeated in `ekklesia.module.json` or in the generated runtime `package.json`. The module's
+source `package.json` is a packaging input, not release metadata inside the finished artifact.
+
+The source module must explicitly declare its license in its own project metadata. The canonical
+packager reads the normal string `license` field from the source module's `package.json`, validates
+it as a supported SPDX license expression, and preserves that declaration in
+`ekklesia.package.json`. It refuses a missing, empty, `UNLICENSED`, legacy object-shaped, malformed,
+or unsupported declaration. It never substitutes the Ekklesia platform's license and does not try
+to decide whether a publisher chose an appropriate license.
+
+For official Ekklesia modules today the declaration is `AGPL-3.0-or-later`, matching the repository
+license. This is a fact about those modules, not a default the packager invents for other modules.
+
+### The package carries the applicable license material
+
+Every distributable Module Package v1 contains a regular file at this canonical path inside the
+module directory:
+
+```text
+LICENSE
+```
+
+`LICENSE` contains the license material applicable to the module release. It is an ordinary payload
+file under ADR 0049:
+
+- it appears exactly once in the strict `files` list in `ekklesia.package.json`;
+- its byte size and SHA-256 are recorded there;
+- the archive SHA-256 covers it and the metadata that records it;
+- it is immutable for that release and changes only by producing a different archive.
+
+The license bytes must be available as an explicit source or build input. The canonical source is a
+module-owned `LICENSE` file at the module source root. Tooling may also accept an explicitly named
+license-text input when a workspace layout needs one, but it must place those bytes at the package's
+canonical `LICENSE` path. It must not search ancestor directories and silently adopt a repository
+license, generate project-specific license material, or download text from the network. The
+in-repository template implementation may later add its own `LICENSE` input or explicitly select
+the repository's AGPL text; this ADR does neither.
+
+The packager validates that both inputs exist: the declared SPDX expression and the applicable
+license text. It preserves the supplied text as deterministic package input. It is not a license
+compatibility engine and does not offer legal advice.
+
+### `THIRD_PARTY_NOTICES` remains a separate concern
+
+`THIRD_PARTY_NOTICES` continues to describe third-party packages actually bundled into or included
+with the module: their identities, versions, declared licenses, uses, and required license and notice
+texts. It is not the module's own license file and cannot satisfy the `LICENSE` requirement.
+
+The module itself is not added to `THIRD_PARTY_NOTICES`. A first-party module is not duplicated there
+merely because it uses the same AGPL license as Ekklesia. `LICENSE` and `THIRD_PARTY_NOTICES` both
+remain required because they describe different parts of the release.
+
+### Bundled Ekklesia code
+
+A module package may bundle Ekklesia-owned SDK, contracts, database adapter, UI, and related code.
+`incorporates` continues to record the exact versions of those Ekklesia components. It is an
+inventory and compatibility fact, not a second authoritative declaration of the module's license.
+
+Today's official module packages and the Ekklesia components they incorporate are all
+`AGPL-3.0-or-later`. Their package `LICENSE` therefore carries the applicable AGPL text once. The
+package does not need one identical copy per incorporated Ekklesia component, and those components
+do not move into `THIRD_PARTY_NOTICES` merely to obtain duplicate text.
+
+This ADR does not decide every future combination of a community module's license with differently
+licensed incorporated code. Publishers remain responsible for their choices and obligations. The
+packager preserves declared information and required material; it does not judge broad license
+compatibility.
+
+### Packaging and verification fail closed
+
+The implementation that follows this ADR must make the packager refuse a module when:
+
+- its source project has no acceptable explicit SPDX license expression;
+- its license-text input is missing or is not a regular file;
+- producing the package would omit `LICENSE` from the strict payload.
+
+The package verifier must refuse an artifact when:
+
+- `ekklesia.package.json.license` is missing, malformed, or outside the expression syntax the
+  contract supports;
+- the `LICENSE` payload is missing;
+- `LICENSE` is absent from the exact `files` list; or
+- its listed size or SHA-256 does not match its bytes, as with every other payload file.
+
+This ADR does not implement those checks. The contracts, packager, verifier, fixtures, template,
+and package proofs must change together in the implementation PR.
+
+### Determinism and runtime metadata
+
+`LICENSE` introduces no timestamp, generated host path, network lookup, or other environmental
+input. The deterministic archive rules in ADR 0049 apply to it unchanged.
+
+The generated runtime `package.json` remains minimal and is not authoritative for licensing. There
+is no runtime need to add a `license` field there. `ekklesia.package.json` is the release metadata,
+while the source module's `package.json` only supplies the publisher's declaration to the packager.
+
+### Package format remains 1
+
+`packageFormat` remains **1**. This is an additive tightening that completes ADR 0049's licensing
+requirement before the first distributable Module Package v1 release. It does not change the archive
+encoding, safety rules, target model, installation layout, or meaning of any existing field.
+
+The strict metadata schema is preserved. A verifier that predates this decision refuses the new
+unknown `license` field; an updated verifier refuses an old package that lacks it or lacks `LICENSE`.
+Both outcomes are safe. There is no installed or published v1 release compatibility promise to
+preserve because ADR 0049 explicitly withheld distributable-release status pending this work.
+
+ADR 0050's database ABI decision is unaffected. Whether a package uses database ABI v1 or the legacy
+database facade has no bearing on its license declaration or payload.
+
+## Consequences
+
+- A Module Package v1 release is self-describing about the module's own license and carries the
+  corresponding material without consulting its source repository or the network.
+- Operators can audit the release declaration in `ekklesia.package.json`, the module's license in
+  `LICENSE`, and dependency obligations in `THIRD_PARTY_NOTICES` without conflating them.
+- Module publishers must make both the SPDX declaration and license text explicit packaging inputs.
+- The template and every package fixture must be updated before packaging succeeds, but only in the
+  later implementation PR.
+- Existing development artifacts produced before this tightening are intentionally rejected and
+  rebuilt; none was a distributable v1 release under ADR 0049.
+- Identical AGPL text is carried once for today's official module and incorporated Ekklesia code.
+
+## Alternatives
+
+- **Use only `THIRD_PARTY_NOTICES`.** Rejected: it describes third-party dependencies and explicitly
+  excludes the module itself and Ekklesia-owned incorporated packages.
+- **Make the generated runtime `package.json` authoritative.** Rejected: it is deliberately minimal
+  runtime discovery metadata, and copying the declaration there would duplicate release metadata.
+- **Copy the platform's license automatically.** Rejected: the platform cannot declare a module's
+  license for its publisher, and a community module may make a different declaration.
+- **Search parent directories for `LICENSE`.** Rejected: the chosen file would depend on checkout
+  layout and could silently apply an unrelated repository's terms. An out-of-tree input must be
+  explicit.
+- **Download standard license text while packaging.** Rejected: builds must remain offline,
+  deterministic, and independent of a mutable remote source.
+- **Duplicate the AGPL text for every incorporated Ekklesia package.** Rejected: identical copies
+  add no information. `incorporates` records component identity and version; one applicable text is
+  sufficient for today's official packages.
+- **Create `packageFormat: 2`.** Rejected: v1 has not crossed its own distributable-release boundary,
+  strict readers fail safely, and no archive or installation mechanism changes.
+- **Make the packager decide license compatibility.** Rejected: preserving declarations and material
+  is mechanical; judging every present and future license combination is a broader legal and policy
+  problem.
+
+## Deferred
+
+- Implementing contract, packager, verifier, fixture, template, and package-proof changes.
+- The exact set and version of SPDX expression syntax accepted by the implementation, beyond the
+  requirement that unsupported expressions fail closed.
+- Broad policy for future mixed-license community modules and incorporated code.
+- Container-image license distribution.
+- Marketplace, installer, publisher verification, and package-signing policy.

docs/architecture/decisions/0052-reviewed-license-supplements.md

@@ -0,0 +1,229 @@
+# 0052: Reviewed license supplements cover redistributed dependencies whose packages omit required material
+
+- Status: Accepted
+- Date: 2026-10-07
+- Extends: [0049](0049-module-package-v1.md), in one respect only. ADR 0049 left exactly how licence
+  and notice material is collected to the packager's implementation. That implementation, and the
+  module development guide, then took material only from a redistributed package's own files, or
+  from a predefined standard licence text that needs no project-specific lines. This ADR adds one
+  further source: a reviewed supplement. Everything else in ADR 0049 is unchanged, as is
+  `packageFormat`.
+- Related: [ADR 0048](0048-generic-image-and-installed-module-storage.md),
+  [ADR 0051](0051-module-package-license-material.md),
+  [ADR 0055](0055-corresponding-source-artifacts.md) (decides the source-obligation policy deferred
+  below)
+
+## Context
+
+ADR 0049 requires every Module Package v1 to carry `THIRD_PARTY_NOTICES`: the licence and notice
+material that redistributing its third-party code requires. It also states that no package is a
+distributable release until licence and notice collection is proven. The canonical packager collects
+material from two places:
+
+- the licence, copying, copyright, and notice files a redistributed package ships at its root;
+- the standard text of the package's declared licence, but only when that text is complete without
+  project-specific lines (Apache-2.0 today).
+
+A package that has neither stops packaging. That is fail-closed by design: an MIT or BSD package
+without its file is refused, because its copyright line exists only in that file.
+
+The first native-target module package needs a dependency that this rule cannot handle.
+`@img/[email protected]` is the prebuilt libvips that `sharp` loads on Linux x64 with
+glibc. It declares `LGPL-3.0-or-later`. The package itself, like its latest release 1.3.4, contains
+only these files:
+- `README.md`
+- `versions.json`
+- `lib/index.js`
+- one glib header
+- one shared library
+
+That shared library includes about 29 libraries. Its README names each one and the licence it is
+used under, mostly with a link:
+- LGPL components, such as libvips, glib, and pango;
+- cairo, under MPL-2.0;
+- many BSD-, MIT-, zlib-, IJG-, and FreeType-licensed libraries.
+
+The package ships no licence text and no copyright notice for any of them. No standard text can stand
+in for that material: it includes per-project copyright notices and several different licences.
+
+Options that were ruled out before this decision:
+- **Downloading material while packaging.** Packaging must stay offline and deterministic (ADR 0049,
+  ADR 0051).
+- **Inventing material.** A packager that guesses notices produces artifacts that look compliant and
+  may not be.
+
+Ekklesia needs a way to carry material that a dependency's own package omits. It has to be reviewed
+by people, tied to exactly the bytes it was reviewed for, and fail closed whenever that tie breaks.
+
+Some of these licences may also impose obligations beyond carrying text: the LGPL and the MPL can
+require recipients to be able to obtain corresponding source. Whether and how such an obligation is
+met for a particular redistributed binary is a legal and compliance determination. This decision
+does not make that determination.
+
+## Decision
+
+### Package-provided material stays the preferred source
+
+The licence, copying, copyright, and notice material that a redistributed package ships remains the
+primary source, collected exactly as it is today. Nothing in this ADR removes, replaces, or rewrites
+package-provided material. A supplement only adds to it.
+
+### A reviewed supplement fills what a package omits
+
+When a redistributed dependency omits material that redistribution requires, the canonical Ekklesia
+packager may use a **license supplement**: a checked-in, reviewed record of that material for one
+exact dependency.
+
+- **Where supplements live.** In the Ekklesia repository, as part of the canonical packager's own
+  versioned inputs. A supplement enters only through Ekklesia's normal reviewed change process, and
+  the change that adds it is its review. A given packager version therefore always carries the same
+  supplements.
+- **What that review is.** Repository review of a supplement is project and code review of a build
+  input: whether its content, its exact match, and its provenance are what the change says they are.
+  It is not legal review, and it does not prove that any redistribution obligation is satisfied.
+- **What a supplement may contain:**
+  - licence texts;
+  - copyright and attribution notices;
+  - provenance: where each piece of material was obtained, and which upstream component versions it
+    covers;
+  - corresponding-source information, such as where upstream source for the exact build is
+    published;
+  - other material that accompanies the dependency's redistribution.
+- **Generic by construction.** Supplements are data. The mechanism contains no package-specific code
+  and treats every supplement identically, whether it is for libvips or for any other dependency.
+
+### A supplement matches one exact package, or it fails closed
+
+A supplement names exactly one redistributed package:
+
+- its package name;
+- its exact version;
+- an integrity value for the package's contents: a digest the packager computes from the package's
+  redistributed files.
+  - **Deterministic.** It covers exactly each redistributed file's normalized relative path within
+    the package and its bytes, combined in an order defined by the paths themselves.
+  - **Host-independent.** It excludes filesystem metadata, timestamps, ownership, permissions, and
+    the order in which files were extracted or listed. The same package contents always give the
+    same digest, wherever and however they were installed.
+  - **Documented.** The implementation defines and documents the exact algorithm, which does not
+    depend on any package manager.
+
+The packager uses a supplement only when all three match the package it is about to redistribute.
+
+- **A mismatch on any of the three fails packaging.** This covers, for example, a supplement whose
+  name and version match but whose integrity differs. It never falls back to a nearby version, and
+  it never silently skips the supplement.
+- **Every match is used.** A supplement that matches is always merged into the notices, including
+  when the package also ships some material of its own.
+- **Gaps still fail.** If a dependency lacks required material and no exact supplement matches, the
+  packager stops, exactly as it does today.
+
+### Supplements are immutable build inputs
+
+- **Immutable.** A supplement is never edited in place to cover a different build. A changed
+  package, a new version, or different contents need a new supplement, reviewed again.
+- **No network.** Packaging reads supplements from the packager's own inputs and never downloads
+  anything. Assembling a supplement's content is a separate, offline-reviewed curation step done
+  when the supplement is authored, never during packaging.
+
+### Merging is deterministic and labelled
+
+The notice generator merges package-provided material and supplement material deterministically. The
+same packager version and the same inputs still produce a byte-identical `THIRD_PARTY_NOTICES`
+(ADR 0049).
+
+- **Order.** Within a dependency's entry, package-provided material comes first, then supplement
+  material.
+- **Labelling.** Supplement material is marked as supplied by Ekklesia's reviewed supplement, never
+  presented as if it came from the package.
+- **No other change.** Dependencies are still sorted, line endings normalized, and each dependency
+  keeps its own entry, exactly as before.
+
+### A supplement never changes a dependency's declared licence
+
+`THIRD_PARTY_NOTICES` keeps reporting the licence the dependency itself declares.
+
+- **No override.** A supplement can add material about the components a dependency contains, but it
+  cannot replace, override, or rewrite the dependency's declared licence.
+- **Consistency check.** A supplement records the declared licence it was reviewed against. If that
+  disagrees with the package's actual declaration, packaging fails.
+
+### Legal and compliance determinations are not made here
+
+A supplement can record corresponding-source information, but this ADR does not decide what
+satisfies any licence's source obligation, and neither does the mechanism:
+- the mechanism never asserts that a written offer, a source URL, a mirror, or any other arrangement
+  satisfies a licence;
+- carrying a supplement shows that the reviewed material is present in the package. It does not
+  certify that the package is compliant;
+- for every redistributed binary under the LGPL, the MPL, or any other licence with source or
+  similar obligations, the determination of whether and how those obligations are met is deferred.
+  It must be made, and verified, separately.
+
+ADR 0049's release gate still applies. A package that redistributes such a binary does not become a
+distributable release just because its supplement was merged. It becomes one only once that
+binary's compliance determination has been made and verified.
+
+### Scope
+
+- **Third-party code only.** Supplements apply only to redistributed third-party dependencies,
+  whether bundled or copied into the package. They never apply to the module's own licence or
+  `LICENSE` (ADR 0051), or to incorporated Ekklesia packages.
+- **No package format change.** `packageFormat` stays **1**. A supplement changes only the content of
+  `THIRD_PARTY_NOTICES`, which is already a listed, digested payload file. No metadata field, archive
+  rule, or verifier contract changes.
+
+### The motivating case
+
+`@img/[email protected]` is the first dependency expected to need a supplement. This ADR
+does not curate it. Its supplement will be assembled, reviewed, and merged separately, together with
+the native-target packaging work that redistributes it. The source-obligation determination for its
+LGPL and MPL components remains open, as above.
+
+## Consequences
+
+- A dependency whose package omits required material can be redistributed after review, offline and
+  deterministically, instead of making native packaging impossible.
+- Each supplement is tied to exact package bytes, so a changed or unexpected dependency fails
+  packaging rather than inheriting material reviewed for something else.
+- Ekklesia takes on reviewing and maintaining supplements. Every version bump of a supplemented
+  dependency needs a new reviewed supplement before packaging works again.
+- `THIRD_PARTY_NOTICES` can now contain material that did not come from the dependency's package. It
+  is always labelled.
+- Carrying material and meeting obligations stay separate. Source-availability questions remain open
+  until they are determined per binary.
+
+## Alternatives
+
+- **Download licence material while packaging.** Rejected: packaging must stay offline,
+  deterministic, and independent of a mutable remote source (ADR 0049, ADR 0051).
+- **Extend the standard-text list.** Rejected: standard texts only work when the licence needs no
+  project-specific line. Bundled native libraries need per-project copyright notices, and several
+  different licences.
+- **Match supplements by name and version alone.** Rejected: identical versions can differ in content
+  across registries or rebuilds, and the material was reviewed for specific bytes.
+- **Fall back to the nearest supplemented version.** Rejected: material reviewed for one build says
+  nothing reliable about another.
+- **Let a supplement restate a dependency's licence.** Rejected: the declaration belongs to the
+  dependency's publisher. A supplement that could override it could misrepresent what is being
+  redistributed.
+- **Per-package special cases in the packager** (for example, code that knows about libvips).
+  Rejected: every supplemented dependency would need new code, and review would be split between
+  code and data.
+- **Treat a recorded source URL or written offer as satisfying copyleft obligations.** Rejected for
+  this ADR: that is a legal determination that has to be verified per binary, not assumed by a build
+  mechanism.
+- **Supplements provided by module authors.** Not adopted now: the canonical packager uses only
+  supplements reviewed into Ekklesia. Whether module repositories may contribute their own reviewed
+  supplements is deferred.
+
+## Deferred
+
+- Implementing the mechanism in the canonical packager: the supplement format and storage location,
+  the integrity algorithm, the matching, the merge, and the tests.
+- Curating and reviewing the supplement for `@img/[email protected]`.
+- The legal and compliance determination of source obligations for each redistributed binary, and
+  how a determination is recorded.
+- Whether the packager should refuse, or flag, packages whose supplements note an open determination.
+- Supplements provided by module repositories.
+- Recording which supplements were used in `ekklesia.package.json`, should that ever be needed.

docs/architecture/decisions/0053-standalone-module-development-packages.md

@@ -0,0 +1,255 @@
+# 0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol
+
+- Status: Accepted
+- Date: 2026-10-07
+- Superseded in part by: [0054](0054-public-package-reads-before-launch.md) — only where this ADR
+  describes the package phase before launch as private, or requires authenticated package reads.
+- Extends: [0049](0049-module-package-v1.md). This is the step ADR 0049 deferred: "publishing the
+  Ekklesia SDK packages for module builds outside a platform workspace". A registry is used only to
+  build a module. Installing one stays registry-free: an installed package is self-contained, as ADR
+  0049 decided.
+- Related: [ADR 0002](0002-pnpm-workspace-and-typescript.md),
+  [ADR 0006](0006-versioned-capabilities-and-compiled-module-runtime.md),
+  [ADR 0021](0021-modules-as-hostable-products.md),
+  [ADR 0023](0023-module-ui-build-pipeline.md),
+  [ADR 0039](0039-shared-design-tokens-and-elements.md),
+  [ADR 0047](0047-module-ci-harness.md),
+  [ADR 0048](0048-generic-image-and-installed-module-storage.md),
+  [ADR 0050](0050-module-database-abi-v1.md),
+  [ADR 0051](0051-module-package-license-material.md),
+  [ADR 0052](0052-reviewed-license-supplements.md)
+
+## Context
+
+Modules are independently versioned products in their own repositories (ADR 0021). Yet no module can
+be built outside Ekklesia's monorepo today. Signage's continuous integration clones the platform at
+a pinned commit, places Signage under `modules/signage`, and installs and builds inside that
+workspace, because its Ekklesia dependencies exist only as `workspace:*` packages.
+
+An investigation of the current packages found the following.
+
+- **One coordinated version.** Every `@ekklesia/*` package, and the platform, is version 0.1.2. The
+  release process already bumps them together. The platform reports its Module SDK version, which
+  manifests' `compatibility.moduleSdk` ranges are checked against (ADR 0006), by reading
+  `@ekklesia/module-sdk`'s own package version.
+- **The tarballs already stand alone.** `pnpm pack` rewrites `workspace:*` ranges to exact versions,
+  and each tarball carries only its built `dist`, declarations, and `LICENSE`. But every package's
+  `prepack` runs a command at the monorepo root, and `@ekklesia/typescript-config` is marked
+  `private`.
+- **The SDK exposes everything.** `@ekklesia/module-sdk` re-exports the whole `@ekklesia/contracts`
+  barrel. That includes contracts no module needs, such as authorization and identity, and the
+  legacy Drizzle `ModuleDatabase` type. `@ekklesia/contracts` depends on `drizzle-orm` for that type,
+  so every module install pulls Drizzle in.
+  - Neither the module template nor Signage imports `@ekklesia/contracts` directly.
+- **Frameworks are declared twice.** `@ekklesia/ui` lists `react`, and `@ekklesia/module-sdk` lists
+  `drizzle-orm`, as both a dependency and a peer dependency. That invites a second copy of a runtime
+  that must be single within one module bundle.
+- **The canonical packager assumes the monorepo**, in two ways:
+  - it finds the module's Node.js range only through an enclosing `pnpm-workspace.yaml`;
+  - it decides that an Ekklesia package is the platform's own, not third-party, because its real
+    path does not contain `node_modules`.
+
+  An `@ekklesia/*` package installed from a registry would therefore be treated as third-party.
+  Packaging would omit it from `incorporates` and skip the Module SDK compatibility check.
+- **The registry and its hosts.**
+  - The current private host is a Gitea 1.27.2 server. Its npm registry is enabled for the
+    organization, and that endpoint and the repositories are currently readable anonymously.
+  - pnpm leaves a tarball URL out of its lockfile only when the URL has the canonical
+    `<registry>/<name>/-/<name>-<version>.tgz` form. Gitea advertises another form, so lockfiles
+    produced against Gitea name the Gitea host.
+  - The integrity hashes in those lockfiles are independent of the host.
+
+## Decision
+
+### The npm registry protocol, not a provider
+
+Ekklesia's module-development packages are distributed over the **standard npm registry protocol**,
+and modules install them with ordinary pnpm or npm commands.
+
+- **No provider is part of the architecture.** Not Gitea, GitHub, npmjs, or any other. A module
+  repository depends on the protocol and on a scope-to-registry mapping in normal npm/pnpm
+  configuration.
+- **Gitea may host the private phase.** It is a host for this phase, not a permanent decision.
+- **No host-neutral lockfile or Ekklesia proxy is required.** Moving to another registry may need a
+  one-time change of a module's registry configuration and a regeneration of its lockfile. The
+  integrity hashes keep verifying the package content across such a move.
+
+A module repository's registry configuration is, for example:
+
+```ini
+# .npmrc, committed: where the @ekklesia scope lives, and nothing secret.
+@ekklesia:registry=https://<registry endpoint>/
+```
+
+```ini
+# User or CI configuration, never committed: the credential, from the environment.
+//<registry endpoint>/:_authToken=${EKKLESIA_PACKAGES_TOKEN}
+```
+
+### The public package set
+
+Only packages a module author needs are published. Nothing is published merely because it exists in
+the workspace.
+
+| Category | Packages |
+| --- | --- |
+| Author API | `@ekklesia/module-sdk`, `@ekklesia/module-database`, `@ekklesia/module-ui-sdk`, `@ekklesia/design-tokens` |
+| Tooling | `@ekklesia/module-ui-build`, `@ekklesia/module-pack`, `@ekklesia/typescript-config` |
+| Pre-1.0 component API | `@ekklesia/ui`: publishable, explicitly unstable before 1.0 |
+| Implementation dependency only | `@ekklesia/contracts`: may be published because the packages above depend on it, but it is **not** a supported direct module-author API |
+| Never published | `@ekklesia/core`, the applications, `@ekklesia/module-ui-host`, `@ekklesia/module-template`, and every other platform internal |
+
+### A curated SDK surface
+
+Before the first external publication, the author-facing SDK is narrowed.
+
+- **A curated API.** `@ekklesia/module-sdk` exposes what a module author needs, and no longer
+  re-exports the complete `@ekklesia/contracts` barrel.
+- **No forced Drizzle.** The stable SDK root does not make Drizzle a dependency of modules that do
+  not use it.
+- **No legacy database contract.** The legacy Drizzle database contract (ADR 0016's facade type) is
+  not part of the standalone author-facing surface. Core still serves the legacy facade for its
+  deprecation window (ADR 0050). This decision only keeps its type out of what new standalone
+  modules build against.
+- **Drizzle support lives in one place.** Drizzle-specific helpers belong to the
+  `@ekklesia/module-database` Drizzle adapter (ADR 0050).
+
+### Dependency rules
+
+These rules apply to the published packages:
+
+- **React and ReactDOM** are peer dependencies of the public UI packages, plus development
+  dependencies for those packages' own builds and tests. This does not change ADR 0023: a module UI
+  artifact still bundles React. The peer only ensures there is one React in that bundle, the
+  module's own.
+- **Drizzle** is an optional peer dependency only where the Drizzle adapter needs it.
+- **Real implementation dependencies,** at run time or build time, remain normal dependencies.
+
+These rules apply to a module repository:
+
+- **Runtime and module-code packages** go in `dependencies`: the Author API packages, `@ekklesia/ui`,
+  React, and the module's ORM if it uses one.
+- **Build tooling and configuration** go in `devDependencies`: `@ekklesia/module-ui-build`,
+  `@ekklesia/module-pack`, `@ekklesia/typescript-config`, and type packages.
+
+### Versioning
+
+- **One coordinated version during 0.x.** Every public Ekklesia module-development package uses one
+  release version, equal to the platform release version. The version the platform reports for
+  `moduleSdk` compatibility is therefore the version of the packages a module was built with.
+- **No mixed trains.** Within a published train, Ekklesia-owned dependencies name the coordinated,
+  tested version, never a version from another train.
+- **Ranges in source, exact artifacts in lockfiles.** A module may declare compatible ranges in its
+  source `package.json`; its lockfile pins exact artifacts with their integrity hashes.
+- **`@ekklesia/module-pack` is pinned exactly.** A module repository pins it in its source
+  `package.json`, not only in its lockfile, because its version affects the package it produces.
+- **Independent package versions are deferred.**
+
+### Standalone packaging
+
+- **No monorepo checkout.** A standalone module builds and packages from its own repository and its
+  installed dependencies.
+- **Its own Node.js range.** The module declares its own Node.js compatibility, preferably in
+  `engines.node`, and the canonical packager reads it from there or from an explicit option. It
+  never requires an enclosing `pnpm-workspace.yaml`.
+- **Ekklesia packages recognized by identity.** The canonical packager recognizes Ekklesia-owned
+  installed packages by explicit package identity and metadata, never by workspace path. So
+  `incorporates` and the Module SDK compatibility check (ADR 0049) work the same whether a package
+  came from the monorepo or from a registry. Ekklesia packages are never reported as third-party
+  software (ADR 0051).
+- **No monorepo-root commands at install time.** Publishing workflows for the public packages run
+  their build in the platform's release pipeline. Nothing in a published package runs a
+  monorepo-root command when a consumer installs or packs it.
+
+### Supply chain
+
+- **Immutable versions.** A version is never republished with other content, and never withdrawn to
+  be reused.
+- **Lockfiles.** pnpm lockfile integrity is part of the reproducibility model: modules install with a
+  frozen lockfile.
+- **Release CI proves the tarballs before publication.** It must:
+  1. build and pack the public package set;
+  2. inspect every tarball: only the intended contents, a `LICENSE`, and no `workspace:` range;
+  3. install those tarballs into a clean standalone module fixture, outside any monorepo;
+  4. prove there that the fixture builds, packages with the canonical packager, and verifies.
+
+  Only then are the versions published.
+- **Signing and provenance are deferred.**
+
+### Registry access and the private phase
+
+- **No secrets in module repositories.** Registry configuration for the scope is normal npm/pnpm
+  configuration.
+- **Credentials from the environment.** Read and publish credentials come from environment or user
+  configuration: a read credential in module CI where reads need one, and a publish credential only
+  in Ekklesia's release pipeline.
+- **No permanent provider.**
+- **Verify access before the first publication.** Check the chosen registry's actual private and
+  read-access behaviour first. Ekklesia's packages must not be published unintentionally to a
+  registry that serves them anonymously while Ekklesia is not public.
+
+### The release workflow
+
+During 0.x, public package releases form a **coordinated SDK train** associated with platform
+releases:
+
+1. build;
+2. pack;
+3. standalone tarball smoke (see [Supply chain](#supply-chain));
+4. publish immutable versions;
+5. downstream module CI installs and tests those versions.
+
+### Signage
+
+The intended result is a normal standalone Signage repository:
+- versioned `@ekklesia/*` dependencies;
+- its own lockfile;
+- continuous integration that installs, builds, packages, and verifies on its own.
+
+That CI must not clone Ekklesia or place Signage under `modules/`. The migration itself is a separate
+change.
+
+## Consequences
+
+- A module repository is an ordinary pnpm project. Clone it, install, build, and package it with the
+  canonical packager, with no Ekklesia checkout.
+- Module authors see a smaller, deliberate API, and the platform can change its internal contracts
+  without breaking them.
+- One coordinated version keeps compatibility simple: SDK version X is what platform version X
+  reports and accepts. The cost is republishing unchanged packages with each platform release.
+- A registry move costs each module a configuration change and a lockfile regeneration, but no
+  source change. Package content stays verifiable by integrity hash throughout.
+- Before the first publication, the SDK surface must be curated and the packager's two monorepo
+  assumptions removed. Both are breaking for code that relied on them.
+- ADR 0047, still proposed, assembles a module into the platform workspace to test it. Before it is
+  accepted it must instead consume published packages and canonical module packages, consistent with
+  this decision and with ADR 0048.
+
+## Alternatives
+
+- **Git URL, tag, or commit dependencies.** Rejected: they tie modules to one Git host, need a build
+  on every install because `dist` is not committed, and cannot express version ranges.
+- **Release-asset tarball URLs.** Rejected: each dependency becomes a host-specific URL, and ranges
+  cannot be resolved.
+- **OCI artifacts for packages.** Rejected: npm and pnpm cannot install from them. (A harness image
+  is a different matter; see ADR 0047.)
+- **Vendoring Ekklesia packages into each module repository.** Rejected: the copies drift, updates
+  are manual, and there would be no single canonical SDK.
+- **Requiring host-neutral lockfiles, or an Ekklesia registry proxy that rewrites tarball URLs.** Not
+  required: a one-time lockfile regeneration on a registry move is an acceptable cost, and integrity
+  hashes already keep content verifiable. Ekklesia may still choose a stable endpoint later.
+- **Publishing `@ekklesia/contracts` as a direct author API.** Rejected: it holds platform-wide
+  contracts. Modules get a curated surface through the SDK packages.
+- **Externalizing React from module UI bundles to share one runtime.** Rejected again: ADR 0023's
+  reasoning stands, and peers only prevent duplicates within one bundle.
+- **Independent versions per package now.** Deferred: during 0.x a coordinated train is simpler for
+  module authors and matches how the platform reports its SDK version.
+
+## Deferred
+
+- Provisioning a registry, and its credentials.
+- Public publication on npmjs or any other public registry.
+- Package signing and provenance.
+- Independent package versioning.
+- Dashboard and UI redesign.
+- The Signage migration itself.

docs/architecture/decisions/0054-public-package-reads-before-launch.md

@@ -0,0 +1,85 @@
+# 0054: Ekklesia's module-development packages are publicly readable before launch
+
+- Status: Accepted
+- Date: 2026-10-08
+- Supersedes (partial): [0053](0053-standalone-module-development-packages.md) — only where it
+  describes the package phase before launch as private: "Gitea may host the private phase", the
+  read credential for module CI in "Registry access and the private phase", and its requirement
+  that packages not be served anonymously while Ekklesia is not public. Every other part of that ADR
+  remains accepted and unchanged: the npm registry protocol, the public package set and its
+  boundaries, the curated SDK, the dependency rules, the coordinated package train, exact release
+  artifacts, standalone module builds, provider portability, supply chain and immutability, and the
+  credential handling for publishing.
+- Related: [ADR 0049](0049-module-package-v1.md)
+
+## Context
+
+ADR 0053 decided how Ekklesia's module-development packages (`@ekklesia/*`) are built, released, and
+distributed over the npm registry protocol. It assumed that the phase before Ekklesia's public
+launch would be private: module CI would carry a read credential where reads needed one, and the
+first publication had to make sure the registry would not serve the packages anonymously.
+
+Checking the chosen host before the first publication showed what keeping the packages private would
+take:
+
+- Gitea 1.27.2 decides package read access by the package **owner's** visibility, never a
+  repository's. The `River_of_Glory_Church` owner is a public organization, so its packages are
+  readable anonymously.
+- That organization's repositories, Ekklesia's source among them, are already publicly readable.
+- The instance allows self-registration, so "limited" visibility, readable by any signed-in user,
+  is readable by anyone who creates an account.
+- Private packages would therefore need a separate private package owner, plus reader accounts and
+  read tokens for every module repository, every module's CI, and every developer.
+
+The project owner has decided that Ekklesia is not secret. Its source is public; the project is
+simply not being launched or promoted yet. Hiding the packages built from that public source would
+protect nothing, and would still cost every module author an account and a token.
+
+## Decision
+
+1. **Ekklesia's module-development packages may be anonymously readable before the project's public
+   launch.** This covers the public package set of ADR 0053: search, metadata, and download.
+2. **Readability is not a launch, and promises nothing more.** Public readability does not mean:
+   - that Ekklesia has been publicly launched;
+   - that the APIs are stable beyond the project's pre-1.0 SemVer policy;
+   - that third-party production use is supported;
+   - that a marketplace or public module ecosystem exists.
+3. **Reading needs no authentication in this phase.** Installing `@ekklesia/*` needs no account,
+   reader account, read token, or authenticated install workflow. A module repository configures only
+   the scope's registry.
+4. **Publication stays authenticated and tightly controlled.** Only Ekklesia's release process
+   publishes, with one dedicated publisher credential that holds nothing beyond package write
+   access, used only by that process, as ADR 0053's credential handling for publishing already
+   requires.
+5. **Published versions stay immutable by Ekklesia policy.** A published version is never deleted or
+   republished with other bytes, whatever the registry technically allows.
+6. **The current Gitea owner is an acceptable host.** The `River_of_Glory_Church` package namespace
+   on the current Gitea may host this phase, as long as publishing permission stays restricted to
+   the publisher. No private package organization is needed.
+7. **A public launch is a separate decision.** Launching or promoting Ekklesia publicly, and anything
+   that changes for its packages then, is a product and release decision this ADR does not make.
+
+## Consequences
+
+- **Module authors and module CI need no Ekklesia credential.** The committed `.npmrc` scope mapping
+  is the whole registry configuration. ADR 0053's example of a read credential in user or CI
+  configuration is no longer needed in this phase.
+- **ADR 0053's pre-publication access check changes meaning.** It now confirms that anonymous reads
+  work as intended and that publishing is refused without the publisher's permission, rather than
+  that reads are private. The disposable-registry suite proves both, and the publication tool can
+  require an anonymous download to match each published artifact.
+- **Restricting publishing is now the whole access boundary**, so the publisher credential's scope,
+  where it is held, and who can reach it matter all the more.
+- **Making the packages private again would be a new decision.** Package names, versions, and
+  contents already published stay public, because a published version is never deleted.
+
+## Alternatives considered
+
+- **A private package organization on the same Gitea.** Rejected: it hides nothing that is not
+  already public in the source, and it requires reader accounts and tokens for every module
+  repository, its CI, and every developer.
+- **"Limited" package visibility.** Rejected: with self-registration open, anyone can read anyway,
+  while the configuration suggests otherwise.
+- **Requiring sign-in for the whole instance.** Rejected: it would also hide the public
+  repositories.
+- **Another registry for a private phase.** Unnecessary once reads are public.

docs/architecture/decisions/0055-corresponding-source-artifacts.md

@@ -0,0 +1,189 @@
+# 0055: Native redistributable packages carry corresponding-source artifacts
+
+- Status: Accepted
+- Date: 2026-10-09
+- Extends: [0049](0049-module-package-v1.md). ADR 0049 withholds distributable-release status from a
+  package until its licence handling is proven. This ADR adds what proving it means for a native
+  package that redistributes copyleft code: a sibling corresponding-source artifact, and a
+  fail-closed gate for public distribution. Module Package v1 is unchanged, and `packageFormat`
+  stays **1**.
+- Decides: the item [ADR 0052](0052-reviewed-license-supplements.md) deferred, "the legal and
+  compliance determination of source obligations for each redistributed binary, and how a
+  determination is recorded", as a project policy. Reviewed supplements are unchanged in purpose
+  and format.
+- Related: [ADR 0051](0051-module-package-license-material.md), whose rules for a module's own
+  licence are unchanged.
+
+## Context
+
+A native Module Package (ADR 0049) copies native dependencies into its `node_modules` exactly as
+built. The first one, the packager's native proof with sharp, redistributes
+`@img/sharp-libvips-linux-x64`. That is one shared object with about 29 libraries built into it.
+Several are under the GNU LGPL, and cairo and some Rust crates are under the MPL.
+
+ADR 0052 made the licence and notice side work. A reviewed supplement adds the licence, copyright,
+and notice files the package omits, with the exact upstream source each came from. But ADR 0052 was
+explicit that carrying material is not meeting obligations. The LGPL and the MPL also oblige whoever
+distributes the binary to make the corresponding source available. For a library linked into a
+larger work, that includes what a recipient needs to rebuild the library and use a modified version.
+Recording upstream URLs does not do that: URLs move, tags are rewritten, and a mirror is somebody
+else's promise.
+
+Until this was decided, every native package containing such components was blocked from public
+distribution, and the blocker had no defined way to be lifted.
+
+## Decision
+
+### Native packages may contain copyleft native dependencies
+
+A native Module Package may redistribute native dependencies under the LGPL, the MPL, or a similar
+licence with source obligations. It may be **distributed publicly** only when it is released
+together with a **corresponding-source artifact** that meets this ADR. A package whose artifact
+cannot be produced and verified is not approved for public distribution.
+
+This is Ekklesia's **project compliance policy**: a conservative rule the project holds itself to.
+It is not legal advice, and it is not legal certification. Repository review of the artifact, its
+inputs, and its instructions is project and code review. It does not replace professional legal
+review, and nothing built from this ADR may claim that it does.
+
+### Supplements and source artifacts do different jobs
+
+- **A reviewed supplement (ADR 0052)** identifies and verifies the licence and notice material for a
+  redistributed binary. It travels inside the package, in `THIRD_PARTY_NOTICES`.
+- **A corresponding-source artifact** carries the source, patches, build definitions, and rebuild
+  and relink instructions for the covered native components. It travels beside the package, as a
+  separate release artifact.
+
+A supplement alone never satisfies the source-availability policy. A source artifact never replaces
+the supplement or `THIRD_PARTY_NOTICES`.
+
+### What the artifact contains
+
+For each covered native dependency the package redistributes, the artifact contains:
+
+- the exact source the binary was built from, as bytes, not as references:
+  - its build definitions;
+  - the source archive of every library compiled into it;
+  - every patch the build applied;
+  - every source package a language package manager resolved for the build;
+  - the source of any runtime library the toolchain linked into it;
+- the licence and copyright material: the reviewed supplement, and the files inside the sources;
+- **instructions** that are technically actionable. They name what the artifact corresponds to and
+  its target, and say how to apply the patches and rebuild the covered library. They also say how a
+  rebuilt or modified library replaces the redistributed one in the installed module, and which
+  toolchain and configuration to use, or point to the included build definitions;
+- a deterministic, machine-readable manifest of every component and file, each with its digest,
+  plus the human-readable provenance.
+
+Components that are not part of the binary are left out, each with its reason recorded: build-only,
+test-only, or another platform's. The exception is a build-time input needed to rebuild the covered
+library, such as a source package a build script requires. That is included and marked as
+build-only. Host system libraries and general-purpose build tools are not redistributed, and the
+instructions name the versions they need.
+
+### It is tied to exact inputs, and verified before it is written
+
+- **Bound to the binary.** An artifact names each covered dependency by package name, version, and
+  the content digest a supplement is matched by (ADR 0052). It names the module identity and target
+  of the package it accompanies. An artifact for one version of a binary never satisfies another.
+- **From reviewed inputs only.** The inputs come from a checked-in, reviewed **source recipe** per
+  covered dependency version. The recipe records each component's name, version, origin,
+  relationship to the binary, and licence material, and each source file's and patch's size and
+  SHA-256.
+- **Acquisition is separate from construction.** Obtaining the recorded bytes may use the network,
+  in an explicit preparation step that stores them in a local cache keyed by content digest.
+  Constructing the artifact is offline. It reads only the cache and checked-in files, verifies every
+  byte against the recipe before writing anything, and never fetches or trusts a current upstream
+  response.
+- **Deterministic.** The same inputs produce the same artifact, byte for byte, in any working
+  directory: normalized relative paths, fixed ownership, modes, and timestamps, sorted entries, and
+  no machine-specific path.
+
+### Binary and source are linked by recorded digests
+
+A public release of a native package with covered components consists of sibling artifacts:
+
+- the Module Package archive and its SHA-256 (ADR 0049);
+- the corresponding-source archive and its SHA-256;
+- machine-readable **redistribution metadata** recording:
+  - the package archive's name and SHA-256;
+  - the module identity and target;
+  - each covered dependency's name, version, licence, and content digest;
+  - the supplement and recipe it was assembled from;
+  - the source archive's name and SHA-256, and the SHA-256 of its manifest;
+- a **release notice**, displayed alongside the binary wherever it is offered. It says, in
+  substance, that the release includes third-party software under licences including the GNU LGPL
+  or the MPL, and that corresponding source and build and relink materials for the covered native
+  dependencies are in the accompanying artifact, named by its exact file name and SHA-256.
+
+A reviewer can therefore tell exactly which source artifact corresponds to which redistributed
+binary, from digests, without guessing from file names. The source archive is never placed inside
+the Module Package. `THIRD_PARTY_NOTICES` stays as it is, and never duplicates the source.
+
+### Public distribution fails closed
+
+Building and testing packages stays unrestricted: the packager produces native packages exactly as
+before, for development, CI, and private use. **Public redistribution approval** is a separate gate.
+For a package intended for public distribution, the gate requires that:
+
+- the package's native dependency inventory is known;
+- every covered dependency has its reviewed supplement and source recipe;
+- the corresponding-source artifact is present;
+- every digest matches;
+- the artifact's manifest validates against the recipe and the archive's own contents;
+- the release notice names the exact artifact.
+
+If any requirement fails, approval fails. Bundled (not copied) code under such a licence is not
+handled by this mechanism, so the gate refuses it rather than approving it.
+
+### Retention, and no rewriting history
+
+- Ekklesia keeps a release's corresponding-source artifact for as long as it distributes, or
+  supports access to, the matching binary release. Nothing deletes one automatically while that
+  binary remains available.
+- The bytes of a source artifact for an existing binary release are never replaced under the same
+  identity.
+- A correction is a new release, or an explicitly versioned compliance artifact that the
+  redistribution metadata names. History is never silently replaced.
+
+### What this ADR does not do
+
+- It does not change any module's own licence, or ADR 0051's rules for it. The module's own source
+  obligations are met by the module's own repository, as before.
+- It does not make **runtime downloading** an acceptable workaround. Fetching a copyleft library at
+  run time instead of redistributing it moves the obligation rather than meeting it, makes
+  installations depend on a third party, and breaks ADR 0048's self-contained installed modules. It
+  is not the preferred path.
+- It does not change Module Package v1, the verifier's acceptance of a package, or the content of
+  existing supplements.
+
+## Consequences
+
+- Native modules that need copyleft native libraries, starting with sharp's libvips, can be
+  distributed publicly under a defined, checkable policy, instead of being blocked indefinitely.
+- Each covered dependency version needs a reviewed source recipe, as it needs a reviewed supplement.
+  A dependency bump needs both before public distribution works again.
+- Releases carry an artifact many times larger than the package itself (about 200 MB for libvips
+  1.3.4, against a 9 MB package), and Ekklesia commits to retaining it.
+- Constructing the artifact needs the verified source cache. Acquisition happens once per recipe,
+  not on every build.
+
+## Alternatives
+
+- **Treat supplements, source URLs, or a written offer as sufficient.** Rejected: URLs and offers
+  depend on third parties and on time. This policy requires the source itself, retained with the
+  release.
+- **Put the source inside the Module Package.** Rejected: installations would store hundreds of
+  megabytes they never need, and the package format would change for a distribution concern.
+- **Download sources while constructing the artifact.** Rejected: a release would depend on mutable
+  remote responses. Acquisition is explicit and verified, and construction is offline.
+- **Download native libraries at run time.** Rejected, as above.
+- **Per-dependency special cases in code.** Rejected for the same reason as in ADR 0052: recipes are
+  reviewed data, and the mechanism knows no particular library.
+
+## Deferred
+
+- Hosting and serving source artifacts for published module releases, and the release CI that runs
+  the gate and keeps the verified source cache.
+- Corresponding source for bundled copyleft code, if a module ever needs it.
+- Recipes provided by module repositories, alongside the question ADR 0052 deferred for supplements.

docs/architecture/decisions/0056-device-credentials-last-while-in-use.md

@@ -0,0 +1,76 @@
+# 0056: A device credential lasts while the device is in use
+
+- Status: Accepted
+- Date: 2026-10-12
+- Supersedes: the "Session lifetime" section of [0036](0036-managed-device-identity-and-pairing.md).
+  Everything else in ADR 0036 — the device as its own principal, pairing, revocation on every
+  request, re-pairing as a new identity — is unchanged.
+
+## Context
+
+ADR 0036 gave a device credential a fixed 180 days from pairing. The intent was that a screen on a
+ceiling should not need re-pairing on a short cycle, and that an abandoned screen should eventually
+stop being an identity.
+
+A fixed horizon does the second and fails the first. Every screen in the building expires on the
+anniversary of its pairing whether or not it was in use the day before, and drops to a pairing code
+in front of the congregation until someone with Dashboard access walks to it. For screens paired
+together, that is every screen at once. Nothing about a working, unrevoked screen is less trustworthy
+on day 181 than on day 179; only the calendar changed.
+
+## Decision
+
+**The 180 days are an idle window, not a lifetime.** A device credential is accepted while the
+device was last seen less than 180 days ago (or, if it has never been seen, was paired less than 180
+days ago). `lastSeenAt` already moves forward on authenticated device requests (throttled to one
+write per 15 minutes), so the server-side window slides with use and needs no new column or
+migration.
+
+**The browser's copy is renewed by the host, not rotated.** The display descriptor —
+`GET /api/v1/module-displays/<module>`, which every display requests when it starts, when it
+reconnects, and periodically while it runs — re-issues the device cookie that authenticated the
+request with a fresh 180-day `Max-Age` and the same attributes as at pairing (`HttpOnly`,
+`SameSite=Strict`, host-only, `Path=/`, `Secure` on https). The value is unchanged.
+
+Renewal happens only for a request that already resolved to a live, unrevoked device. A revoked,
+expired, or unknown credential is anonymous, as before, and is never renewed; a person viewing a
+display never receives a device cookie.
+
+**Revocation remains the boundary.** It is still checked on every request, and an administrator's
+revoke still takes effect immediately.
+
+## Why not rotate
+
+Rotation (issue a new value, invalidate the old) would bound how long any one stolen value works and
+could reveal a cloned credential. For an unattended screen it trades that for a new way to strand
+the display: a renewal response lost to a network drop, a power cut, or a browser that never
+persisted the new cookie leaves the screen holding a dead credential and showing a pairing code,
+which is the failure this decision exists to remove. A refresh-token scheme with overlap windows
+could avoid that, at the cost of real complexity in the one place mistakes are invisible until a
+wall goes dark. That is not justified while revocation is immediate and a device principal can only
+read the displays it was paired for.
+
+## Consequences
+
+- A screen that is used at least once every 180 days stays paired until an administrator revokes
+  it. An abandoned screen still stops being an identity 180 days after it was last seen.
+- Existing credentials need no migration. A screen paired under the fixed rule is renewed the next
+  time it requests its descriptor, provided its browser still holds the cookie.
+- A stolen device credential stays usable for as long as anyone keeps using it, until it is revoked.
+  Under ADR 0036 it was usable for at most 180 days from pairing. The exposure is bounded by what a
+  device may do — the display permissions of the module it was paired for, never a person's access
+  — and by revocation. Operators can see each device's last-seen time and revoke anything
+  unexpected.
+- A credential is not bound to a browser or network. Like a human session cookie, whoever presents
+  it is the device.
+
+## Alternatives
+
+- **Keep the fixed 180 days.** Rejected: every in-use screen fails on a schedule, and screens paired
+  together fail together.
+- **Never expire.** Rejected: an abandoned or forgotten screen would remain an identity forever, and
+  its credential would never stop working without someone remembering to revoke it.
+- **Rotate on renewal.** Rejected for now; see above.
+- **Renew on every authenticated response.** Rejected: principal resolution happens deep in shared
+  middleware that never writes responses. One endpoint every display already requests periodically
+  is enough, and keeps the behaviour in one visible place.

docs/architecture/decisions/0057-dashboard-urls-are-host-owned-routes.md

@@ -0,0 +1,241 @@
+# 0057: Dashboard URLs are real, host-owned routes
+
+- Status: Accepted
+- Date: 2026-10-14
+- Extends: [0026](0026-minimal-ekklesia-module-ui-host.md),
+  [0027](0027-dashboard-navigation-and-flat-modules.md),
+  [0034](0034-host-owned-browser-authentication.md),
+  [0044](0044-self-hosted-reference-deployment.md),
+  [0045](0045-split-dashboard-and-api-origins.md)
+
+## Context
+
+The Dashboard had exactly one URL. `apps/api` served the page at `/` and nowhere else, both
+reference proxies forwarded only `/` to it, and the shell kept "which module is open" in React state.
+Opening a module never changed the address bar, so a refresh always returned to the first module,
+nothing could be bookmarked or shared, and the browser's Back button left the Dashboard entirely.
+ADR 0026 rejected a client router *for that pass* — "a selected-module state is sufficient" — and
+ADR 0027 deferred client routing and deep links.
+
+The product contract now requires them. DESIGN.md §2.7 says the URL represents the current place in
+the product: a refresh returns to the same page, deep links work, Back and Forward behave
+predictably. §5 makes an **Overview** the Dashboard's landing page, and §12.6 says a disabled module's
+routes stop behaving as active routes. Everything else Stage 1 builds — the sidebar, Settings, the
+account area, platform Displays, a module's own pages in the sidebar, and returning to the workflow a
+Settings deep link came from — needs stable addresses to hang from, so this is the first slice.
+
+A route that works in the shell but not on refresh is worse than no route, because it looks like it
+works. Refresh is a server and proxy concern before it is a browser one: the API had to serve the
+page at the new paths, and the proxies had to forward them.
+
+## Decision
+
+### One top-level URL space, shared by platform pages and module pages
+
+```text
+/                          the Overview
+/settings[/…]              Settings
+/account[/…]               the account area
+/<module-id>               a module's page: /signage, /calendar, /people
+/<module-id>/<page>[/…]    reserved for that module's own pages: /signage/timelines
+```
+
+A module is a first-class top-level destination, addressed by its id, exactly as Settings and the
+Account area are. "Module" is an implementation concept — how the platform packages a product — and
+it does not appear in the addresses people see, bookmark, and share. A module id is lowercase
+kebab-case and Core-validated, which is what makes it usable as a path segment with no further
+encoding.
+
+### Platform-owned top-level names are reserved, and Core enforces it
+
+Sharing one namespace means a module must never be able to take a name the platform uses.
+`RESERVED_MODULE_IDS` (`core/src/modules/reserved-ids.ts`) is the complete set the platform serves
+at the top level **today**, taken from what is actually registered rather than from guesses:
+
+| Name | Owned by |
+| --- | --- |
+| `api` | the API: identity, principal, health, Core resources, module routes, module UI artifacts, display descriptors, realtime |
+| `assets` | the Dashboard's and display host's scripts |
+| `display` | the display host's pages and service worker |
+| `settings` | the Dashboard's Settings pages |
+| `account` | the Dashboard's account area |
+
+Discovery refuses a module that declares one (`MODULE_ID_RESERVED`), so the check covers API
+startup, `pnpm modules:validate`, and Module Package verification — before a module is installed,
+not only when it is served. Exact names only: `settings-sync` or `displays` are ordinary ids.
+
+The set is held to reality by tests in `apps/api` rather than by review: every top-level segment the
+composed API registers is a reserved name or a module page, the display host's and Dashboard
+script's path constants all start with a reserved name, and every Dashboard page the shell
+interprets is reserved. Adding a new top-level platform route therefore fails a test until its name
+is reserved. Reserving a name later is a **breaking change** for any installation with a module of
+that id, so the set grows only deliberately, and only for a real route.
+
+The rule lives in Core's discovery rather than in the module manifest grammar
+(`@ekklesia/contracts`), because it is the Ekklesia host's URL space, not a property of a module: a
+standalone host (ADR 0021) has no Settings page to protect. A module built against the current
+public packages is unaffected unless it uses one of these five names.
+
+### The server serves one page, unchanged, at every real Dashboard address — and nowhere else
+
+`createDashboardHostRoutes` answers `GET` (and Hono's implicit `HEAD`) at `/`, at `/settings` and
+`/account` and everything below each (`DASHBOARD_PLATFORM_PAGES`, exported by the shell as
+`@ekklesia/shell/dashboard-routes`, so the server and the shell's router read one list), and at
+`/<module-id>` and everything below it for **each module this process discovered that declares a
+Dashboard UI**. Every answer is the same frozen bytes, the same strong `ETag`, and the same security
+headers as `/`: the path selects a page inside the shell, never a file on the server. Nothing from
+the request is composed into a lookup, no directory is exposed, and the script and source map remain
+reachable only at their own literal paths.
+
+The module set is the boot snapshot's discovered inventory, fixed at startup like every other
+module-derived route, and it deliberately **includes disabled and blocked modules**. A bookmark to a
+module an administrator turned off still opens the Dashboard, which says the module is unavailable;
+that is more useful than an address that suddenly looks like it never existed. A module that is not
+installed, or that has no Dashboard UI (a display-only module, ADR 0033), has no page.
+
+Everything else stays the sanitized `404`: an arbitrary root path (`/definitely-not-a-real-module`),
+a look-alike (`/settings-old`, `/signages`), another method, `/index.html`, and so on. The routes
+also refuse to compose if handed a module page that is not a valid module id, is a reserved name, or
+appears twice — discovery already guarantees all three, and the routes do not trust it.
+
+Serving `/<module-id>` before sign-in means an anonymous request can learn whether a module with a
+Dashboard UI is installed, by its `200` or `404`. That is accepted: it is the same disclosure the
+display host already makes at `/display/<module-id>` (ADR 0033), a module id names a product rather
+than any data, and the alternative — a page at every module-shaped root path — is exactly the
+"arbitrary path becomes a Dashboard page" this decision rejects. The authenticated module inventory
+and every module route keep their authorization unchanged.
+
+### The proxies forward module-shaped names and let the API decide
+
+A proxy cannot know which modules an installation has, and a proxy configuration listing them would
+have to be edited on every install. Both reference Caddyfiles therefore forward every top-level path
+whose first segment has a module id's shape, `^/[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:/.*)?$`, and the API
+answers it with the page or its sanitized `404`. Anything not shaped like one — `/favicon.ico`,
+`/.well-known/…`, an uppercase name — is still refused by the proxy without reaching the API. In the
+split topology (ADR 0045) the Dashboard hostname forwards module-shaped names but still refuses
+`/api`, `/display`, and `/assets`, and the API hostname still serves no Dashboard page. The
+development server falls back to the page for any path with no file.
+
+### The shell's router is host-owned, small, and deliberately not a library
+
+The address bar is the source of truth for which page is open. The shell reads it through a
+four-method `HostHistory` (`pathname`, `push`, `replace`, `subscribe`); the browser implementation is
+built in the entry point from `window` and handed down, so the entry point remains the only file in
+the package that touches a browser global, and every routing behaviour is tested against an in-memory
+history whose entries a test can inspect. No state object is ever stored in a history entry — the path
+alone is meaningful — so nothing put into history can be read back as authority.
+
+`react-router-dom` is not adopted. Modules are refused it because routing belongs to the host
+(ADR 0022, `pnpm boundaries`); the shell's own pages are a handful of host screens plus one mounted
+module; and adopting a library now would prejudge how a module's own pages are addressed, which is
+a separate decision (see **Deferred**).
+
+### What each path shows
+
+- `/` is the **Overview**. The shell no longer opens the first module for the person: the Overview is
+  the landing page. Until modules can contribute cards to it, it says plainly that it has nothing to
+  show yet.
+- `/<module-id>` mounts the module whose navigation entry has that id, through the unchanged generic
+  loader and the unchanged keyed frame, so a stale load still cannot reach a newer page. The server's
+  navigation is the only authority on what is mountable. An id it does not list — a disabled or
+  blocked module whose address the server still serves — shows *This page isn't available* and loads
+  nothing; the page never echoes the address back. This is what makes a disabled module's routes stop
+  behaving as active routes, with no new server state.
+- `/settings…` and `/account…` are the platform's own pages and are never read as module pages. They
+  have no content yet, so they show *Page not found* for now.
+- Everything below `/<module-id>/` belongs to that module's own pages. It is served by the API today
+  and shows *Page not found* in the shell until the module page contract exists. The shell never
+  guesses, and never shows a module's first page for an address the module never defined.
+- One trailing slash is tolerated and corrected to the canonical spelling in place (`replace`, no new
+  entry), so what is bookmarked next is the one canonical address.
+
+### Navigation is real links
+
+Every navigation item is an `<a href>` with its canonical address and `aria-current="page"` when it
+is open, marked by weight as well as colour. An ordinary click opens the page in place and adds one
+history entry; a click with a modifier key or the middle button is left to the browser, so a page can
+be opened in a new tab. Clicking the open page's own link adds no entry. The browser's Back and Forward
+walk exactly the pages that were open.
+
+### Page changes behave like page loads for assistive technology
+
+After an in-place page change the shell moves focus to the page's `<main>` (named after the page) as
+a full load would have; the first page shown after a refresh or sign-in is left alone. The entry point
+names the browser tab after the open page ("Overview", the module's display name, or the error page's
+title, and "Sign in" while signed out) — never "Ekklesia", in keeping with ADR 0046. The static page's
+own `<title>` is unchanged here; it belongs to the branding work.
+
+### Sign-in is unchanged, and still has no return URL
+
+ADR 0034 holds exactly. The sign-in form still replaces the application in place at the current URL,
+so a deep link opened while signed out lands on its own page once the person signs in — with no
+`return`, `next`, or callback value, no redirect, and no script-driven navigation off the
+Dashboard's own paths. The shell only ever moves between its own canonical paths. Emailed
+verification and reset links still land on `/` with a query (ADR 0038).
+
+## Alternatives
+
+- **Module pages under a prefix (`/modules/<id>`).** Rejected: it exposes an implementation concept
+  in every address people see, and makes a module a second-class destination beside Settings. The
+  collision it avoided is handled instead by reserving the platform's names in Core.
+- **Hash routing (`/#/signage`).** Rejected: every address is one page to the server, the proxy, and
+  any analytics; fragments never reach the server, so no server-side decision about a path is
+  possible; and DESIGN.md asks for real URLs.
+- **Serving the page at any module-shaped root path.** Rejected: `/definitely-not-a-real-module`
+  would become a Dashboard page, and the server would answer `200` for every mistyped address. It
+  would remove the installed-module disclosure described above, at the cost of the server no longer
+  meaning anything by a `200`.
+- **Serving only enabled, running modules' pages.** Rejected: a bookmark to a module an
+  administrator disabled would become a bare `404`, indistinguishable from a typo, instead of the
+  Dashboard explaining that the module is unavailable.
+- **Listing modules in the proxy configuration.** Rejected: every install would need a proxy edit.
+- **Reserving more names now** (`login`, `help`, `overview`, …) "just in case". Rejected: a reserved
+  name refuses a real module, so a name is reserved when the platform gets a route there and not
+  before.
+- **Putting the reserved names in the manifest grammar.** Rejected for now: it is the Ekklesia host's
+  URL space, not a module property, and would need a public-contract release for no extra safety,
+  since discovery already refuses the module before it can be installed.
+- **`react-router-dom` or another routing library.** Rejected for now; see above.
+- **Keeping "open the first module" at `/`.** Rejected: DESIGN.md makes the Overview the landing page,
+  and an address that silently means "whatever happens to be first" is not a stable address.
+
+## Consequences
+
+- A refresh, a bookmark, and a shared link land on the page that was open; Back and Forward walk the
+  Dashboard's own pages. Proven at three levels: the shell against an in-memory history; `apps/api`
+  serving the page at platform pages and installed modules' pages and the sanitized `404` everywhere
+  else; and the deploy smoke test, through the real proxy, checking platform deep links, unknown
+  names, a module's address staying served while the module is disabled and disappearing and
+  returning as it is removed and reinstalled,
+  and reloading a module's address in a real browser and requiring the same module to mount again.
+- **The Dashboard opens on the Overview, not on the first module.** A person who used to land in
+  Signage now chooses it once from the navigation, and can bookmark `/signage`.
+- **A module may not be called `account`, `api`, `assets`, `display`, or `settings`.** No known module
+  is; one that was would now fail discovery with `MODULE_ID_RESERVED` and must be renamed.
+- **Operators with their own proxy must forward module-shaped top-level paths** (the matcher above),
+  or a refresh on any page other than `/` is the proxy's `404`. The deployment guide says so.
+- `@ekklesia/shell` gains a `./dashboard-routes` subpath, and `apps/api` reads it. The surface remains
+  private; this is the same relationship `./dashboard-assets` already has.
+- The navigation landmark is labelled "Dashboard" rather than "Modules", because it now contains the
+  Overview as well as modules.
+
+## Deferred
+
+> **Cross-reference — see
+> [ADR 0061](0061-settings-hierarchy-and-module-settings-routes.md).** The Settings pages and their
+> addresses have since been defined; the rest of this list is unchanged.
+
+Each of these needs its own decision. This ADR reserves the addresses for them and decides none of
+them:
+
+- **A module's own pages** — how a module declares the pages that appear under it in the sidebar
+  (`/signage/playback`, `/signage/timelines`, `/signage/displays`), how it learns and changes its
+  current sub-path through the module UI SDK, and what an address below `/<module-id>/` means. The
+  server already serves the page there and the proxies already forward it, so that contract is a
+  manifest, SDK, and shell change with no further routing or deployment change. It is its own ADR.
+- **Return to origin** — how a module or a Settings page links into another part of the Dashboard and
+  comes back to the exact workflow that sent the person there (DESIGN.md §2.7, §4.8). It must remain
+  a validated, same-origin route decision, as ADR 0034 requires, and is designed with the module page
+  contract rather than here.
+- The Settings and Account pages themselves, the sidebar redesign, the mobile drawer, Overview cards,
+  breadcrumbs, and the installation's name in the browser tab.

docs/architecture/decisions/0058-dashboard-shell-navigation-and-lucide-icons.md

@@ -0,0 +1,192 @@
+# 0058: The Dashboard shell's navigation, and Lucide as Ekklesia's icon vocabulary
+
+- Status: Accepted
+- Date: 2026-10-14
+- Extends: [0026](0026-minimal-ekklesia-module-ui-host.md),
+  [0027](0027-dashboard-navigation-and-flat-modules.md),
+  [0039](0039-shared-design-tokens-and-elements.md),
+  [0057](0057-dashboard-urls-are-host-owned-routes.md)
+
+## Context
+
+ADR 0057 gave every Dashboard page a real address, but the shell around those pages was still the
+first proof's layout: a top header holding a hard-coded product name and a Sign out button, a fixed
+`15rem` column of text buttons, and the transitional device panel above the navigation. It had no
+icons, could not collapse, had no account area, and on a phone it was the same two columns squeezed
+until the page was unusable.
+
+DESIGN.md §4 fixes what the shell is: a collapsible left sidebar — icons and labels expanded, icons
+only collapsed, with accessible names — church identity at the top, the account area anchored at the
+bottom, no persistent top bar, and on phones a drawer with the **same** hierarchy (locked decisions
+4–8). It left one thing open that this work cannot proceed without: **which icon library**
+(§27, "Final free icon library selection"). The maintainer has decided it: Lucide.
+
+## Decision
+
+### Lucide is Ekklesia's icon vocabulary
+
+Lucide (`lucide-react`, ISC-licensed, no runtime dependencies) is the one icon set for first-party
+Ekklesia UI: the shell, `@ekklesia/ui` if it ever draws an icon, and first-party modules. Where
+Lucide has an appropriate icon, nobody draws their own; a meaning that Lucide genuinely cannot
+express is the only reason to design one, and that is a decision to record, not a shortcut.
+
+Icons are **decorative**. Every control that shows one also has a text name — visible, or visually
+hidden when the sidebar is collapsed — and every icon is `aria-hidden`. An icon never carries
+meaning alone, and its stroke is `currentColor`, so it takes its colour from the design tokens
+exactly as text does (ADR 0039). Icons are imported by name, so a bundle contains exactly the icons
+it uses.
+
+The shell imports every icon it uses in one file (`surfaces/shell/src/browser/shell-icons.tsx`),
+keyed by meaning — `overview`, `module`, `account`, `signOut`, … — so the vocabulary is reviewable
+and an icon is chosen once per meaning rather than per call site. `lucide-react` is a dependency of
+`@ekklesia/shell` only, pinned exactly (`1.48.0`); no public `@ekklesia/*` package gains it here.
+A module that needs icons in its own UI uses `lucide-react` itself, which `pnpm boundaries` already
+permits (module `.svg` presentation assets remain rejected).
+
+### Modules have no icon of their own yet
+
+Every module in the navigation is drawn with **one generic module icon** (Lucide `Blocks`). There is
+no table mapping known module ids to icons: that would be a second, host-owned answer to a question
+the module owns, and every new module would wait on a shell release to look right. A module will
+declare its own icon — by Lucide name — through the module navigation contract that also brings its
+sub-pages (manifest v9). Nothing in the manifest changes here.
+
+### The shell's layout
+
+On a wide screen (at or above `48em`, which is 768px at the default text size and follows a
+person's own text-size setting), the Dashboard is a sidebar and the page:
+
+```text
+┌────────────┬──────────────────────────────┐
+│ identity  ◂│                              │
+│ Overview   │                              │
+│ GROUP      │           the page           │
+│  Module    │                              │
+│  Module    │                              │
+│ (devices)  │                              │
+│────────────│                              │
+│ Your account                              │
+└────────────┴──────────────────────────────┘
+```
+
+- **Top:** the identity slot and the collapse toggle. The slot is a neutral placeholder (a plain mark
+  and the product name) and deliberately takes **no inputs**: the branding work (issue #101) owns
+  what goes there and where it comes from, and replaces this one component rather than undoing a
+  configuration model invented early. It is not a heading; each page's own title is.
+- **Middle:** the navigation, scrolling on its own — the Overview first, then the server's groups and
+  modules in the server's order (ADR 0027). The shell sorts and filters nothing; a disabled module is
+  absent because the navigation endpoint does not list it (ADR 0028), and its address still shows
+  *This page isn't available* (ADR 0057). Below it, while expanded, the transitional device panel
+  (ADR 0036) until Settings → Displays replaces it.
+- **Bottom:** the account control, a product-owned menu button (below).
+
+**Collapsed**, the sidebar is icons only (`4.5rem` rather than `16rem`). Each item keeps its text in
+the DOM, visually hidden, as its accessible name, and shows a tooltip on hover **and on keyboard
+focus**. The tooltip is a visual duplicate of that name, so it is `aria-hidden` and nothing is
+announced twice; it meets WCAG 2.2 §1.4.13 — dismissible with Escape without moving focus, hoverable,
+and persistent until focus or the pointer leaves — and is positioned beside the item so a scrolling
+sidebar cannot clip it. Group labels stay in the DOM for assistive technology, with a divider
+standing in for them visually. The toggle states what it does ("Collapse navigation" / "Expand
+navigation") and carries `aria-expanded` and `aria-controls`.
+
+There is **no application top bar**: the page begins at the top of its column.
+
+### Expanded or collapsed is a preference of this browser
+
+The mode is remembered in this browser's `localStorage` under `ekklesia.dashboard.sidebar` (exactly
+`expanded` or `collapsed`; anything else is ignored), so it survives a reload. It is a preference of
+the device rather than the person: a narrow laptop and a wide desktop reasonably want different
+answers, and DESIGN.md's synced personal preferences belong to the account area, which does not exist
+yet. Storage can be missing, blocked, or throw; then the mode is remembered for the page only and
+nothing breaks.
+
+The shell reads and writes it through a two-method `SidebarPreference` interface built by the entry
+point, so a synced or per-person store replaces the implementation without touching a component. The
+entry point likewise builds the browser's media query (`HostViewport`) and history (ADR 0057), and
+remains the only file in the package that touches `window`.
+
+### The account area
+
+The signed-in person's control at the bottom of the sidebar opens a product-owned menu following the
+WAI-ARIA menu button pattern: `aria-haspopup="menu"` and `aria-expanded` on the trigger; opening moves
+focus to the first item (ArrowUp opens on the last); arrow keys, Home, and End move between items;
+Escape closes it and returns focus to the trigger; Tab or a press outside closes it and leaves focus
+where it went. It contains **only actions that work today** — Sign out. Profile, personal preferences,
+appearance, and notifications belong here (DESIGN.md §4.5, §9.2) and arrive with the account pages;
+until then there is no dead link to the reserved `/account`.
+
+The shell knows the person only as an opaque user id (`/api/v1/principal`, ADR 0034), which is
+never displayed, so the control reads "Your account" with a generic avatar rather than a name or
+email. Showing the person's name needs a deliberate principal or profile projection, which this
+decision does not add.
+
+### Phones: the same navigation in a drawer
+
+Below the breakpoint the sidebar is not rendered. A single menu button ("Open navigation", with
+`aria-expanded` and `aria-controls`) sits above the page — the one control there, not a bar — and opens
+a drawer containing the **same** identity slot, navigation, current page, device panel, and account
+area, always with labels and with large-control touch targets (48px). The drawer is a real modal:
+
+- `role="dialog"`, `aria-modal="true"`, named "Navigation";
+- the page behind it is `inert`, and Tab and Shift+Tab are also kept inside it, for a browser that
+  does not yet honour `inert`;
+- opening moves focus to its close button; Escape, the close button, and the backdrop dismiss it and
+  return focus to the menu button;
+- choosing a destination closes it and moves focus to the new page (ADR 0057), including when the
+  destination is the page already open;
+- Back and Forward close it and still work.
+
+### Changing layout never disturbs the page
+
+The page's `<main>` keeps one position in the tree in both layouts, so rotating a tablet or resizing
+a window never remounts the open module. The route comes from the URL and the desktop mode from the
+preference, so neither is touched by a layout change. Only an open drawer is dropped, and focus that
+was inside navigation that has just gone away lands on the page rather than on the document.
+
+### Shell-local, not yet `@ekklesia/ui`
+
+The tooltip, the account menu, and the drawer live in the shell. ADR 0039 adds an element to
+`@ekklesia/ui` once two independent consumers need it, and today the shell is the only one; adding
+them to the public package would put unproven API in front of every module. Each is written as a
+self-contained, generic piece so it can be promoted unchanged when a module needs one. The shell's
+own stylesheet (hover, `:focus-visible`, reduced motion) is a token-only, `ek-shell-`-prefixed string
+installed into the shell's document, beside `@ekklesia/ui`'s, and cannot reach a module's isolated
+root (ADR 0040).
+
+## Alternatives
+
+- **Another icon library** (Heroicons, Phosphor, Tabler, Material Symbols). Rejected by the
+  maintainer's decision; Lucide's breadth, consistent stroke style, ISC licence, and per-icon imports
+  fit a calm interface that many modules will extend.
+- **Ekklesia's own SVG set.** Rejected: an icon set is a long-term design and maintenance commitment
+  that buys nothing a mature open set does not already have.
+- **A host-owned map of module ids to icons.** Rejected: the module owns its identity, and a map makes
+  every new module wait on a shell release. The generic icon is honest until modules declare one.
+- **A module-manifest `icon` field now.** Deferred to the manifest-v9 navigation contract, so modules
+  change manifest version once for icons, sub-pages, and the rest of that contract together.
+- **Persisting the mode on the server, per person.** Deferred to the account preferences work; the
+  interface is shaped so that store can replace this one.
+- **CSS-only responsive switching.** Rejected: the drawer must be a modal with focus management, which
+  needs the layout in script, and a media query adapter keeps it testable.
+- **A top bar holding the brand and the menu button on phones.** Rejected: DESIGN.md has no persistent
+  top bar; one button is all the phone layout needs above the page.
+- **Native `<dialog>` for the drawer.** Not chosen for now: its focus return and inertness differ
+  across the browsers a church's volunteers use, and the shell's own handling is explicit and tested.
+
+## Consequences
+
+- The Dashboard has the shell DESIGN.md describes on desktop, tablet, and phone, proven in unit tests
+  against in-memory history, viewport, and preference, and in the deploy smoke test in a real browser:
+  at desktop size (the account menu's Sign out) and at phone size (the drawer's focus, Escape, and
+  choosing a module), and back again.
+- Sign out moved from the header into the account menu.
+- The hard-coded product name now lives in one placeholder component, waiting for branding; there is
+  no other person-facing "Ekklesia" in the authenticated shell.
+- `@ekklesia/shell` depends on `lucide-react`. No public package changed.
+
+## Deferred
+
+Church branding in the identity slot (issue #101); module-declared icons and module sub-pages in the
+sidebar (manifest v9); group icons and the navigation editor; the account pages and synced personal
+preferences, including a per-person sidebar mode; showing the person's name or picture; Settings in the
+navigation; promoting the tooltip, menu, or drawer to `@ekklesia/ui`.

docs/architecture/decisions/0059-shared-interaction-primitives.md

@@ -0,0 +1,196 @@
+# 0059: Shared interaction primitives — confirmation, toasts, errors, loading, Back, and no native dialogs
+
+- Status: Accepted
+- Date: 2026-10-15
+- Extends: [0034](0034-host-owned-browser-authentication.md),
+  [0039](0039-shared-design-tokens-and-elements.md),
+  [0040](0040-module-stylesheets-and-artifact-isolation.md),
+  [0057](0057-dashboard-urls-are-host-owned-routes.md),
+  [0058](0058-dashboard-shell-navigation-and-lucide-icons.md)
+
+## Context
+
+Every Stage 1 surface still to come — Settings, Displays, module management, Signage as the reference
+module — needs the same few interactions DESIGN.md fixes once for the whole product: a product-owned
+confirmation for meaningful actions, with typed confirmation for the serious ones (§8); top-center
+toasts (§7.4); errors that say what failed and keep technical detail out of the way (§7.3); skeleton
+loading that keeps context visible (§7.1); Back plus a page title for nested pages, returning to the
+workflow that sent the person there (§2.7, §4.8); and no `window.alert`, `confirm`, or `prompt`
+anywhere (§8.1).
+
+`@ekklesia/ui` (ADR 0039) had the presentation of some of these and deliberately not the behaviour.
+ADR 0039 deferred "a focus-trap utility"; the package's `Dialog` said a focus trap belonged "in one
+place, tested, not sprinkled through call sites"; its `Toast` said there was "deliberately no toast
+manager", because a package-level singleton would be shared mutable state across every isolated
+artifact on a page (ADR 0040); and ADR 0057 deferred return-to-origin. The only guard against native
+dialogs was a regular expression in one shell test.
+
+Each of these is now needed by more than one consumer, which is ADR 0039's bar for adding to the
+package.
+
+## Decision
+
+### Placement
+
+The primitives with more than one consumer go in `@ekklesia/ui`; what depends on the Dashboard's own
+routes stays in the shell.
+
+| Where | What |
+| --- | --- |
+| `@ekklesia/ui` | `ConfirmationDialog`; `ToastProvider` and `useToasts`; `ErrorState` (extended); `Skeleton` and `SkeletonGroup`; `PageHeader` (extended with `back`); `Dialog` (now with a focus trap) |
+| `@ekklesia/shell` | `parseReturnTarget` and `dashboardBack`: which addresses are safe to go back to |
+| Root `biome.json` and `tests/native-dialogs.test.ts` | the native-dialog guard |
+
+The public additions are components and their prop types only. The focus trap, the duration rule,
+the phrase matcher, and the detail sanitizer are internal: tested, and used by the components, but
+not promised to callers. `@ekklesia/ui` gains no dependency — its few glyphs (`←`, `✕`, the status
+symbols) are text, as its status symbols already were, so a module bundle does not inherit an icon
+library's licence material through it.
+
+### One focus trap, used by every modal surface
+
+`useFocusTrap` remembers what had focus, moves focus into the surface, wraps Tab and Shift+Tab at its
+edges, and returns focus to the remembered control when the surface closes. It reads the focused
+element from the surface's **own root node**, so it works inside a module's shadow root, where the
+document would only report the shadow host (ADR 0040). `Dialog` uses it, so every dialog — including
+the shell's existing device-revocation dialog — now traps and restores focus.
+
+`Dialog` stays rendered in place, never portalled out of an artifact's isolated root. Its scrim
+covers the viewport and takes every pointer press, so nothing behind it can be activated, and does
+not dismiss the dialog. Escape is now handled on the dialog element and stopped there, rather than on
+the whole document, so a drawer or menu the dialog was opened from no longer closes with it. A caller
+can make Escape inert while something is in progress (`dismissible={false}`), and give the dialog an
+accessible description.
+
+### Confirmation: three severities, chosen by the caller
+
+`ConfirmationDialog` is one element for a simple confirmation, a destructive one, and a destructive
+one that also requires a typed phrase. The consuming feature chooses; the element never upgrades or
+downgrades severity.
+
+- It is a `Dialog`: named by its title, described by its description, focus trapped and restored.
+- **Destructive** is marked by a symbol in the title and on the action, a heavier frame, and the
+  danger button — never by colour alone — and focus starts on **Cancel**, so a stray Enter is safe.
+- **Typed confirmation** is `requiredPhrase`: `DELETE`, or a resource's own name. Confirm is disabled
+  until the typed value matches exactly and case-sensitively, forgiving only surrounding whitespace and
+  Unicode composition (NFC), which phone keyboards introduce unasked. The field is labelled with the
+  phrase, has autocapitalize, autocorrect, and spellcheck off, says politely whether it matches, and
+  submits on Enter once it does. The typed value is forgotten whenever the dialog closes.
+- **Busy** disables both actions, makes Escape inert, and marks the form `aria-busy`, so an action in
+  flight cannot be abandoned half-done; the caller closes the dialog when it finishes.
+
+### Toasts: a system per React tree, never a package singleton
+
+`ToastProvider` owns one tree's toasts, timers, and top-center region; `useToasts()` returns
+`show(options) → id` and `dismiss(id)`. ADR 0040's isolation is why there is no package-level store:
+each module artifact and the shell render their own tree, and a store shared through the package
+would be mutable state reaching across all of them.
+
+- **Severities:** success, info, warning, and error (`danger`), each with its symbol.
+- **Duration:** never under about three seconds (DESIGN.md §7.4), longer for longer text and for
+  warnings, up to a ceiling. An error stays until dismissed unless its caller gives it a duration — a
+  routine validation error, say.
+- **Calm under load:** at most three routine toasts at once, newest on top; an error is listed first
+  and never displaced by a routine toast; an identical toast already showing is refreshed rather than
+  stacked.
+- **Accessible:** the region's polite and assertive live regions exist before any toast arrives, so
+  additions are announced — routine toasts politely, errors assertively — and no toast is a nested
+  live region of its own. Timers pause while the pointer is over the region or focus is in it (WCAG
+  2.2 §2.2.1). Every toast has a dismiss control named for it; Escape dismisses the focused toast; when
+  the last one goes, focus returns to where it was.
+- **Clean:** every timer is cleared when its toast goes and when the provider unmounts.
+
+The shell does not mount a provider yet, and nothing is wired to toasts merely to show them. A module
+mounts its own provider today. One host-owned region that modules post into would need a module UI
+SDK contract, and is deferred.
+
+### Errors: plain message first, technical detail on request
+
+`ErrorState` keeps its existing props and adds `actions` (recovery and remedies — a caller that knows
+the viewer can administer the problem passes those remedies too; the element has no notion of roles),
+`details` (plain text), `reference` (a diagnostic id), and `announce` (`role="alert"` by default, off
+for an error that is part of a page's initial content). Details and the reference sit in a closed
+`<details>` disclosure, so they never dominate. `details` is a string, chosen deliberately: never an
+exception, so a stack cannot arrive by accident. It is rendered as text, so markup in it is shown and
+never interpreted, with control characters removed and its length bounded (2,000 characters).
+
+### Skeletons: shape without pretence
+
+`Skeleton` (text line, block, circle) is decorative and hidden from assistive technology.
+`SkeletonGroup` is the region it stands in for: `role="status"`, `aria-busy`, and one label announced
+once ("Loading displays") rather than every placeholder. Placeholders pulse gently and stop for a
+person whose system asks for reduced motion; there is no percentage, because there is no progress to
+report. When the personal reduced-motion preference arrives, it overrides the same single rule.
+
+### Back: a validated origin, or the page's own parent
+
+`PageHeader` takes an optional `back: { label, href?, onBack }` and renders it above the page's one
+`h1`: a real link when it has an address (so it can be opened in a new tab), a button otherwise.
+Breadcrumbs are not part of it (DESIGN.md §4.8). The element knows nothing about routes; the host
+decides where Back goes.
+
+In the shell, `dashboardBack(history, { returnTarget, fallback, label })` decides. A return target is
+input from whoever built the link, so it is hostile until proven otherwise, and ADR 0034 requires any
+return location to be a validated, same-origin route decision. `parseReturnTarget` accepts only a
+string of at most 2 KiB that begins with exactly one `/`, contains no whitespace, control character,
+backslash, percent-encoded slash, backslash, or dot, and no dot-segment, query, or fragment, and names
+a page the Dashboard actually has. Its answer is a destination, never the raw string, so Back can only
+go to the canonical address of a real page. Without a valid target, Back goes to the page's declared
+parent. It never calls the browser's `history.back()`: after a bookmark or a link from outside, the
+previous entry is not the Dashboard's.
+
+How a link *carries* a return target — a query parameter, or something the module navigation contract
+defines — is deliberately not decided here (ADR 0057); whatever carries it hands it to
+`parseReturnTarget` first.
+
+### No native dialogs, enforced repository-wide
+
+Biome's scope-aware `suspicious/noAlert` is an **error** in the root `biome.json`, which every package,
+surface, and template in this repository lints against. It reports `alert(`, `confirm(`, and
+`prompt(`, called bare, through `window` or `globalThis`, or by computed member, and leaves alone a
+local function that shares the name, a method such as `dialog.confirm()`, a property such as
+`onConfirm`, a string, and a comment. `tests/native-dialogs.test.ts` proves both directions against
+fixtures with the repository's own configuration, and scans browser source for the two forms the rule
+cannot see — a call through `self`, `top`, `parent`, or `frames`, and borrowing the function without
+calling it. The shell's earlier regular-expression test is superseded and removed.
+
+A module repository has its own lint configuration and is outside this repository's reach. It should
+enable the same rule; the module development guide says so.
+
+## Alternatives
+
+- **A third-party toast or dialog library.** Rejected: the behaviour is small, it must work inside
+  isolated roots without portals, and a framework would bring its own styling and a dependency into
+  every module bundle.
+- **A package-level toast singleton (`toast("Saved")` from anywhere).** Rejected for ADR 0040's
+  reason: shared mutable state across every artifact on the page.
+- **Native `<dialog>` with `showModal()`.** Not chosen for now: it promotes the dialog to the top
+  layer, outside an artifact's isolated root, and its focus return and inertness differ across the
+  browsers churches use.
+- **`history.back()` as Back's fallback.** Rejected: it can leave the Dashboard.
+- **Accepting any same-origin path as a return target.** Rejected: an address the Dashboard has no
+  page for is not a workflow to return to, and a narrow grammar is easier to prove safe.
+- **Typed confirmation that ignores case.** Rejected: typing `DELETE` is meant to be deliberate.
+- **Enforcing native dialogs at module build time** (`@ekklesia/module-ui-build`). Not chosen: the build
+  sees a bundle without scope information, so it would either miss shadowed names or report code in
+  dependencies; a scope-aware lint rule in source is the accurate tool.
+- **Exporting the focus trap and helpers.** Deferred: they are tested internals until a caller needs
+  them outside these components.
+
+## Consequences
+
+- Later Stage 1 pages compose these instead of inventing their own, and modules get the same ones.
+- `Dialog`'s Escape is handled on the dialog element rather than on the document. A caller that relied
+  on Escape reaching the document while focus was elsewhere sees a change; with focus trapped inside
+  the dialog, that situation no longer arises. The existing test was updated accordingly.
+- `@ekklesia/ui` grows by two components, a provider and its hook, and three extended props. It remains
+  dependency-free beyond `@ekklesia/design-tokens`.
+- `pnpm lint` now fails on any native dialog in this repository.
+
+## Deferred
+
+A host-owned toast region that module UI posts into through the module UI SDK; how a link carries a
+return target (with the module navigation contract); exporting the focus trap; migrating the shell's
+navigation drawer onto the shared focus trap; replacing the device panel's revocation dialog with a
+`ConfirmationDialog` (it moves to Settings → Displays); a personal reduced-motion override; and the
+module repositories' own lint configuration.

docs/architecture/decisions/0060-light-dark-system-theme-and-motion.md

@@ -0,0 +1,189 @@
+# 0060: Light, Dark, and System appearance; reduced motion; and one radius scale
+
+- Status: Accepted
+- Date: 2026-10-15
+- Extends: [0039](0039-shared-design-tokens-and-elements.md),
+  [0040](0040-module-stylesheets-and-artifact-isolation.md),
+  [0058](0058-dashboard-shell-navigation-and-lucide-icons.md),
+  [0059](0059-shared-interaction-primitives.md)
+
+## Context
+
+DESIGN.md requires every normal first-party interface to support Light, Dark, and System, with System
+the default and a person's choice syncing across their devices (§3.2, locked decisions 25–26);
+reduced motion following the operating system by default, with a personal override (§3.3, locked
+27); a configurable, bounded corner radius (§3.6); shared semantic tokens for every colour (§3.1);
+and WCAG AA (§24, locked 92).
+
+ADR 0039 built the semantic token registry and explicitly deferred "a dark theme or any second theme".
+The registry had one value per token and was installed as a single `:root` rule. Modules already
+consumed it the right way: every module artifact mounts in an isolated shadow root (ADR 0040), and
+CSS custom properties inherit through shadow boundaries, so a module reads `var(--ekklesia-…)`
+without importing anything at run time.
+
+Measured before this change, the light theme did not meet AA in two places: muted text was 4.10–4.43:1
+on the page, canvas, and surface (4.5:1 required), and form controls drew their boundary in
+`border.base`, 1.38:1 against a surface (3:1 required for a control's boundary, §1.4.11).
+
+## Decision
+
+### A token may vary by colour scheme, and by motion
+
+`DesignTokenInput` gains two optional values, validated exactly like `value`:
+
+- **`dark`** — the token's value in the dark scheme. Every colour, border colour, and shadow has one;
+  lengths, weights, and font stacks do not, and keep one value.
+- **`reduced`** — the token's value when motion is reduced. Every motion token has one, and it is zero.
+
+A registry built without either emits exactly the single rule it always did. The registry adds
+`valueFor(name, scheme)`.
+
+### The stylesheet resolves the mode, in CSS
+
+`installEkklesiaDesignTokens` installs one stylesheet that selects values by CSS alone:
+
+```css
+:root { color-scheme: light; /* every default (light) value */ }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-ekklesia-appearance="light"]) { color-scheme: dark; /* dark values */ }
+}
+:root[data-ekklesia-appearance="dark"] { color-scheme: dark; /* dark values */ }
+
+@media (prefers-reduced-motion: reduce) {
+  :root:not([data-ekklesia-motion="allow"]) { /* motion durations: 0 */ }
+}
+:root[data-ekklesia-motion="reduce"] { /* motion durations: 0 */ }
+```
+
+(and the same with `:host(…)` for an isolated root that has no inheriting ancestor).
+
+Because the browser resolves it:
+
+- **System is live.** An operating-system change restyles the page immediately — no script, no
+  listener, no reload.
+- **An explicit choice wins.** `light` or `dark` on the theme root overrides the system; `system` (or
+  no attribute) follows it.
+- **Modules follow without a contract change.** Custom properties and `color-scheme` inherit into
+  every module's shadow root, so the same switch restyles module UI — Signage included — with no SDK
+  change and no module release. This was verified in a real browser across the shadow boundary.
+- **Native UI follows too.** `color-scheme` goes with the tokens, so form controls and scrollbars
+  match the scheme; nothing critical depends on browser-default styling.
+
+### A small appearance API in `@ekklesia/design-tokens`
+
+Framework-free and dependency-free, like the rest of the package:
+
+- `EkklesiaAppearance` = `system` | `light` | `dark`; `EkklesiaMotionPreference` = `system` | `reduce` |
+  `allow` — the model DESIGN.md asks for, including a future "allow" override of a reduced-motion
+  system.
+- `parseEkklesiaAppearance` / `parseEkklesiaMotionPreference` read untrusted stored values; anything
+  unrecognised is `system`.
+- `resolveEkklesiaColorScheme` / `resolveEkklesiaReducedMotion` say what is in effect.
+- `createEkklesiaThemeController({ target, matchMedia?, appearance?, motion? })` sets the two attributes
+  **immediately** and answers `colorScheme()`, `reducedMotion()`, `setAppearance`, `setMotion`, and
+  `subscribe` (which also reports system changes) for code that needs to know.
+
+The host owns the choice. A module reads the theme through tokens and never sets appearance; nothing
+in the module UI contract changed.
+
+### The shell applies it before React renders
+
+`surfaces/shell/src/browser/main.tsx` creates the controller on `document.documentElement` before the
+first render, with `system` for both. That is the **bootstrap hook** for the account preferences
+work: it will read a remembered choice synchronously and pass it here, so an explicit Light or Dark is
+in place before the first frame. Nothing is persisted in this decision, and there is no temporary
+user-facing switch to remove later.
+
+The Dashboard page declares `<meta name="color-scheme" content="light dark">` and takes its body
+background and text colour from tokens, so the browser's own canvas is already in the system's scheme
+before any script runs: a dark system never flashes white while the shell loads. (A future explicit
+choice opposite to the system can still show the system's empty canvas for the moment before the
+module script runs; that is the remaining cost of a page with no inline script.)
+
+The **display host stays Light**, whatever its operating system prefers. A screen in a lobby is
+configured by whoever set it up, not by a person's appearance preference, and Stage 0 displays must
+look exactly as they did; motion there still follows the system.
+
+### The dark theme is designed, not inverted
+
+Teal-tinted charcoal backgrounds in an elevation ladder (page `#0e1615` → canvas → surface → raised),
+never pure black; primary text `#e4edeb`, never pure white; the same teal accent, slightly lifted, with
+dark text on it rather than a glowing control; status colours desaturated to sit on dark tints; deeper
+shadows; and a darker overlay. It is the same product in both schemes.
+
+### Contrast is tested, and two light pairings were fixed
+
+`packages/design-tokens/tests/contrast.test.ts` computes WCAG contrast for 41 pairings the elements
+actually use — text on every background tier, quiet and selected navigation, primary and danger
+buttons, field hints and errors, status notices and badges, control boundaries, and focus rings — in
+both schemes: 4.5:1 for text, 3:1 for control boundaries and focus indication. A real-browser check of
+rendered elements in both schemes agrees.
+
+Two intentional, visible light-theme changes make it pass:
+
+- `text.muted` darkens from `#6c7b77` to `#5d6d69` (5.44:1 on a surface).
+- A new **`border.control`** token (`#7a8d89`, 3.5:1) draws form controls' boundaries instead of
+  `border.base`, which stays the quieter decorative border of cards and panels. `border.strong` is
+  redefined to be stronger than `border.control` in both schemes, since it is the hovered control's
+  border.
+
+`background.placeholder` is new: the skeleton's colour, visibly distinct from the page and a surface
+in both schemes (it had used `background.inset`, which in a dark scheme is correctly darker than the
+page and made skeletons vanish).
+
+### Motion and radius are tokens
+
+A new **`motion`** category: `motion.duration-short` (160ms; transitions such as the sidebar and a
+toast arriving) and `motion.duration-ambient` (1.6s; a loading placeholder's pulse, and the spinner
+at 0.625 of it). Both are zero when motion is reduced, so an element that animates for a motion-token
+duration needs no reduced-motion rule of its own; the per-element rules in `@ekklesia/ui` and the
+shell are removed, which is also what lets an explicit `allow` work.
+
+**`radius.scale`** (default `1`) multiplies `radius.sm`, `radius.md`, and `radius.lg`, which become
+`calc(<today's value> * var(--ekklesia-radius-scale))`; `radius.none` and `radius.pill` do not scale.
+At the default nothing looks different. A later appearance or branding control changes one value to
+make every corner squarer or rounder; it should offer a bounded range (DESIGN.md §3.6).
+
+### Every Dashboard colour and corner is a token, and that is checked
+
+The sign-in, verification, and recovery card (`AuthCard`) and the module loading and error text
+(`ModuleUiFrame`) carried literal colours; they now use tokens, and the sign-in action is the
+platform's primary button. `tests/theme-guards.test.ts` scans the shell's Dashboard source and
+`@ekklesia/ui` for raw colours and literal corner radii, and `@ekklesia/ui`'s own tests require its
+stylesheet's colours, radii, and durations to be tokens. The display host is the named exception,
+pinned light, until displays move to Settings → Displays.
+
+## Alternatives
+
+- **Toggle a class from JavaScript on OS changes.** Rejected: CSS media queries already do it, live,
+  in every isolated root, with nothing to wire up or forget to unsubscribe.
+- **A second token registry or stylesheet per theme.** Rejected: two registries drift; one token with
+  two values cannot lose its dark half without a test failing.
+- **Automatic dark values (inverting, or adjusting lightness).** Rejected: an inverted theme is exactly
+  the naive dark mode DESIGN.md warns against, and generated colours would not be reviewable.
+- **Inline bootstrap script to apply a stored choice before paint.** Rejected: the Dashboard has no
+  inline script so a strict `script-src` needs no exception; the meta element covers the system case.
+- **Per-element `prefers-reduced-motion` rules.** Replaced: they cannot honour an explicit `allow`, and
+  every new animation would have to remember one.
+- **Many radius tokens per component.** Rejected: one multiplier over a three-step scale is what a
+  bounded "roundness" control needs.
+- **Letting the display host follow the system.** Rejected for now: it would change Stage 0 screens
+  overnight when a kiosk's OS setting changes.
+
+## Consequences
+
+- The Dashboard and every module UI are Light or Dark by the operating system today; an explicit choice
+  is one call once the account preferences exist.
+- `@ekklesia/design-tokens` adds the `motion` category, `dark` and `reduced` values, `valueFor`, three
+  tokens (`border.control`, `background.placeholder`, `radius.scale`) plus two motion tokens, and the
+  appearance API. `@ekklesia/ui` uses them. Both changes are additive; code that switches exhaustively
+  over `DesignTokenCategory` sees one more case.
+- Visible changes in light: slightly darker muted text and form-control borders, and the sign-in card
+  in the platform's colours.
+
+## Deferred
+
+The Account → Appearance page and synced preference storage; a church theme editor and per-installation
+overrides of dark values; branding; the display host's own appearance and its pairing and offline
+screens' colours; the bounded radius range a future control offers; and exposing the resolved scheme
+to module code (modules read it through tokens today).

docs/architecture/decisions/0061-settings-hierarchy-and-module-settings-routes.md

@@ -0,0 +1,177 @@
+# 0061: Settings is one host-owned hierarchy; module lifecycle is Discover, and a module's settings live at `/settings/<module-id>`
+
+- Status: Accepted
+- Date: 2026-10-15
+- Extends: [0027](0027-dashboard-navigation-and-flat-modules.md),
+  [0028](0028-module-operational-lifecycle.md),
+  [0029](0029-module-configuration-and-secrets.md),
+  [0057](0057-dashboard-urls-are-host-owned-routes.md),
+  [0058](0058-dashboard-shell-navigation-and-lucide-icons.md),
+  [0059](0059-shared-interaction-primitives.md)
+
+## Context
+
+DESIGN.md makes Settings the one home for shared administration (§9): church-wide configuration in
+Settings, personal configuration under the account area (§9.2), every module's settings reachable
+through Settings rather than an independent system inside the module (§9.3), and people without
+management permission not shown administration they cannot carry out (§9.2). ROADMAP §5.3 asks that
+the navigation and ownership model exist before every category is functional.
+
+ADR 0057 reserved `/settings` and served the Dashboard page throughout it, but defined no page there.
+Three things had to be decided before any section could be built: the address of each page, how the
+Settings hierarchy sits in the shell's one sidebar (ADR 0058), and how the browser learns which
+Settings destinations a person may see — it knew only that they were signed in, plus each module's
+own permission hints (ADR 0026).
+
+## Decision
+
+### The URL model
+
+```text
+/settings                           the Settings landing page
+/settings/general                   General: how this installation works for everyone
+/settings/branding                  Branding: the church's name, logo, and colours
+/settings/displays                  Displays: paired screens
+/settings/discover                  enters Discover at Browse (respelled in place, below)
+/settings/discover/browse           Browse: find and install modules
+/settings/discover/installed        Installed: see and manage installed modules
+/settings/discover/updates          Updates: module and platform updates
+/settings/system                    System: version, health, and diagnostics
+/settings/<module-id>               that module's settings
+/settings/<module-id>/…             reserved for a module's deeper settings pages
+```
+
+The distinction is the decision:
+
+- **`/settings/discover/…` is module lifecycle** — finding, installing, turning on and off, inspecting,
+  updating, and eventually removing modules.
+- **`/settings/<module-id>` is configuring that module.** It is never nested under Discover or under a
+  `modules` segment: a module's settings are a first-class Settings destination.
+
+**"Modules" is the product's word**, in the interface as in the architecture — never "features",
+"apps", "extensions", or "add-ons". "Discover" is the name of a navigation destination, not a
+replacement for it: inside Discover the pages say "Discover modules", "Installed modules", and "Module
+updates". Implementation terms — Core, a platform module — never appear.
+
+**Entering Discover opens Browse, at one address.** `/settings/discover` reads as Browse, whose
+canonical spelling is `/settings/discover/browse`; the shell respells it in place (`replace`, no new
+history entry), exactly as it corrects a trailing slash (ADR 0057). There is one meaningful Browse
+address rather than two, and Discover's own item in the navigation links to it.
+
+**`/settings` is a real landing page**, never a redirect to the first section: the two groups the
+person may open, each item named and described in a line. It is an index, not a dashboard.
+
+Anything deeper than these addresses is `not-found` in the shell until its page exists. The API already
+serves the page throughout `/settings/*`, and the proxies already forward it (ADR 0057), so deeper pages
+need no server or deployment change.
+
+### Module ids cannot collide with a Settings section
+
+A module id is a **stable URL identifier**: its page is `/<module-id>` and its settings
+`/settings/<module-id>`. So the platform's own Settings section names join the top-level names in Core's
+one list, `RESERVED_MODULE_IDS` (`core/src/modules/reserved-ids.ts`), now in two documented groups:
+
+| Group | Names |
+| --- | --- |
+| Top-level namespaces (`/<name>`) | `account`, `api`, `assets`, `display`, `settings` |
+| Settings sections (`/settings/<name>`) | `branding`, `discover`, `displays`, `general`, `system` |
+
+Discovery refuses a module that declares any of them (`MODULE_ID_RESERVED`), at startup, in
+`pnpm modules:validate`, and in package verification. Look-alikes stay valid — `general-info`,
+`discovery`, `display-board`, `systems` — and so does `modules`, since module management is Discover.
+Discover's views live beneath `/settings/discover/`, so they cannot collide with a module and are not
+reserved. `apps/api` tests hold Core's Settings group equal to the shell's `SETTINGS_SECTIONS`, so a
+section cannot be added to one without the other.
+
+### Settings sits in the same sidebar
+
+Settings is one item in the shell's one navigation (ADR 0058), after the modules and above the account
+area. While a Settings page is open it expands in place into two labelled groups — **Platform**
+(General, Branding, Displays, Discover, System) and **Modules** (each module's settings) — and inside
+Discover, Browse, Installed, and Updates beneath it. The rest of the navigation stays where it is, so
+leaving Settings is one click on any other item; it is not a second application with its own shell.
+The phone drawer shows the identical hierarchy. Exactly one item carries `aria-current="page"`.
+
+### Which destinations a person sees is evaluated by the server
+
+`GET /api/v1/dashboard/settings` (`apps/api/src/dashboard-settings-routes.ts`), readable by any signed-in
+person (`core.modules.ui.read`, like the navigation beside it), answers which sections and which modules'
+settings this person may see, through Core's one authorization evaluator:
+
+| Destination | Shown to |
+| --- | --- |
+| Displays | `core.devices.manage` |
+| Discover | `core.modules.lifecycle.manage` — deciding which modules run |
+| a module's settings | `core.modules.configuration.manage` (ADR 0029), for every module that declares configuration |
+| General, Branding, System | the **platform owner** only, until each defines its own permission |
+
+General, Branding, and System have no permission yet because nothing in them exists to authorize.
+Rather than invent three speculative permissions, they are shown only to the platform owner — the one
+principal who already holds every permission — and each gains a delegable permission in the work that
+builds it. Platform updates in Discover → Updates will likewise get their own permission then.
+
+A module **has settings** when its manifest declares configuration (ADR 0029). That is the existing,
+authoritative signal; no manifest change is needed. A disabled or blocked module with settings is listed
+with `available: false`.
+
+These are **presentation hints, not authority**, as ADR 0026's are. Every route behind a section keeps
+its own enforcement, unchanged, and a test proves the data behind each is still refused without its
+permission. An evaluation failure is a `503`, never an empty answer that would look like a permissions
+problem. The browser decides nothing about permissions itself.
+
+### What each Settings address shows
+
+- A section or module the person may see shows its page.
+- A section the person may not see, or a module they know of but cannot configure (or that has no
+  settings), shows *These settings aren't available* — without saying which.
+- A disabled module's settings show *This module is turned off*. Never a silent redirect.
+- A name that is no module the person knows of is *Page not found*.
+- When the Settings view cannot be loaded, the Settings link is withheld and its pages say so, with
+  Retry; the rest of the Dashboard keeps working.
+- When a person can see nothing in Settings, the Settings link is not shown at all.
+
+### Pages are honest placeholders
+
+Every section, Discover view, and module's settings page in this decision is a placeholder: Back to
+Settings (`PageHeader`, ADR 0059), a title and one-line description, and *Not available yet* with what
+will happen there. No fake controls, no dead fields. The work that builds each replaces its placeholder.
+
+Back goes to the page's parent, Settings. A validated return target (ADR 0059) takes precedence once
+something carries one, so `/signage` → `/settings/signage` can return to `/signage`; how a module links
+into its settings with a return target is the module navigation contract's to define.
+
+## Alternatives
+
+- **`/settings/modules` for module management, and `/settings/modules/<module-id>` for a module's
+  settings.** Rejected: it nests a module's configuration under its lifecycle and makes "configure
+  Signage" two levels deep. Discover is lifecycle; `/settings/<module-id>` is configuration.
+- **`/settings/discover` as a page of its own beside `/settings/discover/browse`.** Rejected: two
+  meaningful addresses for one view.
+- **Redirecting `/settings` to the first section.** Rejected: a landing page says what Settings holds,
+  and the first section differs per person.
+- **Replacing the module navigation with the Settings hierarchy while in Settings.** Rejected: DESIGN.md
+  keeps one sidebar with Settings in it (§4.2), and leaving Settings should not require a second
+  navigation model.
+- **Probing each section's API for a `403` from the browser.** Rejected: several requests per page view,
+  and it confuses "may not" with "failed".
+- **Defining General, Branding, and System permissions now.** Rejected as speculative; the owner-only
+  interim rule is deny-by-default with the owner's existing bypass.
+- **A manifest field declaring "has settings".** Unnecessary: declared configuration already says so;
+  module-owned settings pages arrive with the module navigation contract.
+- **Reserving Discover's view names.** Unnecessary: they live under `/settings/discover/`.
+
+## Consequences
+
+- Every later Settings section has an address, a navigation entry, a permission rule, and a placeholder
+  to replace.
+- A module may not be called `branding`, `discover`, `displays`, `general`, or `system`. No known module
+  is; one that was would fail discovery and must be renamed.
+- The shell asks one more endpoint at bootstrap, alongside the navigation.
+- A person without any administrative permission sees no Settings link.
+
+## Deferred
+
+The real General, Branding, Displays, Discover (catalog, installation, lifecycle, updates), and System
+pages, and each one's permission; module settings screens and their deeper pages; how a module links to
+its settings with a validated return target (the module navigation contract, manifest v9); moving the
+transitional device panel into Settings → Displays; and the account area.