feat: add the module configuration and secrets contract #28

2026-08-23T02:49:21Z

Zayin_Admin commented

2026-08-23 02:49:21 +00:00

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]

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

Zayin_Admin added 1 commit 2026-08-23 02:49:21 +00:00

feat: add the module configuration and secrets contract

CI / verify (pull_request) Successful in 35s

Details

CI / infrastructure-smoke (pull_request) Successful in 21s

Details

CI / migration-smoke (pull_request) Successful in 46s

Details

baa689b2a7

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

Zayin_Admin merged commit 527239f6de into main

2026-08-23 02:51:37 +00:00

Zayin_Admin deleted branch phase-7a/module-configuration

2026-08-23 02:51:37 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Zayin/Ekklesia#28