ekklesiaandClaude Opus 5
c444ff570b
The platform has had a complete story for one module using another's
*backend* since ADR 0006 — capabilities, versioned ranges, provider
registration. It has had none at all for one module using another's *browser*
code, and every workaround is wrong in a way that matters: a consumer cannot
import a peer module, it cannot re-implement a renderer for a domain it does
not own, and a second `entrypoints` role would put the platform in charge of
deciding when a slot inside someone else's screen should be filled.
Add a generic browser contribution. `manifestVersion: 7` declares one:
namespaced id, its own version, a target capability, a compatible range, and
one artifact. That is the complete list, and the omissions are the decision —
no payload schema, slot, ordering, or rendering hint exists anywhere, so Core
cannot learn what a slide is because the declaration cannot express it.
Discovery resolves a contribution artifact through the *identical* loop every
other compiled entrypoint uses, inheriting the path, containment, symlink,
extension, and file-kind checks rather than getting a weaker copy of them. The
registry publishes one only when another eligible module provides the target
capability within the declared range; otherwise it is absent rather than
mounted and broken. `apps/api` serves it as a sibling of the artifact and
display routes, with the same policy: three lookup keys, one exact match, one
already-validated path, and one indistinguishable 404 for unknown, undeclared,
stale, and incompatible alike.
A consumer discovers through the host, never through a URL. Its descriptor
carries identity, version, and capability; the URL stays server-side and is
resolved exactly as `api.request("records")` is. A module can only ever see
contributions aimed at a capability it itself provides, and cannot name its
way to anything else — a mount for a withheld id fails without fetching.
The consumer owns the domain contract entirely. Input is opaque JSON, checked
structurally so a Date, a function, a cycle, or `undefined` fails at the
boundary rather than vanishing somewhere far from the mistake, and checked for
nothing else. A contributed renderer receives its own id and that input: no
API client, realtime, principal, configuration, database, storage, or
credential. Loading one grants its module nothing.
The contribution ABI is versioned separately from the module UI ABI, because
the two have different shapes and lifecycles and coupling them would force
every module to rebuild whenever either moved. It supports asynchronous
readiness, update-without-remount (a screen that remounted per tick would
restart animations and reload media), deterministic cleanup in a `finally`,
and sanitized failure that never carries the consumer's domain data. Each
renderer mounts in its own isolated root with its own stylesheet.
The template now declares a contribution, so `pnpm build` exercises the whole
authoring path, and the shell suite drives the full relationship — one module
discovering, mounting, updating, and unmounting another's React renderer with
neither importing the other.
Co-Authored-By: Claude Opus 5 <[email protected]>
5.2 KiB
5.2 KiB
Contributing
Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency boundaries described in repository-boundaries.md.
Before opening a change, run:
pnpm verify
Migration-runner changes and changes to identity/authentication or the API's session transport also require the disposable live PostgreSQL suite:
pnpm test:migrations:integration
See the testing guide for the distinction between unit and live evidence and for credential-safe troubleshooting.
When adding or changing a module manifest, also run pnpm modules:validate directly for focused,
path-aware discovery errors. It is included in pnpm verify.
If Docker is available, also validate the development infrastructure:
pnpm infrastructure:config
Package rules
- Use strict TypeScript for production packages.
- Expose supported entry points through package
exports; do not import another package's private source paths. - Use
workspace:ranges for internal package dependencies. - Modules own their own UI and author it in React and TypeScript (ADR 0022). A module package may
contain
.tsxand depend onreact,react-dom, and@ekklesia/module-ui-sdk, and may author plain.cssinside a browser-artifact source root (ADR 0040). Every other UI framework,.jsx, other stylesheet dialects, and other presentation formats remain rejected bypnpm boundaries. Primary and display sources live at the exactsrc/ui/index.tsxandsrc/display/index.tsxconventions; onepnpm buildinvocation atomically compiles every role the v7 manifest declares via@ekklesia/module-ui-build(ADR 0023/0033), including every declared browser contribution atsrc/contributions/<local-name>/index.tsx(ADR 0041). Module authors write no bundler configuration. A module's stylesheets are compiled into its declared artifact as text and installed by the host into that artifact's own Shadow DOM root, so module styles cannot leak into the Dashboard or another module (ADR 0040). Both roles use the same UI SDK context with no presentation-mode flag, and the same versioned mount ABI. - A module may also consume exactly two shared design packages —
@ekklesia/design-tokensand@ekklesia/ui(ADR 0039) — so two modules' screens look like one product. That is a named allowlist: every other shared role (api-client,auth-client,surface-sdk,module-ui-host) stays rejected inside a module. Reference registered semantic tokens; never define an--ekklesia-*custom property of your own. - Module UI reaches its host only through
@ekklesia/module-ui-sdk— never@ekklesia/module-ui-host, which is the host-side loader — and asks the host for its own API by relative path — never by constructing/api/v1/modules/<id>/..., which is Ekklesia's private deployment detail and would break standalone hosting. - The containing application shell, navigation, global theme, and platform policy belong to Core and
the host application, never to a module. Ekklesia's own shell is
surfaces/shell; it discovers primary module UIs throughGET /api/v1/dashboard/navigation, resolves a dedicated display throughGET /api/v1/module-displays/<module-id>, mounts both with@ekklesia/module-ui-host, and statically imports no module (ADR 0026/0033). - A module may contribute a browser renderer to a capability another module provides
(
manifest.contributions, ADR 0041). The consumer discovers and mounts it throughModuleUiHostContext.contributions, never by building a publication URL, and owns the input contract entirely: the platform carries opaque JSON and defines no payload schema, slot, or ordering. A contributed renderer gets its own id and that input, and nothing else. - Dedicated displays are module-owned renderers mounted by a separate full-viewport surface at
/display/<module-id>, never Dashboard UI with hidden chrome. Its page and descriptor require the module-owned, non-public permission declared byentrypoints.display; artifact bytes remain anonymous trusted code. Public/device identity, display inventory, and variants are deferred. - Dashboard groups are presentation configuration, never module structure. Do not add a parent
module, child module, owning module, or group-derived dependency: real module relationships are
the dependency contract's job alone, and grouping must never influence discovery, dependency
ordering, startup, or authorization (ADR 0027). A module declares its display name
(
manifest.name); the Dashboard owns where it appears. - A surface is browser code. It may depend on browser-safe shared roles only — never
@ekklesia/contractsor@ekklesia/module-sdk, whose type graphs pull Node's globals into the browser — and it reaches the server over HTTP. - Add or update tests when changing a contract or architectural rule.
- Record major architectural changes in an ADR rather than burying them in an implementation.
Runtime registries and aggregate schemas will be produced by later phases. Do not add a manually
maintained feature-module registry; discovery starts from validated ekklesia.module.json files.