feat: deliver module database ABI by manifest

packages/contracts/src/module-runtime.ts

@@ -1,7 +1,8 @@
 import type { CapabilityId, ModuleId } from "./identifiers.js";
 import { moduleIdSchema } from "./identifiers.js";
 import type { ModuleConfiguration } from "./module-configuration.js";
-import type { ModuleRuntimeServices } from "./module-database.js";
+import type { ModuleDatabase, ModuleRuntimeServices } from "./module-database.js";
+import type { ModuleDatabaseExecutor } from "./module-database-abi.js";
 import type { ModuleHttpRouteRegistrar } from "./module-http.js";
 import type { ModuleRealtimeChannelRegistrar, ModuleRealtimePublisher } from "./module-realtime.js";
 import type { ModuleStorage } from "./module-storage.js";
@@ -24,12 +25,14 @@ export interface CapabilityRegistrar extends CapabilityResolver {
   provide(capabilityId: CapabilityId, implementation: unknown): void;
 }
 
-export interface ModuleRegistrationContext {
+export interface ModuleRegistrationContext<
+  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
+> {
   readonly capabilities: CapabilityRegistrar;
   /** Available only during `register` — never on `ModuleRuntimeContext` — so a route can only ever
    * be declared while Core is still building the immutable startup snapshot, never added or removed
    * afterward from `start`, `stop`, or any other post-registration code path. */
-  readonly http: ModuleHttpRouteRegistrar;
+  readonly http: ModuleHttpRouteRegistrar<Database>;
   /** Declarative, registration-only channel publication. Live publishing is available only from
    * runtime and request-handler contexts. */
   readonly realtime: ModuleRealtimeChannelRegistrar;
@@ -49,10 +52,12 @@ export interface ModuleRegistrationContext {
  * same frozen `services` object identity as the other, for a given API runtime — never a fresh
  * `ModuleRuntimeServices` built per hook invocation. Unlike `ModuleRegistrationContext`, this never
  * carries `http`: a route can only ever be declared during `register`. */
-export interface ModuleRuntimeContext {
+export interface ModuleRuntimeContext<
+  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
+> {
   readonly capabilities: CapabilityResolver;
   readonly moduleId: ModuleId;
-  readonly services: ModuleRuntimeServices;
+  readonly services: ModuleRuntimeServices<Database>;
   /**
    * This module's own scoped object storage (ADR 0030).
    *
@@ -70,8 +75,8 @@ export interface ModuleRuntimeContext {
   /**
    * This module's own validated configuration, frozen for the lifetime of the process.
    *
-   * Deliberately **not** a field on `ModuleRuntimeServices`: that object is one shared instance
-   * every module receives, and configuration is per-module by definition. It sits beside `moduleId`
+   * Deliberately **not** a field on `ModuleRuntimeServices`: that object holds live platform
+   * services while configuration is a separately resolved snapshot. It sits beside `moduleId`
    * — the context's other per-module fact — so the scoping is visible in the shape rather than
    * asserted in a comment.
    *
@@ -82,15 +87,28 @@ export interface ModuleRuntimeContext {
   readonly config: ModuleConfiguration;
 }
 
-export interface ModuleRuntimeDefinition {
+interface ModuleRuntimeDefinitionBase<Database extends ModuleDatabase | ModuleDatabaseExecutor> {
   readonly id: ModuleId;
-  readonly register?: (context: ModuleRegistrationContext) => Awaitable<void>;
-  readonly start?: (context: ModuleRuntimeContext) => Awaitable<void>;
-  readonly stop?: (context: ModuleRuntimeContext) => Awaitable<void>;
+  readonly register?: (context: ModuleRegistrationContext<Database>) => Awaitable<void>;
+  readonly start?: (context: ModuleRuntimeContext<Database>) => Awaitable<void>;
+  readonly stop?: (context: ModuleRuntimeContext<Database>) => Awaitable<void>;
   readonly version: string;
 }
 
-const runtimeDefinitionKeys = new Set(["id", "register", "start", "stop", "version"]);
+export interface LegacyModuleRuntimeDefinition extends ModuleRuntimeDefinitionBase<ModuleDatabase> {
+  readonly database?: never;
+}
+
+export interface ModuleDatabaseAbiRuntimeDefinition
+  extends ModuleRuntimeDefinitionBase<ModuleDatabaseExecutor> {
+  readonly database: { readonly abi: 1 };
+}
+
+export type ModuleRuntimeDefinition =
+  | LegacyModuleRuntimeDefinition
+  | ModuleDatabaseAbiRuntimeDefinition;
+
+const runtimeDefinitionKeys = new Set(["database", "id", "register", "start", "stop", "version"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -107,6 +125,14 @@ export function isModuleRuntimeDefinition(value: unknown): value is ModuleRuntim
   if (Object.keys(value).some((key) => !runtimeDefinitionKeys.has(key))) {
     return false;
   }
+  if (
+    value.database !== undefined &&
+    (!isRecord(value.database) ||
+      Reflect.ownKeys(value.database).length !== 1 ||
+      value.database.abi !== 1)
+  ) {
+    return false;
+  }
   return [value.register, value.start, value.stop].every(
     (hook) => hook === undefined || typeof hook === "function",
   );
@@ -116,11 +142,22 @@ export function parseModuleRuntimeDefinition(value: unknown): ModuleRuntimeDefin
   if (!isModuleRuntimeDefinition(value)) {
     throw new TypeError("Invalid Ekklesia module runtime definition.");
   }
-  return Object.freeze({
-    id: value.id,
-    version: value.version,
+  const hooks = {
     ...(value.register ? { register: value.register } : {}),
     ...(value.start ? { start: value.start } : {}),
     ...(value.stop ? { stop: value.stop } : {}),
-  });
+  };
+  if (value.database) {
+    return Object.freeze({
+      database: Object.freeze({ abi: 1 as const }),
+      id: value.id,
+      version: value.version,
+      ...hooks,
+    }) as ModuleDatabaseAbiRuntimeDefinition;
+  }
+  return Object.freeze({
+    id: value.id,
+    version: value.version,
+    ...hooks,
+  }) as LegacyModuleRuntimeDefinition;
 }