feat: add the module configuration and secrets contract

Modules had no way to be told anything. Announcements — the first real
product Ekklesia will absorb — has zero environment variables and compiles
a LAN IP address into its source, so this is the contract standing between
it and the module system.

- A module declares what it needs in its manifest, using six bounded types
  (string, integer, boolean, enum, url, secret) with no nesting and no
  regular expressions. Static declaration is what lets the platform validate
  configuration *before* deciding whether a module may start: an enabled
  module missing a required value is reported `blocked ·
  configuration_missing · <key>` rather than taking startup down from inside
  its own `start` hook, and Doctor reports the same while still importing no
  module code. That forces `manifestVersion: 5`, a hard cutover.
- Ordinary values persist in one Core table (migration 0005), one row per
  (module_id, key), stored as text until validated against the declaring
  module's current manifest. Nothing is coerced; an invalid stored value
  blocks the module rather than falling back to the default. A key the
  manifest no longer declares is retained and ignored.
- Secrets are never persisted. There is no encryption at rest in this
  repository, so a `secret` key is deployment-supplied and mapped in by the
  host under a name the module never sees. A secret declaration has no
  `default` field, the write API refuses secret material, and the HTTP view
  has no `value` field for one — absent by construction, not filtered.
- Modules receive a frozen `context.config` on the registration, runtime,
  and HTTP handler contexts: the same object identity, per module, beside
  `services` rather than inside it (services is deliberately one shared
  instance). No environment access, no database reference, no way to reach
  another module's values.
- Configuration decides eligibility through ADR 0028's existing resolver:
  three new blocked reasons, each with a distinct operator fix, propagating
  to required dependents through the same mechanism as a disabled module.
- Changes take effect at the next restart; both resources report
  restartRequired. New restricted permission
  `core.modules.configuration.manage`, separate from lifecycle, at the
  sibling prefix `/api/v1/module-configuration`.
- Migration participation stays independent of configuration validity.
  Endpoints and credentials for shared infrastructure stay platform
  concerns; a module declares which bucket it needs, not an S3 endpoint.

See ADR 0029.

Co-Authored-By: Claude Opus 5 <[email protected]>

core/src/modules/runtime.ts

