Ekklesia/docs/architecture/decisions/0041-module-browser-contributions.md

0041: One module may contribute a browser renderer to another module's capability

• Status: Accepted
• Date: 2026-08-27
• Supersedes: none
• Related: ADR 0006, ADR 0021, ADR 0022, ADR 0024, ADR 0025, ADR 0033, ADR 0040

Context

The platform already has a complete story for one module using another's backend: capabilities, versioned dependency ranges, and provider registration (ADR 0006). It has no story at all for one module using another's browser code, and the first real product needs one.

The concrete shape, stated so the mechanism can be judged against it rather than against an abstraction:

Signage        provides a backend capability and owns a screen made of timeline slots
Announcements  requires that capability and registers a backend provider for it
Announcements  also ships a React renderer that knows how an announcement should look
Signage        mounts that renderer for one slot, drives it, and takes it down

Every alternative available today is wrong in a way that matters. Signage cannot import Announcements: modules are independently installed, independently versioned peers, and pnpm boundaries rejects it outright. Signage cannot re-implement the renderer: it does not own the domain and the two would drift on the first change. Announcements cannot declare a second primary UI: entrypoints.ui and entrypoints.display are artifacts a host mounts in surfaces the host owns, and nothing about "a slot inside another module's timeline" is a host concern. And the platform must not learn what a slide is — the moment Core has a slide type, every future consumer inherits Signage's vocabulary.

Decision

Add a generic browser contribution: a compiled renderer one module declares for a capability another module provides, mounted by that other module inside a container it owns.

The manifest declaration is inert and small

manifestVersion: 7 adds a top-level contributions array. Each entry declares:

Field	Meaning
id	<module-id>.<local-name> — namespaced, so uniqueness needs no registry
version	The contribution's own version, independent of its module's
capability	The capability it plugs into, owned by whichever module provides it
capabilityRange	The provider versions it is compatible with
artifact	One compiled browser artifact, package-relative

That is the complete list, and the omissions are the decision. There is no payload schema, no slot, no ordering, no rendering hint, and no domain vocabulary of any kind. Core cannot learn what a slide is from this declaration, because the declaration cannot express it.

Validation is static and fails closed: the id must be namespaced to the declaring module and have exactly one local segment; ids and artifact paths must be unique within a module; the artifact must not collide with any entrypoint; and a contribution may not target a capability its own module provides — a module contributing to itself needs no platform mechanism and would make the compatibility check a comparison of a module with itself.

Version 7 is a hard cutover, exactly as every prior manifest version has been (ADR 0006, 0014, 0021, 0033). Upgrading a module that contributes nothing is a one-character edit.

Publication is the existing mechanism, extended

Discovery resolves each contribution artifact through the identical loop every other compiled entrypoint uses, so a contribution inherits the path grammar, containment, symlink-resolution, extension, and file-kind checks rather than receiving a second, weaker implementation of them. Two contributions that resolve through a link to one file are rejected.

The publication registry adds contributions on three conditions, all of which must hold: the contributing module is in the eligible set, some other eligible module provides the target capability, and that provider's declared capability version satisfies the declared range. A contribution that fails any of them is absent — never published-but-broken, and never mounted with a shrug.

apps/api serves it at GET /api/v1/module-ui/<module-id>/<version>/contributions/<contribution-id> — a sibling of the artifact and display routes, under the same prefix, with the same policy: three lookup keys, one exact registry match, one already-validated canonical path, no request value ever composed into a filesystem path, and one indistinguishable 404 for unknown, undeclared, stale, and incompatible alike. Source maps, sibling chunks, and package-root files stay unreachable by construction.

A consumer discovers through the host, never through a URL

The consuming module's descriptor gains a contributions array: identity, version, capability, and the server-produced URL. A module UI sees only the first three; the URL lives in the host, which resolves it exactly as it resolves api.request("records"). A module that built /api/v1/module-ui/<id>/<version>/contributions/<id> itself would be welded to Ekklesia's private deployment detail and could never run under a standalone host.

ModuleUiHostContext gains a sixth member, contributions, with list(capabilityId) and mount({ contributionId, container, input }). A consumer can only ever see contributions aimed at a capability it provides, because that is the only thing the server put in its descriptor — and it cannot name its way to anything else, because a mount for an id the server withheld fails without fetching anything.

The consumer owns the domain contract, entirely

