feat: define module database access

Introduce ModuleDatabase (a typed, restricted Drizzle query surface) and the frozen
ModuleRuntimeServices boundary in @ekklesia/contracts, and thread the same services object
through Core's module start/stop lifecycle hooks and apps/api's authorized module HTTP handler
context. apps/api builds the facade via a new core/src/modules/database.ts view (createModuleDatabaseView)
over the one existing shared PostgreSQL pool, alongside the identity and authorization views, and
wires it into startApi's fixed startup order ahead of Identity/Authorization construction.
Registration stays database-free; a module reaches its database only through an authorized start,
stop, or HTTP handler invocation.

apps/api/src/app.ts

@@ -1,4 +1,8 @@
-import { isAuthenticatedPrincipal, type RegisteredModuleHttpRoute } from "@ekklesia/contracts";
+import {
+  isAuthenticatedPrincipal,
+  type ModuleRuntimeServices,
+  type RegisteredModuleHttpRoute,
+} from "@ekklesia/contracts";
 import type {
   AuthorizationEvaluator,
   AuthorizationStore,
@@ -28,6 +32,11 @@ export interface CreateApiAppOptions {
    * caller not exercising modules must say so explicitly (an empty frozen array), never rely on an
    * implicit fallback. */
   readonly moduleRoutes: readonly RegisteredModuleHttpRoute[];
+  /** The same frozen services object the caller's started module runtime already passed to every
+   * module's `start`/`stop` hooks (`apps/api/src/server.ts`) — reference-identical, never a fresh
+   * object built here, so a module's HTTP handlers and lifecycle hooks share exactly one
+   * `ModuleDatabase` for the lifetime of this API runtime. */
+  readonly moduleServices: ModuleRuntimeServices;
   readonly runtime: EkklesiaIdentityRuntime;
   /** Exact allowed browser origins. Never a wildcard; combined with `credentials: true`, only an
    * exact, reflected match is ever returned in `Access-Control-Allow-Origin`. Also the trusted set
@@ -147,6 +156,7 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
     evaluator: options.authorization.evaluator,
     registry: options.authorization.registry,
     runtime,
+    services: options.moduleServices,
     trustedOrigins: allowedOrigins,
   });
 

apps/api/src/database.ts

@@ -1,26 +1,30 @@
+import type { ModuleDatabase } from "@ekklesia/contracts";
 import {
   type AuthorizationDrizzleDatabase,
   createAuthorizationDrizzleView,
 } from "@ekklesia/core/authorization";
 import { createValidatedPostgresPool, type PostgresPoolOptions } from "@ekklesia/core/database";
 import { createIdentityDrizzleView, type IdentityDrizzleDatabase } from "@ekklesia/core/identity";
+import { createModuleDatabaseView } from "@ekklesia/core/modules";
 
 export interface ApiDatabaseHandle {
   readonly authorization: AuthorizationDrizzleDatabase;
   readonly identity: IdentityDrizzleDatabase;
+  readonly module: ModuleDatabase;
   /** Closes the one shared pool exactly once, regardless of how many typed views were created
    * over it. Safe to call from both a startup-failure cleanup path and normal shutdown. */
   readonly close: () => Promise<void>;
 }
 
 /**
- * Composes the one physical PostgreSQL pool this process uses for both Core's identity and
- * authorization schemas: one validated, timeout-bounded `pg.Pool` (`createValidatedPostgresPool`,
- * `@ekklesia/core/database`), wrapped by two independent typed Drizzle views
- * (`createIdentityDrizzleView`, `createAuthorizationDrizzleView`). Neither Core domain owns or
- * closes the pool in this composition — `close()` here is the only thing that ever calls
- * `pool.end()`. `createIdentityDrizzleDatabase`/`createAuthorizationDrizzleDatabase` remain
- * available, unaffected, and independently testable for callers that only need one domain.
+ * Composes the one physical PostgreSQL pool this process uses for Core's identity and
+ * authorization schemas plus the module database facade: one validated, timeout-bounded
+ * `pg.Pool` (`createValidatedPostgresPool`, `@ekklesia/core/database`), wrapped by three
+ * independent typed Drizzle views (`createIdentityDrizzleView`, `createAuthorizationDrizzleView`,
+ * `createModuleDatabaseView`). No domain owns or closes the pool in this composition — `close()`
+ * here is the only thing that ever calls `pool.end()`. `createIdentityDrizzleDatabase`/
+ * `createAuthorizationDrizzleDatabase` remain available, unaffected, and independently testable
+ * for callers that only need one domain.
  */
 export function createApiDatabase(
   databaseUrl: string,
@@ -32,5 +36,6 @@ export function createApiDatabase(
     authorization: createAuthorizationDrizzleView(pool),
     close,
     identity: createIdentityDrizzleView(pool),
+    module: createModuleDatabaseView(pool),
   });
 }

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