@@ -1,6 +1,8 @@
 import { pathToFileURL } from "node:url";
 import {
   type CapabilityId,
+  EMPTY_MODULE_CONFIGURATION,
+  type ModuleConfiguration,
   type CapabilityRegistrar,
   type CapabilityResolver,
   capabilityIdSchema,
@@ -76,6 +78,24 @@ export interface StartedModuleRuntime {
   stop(): Promise<void>;
 }
 
+/**
+ * Per-module frozen configuration snapshots, keyed by module id (ADR 0029).
+ *
+ * A lookup rather than a field on `ModuleRuntimeServices`, because `services` is deliberately **one
+ * shared object identity every module receives** — a property this runtime has a test for — while
+ * 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.
+ */
+export type ModuleConfigurationLookup = ReadonlyMap<string, ModuleConfiguration>;
+
+function configurationFor(
+  configurations: ModuleConfigurationLookup,
+  moduleId: string,
+): ModuleConfiguration {
+  return configurations.get(moduleId) ?? EMPTY_MODULE_CONFIGURATION;
+}
+
 export interface ModuleRuntimeTimeoutOptions {
   /** Test-only narrowing of `MODULE_STOP_HOOK_TIMEOUT_MS`, applied to both normal stop and startup
    * rollback, so a deadline can be proven in milliseconds instead of ten seconds. Production
@@ -83,9 +103,23 @@ export interface ModuleRuntimeTimeoutOptions {
   readonly hookTimeoutMs?: number;
 }
 
+export interface ModuleRuntimeCompositionOptions extends ModuleRuntimeTimeoutOptions {
+  /**
+   * The per-module configuration snapshots this runtime hands to each module's `register`, `start`,
+   * `stop`, and HTTP handler contexts (ADR 0029). Production composition supplies exactly the map
+   * `resolveModuleEligibility` produced while deciding which modules may run, so the configuration
+   * that made a module eligible is the identical object it receives — never revalidated, and never
+   * re-read, between those two moments.
+   *
+   * Omitted by a caller exercising no configuration; every module then receives
+   * `EMPTY_MODULE_CONFIGURATION`.
+   */
+  readonly configurations?: ModuleConfigurationLookup;
+}
+
 export interface StartModuleRuntimeOptions
   extends ModuleDiscoveryOptions,
-    ModuleRuntimeTimeoutOptions {
+    ModuleRuntimeCompositionOptions {
   /** 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`. */
@@ -222,6 +256,7 @@ class StagedCapabilityRegistry {
     module: DiscoveredModule,
     phase: "rollback" | "start" | "stop",
     services: ModuleRuntimeServices,
+    config: ModuleConfiguration,
   ): ModuleRuntimeContext {
     const capabilities: CapabilityResolver = Object.freeze({
       resolve: (capabilityId: CapabilityId): RegisteredCapability | undefined => {
@@ -229,7 +264,7 @@ class StagedCapabilityRegistry {
         return this.#registered.get(capabilityId);
       },
     });
-    return Object.freeze({ capabilities, moduleId: module.manifest.id, services });
+    return Object.freeze({ capabilities, config, moduleId: module.manifest.id, services });
   }
 
   publish(): CapabilityRegistry {
@@ -464,12 +499,14 @@ async function registerModules(
   modules: readonly LoadedModule[],
   capabilityRegistry: StagedCapabilityRegistry,
   httpRoutes: StagedModuleHttpRoutes,
+  configurations: ModuleConfigurationLookup,
 ): Promise<void> {
   for (const module of modules) {
     const capabilityStage = capabilityRegistry.createRegistrationStage(module.discovered);
     const routeStage = httpRoutes.createRegistrationStage(module.discovered);
     const context: ModuleRegistrationContext = Object.freeze({
       capabilities: capabilityStage.capabilities,
+      config: configurationFor(configurations, module.discovered.manifest.id),
       http: routeStage.http,
       moduleId: module.discovered.manifest.id,
     });
@@ -561,6 +598,7 @@ async function stopModules(
   registry: StagedCapabilityRegistry,
   phase: "rollback" | "stop",
   services: ModuleRuntimeServices,
+  configurations: ModuleConfigurationLookup,
   options: StopModulesOptions = {},
 ): Promise<readonly ModuleRuntimeIssue[]> {
   const timeoutMs = options.hookTimeoutMs ?? MODULE_STOP_HOOK_TIMEOUT_MS;
@@ -574,7 +612,16 @@ async function stopModules(
     }
     try {
       const outcome = await awaitHookWithinDeadline(
-        Promise.resolve(stop(registry.createRuntimeContext(module.discovered, phase, services))),
+        Promise.resolve(
+          stop(
+            registry.createRuntimeContext(
+              module.discovered,
+              phase,
+              services,
+              configurationFor(configurations, moduleId),
+            ),
+          ),
+        ),
         timeoutMs,
       );
       if (outcome === "timed-out") {
@@ -609,6 +656,7 @@ async function startModules(
   modules: readonly LoadedModule[],
   registry: StagedCapabilityRegistry,
   services: ModuleRuntimeServices,
+  configurations: ModuleConfigurationLookup,
   options: StopModulesOptions = {},
 ): Promise<void> {
   // A module joins the rollback set the moment its `start` hook is *invoked*, not when it
@@ -622,7 +670,12 @@ async function startModules(
     rollbackCandidates.push(module);
     try {
       await module.definition.start?.(
-        registry.createRuntimeContext(module.discovered, "start", services),
+        registry.createRuntimeContext(
+          module.discovered,
+          "start",
+          services,
+          configurationFor(configurations, module.discovered.manifest.id),
+        ),
       );
     } catch (error) {
       const startIssue =
@@ -639,6 +692,7 @@ async function startModules(
         registry,
         "rollback",
         services,
+        configurations,
         options,
       );
       throw new ModuleRuntimeError([startIssue, ...rollbackIssues]);
@@ -657,13 +711,14 @@ async function startModules(
 export async function startDiscoveredModuleRuntime(
   discoveredModules: readonly DiscoveredModule[],
   services: ModuleRuntimeServices,
-  timeouts: ModuleRuntimeTimeoutOptions = {},
+  timeouts: ModuleRuntimeCompositionOptions = {},
 ): Promise<StartedModuleRuntime> {
   const modules = await loadRuntimeDefinitions(discoveredModules);
   const capabilityRegistry = new StagedCapabilityRegistry();
   const httpRoutes = new StagedModuleHttpRoutes();
-  await registerModules(modules, capabilityRegistry, httpRoutes);
-  await startModules(modules, capabilityRegistry, services, timeouts);
+  const configurations = timeouts.configurations ?? new Map<string, ModuleConfiguration>();
+  await registerModules(modules, capabilityRegistry, httpRoutes, configurations);
+  await startModules(modules, capabilityRegistry, services, configurations, timeouts);
 
   const capabilities = capabilityRegistry.publish();
   const routes = httpRoutes.publish();
@@ -683,7 +738,14 @@ export async function startDiscoveredModuleRuntime(
     routes,
     stop: (): Promise<void> => {
       stopPromise ??= (async () => {
-        const issues = await stopModules(modules, capabilityRegistry, "stop", services, timeouts);
+        const issues = await stopModules(
+          modules,
+          capabilityRegistry,
+          "stop",
+          services,
+          configurations,
+          timeouts,
+        );
         if (issues.length > 0) {
           throw new ModuleRuntimeError(issues);
         }
@@ -698,6 +760,7 @@ export async function startModuleRuntime(
 ): Promise<StartedModuleRuntime> {
   const discovered = await discoverModules(options);
   return startDiscoveredModuleRuntime(discovered, options.services, {
+    ...(options.configurations === undefined ? {} : { configurations: options.configurations }),
     ...(options.hookTimeoutMs === undefined ? {} : { hookTimeoutMs: options.hookTimeoutMs }),
   });
 }