feat: add the minimal operational module lifecycle
Ekklesia had no notion of a module being on or off: the accepted module set was exactly "whatever discovery found on disk", and `ModuleLifecycleStage` named nine states nothing produced or consumed. This replaces that vocabulary with two axes that real code produces — persistent, administrator-owned configuration (`enabled`/`disabled`) and per-boot runtime observation (`running`/`disabled`/`blocked`) — and wires them through startup. - One Core table (`ekklesia_core_module_state`, migration 0004) holding only `module_id` and `enabled`. A module with no record is enabled by default, so deploying a module is still sufficient to run it and discovery never needs an initialization write. A record for an undeployed module is retained and ignored, so redeploying restores the decision. - `resolveModuleEligibility` is pure: a disabled module transitively blocks every module that *requires* it (module and capability edges alike) with a structured reason naming the provider; optional dependencies never block; and a missing, incompatible, or cyclic dependency stays discovery's concern. - `startApi` starts only the eligible set and builds the UI publication registry from that same list, so routes, artifacts, browser inventory, and Dashboard navigation all follow one authoritative set. A disabled module is never imported, so there is no per-request enablement check anywhere. - Startup stays all-or-nothing, deliberately; there is consequently no `failed` runtime state. `pnpm modules:enable`/`modules:disable` is the out-of-band recovery path for a module that breaks startup. - Changes take effect at the next start, and the read model reports configuration, runtime, and `restartRequired` separately rather than claiming a module stopped when it has not. - Migration participation and permission composition still span the deployed and discovered inventories respectively, unchanged. - New restricted platform permission `core.modules.lifecycle.manage` gates both reading and changing enablement, at a sibling prefix (`/api/v1/module-lifecycle`) that cannot collide with the module route namespace. - `pnpm doctor` gains a `modules.lifecycle` check so "why is this module unavailable?" is answerable without reading logs. See ADR 0028. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
co-authored by
Claude Opus 5
parent
db67cf7700
commit
7729c99e24
@@ -152,6 +152,28 @@ key material is ever committed to this repository** — and the disposable conta
|
||||
`afterAll` even when an assertion fails. See
|
||||
[ADR 0018](../architecture/decisions/0018-identity-session-resolution-and-database-transport.md).
|
||||
|
||||
A fifth dedicated suite (`core/tests/module-lifecycle-store.integration.ts`, included in the same
|
||||
`pnpm test:migrations:integration` run) proves the module enablement store against real PostgreSQL:
|
||||
that migration `0004` really creates `ekklesia_core_module_state` with exactly the four columns and
|
||||
the one declared CHECK constraint the schema states — and, load-bearingly, that `enabled` has **no
|
||||
column default**, so the platform's default for a newly discovered module is genuinely the absence of
|
||||
a row rather than a materialized decision nobody made; that a decision survives a completely new
|
||||
connection; that the upsert is idempotent on `module_id` and bumps `updated_at` in place rather than
|
||||
inserting a second row; that a malformed identifier is rejected before it reaches PostgreSQL and the
|
||||
empty-string case is refused by the database too; and that a record for a module which is no longer
|
||||
deployed is retained and simply ignored by resolution, so redeploying restores the decision.
|
||||
|
||||
The API suite additionally drives the whole lifecycle end to end against a real database and real
|
||||
fixture modules: a disabled module's compiled entrypoint is never imported (proven by its
|
||||
`register`/`start`/`stop` markers staying empty), its routes return the platform's ordinary `404`,
|
||||
its UI artifact and inventory and navigation entries are all absent, and its neighbours run normally;
|
||||
a module blocked by a disabled required dependency is explained over HTTP with a structured reason
|
||||
naming that dependency and no filesystem path anywhere in the payload; a change made through
|
||||
`PUT /api/v1/module-lifecycle/<id>/enabled` reports `restartRequired: true` while the module
|
||||
demonstrably keeps serving, and is applied only by the next start; and a disabled module's migrations
|
||||
are still discovered, because deployed schema ownership is not runtime enabled state. See
|
||||
[ADR 0028](../architecture/decisions/0028-module-operational-lifecycle.md).
|
||||
|
||||
### Which kind of timing proof lives where
|
||||
|
||||
Pass 4 introduced several deadlines, and their tests deliberately differ in kind:
|
||||
|
||||
Reference in New Issue
Block a user