input is opaque JSON. The platform validates that it is genuinely JSON-serializable — structurally, so a Date, a function, undefined, a non-finite number, or a cycle fails at the boundary rather than vanishing somewhere far from the mistake — and validates nothing about its shape or meaning. A consumer publishes its own input contract alongside its capability and versions it through its own capability version. Neither the manifest, the registry, the route, nor the SDK has a place to put a schema, which is what stops one from appearing.

The contribution ABI is separate and versioned

MODULE_CONTRIBUTION_ABI_VERSION is stamped by defineModuleContribution, never written by an author. It is deliberately not the same number as MODULE_UI_ABI_VERSION: the two contracts have different lifecycles — one receives a host context, the other receives a consumer's input and can be updated in place — and versioning them together would force every module to rebuild whenever either moved. A mismatched artifact fails with its own code before mounting.

The ABI supports exactly what a long-running screen needs:

• asynchronous readiness — mount may return a promise, so a consumer can sequence a transition instead of guessing when a renderer has decoded its media;
• update without remounting — remounting per change would destroy DOM, restart animations, and reload media on every tick. A renderer that genuinely cannot update in place omits update, and the consumer is told to remount rather than left rendering stale content behind a silently ignored call;
• deterministic cleanup — the loader runs the renderer's cleanup and removes its isolated root in a finally, so a renderer that fails to clean up still has its styles taken out of the page;
• sanitized failure — every code is fixed, and no message, stack, or cause ever carries the consumer's domain data.

Each contribution mounts inside its own Shadow DOM root (ADR 0040) with its own compiled stylesheet, so a contributed renderer cannot restyle the consuming module's screen around it, and that module's rules cannot reach in.

What a contribution is not given

No database, no object storage, no credential, no session, no API client, and no reach into any module — including the one that contributed it. Its context is two members: its own id and the consumer's input.

Loading a contribution grants its module nothing. Server-side authorization is unchanged and remains the only authority. Everything a contributed renderer needs arrives through the consumer's input, because the consumer is the party that was authorized to obtain it.

A contribution artifact is still installed, trusted, first-party code in the host's realm (ADR 0022, ADR 0024). Its isolated root is a correctness boundary for styles and must never be described as a sandbox.

Consequences

• One module can extend another's screen without either importing the other, and without the platform learning either one's vocabulary.
• The Dashboard bundle now contains two dynamic imports rather than one, both the generic loader's: a module UI artifact and a contributed renderer.
• Manifest version 7 requires every module to update one field. Nothing else changes for a module that contributes nothing.
• ModuleUiHostContext grew from five members to six. It is present on every context and empty for the overwhelming majority of modules, so a module writes the same code whether or not anything was contributed — and a standalone host running one module supplies an empty implementation that is the correct one rather than a stub.
• A consuming module must handle an empty list: a contribution can be absent because nobody contributed, because the contributor is disabled, or because it is outside the compatible range. That is the same discipline an optional capability dependency already requires.

Alternatives

• Let the consumer import the contributor. Rejected: it is the layer violation the boundary checker exists to prevent, and it would make two independently installable modules one unit.
• Put the renderer in the consumer. Rejected: the consumer does not own the domain, so the renderer and the data it draws would drift on the first change to either.
• A second entrypoints role. Rejected: the two existing roles are artifacts a host mounts in surfaces the host owns. A contribution is mounted by a module, at a moment and in a place only that module understands; calling it an entrypoint would put the platform in charge of deciding when a slot should be filled.
• A platform-defined payload schema. Rejected, emphatically. It would make Core the owner of a vocabulary it cannot possibly own, force every future consumer to inherit the first one's shape, and require a platform release to change a domain contract between two modules.
• Give the contribution its own API client. Rejected: a renderer with its own authority is a privilege the consumer never granted, and a second authorization path to reason about. The consumer was authorized to fetch the data; it passes what it fetched.
• Let a consumer construct the artifact URL. Rejected for the same reason a module may not build its own API prefix (ADR 0022): it welds the module to Ekklesia's deployment detail.
• One shared ABI version for UI artifacts and contributions. Rejected: it couples two contracts with different shapes and lifecycles, and would make every module rebuild whenever either moved.

Deferred

Contribution ordering and priority, a consumer-declared "extension point" manifest declaration, per-contribution permissions, contributions to backend extension points, host-mediated communication back from a contribution to its own module, contribution-level configuration, hot reload, and a module store or installer that would let contributions arrive without a restart.