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

packages/contracts/src/module-lifecycle.ts

@@ -1,17 +1,97 @@
 import { z } from "zod";
+import { moduleIdSchema } from "./identifiers.js";
 
-export const MODULE_LIFECYCLE_STAGES = [
-  "discovered",
-  "validated",
-  "configured",
-  "registered",
-  "migrated",
-  "initialized",
-  "started",
-  "stopped",
-  "failed",
+/**
+ * The two axes of a module's operational state, kept deliberately separate because they answer
+ * different questions, change at different times, and have different owners.
+ *
+ * **Configuration** is what an administrator decided: is this module supposed to run? It is
+ * persistent, survives restarts, and is platform-owned — a module never declares, reads, or
+ * influences it (ADR 0028). **Runtime** is what this process actually did with the module during
+ * *this* boot. Because Ekklesia has no hot loading or unloading, the two can legitimately
+ * disagree between a configuration change and the next restart, and the read model reports both
+ * rather than pretending a change took effect immediately.
+ *
+ * This replaces the nine-name `MODULE_LIFECYCLE_STAGES` vocabulary that shipped with ADR 0006 and
+ * which nothing ever implemented — ADR 0025 and ADR 0026 both recorded it as "vocabulary with no
+ * runtime state machine behind it". Every name below is produced by real code and observable
+ * through `GET /api/v1/module-lifecycle`; a stage that could never be observed would be a
+ * contract that lies.
+ */
+export const MODULE_RUNTIME_STATES = ["running", "disabled", "blocked"] as const;
+
+export const moduleRuntimeStateSchema = z.enum(MODULE_RUNTIME_STATES);
+
+/**
+ * What this process did with one module.
+ *
+ * - `running` — the module was enabled and eligible, and the module runtime loaded, registered,
+ *   and started it. It says the module's `start` hook completed; it says **nothing** about whether
+ *   every external resource that module uses is reachable now. Ekklesia has no runtime
+ *   health-probe contract, and this state must never be read as one.
+ * - `disabled` — configuration says it must not run, so the platform never imported its server
+ *   entrypoint, never invoked a lifecycle hook, never registered a route, and never published its
+ *   UI.
+ * - `blocked` — configuration says it should run, but a *required* dependency cannot, so starting
+ *   it would violate the dependency contract. See `ModuleBlockedReason`.
+ *
+ * There is deliberately no `failed`. Module startup remains all-or-nothing (ADR 0015, ADR 0020,
+ * preserved by ADR 0028): a module that fails to load, register, or start aborts API startup
+ * entirely, so no live process can ever report it. Adding the name before the behavior exists would
+ * publish a state nothing can produce.
+ */
+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.
+ *
+ * `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.
+ */
+export const MODULE_BLOCKED_REASONS = [
+  "required_dependency_disabled",
+  "required_dependency_blocked",
 ] as const;
 
-export const moduleLifecycleStageSchema = z.enum(MODULE_LIFECYCLE_STAGES);
+export const moduleBlockedReasonSchema = z.enum(MODULE_BLOCKED_REASONS);
 
-export type ModuleLifecycleStage = z.infer<typeof moduleLifecycleStageSchema>;
+export type ModuleBlockedReason = z.infer<typeof moduleBlockedReasonSchema>;
+
+/** 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
+ * something they can act on. */
+export const MODULE_DEPENDENCY_KINDS = ["module", "capability"] as const;
+
+export const moduleDependencyKindSchema = z.enum(MODULE_DEPENDENCY_KINDS);
+
+export type ModuleDependencyKind = z.infer<typeof moduleDependencyKindSchema>;
+
+/**
+ * The dependency that caused a block: which module is unavailable, and — for a capability edge
+ * — which capability was being depended on. `moduleId` is always the module an administrator
+ * would have to enable; `capabilityId` is present only when the edge came from
+ * `dependencies.capabilities.required`.
+ */
+export interface ModuleBlockingDependency {
+  readonly kind: ModuleDependencyKind;
+  readonly moduleId: string;
+  readonly capabilityId?: string;
+}
+
+/** One persisted enablement decision. Deliberately the smallest possible record: an identity and a
+ * boolean. There is no install source, download URL, update channel, signature, marketplace
+ * metadata, or free-form JSON — none of those exist in this platform, and a column for one would
+ * invite inventing it (ADR 0028). */
+export const moduleEnablementRecordSchema = z
+  .object({
+    moduleId: moduleIdSchema,
+    enabled: z.boolean(),
+  })
+  .strict();
+
+export type ModuleEnablementRecord = z.infer<typeof moduleEnablementRecordSchema>;