82 lines
4.8 KiB
Markdown
82 lines
4.8 KiB
Markdown
# 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.
|