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.

core/src/modules/database.ts

@@ -0,0 +1,43 @@
+import type { ModuleDatabase } from "@ekklesia/contracts";
+import { drizzle } from "drizzle-orm/node-postgres";
+import type { Pool } from "pg";
+
+/**
+ * A typed `ModuleDatabase` view over an externally owned pool — the module-facing counterpart to
+ * `createIdentityDrizzleView` (`core/src/identity/database.ts`) and
+ * `createAuthorizationDrizzleView` (`core/src/authorization/database.ts`): the same "one pool, one
+ * typed view per domain" composition, extended to a third domain. Never constructs, registers an
+ * error listener on, or closes a pool itself — the caller (`apps/api/src/database.ts`) retains that
+ * responsibility exactly once, regardless of how many typed views it creates over the same pool.
+ *
+ * Carries no schema, unlike the identity and authorization views: a module brings its own Drizzle
+ * table objects to each call rather than selecting against a schema this facade would otherwise
+ * have to know about, so there is no `TFullSchema` for `drizzle(...)` to accept here. Building this
+ * view performs no query and no migration — `drizzle(pool)` only wraps the given client, the same
+ * synchronous, I/O-free construction `createIdentityDrizzleView`/`createAuthorizationDrizzleView`
+ * already rely on.
+ *
+ * Deliberately returns a fresh object with each operation explicitly bound to the underlying
+ * Drizzle instance, rather than the `drizzle(pool)` instance itself: Drizzle's own query methods
+ * are plain prototype methods that read `this.session`/`this.dialect` internally (not
+ * arrow-function instance properties), so handing that instance straight to a module would both
+ * break the moment a module destructured a method off it (`const { select } = database` loses
+ * `this`) and, more importantly, would leave every non-public property (`$client`, `_`, `query`,
+ * `$cache`, `with`) physically reachable on the object at runtime — reachable to a module written
+ * in plain JavaScript or one that bypasses the `ModuleDatabase` type with a cast, not just hidden
+ * by TypeScript. Building this literal, `Object.freeze`d object closes both gaps: only the eight
+ * intended operations exist on it at all, each correctly bound, and nothing else does.
+ */
+export function createModuleDatabaseView(pool: Pool): ModuleDatabase {
+  const db = drizzle(pool);
+  return Object.freeze({
+    delete: db.delete.bind(db),
+    execute: db.execute.bind(db),
+    insert: db.insert.bind(db),
+    select: db.select.bind(db),
+    selectDistinct: db.selectDistinct.bind(db),
+    selectDistinctOn: db.selectDistinctOn.bind(db),
+    transaction: db.transaction.bind(db),
+    update: db.update.bind(db),
+  });
+}

core/src/modules/index.ts

@@ -1,3 +1,4 @@
+export * from "./database.js";
 export * from "./discovery.js";
 export * from "./migration-discovery.js";
 export * from "./permissions.js";

core/src/modules/runtime.ts

