ekklesiaandClaude Opus 5
ca3f37d5f9
A display is the one surface expected to outlive its network: a television on a wall in a building whose uplink is a consumer router, with nobody standing in front of it. When that uplink drops and the screen reboots, the browser shows its own error page — not the display shell, not an Ekklesia message, nothing that recovers on its own, because there is no Ekklesia code left running to recover. Cache the shell and the declared code, in a service worker scoped to `/display/`: the page, the host script, the module's display artifact, and every contributed renderer that display actually mounted. All of them are code whose bytes already confer no authority, and all of them are addressed by a URL carrying an exact version. Cache nothing else, ever. Not the descriptor, not `/api/v1/principal`, not a module or platform API response, not the realtime stream, not a pairing exchange, and not any cross-origin request — which is what a signed object-delivery URL is. It is an allowlist rather than a deny list, so the cost of forgetting a new endpoint is that code goes uncached rather than that a permission decision gets stored. The consequence is stated rather than papered over: a display cannot render module content while offline. Mounting needs a descriptor, a descriptor is authorization-bearing, and it is never cached — so a revoked device stays revoked and cached code can never manufacture current authorization. What the cache buys is that a kiosk rebooting mid-outage boots into Ekklesia's own offline state and keeps retrying, that reconnecting mounts with nothing left to download, and that a hiccup fetching 600 KB of artifact after the tiny descriptor already resolved falls back to identical bytes instead of failing the display. Network-first everywhere, so a screen picks up new code the moment the server returns and can never be trapped on an obsolete build — the failure mode a cache-first worker produces on a screen nobody visits. Only a complete same-origin 200 is stored. Cache names carry a policy version and superseded generations are deleted; artifacts are pruned to the current version per module, keeping every artifact belonging to that version because a display artifact and its contributed renderers share one. The worker never caches itself. The page gets a small signal built from two sources, because either alone lies: `navigator.onLine` is optimistic behind a captive portal, and only the worker knows it actually served from cache. A display shows a quiet corner indicator rather than blanking a lobby wall, and resolves its descriptor again by itself when the network returns — nobody presses Retry on a lobby TV. Every caching decision lives in a module that touches no global, so the behaviour is exercised directly rather than through a worker a test runner cannot host. Registration is an enhancement: no service workers, plain HTTP, or a refusing policy all leave a display that works exactly as before. Co-Authored-By: Claude Opus 5 <[email protected]>
86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
# Contributing
|
|
|
|
Ekklesia is being built in verified, reviewable phases. Changes should preserve the dependency
|
|
boundaries described in [repository-boundaries.md](docs/architecture/repository-boundaries.md).
|
|
|
|
Before opening a change, run:
|
|
|
|
```bash
|
|
pnpm verify
|
|
```
|
|
|
|
Migration-runner changes and changes to identity/authentication or the API's session transport also
|
|
require the disposable live PostgreSQL suite:
|
|
|
|
```bash
|
|
pnpm test:migrations:integration
|
|
```
|
|
|
|
See the [testing guide](docs/development/testing.md) 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:
|
|
|
|
```bash
|
|
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 `.tsx` and depend on `react`, `react-dom`, and `@ekklesia/module-ui-sdk`, and may author
|
|
plain `.css` inside a browser-artifact source root (ADR 0040). Every other UI framework, `.jsx`,
|
|
other stylesheet dialects, and other presentation formats remain rejected by `pnpm boundaries`. Primary and display sources live at the exact `src/ui/index.tsx` and
|
|
`src/display/index.tsx` conventions; one `pnpm build` invocation atomically compiles every role
|
|
the v7 manifest declares via `@ekklesia/module-ui-build` (ADR 0023/0033), including every declared
|
|
browser contribution at `src/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-tokens` and
|
|
`@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 through `GET /api/v1/dashboard/navigation`, resolves a dedicated display
|
|
through `GET /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 through
|
|
`ModuleUiHostContext.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 by `entrypoints.display`; artifact bytes remain
|
|
anonymous trusted code. Public/device identity, display inventory, and variants are deferred. A
|
|
display-scoped service worker caches the shell and declared artifacts only, network-first, and
|
|
never a descriptor, an API response, or anything else authorization-bearing (ADR 0043).
|
|
- 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/contracts` or `@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.
|