feat: add module runtime lifecycle

docs/architecture/decisions/0005-static-module-manifests.md

@@ -1,6 +1,7 @@
 # 0005: Static module manifests and atomic discovery
 
-- Status: Accepted
+- Status: Superseded
+- Superseded by: [0006](0006-versioned-capabilities-and-compiled-module-runtime.md)
 - Date: 2026-07-12
 
 ## Context

docs/architecture/decisions/0006-versioned-capabilities-and-compiled-module-runtime.md

@@ -0,0 +1,81 @@
+# 0006: Versioned capabilities and compiled module runtime
+
+- Status: Accepted
+- Date: 2026-07-12
+- Supersedes: [0005](0005-static-module-manifests.md)
+
+## Context
+
+Static module manifests let Core validate the complete installed module graph without executing
+module code. The first manifest shape treated capabilities as unversioned identifiers and the
+Module SDK helper validated a second programmatic copy of that manifest. Neither model could
+express compatibility between independently evolving capability contracts without duplicating
+canonical metadata.
+
+Core also needs an explicit production loading boundary. Importing source TypeScript would couple
+production startup to a development loader. Resolving arbitrary package exports from Core would
+require each discovered module to become a declared Core dependency or require a central import
+registry, which conflicts with install-by-cloning discovery.
+
+## Decision
+
+`ekklesia.module.json` remains the one canonical static manifest and moves to
+`manifestVersion: 2`. Provided capabilities are declarations containing an identifier and an exact
+semantic version. Required and optional capability dependencies map identifiers to semantic-version
+ranges. Capability versions describe their public contracts and evolve independently from the
+module package version. A missing optional capability is allowed; an installed but incompatible
+optional capability fails discovery.
+
+`defineModuleRuntime` is the Module SDK helper for a module's executable server definition. The
+definition repeats only module ID and module version as build-artifact identity markers, plus the
+`register`, `start`, and `stop` hooks. It does not duplicate capabilities, dependencies,
+permissions, storage requests, or entrypoints from the static manifest. Core validates every
+runtime definition against its manifest before running any hook.
+
+Production server entrypoints are direct package-relative paths to compiled ESM JavaScript ending
+in `.js` or `.mjs`, normally `./dist/server/index.js`. Core imports their canonical file URLs only
+after complete atomic discovery succeeds. A module can therefore be installed without a registry
+edit by cloning it into `modules/`, installing workspace dependencies, building the workspace, and
+running module validation. `pnpm modules:validate` builds the workspace before discovery so missing
+or stale build artifacts are caught at that boundary.
+
+Registration and lifecycle execution use discovery's deterministic dependency-first order. Each
+module registers its declared capabilities into a private stage; successful stages become visible
+to later dependent registrations but are not published to callers until all registration and
+startup hooks succeed. All registration completes before startup. Normal shutdown runs in reverse
+order. If startup fails, Core stops modules whose startup completed, in reverse order, and continues
+rollback even if cleanup fails.
+
+The injected contexts contain only the module ID and a capability registrar or resolver. Runtime
+errors use stable structured issues and do not expose caught exception messages, stacks, import
+URLs, absolute paths, or causes.
+
+## Alternatives
+
+- Source TypeScript entrypoints were rejected because production should not depend on an implicit
+  TypeScript loader or execute unbuilt source.
+- Package export subpaths were deferred because pnpm's strict dependency model cannot resolve an
+  arbitrary discovered package from Core without a declared dependency or generated registry.
+- Duplicating the complete static manifest in TypeScript was rejected because the two copies could
+  drift and make authority ambiguous.
+- Publishing capability registrations as each hook runs was rejected because a later registration
+  failure would expose a partially initialized platform.
+
+## Consequences
+
+Module builds must preserve the runtime definition's ID and version and produce the declared server
+artifact. Entrypoint modules are trusted backend plugins, not a sandbox boundary. Their top-level
+evaluation must be side-effect-free because ESM evaluation cannot be rolled back or unloaded.
+Registration hooks must remain declarative; modules acquire resources in `start` and release them
+in `stop`. A failing `start` hook is responsible for cleaning up work it began before rejecting;
+Core rollback covers modules whose startup already completed.
+
+Runtime restart, hot replacement, typed capability tokens, schema aggregation, authentication,
+HTTP routing, jobs, and physical storage provisioning remain outside this slice.
+
+## Migration implications
+
+Manifest version 1 is rejected rather than interpreted as version 2. Existing development modules
+must convert capability arrays into versioned declarations, capability dependency arrays into
+range maps, build their server entrypoint to ESM JavaScript, and export a `defineModuleRuntime`
+definition from that entrypoint.

docs/architecture/decisions/README.md

@@ -13,4 +13,5 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0002: pnpm workspace and strict TypeScript](0002-pnpm-workspace-and-typescript.md) — Accepted
 - [0003: Development infrastructure](0003-development-infrastructure.md) — Accepted
 - [0004: Replace unmaintained MinIO baseline](0004-replace-unmaintained-minio.md) — Accepted
-- [0005: Static module manifests and atomic discovery](0005-static-module-manifests.md) — Accepted
+- [0005: Static module manifests and atomic discovery](0005-static-module-manifests.md) — Superseded
+- [0006: Versioned capabilities and compiled module runtime](0006-versioned-capabilities-and-compiled-module-runtime.md) — Accepted

docs/architecture/platform-architecture.md

@@ -59,11 +59,11 @@ surfaces.
 ## Current implementation status
 
 Implemented now: the Phase 1 repository and infrastructure foundation plus public module contracts,
-the Module SDK manifest API, static versioned module manifests, automatic filesystem discovery,
-compatibility/dependency ordering, structured discovery failures, and a backend-only module
-template. Core can validate zero or more modules without importing their server behavior.
+static versioned manifests, independent capability versions and dependency ranges, automatic
+filesystem discovery, compiled server loading, runtime-definition verification, staged capability
+registration, dependency-ordered startup and reverse shutdown, rollback, and a backend-only module
+template.
 
-Target architecture, not yet implemented: lifecycle execution and runtime registration, Drizzle
-schema aggregation/migrations, Better Auth, permissions, physical storage-bucket provisioning,
-Surface SDK, capability/resource/action registries, API server, dashboard, Builder, and reference
-feature modules.
+Target architecture, not yet implemented: Drizzle schema aggregation and migrations, Better Auth,
+permission enforcement, physical storage-bucket provisioning, Surface SDK, richer public resource
+and action contracts, API server, dashboard, Builder, and reference feature modules.