@ekklesia/contracts still emitted a type-only import of
drizzle-orm/node-postgres for the legacy ModuleDatabase facade, so a
standalone module type-checked only because skipLibCheck hid it.
- ModuleDatabase, LegacyModuleRuntimeServices and
AnyModuleRuntimeServices move to core/src/modules/database.ts, beside
the facade Core builds; the facade itself is unchanged.
- contracts' runtime, route, and services generics no longer name an
ORM: the database type is a plain parameter defaulting to the ABI v1
executor, and the legacy definition's database is opaque until Core
specializes it. Core and apps/api name the legacy types from Core.
- contracts drops its drizzle-orm optional peer and devDependency;
Drizzle stays public only through @ekklesia/module-database/drizzle.
- The facade's type-level test moves from contracts to Core.
- Regression proof: the standalone fixture type-checks with
skipLibCheck: false against the packed tarballs, with no drizzle-orm
installed (the smoke asserts both). Against the previous contracts
tarball the same check fails with TS2307 on drizzle-orm/node-postgres.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
`manifest.storage.buckets` has existed since manifest version 1 and meant
nothing — discovery validated it and no code read it. This turns it into a
real capability, which is what stands between Announcements and the module
system: that product currently fetches a hardcoded LAN S3 endpoint, parses
ListObjectsV2 XML by hand, and hands the browser direct object URLs.
- A module declares a logical bucket and receives a scoped facade at
`context.storage` — list, head, get, put, delete. The contract names no
provider: no endpoint, region, credential, or physical bucket is reachable
from it, which is what lets the same module run under a future standalone
host over its own or a shared S3-compatible service.
- Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the
deployment target (ADR 0004), never an API name. Probing the pinned image
found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's
`BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would
have failed every second boot. A live test pins it.
- Logical → physical mapping is deterministic and collision-safe: an
installation prefix, the module and bucket ids joined by `--` (which cannot
occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide),
and a digest over the full untruncated identity. Two modules declaring
`assets` always get separate namespaces; neither can see the physical name.
- Declaring a bucket is now a requirement: with no provider configured the
module is `blocked · storage_unavailable` through ADR 0028's existing
resolver, propagating to required dependents. An installation with no object
storage stays a complete deployment.
- Binding availability is not provider health. Eligibility asks whether
storage is configured, never whether it answered; bucket creation is lazy on
first use so a storage outage cannot stop the platform booting; a running
module whose store blinks stays running and retries. Nothing deletes a
bucket.
- Credentials are deployment-supplied, never persisted, never routed through
module configuration, and never visible to modules, module UI, diagnostics,
or API responses. Provider errors translate to a closed code set carrying no
endpoint, bucket, request id, or XML.
- Retires ADR 0029's transitional `bucket` configuration key. No manifest
version change. The template declares no bucket, so it still runs without S3.
See ADR 0030.
Co-Authored-By: Claude Opus 5 <[email protected]>
Modules had no way to be told anything. Announcements — the first real
product Ekklesia will absorb — has zero environment variables and compiles
a LAN IP address into its source, so this is the contract standing between
it and the module system.
- A module declares what it needs in its manifest, using six bounded types
(string, integer, boolean, enum, url, secret) with no nesting and no
regular expressions. Static declaration is what lets the platform validate
configuration *before* deciding whether a module may start: an enabled
module missing a required value is reported `blocked ·
configuration_missing · <key>` rather than taking startup down from inside
its own `start` hook, and Doctor reports the same while still importing no
module code. That forces `manifestVersion: 5`, a hard cutover.
- Ordinary values persist in one Core table (migration 0005), one row per
(module_id, key), stored as text until validated against the declaring
module's current manifest. Nothing is coerced; an invalid stored value
blocks the module rather than falling back to the default. A key the
manifest no longer declares is retained and ignored.
- Secrets are never persisted. There is no encryption at rest in this
repository, so a `secret` key is deployment-supplied and mapped in by the
host under a name the module never sees. A secret declaration has no
`default` field, the write API refuses secret material, and the HTTP view
has no `value` field for one — absent by construction, not filtered.
- Modules receive a frozen `context.config` on the registration, runtime,
and HTTP handler contexts: the same object identity, per module, beside
`services` rather than inside it (services is deliberately one shared
instance). No environment access, no database reference, no way to reach
another module's values.
- Configuration decides eligibility through ADR 0028's existing resolver:
three new blocked reasons, each with a distinct operator fix, propagating
to required dependents through the same mechanism as a disabled module.
- Changes take effect at the next restart; both resources report
restartRequired. New restricted permission
`core.modules.configuration.manage`, separate from lifecycle, at the
sibling prefix `/api/v1/module-configuration`.
- Migration participation stays independent of configuration validity.
Endpoints and credentials for shared infrastructure stay platform
concerns; a module declares which bucket it needs, not an S3 endpoint.
See ADR 0029.
Co-Authored-By: Claude Opus 5 <[email protected]>
Introduce ModuleDatabase (a typed, restricted Drizzle query surface) and the frozen
ModuleRuntimeServices boundary in @ekklesia/contracts, and thread the same services object
through Core's module start/stop lifecycle hooks and apps/api's authorized module HTTP handler
context. apps/api builds the facade via a new core/src/modules/database.ts view (createModuleDatabaseView)
over the one existing shared PostgreSQL pool, alongside the identity and authorization views, and
wires it into startApi's fixed startup order ahead of Identity/Authorization construction.
Registration stays database-free; a module reaches its database only through an authorized start,
stop, or HTTP handler invocation.
Phase 5B, pass 1: framework-neutral module HTTP route contracts and runtime
registration. Adds @ekklesia/contracts' module-http.ts (methods, canonical
path grammar, route definition/context/handler types, and validation)
and Core's module runtime staging/publication of a module's declared
routes alongside its capabilities, gated on the module's own manifest
permissions. Routes are collected into StartedModuleRuntime as an
immutable snapshot but are not yet mounted into apps/api; that is pass 2.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
