Files

T

ekklesiaandClaude Opus 5 c444ff570b feat: let one module contribute a browser renderer to another's capability

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]>

2026-08-27 07:47:10 -05:00

drizzle

feat: add module migration contracts and validation

2026-07-21 08:09:30 -05:00

src

feat: let one module contribute a browser renderer to another's capability

2026-08-27 07:47:10 -05:00

tests

feat: let one module contribute a browser renderer to another's capability

2026-08-27 07:47:10 -05:00

drizzle.config.ts

feat: add module migration contracts and validation

2026-07-21 08:09:30 -05:00

ekklesia.module.json

feat: let one module contribute a browser renderer to another's capability

2026-08-27 07:47:10 -05:00

package.json

feat: give module UI real stylesheets, and every artifact its own root

2026-08-27 07:21:14 -05:00

README.md

feat: add display kiosk host

2026-08-23 20:50:56 -05:00

tsconfig.build.json

feat: add module contracts and discovery

2026-07-12 22:14:01 -05:00

tsconfig.json

feat: build module UI into its declared browser artifact

2026-08-21 21:24:18 -05:00

tsconfig.ui-test.json

feat: build module UI into its declared browser artifact

2026-08-21 21:24:18 -05:00

tsconfig.ui.json

feat: let one module contribute a browser renderer to another's capability

2026-08-27 07:47:10 -05:00

README.md

Ekklesia module template

This is the smallest supported Ekklesia module product. It proves the static manifest, compiled runtime and schema entrypoints, capability registration, a module-owned Drizzle table, a generated module-owned migration, logical storage-bucket declarations, and one permissioned HTTP route (GET /records, declared in register) that reads that table through context.services.database — the platform-provided ModuleDatabase facade, never a module-constructed Drizzle instance or a raw pg client. Migration execution and storage provisioning are intentionally not included.

It also ships two independently optional React roles: a primary/management UI at src/ui/index.tsx and a full-viewport display at src/display/index.tsx. One invocation of pnpm build compiles each declared role to the exact artifact in entrypoints.ui and entrypoints.display.artifact (ADR 0023). Both default-export the same role-neutral defineModuleUi({ id, version, mount }) ABI and receive the same ModuleUiHostContext; there is deliberately no mode flag. The manifest entrypoint and the host route choose the role.

Either role can be omitted independently. To remove only the display example, delete src/display/ and entrypoints.display (and remove example.display.view if nothing else uses it). To keep the module backend-only, also delete src/ui/, tsconfig.ui.json, tsconfig.ui-test.json, tests/module-ui.test.ts, the ui entrypoint, and the React/module-UI dependencies. The builder succeeds with an empty artifact list when neither role is declared.

tests/module-ui.test.ts builds both artifacts from source, validates them with parseModuleUiExport, mounts each into a real DOM, and unmounts it. Ekklesia mounts the primary UI inside its Dashboard shell and serves the display without Dashboard chrome at the stable /display/example page. See Declaring UI entrypoints.

To create a module inside this repository:

Copy this directory to modules/<module-id>.
Rename the package in package.json and remove private when it is ready for publication.
Update the ID, name, version, namespaces, compatibility ranges, and bucket requests in ekklesia.module.json.
Keep the manifest capability versions and dependency ranges aligned with the contracts the module actually implements and consumes.
Replace src/server/index.ts with backend behavior only. Its defineModuleRuntime ID and version must match the manifest; do not duplicate the rest of the manifest in TypeScript. Declare HTTP routes only in register, against a permission the manifest already declares; start, stop, and every route handler — never register — receive context.services.database, a typed ModuleDatabase view over the platform's one PostgreSQL pool.
Replace the pure Drizzle declarations in src/schema/tables.ts and keep its table prefix aligned with the module ID. Keep the defineModuleSchema ownership wrapper in src/schema/index.ts aligned too, and never import another module's schema.
Update drizzle.config.ts, generate forward migrations with pnpm migration:generate --name=lowercase_name from the module directory, and review the SQL. Keep each generated tag in drizzle/meta/_ekklesia.json, classify it as none or approval-required, and change that file's moduleId when renaming the template.
Run pnpm install, pnpm build, pnpm modules:validate, pnpm migrations:validate, and pnpm verify from the repository root. The declared production entrypoint is the compiled dist/server/index.js, not source TypeScript; the schema entrypoint is likewise compiled to dist/schema/index.js.

The module owns its feature screens and display renderer. Do not add platform navigation, the containing shell, global theme, authentication screens, or top-level routing; those belong to surfaces and Core. A module UI asks its host for relative API paths and realtime state, and never hardcodes Ekklesia routes. The display permission is enforced by the host before it serves the page or descriptor; context.permissions remains a presentation-only hint. Keep imports side-effect-free, register capabilities in register, acquire resources in start, and release them in stop. Never construct a Drizzle instance, read DATABASE_URL, or reach for a raw pg client — context.services.database is the only supported way to query this module's own tables, and it is never available during register.

The migration directory uses the pinned stable Drizzle Kit 0.31.10 PostgreSQL journal and snapshot format. Migrations are forward-only and may modify only this module's objects. Offline validation treats SQL as opaque bytes, calculates SHA-256 from the exact contents, and never opens a database or executes SQL. Destructive declarations are review metadata, not automatic SQL classification or approval.