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
@@ -65,26 +65,28 @@ export interface ModuleUiPublicationRegistry {
|
||||
/**
|
||||
* Builds the platform's module UI publication policy from an already-discovered module list.
|
||||
*
|
||||
* The policy is deliberately small, because the repository's module state is deliberately small:
|
||||
* Ekklesia has one accepted module set — the modules `discoverModules` validated at startup — and
|
||||
* no installer, no enable/disable state, and no trust store. `ModuleLifecycleStage`
|
||||
* (`@ekklesia/contracts`) names stages as a vocabulary but no runtime state machine implements
|
||||
* them. So "publishable" means exactly:
|
||||
* The policy is deliberately small. "Publishable" means exactly:
|
||||
*
|
||||
* 1. the module is in the discovered, fully validated set the platform accepted at startup, and
|
||||
* 1. the module is in the **eligible** set the platform started — it survived discovery *and*
|
||||
* the operational lifecycle permits it to run (`resolveModuleEligibility`, `./lifecycle.js`) —
|
||||
* and
|
||||
* 2. its manifest declares `entrypoints.ui`, which discovery resolved to a real compiled file
|
||||
* inside the module package.
|
||||
*
|
||||
* A module directory sitting on disk satisfies neither on its own — it has to have survived
|
||||
* discovery — which is the property `docs/development/security.md` requires: *the existence of an
|
||||
* artifact on disk must not be what makes it servable*.
|
||||
* artifact on disk must not be what makes it servable*. Since ADR 0028 the same is true of a module
|
||||
* an administrator disabled: it is discovered and validated, and it is still not publishable,
|
||||
* because this registry is built from the eligible list rather than the discovered one. That is why
|
||||
* the filtering lives at the *call site's choice of input* rather than as a `disabled` check
|
||||
* somewhere downstream — there is exactly one authoritative eligible set, and everything that
|
||||
* exposes a module consumes it.
|
||||
*
|
||||
* Pure and synchronous: no filesystem, environment, database, or network access, and it never
|
||||
* imports, evaluates, or otherwise executes a module's UI artifact. The caller supplies a complete
|
||||
* discovered list; production composition (`apps/api/src/server.ts`) builds this only after the
|
||||
* module runtime has started, so the published set is also the running set — module startup is
|
||||
* all-or-nothing (`startDiscoveredModuleRuntime`, `./runtime.js`), so a module that failed to load,
|
||||
* register, or start takes the whole API startup down with it rather than lingering as a
|
||||
* imports, evaluates, or otherwise executes a module's UI artifact. Production composition
|
||||
* (`apps/api/src/server.ts`) passes the exact list it just started, and only after
|
||||
* `startDiscoveredModuleRuntime` succeeded — startup is all-or-nothing across that set, so a module
|
||||
* that failed to load, register, or start takes API startup down with it rather than lingering as a
|
||||
* publishable-but-not-running module.
|
||||
*/
|
||||
export function createModuleUiPublicationRegistry(
|
||||
|
||||
Reference in New Issue
Block a user