@@ -10,6 +10,7 @@ import {
   type ModuleRouteDefinitionInput,
   type ModuleRuntimeContext,
   type ModuleRuntimeDefinition,
+  type ModuleRuntimeServices,
   moduleRouteShapeKey,
   parseModuleRuntimeDefinition,
   type RegisteredCapability,
@@ -70,7 +71,12 @@ export interface StartedModuleRuntime {
   stop(): Promise<void>;
 }
 
-export interface StartModuleRuntimeOptions extends ModuleDiscoveryOptions {}
+export interface StartModuleRuntimeOptions extends ModuleDiscoveryOptions {
+  /** The same frozen services object every started module's `start`/`stop` hooks and (once
+   * `apps/api` mounts routes) HTTP handlers receive for this runtime — a required production
+   * dependency, never an optional test-only global. See `ModuleRuntimeServices`. */
+  readonly services: ModuleRuntimeServices;
+}
 
 interface LoadedModule {
   readonly definition: ModuleRuntimeDefinition;
@@ -201,6 +207,7 @@ class StagedCapabilityRegistry {
   createRuntimeContext(
     module: DiscoveredModule,
     phase: "rollback" | "start" | "stop",
+    services: ModuleRuntimeServices,
   ): ModuleRuntimeContext {
     const capabilities: CapabilityResolver = Object.freeze({
       resolve: (capabilityId: CapabilityId): RegisteredCapability | undefined => {
@@ -208,7 +215,7 @@ class StagedCapabilityRegistry {
         return this.#registered.get(capabilityId);
       },
     });
-    return Object.freeze({ capabilities, moduleId: module.manifest.id });
+    return Object.freeze({ capabilities, moduleId: module.manifest.id, services });
   }
 
   publish(): CapabilityRegistry {
@@ -466,11 +473,14 @@ async function stopModules(
   modules: readonly LoadedModule[],
   registry: StagedCapabilityRegistry,
   phase: "rollback" | "stop",
+  services: ModuleRuntimeServices,
 ): Promise<readonly ModuleRuntimeIssue[]> {
   const issues: ModuleRuntimeIssue[] = [];
   for (const module of [...modules].reverse()) {
     try {
-      await module.definition.stop?.(registry.createRuntimeContext(module.discovered, phase));
+      await module.definition.stop?.(
+        registry.createRuntimeContext(module.discovered, phase, services),
+      );
     } catch (error) {
       if (error instanceof ModuleRuntimeSignal) {
         issues.push(error.issue);
@@ -492,11 +502,14 @@ async function stopModules(
 async function startModules(
   modules: readonly LoadedModule[],
   registry: StagedCapabilityRegistry,
+  services: ModuleRuntimeServices,
 ): Promise<void> {
   const started: LoadedModule[] = [];
   for (const module of modules) {
     try {
-      await module.definition.start?.(registry.createRuntimeContext(module.discovered, "start"));
+      await module.definition.start?.(
+        registry.createRuntimeContext(module.discovered, "start", services),
+      );
       started.push(module);
     } catch (error) {
       const startIssue =
@@ -508,7 +521,7 @@ async function startModules(
               module.discovered.manifest.id,
               `Module ${module.discovered.manifest.id} startup failed.`,
             );
-      const rollbackIssues = await stopModules(started, registry, "rollback");
+      const rollbackIssues = await stopModules(started, registry, "rollback", services);
       throw new ModuleRuntimeError([startIssue, ...rollbackIssues]);
     }
   }
@@ -524,12 +537,13 @@ async function startModules(
  */
 export async function startDiscoveredModuleRuntime(
   discoveredModules: readonly DiscoveredModule[],
+  services: ModuleRuntimeServices,
 ): Promise<StartedModuleRuntime> {
   const modules = await loadRuntimeDefinitions(discoveredModules);
   const capabilityRegistry = new StagedCapabilityRegistry();
   const httpRoutes = new StagedModuleHttpRoutes();
   await registerModules(modules, capabilityRegistry, httpRoutes);
-  await startModules(modules, capabilityRegistry);
+  await startModules(modules, capabilityRegistry, services);
 
   const capabilities = capabilityRegistry.publish();
   const routes = httpRoutes.publish();
@@ -549,7 +563,7 @@ export async function startDiscoveredModuleRuntime(
     routes,
     stop: (): Promise<void> => {
       stopPromise ??= (async () => {
-        const issues = await stopModules(modules, capabilityRegistry, "stop");
+        const issues = await stopModules(modules, capabilityRegistry, "stop", services);
         if (issues.length > 0) {
           throw new ModuleRuntimeError(issues);
         }
@@ -563,5 +577,5 @@ export async function startModuleRuntime(
   options: StartModuleRuntimeOptions,
 ): Promise<StartedModuleRuntime> {
   const discovered = await discoverModules(options);
-  return startDiscoveredModuleRuntime(discovered);
+  return startDiscoveredModuleRuntime(discovered, options.services);
 }