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-lifecycle.ts

@@ -43,24 +43,62 @@ export const moduleRuntimeStateSchema = z.enum(MODULE_RUNTIME_STATES);
 export type ModuleRuntimeState = z.infer<typeof moduleRuntimeStateSchema>;
 
 /**
- * Why an enabled module is not running. A structured reason plus the exact dependency it names,
- * rather than one state name per case — four states would encode the same two facts twice.
+ * Why an enabled module is not running. A structured reason plus the exact thing it names — a
+ * dependency, or a configuration key — rather than one state name per case, which would encode the
+ * same two facts twice.
  *
  * `required_dependency_disabled` means the dependency an administrator turned off is the direct
  * cause. `required_dependency_blocked` means the named dependency is itself blocked, so the cause
- * is transitive; following the chain always terminates at a `..._disabled` entry, because a
- * dependency that is merely absent or incompatible is rejected by discovery long before
- * eligibility is resolved.
+ * is transitive; following the chain always terminates at a reason that is not
+ * `required_dependency_blocked`, because a dependency that is merely absent or incompatible is
+ * rejected by discovery long before eligibility is resolved. Since ADR 0029 that terminal reason
+ * may also be one of the three configuration reasons below — a module blocked by its own
+ * configuration blocks its required dependents exactly like a disabled one does.
  */
 export const MODULE_BLOCKED_REASONS = [
   "required_dependency_disabled",
   "required_dependency_blocked",
+  "configuration_missing",
+  "configuration_invalid",
+  "secret_missing",
 ] as const;
 
 export const moduleBlockedReasonSchema = z.enum(MODULE_BLOCKED_REASONS);
 
 export type ModuleBlockedReason = z.infer<typeof moduleBlockedReasonSchema>;
 
+/**
+ * The three configuration reasons an enabled module may fail to become eligible (ADR 0029). They
+ * are separate because each has a **different operational fix**, which is the only justification
+ * for a distinct reason code:
+ *
+ * - `configuration_missing` — a required key has no stored value and no default. Fix: set a value
+ *   through the configuration API.
+ * - `configuration_invalid` — a stored value exists but does not satisfy the module's own declared
+ *   type or constraints. Fix: correct the value. A persisted value is never silently coerced,
+ *   truncated, or replaced by a default.
+ * - `secret_missing` — a required `secret` key has no deployment-supplied value. Fix: set it in the
+ *   deployment environment, not in the database — Ekklesia never stores secret material
+ *   (ADR 0029).
+ *
+ * Each names the offending **key**, never the value. A key is public — it is declared in an
+ * installed module's manifest — while a value may be a credential.
+ */
+export const MODULE_CONFIGURATION_BLOCKED_REASONS = [
+  "configuration_missing",
+  "configuration_invalid",
+  "secret_missing",
+] as const;
+
+export type ModuleConfigurationBlockedReason =
+  (typeof MODULE_CONFIGURATION_BLOCKED_REASONS)[number];
+
+export function isModuleConfigurationBlockedReason(
+  reason: ModuleBlockedReason,
+): reason is ModuleConfigurationBlockedReason {
+  return (MODULE_CONFIGURATION_BLOCKED_REASONS as readonly string[]).includes(reason);
+}
+
 /** Both kinds of edge a module's manifest can declare as required: another module, or a capability
  * some other module provides. Both block identically — a required capability is exactly as
  * required as a required module — and both name the *providing module* so an operator has