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

0006: Versioned capabilities and compiled module runtime

• Status: Accepted
• Date: 2026-07-12
• Supersedes: 0005

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.