# 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.