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]>

packages/contracts/src/module-manifest.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { type PermissionDeclaration, permissionDeclarationSchema } from "./authorization.js";
+import {
+  type ModuleConfigurationDeclaration,
+  moduleConfigurationDeclarationSchema,
+} from "./module-configuration.js";
 import {
   capabilityIdSchema,
   logicalBucketIdSchema,
@@ -102,17 +106,25 @@ function reportDuplicates(
 }
 
 /**
- * The one manifest shape Core accepts. Adding `entrypoints.ui` is an incompatible shape change —
- * version 3's `entrypoints` object is `.strict()` and rejects `ui` outright — so the canonical
- * manifest moves to `manifestVersion: 4` rather than reinterpreting version 3 (ADR 0021).
+ * The one manifest shape Core accepts. Adding a top-level `configuration` array is an incompatible
+ * shape change — version 4's manifest object is `.strict()` and rejects `configuration` outright —
+ * so the canonical manifest moves to `manifestVersion: 5` rather than reinterpreting version 4
+ * (ADR 0029).
  *
- * Version 3, and every other version, fails validation: there is no compatibility adapter, no
+ * Configuration is declared **statically, in this inert document**, rather than registered by
+ * executable module code, for one decisive reason: the platform validates a module's configuration
+ * *before* deciding whether it may start, so an enabled module whose required configuration is
+ * missing is reported as `blocked` with a structured reason instead of taking API startup down from
+ * inside its own `start` hook. Discovery, `pnpm modules:validate`, and Doctor all read this without
+ * importing a single line of module code, exactly as they always have.
+ *
+ * Version 4, and every other version, fails validation: there is no compatibility adapter, no
  * automatic conversion, and no dual acceptance, exactly as version 1 was rejected by version 2
- * (ADR 0006) and version 2 by version 3 (ADR 0014). One manifest document can therefore never be
- * read as two different versions. Upgrading a backend-only version 3 manifest is a one-character
- * edit: no field added by version 4 is required.
+ * (ADR 0006), version 2 by version 3 (ADR 0014), and version 3 by version 4 (ADR 0021). One
+ * manifest document can therefore never be read as two different versions. Upgrading a version 4
+ * manifest is a one-character edit: no field added by version 5 is required.
  */
-export const MODULE_MANIFEST_VERSION = 4;
+export const MODULE_MANIFEST_VERSION = 5;
 
 export const moduleManifestSchema = z
   .object({
@@ -130,6 +142,10 @@ export const moduleManifestSchema = z
     dependencies: dependenciesSchema,
     capabilities: z.array(moduleCapabilityDeclarationSchema).default(() => []),
     permissions: z.array(permissionDeclarationSchema).default(() => []),
+    /** What this module needs an operator to configure, and how to validate it (ADR 0029). Inert
+     * data: declaring configuration never causes Core to read a database, contact a host, or run
+     * module code during discovery. A module that needs nothing configured omits the field. */
+    configuration: z.array(moduleConfigurationDeclarationSchema).default(() => []),
     storage: moduleStorageSchema,
     entrypoints: entrypointsSchema,
   })
@@ -153,6 +169,15 @@ export const moduleManifestSchema = z
       context,
       "id",
     );
+    // One namespace for every configuration key a module owns, so an ordinary key and a secret key
+    // can never collide: a module cannot declare `apiToken` as both a defaultable string and a
+    // deployment-supplied secret and leave the platform to guess which one a stored row means.
+    reportDuplicates(
+      manifest.configuration.map((declaration) => declaration.key),
+      ["configuration"],
+      context,
+      "key",
+    );
 
     manifest.capabilities.forEach((capability, index) => {
       if (!capability.id.startsWith(`${manifest.id}.`)) {
@@ -228,6 +253,10 @@ export function safeParseModuleManifest(input: unknown) {
 export type ModuleManifestInput = z.input<typeof moduleManifestSchema>;
 export type ModuleManifest = z.output<typeof moduleManifestSchema>;
 export type ModuleBucketDeclaration = z.output<typeof moduleBucketDeclarationSchema>;
+/** A module manifest's `configuration` array entry — the same `ModuleConfigurationDeclaration` shape
+ * Core's configuration resolver consumes (`packages/contracts/src/module-configuration.ts`), aliased
+ * here for discoverability alongside the manifest's other per-field declaration types. */
+export type ModuleManifestConfigurationDeclaration = ModuleConfigurationDeclaration;
 export type ModuleCapabilityDeclaration = z.output<typeof moduleCapabilityDeclarationSchema>;
 /** A module manifest's `permissions` array entry — the same `PermissionDeclaration` shape Core's
  * authorization registry consumes (`packages/contracts/src/authorization.ts`), aliased here for