@@ -1,6 +1,7 @@
 import type {
   ModuleId,
   ModuleRouteHandlerContext,
+  ModuleRuntimeServices,
   RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
 import type { Context, Hono } from "hono";
@@ -24,6 +25,11 @@ const STRIPPED_CORS_RESPONSE_HEADERS = [
 
 export interface ModuleHttpRoutesOptions extends AuthorizationMiddlewareOptions {
   readonly trustedOrigins: ReadonlySet<string>;
+  /** The same frozen services object the started module runtime's `start`/`stop` hooks already
+   * 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;
 }
 
 /** Never carries the offending permission id, route path, module id, or any other configuration
@@ -149,7 +155,11 @@ function sanitizeModuleResponse(response: Response): Response {
  * implicit `HEAD` handling, which re-enters this exact same middleware chain and strips the
  * response body afterward — there is no separate `HEAD` registration or permission path.
  * `route.handler` is invoked only after authorization succeeds, with the raw Fetch `Request` and a
- * frozen context — never a Hono `Context`, database, store, or configuration.
+ * frozen context carrying exactly `moduleId`, `principal`, `params`, and `services` — never a Hono
+ * `Context`, authorization store, or configuration; `services.database` is the module's only
+ * reachable database surface, and is unreachable to anything short of a successfully authorized
+ * handler invocation (a denied request, a rejected trusted-origin check, and `OPTIONS` never reach
+ * this handler at all).
  *
  * Because the routes and registry both derive from the same discovered inventory
  * (`prepareStartupModuleInventory`), every registered route permission should already be
@@ -183,6 +193,7 @@ export function mountModuleHttpRoutes(
         moduleId: route.moduleId,
         params: Object.freeze({ ...c.req.param() }),
         principal: getAuthorizedPrincipal(c),
+        services: options.services,
       });
 
       let response: Response;

apps/api/src/server.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import type { ModuleRuntimeServices } from "@ekklesia/contracts";
 import {
   createAuthorizationEvaluator,
   createAuthorizationStore,
@@ -84,12 +85,15 @@ function bindServer(app: Hono, host: string, port: number): Promise<ServerType>
  * 1. Discover every installed module's manifest exactly once and compose the one immutable
  *    platform permission registry from Core's own declarations plus every module's
  *    (`prepareStartupModuleInventory`, `./platform-permissions.js`).
- * 2. Construct the one shared PostgreSQL pool (identity and authorization each get a typed
- *    Drizzle view over it — see `./database.js`).
- * 3. Construct the Core identity runtime, authorization store, and evaluator.
+ * 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,
+ *    then the Core identity runtime, authorization store, and evaluator.
  * 4. Start the module runtime from that exact same discovered inventory
- *    (`startDiscoveredModuleRuntime`) — never rediscovering modules a second time.
- * 5. Create the Hono application, mounting the started module runtime's published routes.
+ *    (`startDiscoveredModuleRuntime`) — never rediscovering modules a second time — passing it the
+ *    same services object every module's `start`/`stop` hook receives.
+ * 5. Create the Hono application, mounting the started module runtime's published routes and
+ *    passing the exact same services object to every module HTTP handler.
  * 6. Bind the Node HTTP server.
  *
  * Discovery and permission composition happen before any pool, Better Auth instance, module
@@ -97,12 +101,13 @@ function bindServer(app: Hono, host: string, port: number): Promise<ServerType>
  * manifest, a dependency-graph problem, a module claiming the reserved `core.*` permission
  * namespace, or a duplicate permission declaration — leaves nothing to close: it propagates
  * directly, and startup never falls back to a Core-only registry. Core infrastructure (the pool,
- * identity, authorization) exists before any executable module lifecycle code runs, and every
- * module route is published only after the entire module runtime has registered and started
- * successfully, so no request can ever reach a module before every module has started. Returns a
- * handle with an idempotent `shutdown()` so both the executable entry point and tests can stop the
- * server, the module runtime, and the shared pool deterministically. Never applies migrations or
- * generates schema — the database must already be migrated through `pnpm migrations:apply`.
+ * module database facade, identity, authorization) exists before any executable module lifecycle
+ * code runs, and every module route is published only after the entire module runtime has
+ * registered and started successfully, so no request can ever reach a module before every module
+ * has started. Returns a handle with an idempotent `shutdown()` so both the executable entry point
+ * and tests can stop the server, the module runtime, and the shared pool deterministically. Never
+ * applies migrations, generates schema, or issues a module database query merely because modules
+ * were discovered — the database must already be migrated through `pnpm migrations:apply`.
  */
 export async function startApi(
   config: ApiRuntimeConfig,
@@ -122,9 +127,11 @@ export async function startApi(
     operationTimeoutMs,
   });
 
+  let services: ModuleRuntimeServices;
   let runtime: ReturnType<typeof createIdentityRuntime>;
   let authorizationStore: ReturnType<typeof createAuthorizationStore>;
   try {
+    services = Object.freeze({ database: databaseHandle.module });
     runtime = createIdentityRuntime({
       config: config.identity,
       db: databaseHandle.identity,
@@ -146,7 +153,7 @@ export async function startApi(
   // handle to stop here, only the pool this failure leaves open.
   let moduleRuntime: StartedModuleRuntime;
   try {
-    moduleRuntime = await startDiscoveredModuleRuntime(inventory.modules);
+    moduleRuntime = await startDiscoveredModuleRuntime(inventory.modules, services);
   } catch (error) {
     await safeCloseDatabase(databaseHandle);
     throw error;
@@ -161,6 +168,7 @@ export async function startApi(
         store: authorizationStore,
       },
       moduleRoutes: moduleRuntime.routes,
+      moduleServices: services,
       runtime,
       trustedOrigins: config.identity.trustedOrigins,
     });
@@ -184,12 +192,14 @@ export async function startApi(
   // would previously get an already-resolved `undefined` immediately, before the listener had
   // actually drained or the pool had actually closed. Storing the promise itself means every
   // caller — concurrent or sequential — awaits the exact same drain-then-close operation and
-  // observes it complete (or fail) exactly once. Order matters: the HTTP listener is drained and
-  // closed first so no new or in-flight request can reach a module handler while the module
-  // runtime is stopping, then the module runtime stops, then the shared pool closes. Unlike the
-  // startup-cleanup paths above, a module-stop failure here is not swallowed — it is a genuine
-  // shutdown result a caller should observe — but database cleanup still always runs first, so a
-  // stop failure never leaves the pool open.
+  // observes it complete (or fail) exactly once. Order matters, and is now additionally
+  // load-bearing for the module database facade: the HTTP listener is drained and closed first so
+  // no new or in-flight request can reach a module handler while the module runtime is stopping;
+  // then the module runtime stops — its stop hooks may still use `services.database`, which is
+  // safe because the pool is not yet closed; only then does the shared pool close, so no module
+  // code can run against it afterward. Unlike the startup-cleanup paths above, a module-stop
+  // failure here is not swallowed — it is a genuine shutdown result a caller should observe — but
+  // database cleanup still always runs first, so a stop failure never leaves the pool open.
   let shutdownPromise: Promise<void> | undefined;
   const shutdown = (): Promise<void> => {
     if (!shutdownPromise) {