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

docs/development/api.md

@@ -82,6 +82,8 @@ No real values are shown here — configure per environment and never commit the
 | `GET /api/v1/module-ui/<module-id>/<version>` | Ekklesia | Publishes an installed module's validated `entrypoints.ui` artifact at a browser-loadable URL. No authentication; only the declared artifact, never another file. See [Module UI asset publication](#module-ui-asset-publication). |
 | `GET /api/v1/module-lifecycle` | Ekklesia | Which installed modules are enabled, what this process actually did with each, and whether a restart is pending. Requires `core.modules.lifecycle.manage` (baseline `restricted`). See [Module lifecycle](#module-lifecycle). |
 | `PUT /api/v1/module-lifecycle/<module-id>/enabled` | Ekklesia | Enable or disable one installed module. Takes effect at the next API start. Requires `core.modules.lifecycle.manage` and a trusted `Origin`. See [Module lifecycle](#module-lifecycle). |
+| `GET /api/v1/module-configuration/<module-id>` | Ekklesia | One module's declared configuration schema, its stored values, and whether a restart is pending. Never returns a secret value. Requires `core.modules.configuration.manage` (baseline `restricted`). See [Module configuration](#module-configuration). |
+| `PUT /api/v1/module-configuration/<module-id>` | Ekklesia | Replace one module's stored configuration. Takes effect at the next API start. Requires `core.modules.configuration.manage` and a trusted `Origin`. See [Module configuration](#module-configuration). |
 
 Better Auth's handler is unreachable outside `/api/auth/*`; every other unmatched path returns a
 deterministic `404 {"code":"NOT_FOUND"}`.
@@ -387,9 +389,12 @@ account.
 3. Construct the module database facade and the frozen `ModuleRuntimeServices` object from that same
    pool (see [Module database access](#module-database-access)).
 4. Construct the Core identity runtime, authorization store, and evaluator.
-5. Read the stored module enablement configuration and resolve, over that exact same discovered
-   inventory, which modules are **eligible** to run (`resolveModuleEligibility`,
-   `@ekklesia/core/modules` — see [Module lifecycle](#module-lifecycle)).
+5. Read the stored module enablement configuration and then the stored module configuration, and
+   resolve, over that exact same discovered inventory, which modules are **eligible** to run and
+   what each eligible module's frozen configuration snapshot is (`resolveModuleEligibility`,
+   `@ekklesia/core/modules` — see [Module lifecycle](#module-lifecycle) and
+   [Module configuration](#module-configuration)). The two reads are sequential rather than raced so
+   a broken deployment reports the same error code every time.
 6. Start the module runtime from the eligible subset (`startDiscoveredModuleRuntime`) — modules are
    never rediscovered for this step — passing it the services object every module's `start`/`stop`
    hook receives.
@@ -417,7 +422,8 @@ disabled, or blocked by a disabled required dependency, is never imported at all
 
 Step 5 makes startup depend on a reachable, migrated database: if the enablement configuration
 cannot be read, `startApi` **refuses to start** with Core's sanitized `MODULE_LIFECYCLE_READ_FAILED`
-rather than starting every discovered module. The platform cannot know what an administrator
+(and `MODULE_CONFIGURATION_READ_FAILED` if the enablement read succeeded and the configuration read
+did not) rather than starting every discovered module. The platform cannot know what an administrator
 decided, and starting a module they disabled is worse than not starting. Nothing is created or
 repaired on that path.
 
@@ -548,6 +554,116 @@ pnpm modules:enable  -- --module announcements
 It reads `DATABASE_URL`, runs the same manifest-only discovery the API does (so it refuses a module
 this deployment cannot see), writes the decision, and starts nothing. Restart the API to apply it.
 
+## Module configuration
+
+```text
+GET /api/v1/module-configuration/<module-id>
+PUT /api/v1/module-configuration/<module-id>     { "values": { "slideSeconds": 12 } }
+```
+
+What one installed module declares it needs configured, what an operator has stored, and whether the
+running process is still using it
+([ADR 0029](../architecture/decisions/0029-module-configuration-and-secrets.md)).
+
+A **sibling** of `/api/v1/modules/`, never a child, for the same reason `/api/v1/module-ui` and
+`/api/v1/module-lifecycle` are: `config` and `configuration` are legal module route segments, so a
+module could otherwise collide with the platform at `/api/v1/modules/<id>/config`.
+
+```json
+{
+  "moduleId": "announcements",
+  "version": "1.0.0",
+  "keys": [
+    { "key": "slideSeconds", "type": "integer", "required": false, "default": 7,
+      "description": "How long each slide is shown.", "configured": false },
+    { "key": "bucket", "type": "string", "required": true, "value": "slides", "configured": true },
+    { "key": "storageCredential", "type": "secret", "required": true, "configured": true }
+  ],
+  "unknownKeys": [],
+  "restartRequired": false
+}
+```
+
+### A secret's value is absent, not redacted
+
+Note what the `storageCredential` entry above does **not** have: a `value` field. Not `null`, not
+`"***"` — absent. Ekklesia never persists secret material, so the store this route reads from
+contains none, and there is no code path that could serve one. `configured` answers the only question
+an operator needs from here: does the deployment supply it?
+
+### The declared types
+
+| type | notes |
+| --- | --- |
+| `string` | optional `minLength` / `maxLength` |
+| `integer` | optional `minimum` / `maximum`; submitted as a JSON number, never a string |
+| `boolean` | submitted as a JSON boolean |
+| `enum` | closed `values` list |
+| `url` | absolute `http:`/`https:` only |
+| `secret` | deployment-supplied; never stored, never returned, never defaulted |
+
+No nesting, no arrays, no regular expressions. This is a validation vocabulary, not a form-builder
+DSL; a module needing structured data owns a table for it.
+
+### Writing is a whole-document replace, with closed validation
+
+A key the module does not declare is `400 CONFIGURATION_KEY_UNDECLARED`. A wrong JSON type or a value
+failing the module's own declared constraints is `400 CONFIGURATION_VALUE_INVALID`. A `secret` key is
+`400 CONFIGURATION_SECRET_NOT_WRITABLE` — there is no supported way to submit secret material to this
+platform. Nothing is coerced: `{"slideSeconds": "7"}` is a `400`, not a silent `7`.
+
+Constraint checking runs through **the same resolver startup uses**, over the exact document about to
+be stored, so the API and startup can never disagree about whether a value is valid.
+
+An *incomplete* document is accepted deliberately — an operator may save partial work, and the module
+is reported `blocked · configuration_missing` until they finish. An *invalid* one never is.
+
+A key omitted from the submission is deleted. Stored keys the module's current manifest no longer
+declares are **retained and ignored**, and listed as `unknownKeys`, so a downgrade or a rename does
+not destroy an operator's value.
+
+### Changes take effect at the next start
+
+Modules receive a configuration snapshot resolved once at startup, so a `PUT` changes nothing about
+the running process and the response reports `restartRequired` rather than pretending otherwise.
+Nothing is hot-reloaded. A setting that genuinely must change live is the module's own domain state,
+stored in the module's own tables and exposed through its own route — not platform configuration.
+
+### Missing or invalid configuration blocks the module
+
+An enabled module whose required configuration cannot be satisfied is never imported. It appears in
+`GET /api/v1/module-lifecycle` as `blocked` with a structured reason naming the offending **key**:
+
+```json
+{ "runtime": { "state": "blocked", "reason": "configuration_missing", "configurationKey": "bucket" } }
+```
+
+`configuration_missing` (set a value), `configuration_invalid` (correct the value), and
+`secret_missing` (set it in the deployment environment) are separate reasons because each has a
+different fix. A blocked module blocks its required dependents exactly like a disabled one does.
+
+### Secrets come from the deployment
+
+A module declares a `secret` key; the host maps it to a deployment-supplied value. In an Ekklesia
+deployment that mapping is an environment variable:
+
+```text
+EKKLESIA_MODULE_SECRET__<MODULE_ID>__<KEY>
+EKKLESIA_MODULE_SECRET__ANNOUNCEMENTS__STORAGE_CREDENTIAL
+```
+
+The module never sees that name — it calls `config.getSecret("storageCredential")` — which is what
+lets a future standalone host supply the same declared secret from somewhere else entirely.
+
+### Authority
+
+Both verbs require `core.modules.configuration.manage` (baseline `restricted`), deliberately separate
+from `core.modules.lifecycle.manage`: deciding whether a module runs and deciding how it behaves are
+different authorities. Mutations additionally require an exact trusted `Origin` and a bounded body.
+
+No response carries a filesystem path, package name, manifest path, caught error, stack, or secret
+value.
+
 ## Module HTTP routes
 
 An installed module's routes (declared via `http.route(...)` in its `register` hook — see