54 Commits

Include renames

Author	SHA1	Message	Date
ekklesia	4be046c8d0	fix: support native package verifier scratch	2026-10-09 18:05:04 -05:00
ekklesiaandClaude Opus 5.5	e083c44e05	feat: corresponding-source artifacts for native packages that redistribute copyleft code (ADR 0055) ... Ekklesia may publicly distribute a native Module Package containing LGPL or MPL components only beside a version-specific corresponding-source artifact. The artifact carries the exact source, patches, build definitions, and rebuild and relink instructions for those components. ADR 0055 (Accepted) records the policy: project compliance policy, not legal certification. It decides the item ADR 0052 deferred, and extends ADR 0049's distributable-release gate. Module Package v1, packageFormat 1, and both libvips supplements are unchanged. The mechanism is generic and lives in @ekklesia/module-pack: - Source recipes: reviewed data under corresponding-sources/<package>/<version>/. recipe.json names the exact package (name, version, content digest) and the exact supplement it was prepared with, and lists every component with its role, licence, licence material, and relationship to the binary. Every source file and patch is recorded by origin, size, and SHA-256; documents are hashed too, and every exclusion has a reason. Loading is strict and refuses anything unlisted. - Acquisition (the only network step) fetches each recorded file once into a cache keyed by SHA-256. It uses node:https with exact headers and no decoding, retries transient failures, and stores only bytes that match. - Construction is offline. From a built package it finds the covered native dependencies (by declared licence, or by a supplement component's licence), verifies every byte, and writes four sibling artifacts: the deterministic <package>-corresponding-source.tar.gz and its .sha256; <package>.redistribution.json, linking package, dependencies, supplement, recipe, and source by digest; and <package>.source-notice.txt, the release notice. - The public-distribution gate (verifyRedistribution, `ekklesia-corresponding-source verify`) approves only when the recipe, supplement, canonical archive, manifest, and metadata identify exactly these files. It refuses bundled copyleft code, and approves packages with no covered native code without an artifact. packModule is untouched. First complete proof: @img/[email protected] (sharp 0.35.5), from the reviewed supplement and provenance. - 383 components and 387 source files, about 208 MB: the sharp-libvips v1.3.4 build definitions, the 27 library archives, the five build-time patches, the 353 crates librsvg's resolved Cargo.lock records, and rust-src for nightly-2026-09-27 (rustc 75a75c3e0), which vendors std's dependencies. - BUILDING.md and two helpers point sharp-libvips's unchanged build logic at those files. - Followed in a Rocky Linux 8 container with networking disabled, they rebuilt libvips-cpp.so.8.18.7, byte-identically across two builds. Swapped into a verified, extracted native package, the rebuilt library was the one loaded, and sharp ran. - The native proof's source artifact, native-proof-0.1.0-linux-x64-glibc-corresponding-source.tar.gz, is 207242785 bytes, sha256 cc405492032b04a5391ab84e64f0e5e50f78e571ef7818204782c25a03eb50b7. It is byte-identical from unrelated directories and from a cache acquired fresh from upstream. Tests: - corresponding-source.test.ts runs in CI: synthetic inputs, every negative case, acquisition with retries and refusal, and determinism. - corresponding-source-native.test.ts checks the real recipe everywhere. With a verified cache (`pnpm test:corresponding-source`, which acquires once) it builds the real artifact twice, gates it, fails it closed, and runs sharp from the package. Docs: the module guide's distribution section, the README and architecture notes, and an ADR 0052 cross-reference. No Signage change, version bump, publication, or tag. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 23:17:35 -05:00
ekklesiaandClaude Opus 5.5	afaf3a853c	feat: reviewed libvips 1.3.4 supplement, and the native proof on sharp 0.35.5 ... sharp 0.35.4 carries a production-relevant librsvg advisory (GHSA-wq5f-xc86-pv6w). Its fix, sharp 0.35.5, loads @img/sharp-libvips-linux-x64 1.3.4, which ships no licence material either. This adds the reviewed supplement for that exact package (ADR 0052) and moves the packager's native proof to sharp 0.35.5, so a later 0.2.1 release can package it on linux-x64-glibc. Nothing in module-pack's code changes: supplement selection is already by exact name, version, and content digest. - Supplement: license-supplements/@img/sharp-libvips-linux-x64/1.3.4/ - content digest ekklesia-content-v1:sha256:2927fe11493461fa34847191d0b9b1c6441007c3e99f306e5708cb07fb0a5e59; - 190 components and 146 hashed texts; - assembled with the same method as 1.3.3's, from sharp-libvips v1.3.4's own inputs. That method reproduces the 1.3.3 supplement byte for byte. - PROVENANCE.md records: - the 27 upstream archives and five build-time patches, by sha256; - the librsvg 2.63.2 crate reproduction (cargo 1.99.0; Cargo.lock 5723e14c…); - rustc 75a75c3e…; - every change from 1.3.3. - Notable: sharp-libvips v1.3.4 now states cairo is used under MPL 1.1, not MPL 2.0. cairo ships that text itself, so the standard MPL 2.0 text is no longer added for cairo; selectors still carries it. - No legal conclusion: the LGPL and MPL source-availability determination stays open, as for 1.3.3. - The 1.3.3 supplement is unchanged, and still proven: module-pack keeps sharp 0.35.4 as a test-only devDependency alias (`sharp-0.35.4`). Each supplement is pinned against its real installed libvips, and each matches only its own. - Native proof fixture: sharp 0.35.4 → 0.35.5. The closure has the same shape: sharp, @img/colour, detect-libc, semver, and @img/sharp-linux-x64 0.35.5 with @img/sharp-libvips-linux-x64 1.3.4. The runtime read from the binaries is unchanged: Node-API 9, glibc >= 2.28, x86-64. - Docs: the module guide's note on available supplements. No version bump, no publication, no tag. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 21:34:35 -05:00
ekklesiaandClaude Opus 5.5	98e59d4ba0	chore(release): prepare 0.2.0 ... Every platform workspace package and every public @ekklesia/* package declares 0.2.0, and the deploy README's image build example names it. templates/module keeps its own version. 0.2.0, not 0.1.3: before 1.0 a minor version is the breaking one (docs/development/releases.md, ADR 0054), and since 0.1.2 main has broken modules, module authors, and operators: - #64 (ADR 0048): one generic image; installed modules live outside it; - #66, #72 (ADR 0049, 0050): modules install as Module Package v1, and move to the Module Database ABI; - #71: the manifest v8 cutover; v7 manifests are refused; - #79 (ADR 0053): the curated SDK drops defineModuleSchema and the legacy ModuleDatabase type; plus #67 (AGPL), #74, #77 (licensing, native targets), and the public package train (#80, #81). It is also the first package train to publish: 0.1.2 never will be. Because 0.2.0 is outside ^0.1.0, the same change moves to ^0.2.0: - the standalone fixture's @ekklesia ranges and its exact module-pack pin; - the compatibility ranges of the modules built for this release: the template, the standalone fixture, and the native proof module; - the test fixtures that model a module of the current release, or the current platform's versions; - the module-development guide's examples, and the release guide, which now names what a minor bump moves. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 17:26:13 -05:00
ekklesiaandClaude Opus 5.5	486356a01e	docs: ADR 0054, Ekklesia's module-development packages are publicly readable before launch ... ADR 0053 was accepted assuming a private package phase before launch. The project owner has decided otherwise: Ekklesia is not secret, its source is already public, and only publication must be restricted. ADR 0054 supersedes ADR 0053 only where it describes that phase as private or requires authenticated package reads. Packages may be read anonymously, which is neither a launch nor an API stability promise beyond pre-1.0 SemVer; publication stays authenticated and restricted; published versions stay immutable; the River_of_Glory_Church Gitea namespace is an acceptable host; a public launch remains a separate decision. Every other ADR 0053 decision is unchanged. ADR 0053 gets only a cross-reference line. The ADR index, the release and module-development guides, the README status, and the publish workflow's comment now point at ADR 0054. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 10:24:17 -05:00
ekklesiaandClaude Opus 5.5	d3c62e63bf	feat: publish the exact @ekklesia package train to the npm registry (ADR 0053) ... Publishes one package release train to the Gitea npm registry under River_of_Glory_Church, whose packages are publicly readable on purpose: exactly the .tgz files the package-release gate proved, and nothing else. Nothing is published by this change. - scripts/publish-package-train.ts validates the whole local train before any request (gate manifest hash, version, revision, unmodified source, the nine packages, every artifact's size, SHA-256, integrity, SHA256SUMS line, and inner package.json), then publishes in dependency order with `npm publish <file.tgz>` under a staging tag. Each package is reconciled first (absent: publish; same bytes: accept; other bytes: hard stop, version burned), then read back: metadata (name, version, integrity, dependency maps, normalized bin, tarball on the registry) and the tarball itself, byte for byte, also anonymously. `latest` moves only after all nine verify; reruns converge and never delete anything. It writes a publication record. The token comes from EKKLESIA_PACKAGES_PUBLISH_TOKEN only, through a temporary npm config that refers to the variable. - scripts/test-package-publication.sh proves it against a disposable Gitea 1.27.2 with public owners, a publisher team and an outsider: anonymous reads, refused unauthorized publishing, byte-identical round trips, the registry's own 409, partial-train recovery, the burned version hard stop, and dist-tag retry convergence. - CI: package-release keeps its proven release and hands it on as an artifact with its manifest hash; the new package-publication job publishes exactly that artifact to the disposable Gitea. Artifact actions v3 (node20): v4 refuses any server other than github.com. - .github/workflows/publish-packages.yml publishes to the real registry only by manual dispatch on main, after its own gate run, with the secret in the publish step alone. - docs: the public-read model, the workflow, the record, credentials, immutability policy, provider moves, and the first-publication steps. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 09:49:27 -05:00
ekklesiaandClaude Opus 5.5	9debe4e891	feat: the public @ekklesia package release train, built, reproduced, and proven (ADR 0053) ... Produces the exact public package tarballs of a platform release, validates them, and proves a standalone module consumes those artifacts end to end. Nothing is published and no credential is configured. - scripts/package-release.ts (pnpm packages:release) is the canonical release builder: from a clean commit it rebuilds the nine public packages from clean output, packs each, inspects every tarball, checks the release set and coordinated versions, and only then writes ekklesia-packages-<version>/ with the tarballs, SHA256SUMS, and a provider-neutral manifest (ekklesia-package-train.json: version, revision, and each package's file, size, SHA-256, npm integrity). - Packing uses a pack-only pnpm beforePacking hook (passed with --config.pnpmfile, never the workspace's install settings). pnpm inserts rewritten workspace: dependencies in async completion order, so two checkouts of one commit packed module-pack's package.json with keys in a different order; the hook restores the source key order (and the inspection enforces it). It also drops devDependencies, which named private packages outside the train. - scripts/test-package-release.sh (pnpm test:package-release, the CI package-release gate) builds the train twice, the second time from a separate worktree, requires byte-identical release directories, then runs the standalone consumer proof on the release: manifest checked, offline install from the tarballs only, lockfile integrity equal to the manifest's, frozen-lockfile reinstall, no Drizzle, one React, contracts only transitive, every @ekklesia package and module-pack at the release version, skipLibCheck: false, UI build, pack, and Core verification. - docs/development/releases.md documents the release order, the train, the artifacts, and the reproducibility findings; registry publication remains unimplemented. - ADR 0053 is Accepted: everything it decides that does not need a registry is now proven, and registry provisioning is on its own Deferred list. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 08:02:41 -05:00
ekklesiaandClaude Opus 5.5	89d5d0f2da	feat: standalone module-build readiness for the public @ekklesia packages (ADR 0053) ... Makes the public module-development package set usable from a module repository outside the monorepo. Nothing is published. - Curated @ekklesia/module-sdk: an explicit author API, no contracts barrel, no identity/authorization internals, no Drizzle and no legacy ModuleDatabase type. defineModuleRuntime returns the SDK's own named interfaces so a module's emitted declarations never reach into @ekklesia/contracts. defineModuleSchema is gone; createModuleTable and defineModuleSchemaMetadata live in @ekklesia/module-database. - Drizzle: no longer a dependency of module-sdk or contracts. Core keeps the legacy Drizzle schema validator (moved to core/src/modules) and its legacy runtime support; drizzle-orm is an optional peer only. - React is a peer (plus devDependency) of @ekklesia/ui; the boundary checker allows exactly that consumer-selected peer. - @ekklesia/typescript-config is publishable; module-ui-host is private. Every public package carries "ekklesia.distribution": "module-development" and no monorepo-root prepack. - module-pack reads the Node.js range from the module's own engines.node and recognizes Ekklesia packages by name plus that marker, so registry-installed packages are incorporated, SDK-compatibility checked, and never credited as third-party. - scripts/pack-public-packages.ts (pnpm packages:pack) rebuilds, packs and inspects the nine public tarballs; scripts/test-standalone-module.sh (pnpm test:standalone-module, new CI job) installs them into a fixture module outside the repository and proves it typechecks, builds, packages, and verifies. - Public-package boundary tests and module-development docs. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 07:28:54 -05:00
ekklesiaandClaude Opus 5.5	44d385cd7f	feat: native linux-x64-glibc module packages and reviewed license supplements (ADR 0049, ADR 0052) ... Implements ADR 0049's deferred native target and ADR 0052's reviewed license supplements. The proof case is a real module using sharp. packageFormat stays 1, and `any` is unchanged. Packager (@ekklesia/module-pack): - --target linux-x64-glibc. Native or platform-specific packages, found by the same generic rule that refuses them in `any`, stay outside the bundle. - Each native package's production closure is walked through its own dependencies, installed optionalDependencies that match the target, and required peers. It is copied as real files flat under node_modules/<name>, with no links, dev dependencies, declarations, source maps, or other platforms' packages. Missing or foreign-platform required dependencies, version conflicts, links, foreign machines, and Node.js range conflicts fail closed. - runtime.nodeApi, nodeAbi, and libcVersion are read from the binaries by a small ELF reader: the addon's node_api_module_get_api_version_v1 and the newest GLIBC_ symbol version needed. No shelling out. A native target with no addon is refused. - ADR 0052 supplements: package-provided material stays primary. An exact match on name, version, and ekklesia-content-v1 digest (sorted normalized paths with each file's size and SHA-256; no metadata) adds labelled material after the package's own. Any mismatch, a declared-licence conflict, or a malformed or unreviewed supplement file fails. Missing material with no supplement still fails. Supplement for @img/[email protected]: - 184 components and 143 unique texts, assembled from the exact upstream sources sharp-libvips v1.3.3 builds linux-x64 from: 27 C/C++ libraries, glib's gvdb, librsvg's Rust crates (reproduced with cargo tree), the Rust standard library at the rustc commit recorded in the binary, plus the LGPL-3.0, GPL-3.0, and MPL-2.0 texts. Each source is recorded with its SHA-256 in PROVENANCE.md. - It pins digest ekklesia-content-v1:sha256:50647b0b…, which is identical from the installed copy and from the registry tarball. - LGPL/MPL source-availability determinations stay open, as ADR 0052 states. Nothing claims they are met. Verifier (Core): - linux-x64-glibc is accepted only on a host whose platform, arch, glibc family and version, and Node-API version (from Node itself) match. - Every ELF file must be x86-64; every .node must be an ELF object. - `any` packages now also refuse node_modules/ and ELF files. - Contract: native metadata must state nodeApi or nodeAbi, and Linux targets libcVersion (ADR 0049). Proof: - A checked-in AGPL native fixture packs byte-identically from unrelated copies (8.86 MB) and verifies with Core's verifier. - Extracted elsewhere, it runs a sharp resize and PNG round trip in an empty-environment process. Every resolution stays in the package, and only the package's addon and libvips plus host system libraries load. Signage is untouched. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 20:16:53 -05:00
ekklesiaandClaude Opus 5.5	85fae9e07e	feat: Module Package v1 carries the module's own license (ADR 0051) ... Every Module Package v1 now declares the module's license and carries its text. packageFormat stays 1; pre-ADR-0051 metadata fails closed. - Contracts: ekklesia.package.json requires an SPDX `license` expression, validated with spdx-expression-parse, with UNLICENSED and non-expressions refused. The `files` list must hold exactly one non-empty root LICENSE. The package contracts move to the @ekklesia/contracts/module-package subpath, so the SPDX parser and its data (spdx-exceptions and spdx-license-ids ship no licence files) never reach a module bundle through the SDK's re-export of the contracts root. - Packager: reads the source package.json's string SPDX declaration and never invents one. It requires an explicit --license-file (a non-empty regular file, no symlink, no parent search, no download) and copies its bytes unchanged to LICENSE, listed with size and SHA-256 and covered by the archive digest. THIRD_PARTY_NOTICES stays third-party only, and bundled Ekklesia code stays in `incorporates`. - Verifier: rejects missing or invalid license metadata, and a missing, unlisted, duplicated, or corrupted LICENSE, through the schema and the existing strict inventory. - Template: packaged as AGPL-3.0-or-later with the repository's canonical LICENSE, passed explicitly (Dockerfile, smoke, docs). Packing it twice gives byte-identical archives. Started by Codex; reviewed and completed in Claude Code (empty license-text refusal, schema non-empty LICENSE, symlink and empty-file tests). ADR 0051 is Accepted. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 18:51:03 -05:00
ekklesia	70854d234c	feat: transition module packages to database ABI v1	2026-10-07 18:00:04 -05:00
ekklesia	49b4d4165d	feat: deliver module database ABI by manifest	2026-10-07 17:29:32 -05:00
ekklesia	859675c3c7	feat: add module database ABI v1 adapters	2026-10-07 16:44:28 -05:00
ekklesiaandClaude Opus 5.5	52a665502f	chore: license Ekklesia under AGPL-3.0-or-later instead of AGPL-3.0-only ... The project decision is the GNU Affero General Public License, version 3 or (at your option) any later version. - "license": "AGPL-3.0-or-later" in all 14 Ekklesia-owned package.json files. - README: the License section states AGPL v3 or any later version (SPDX AGPL-3.0-or-later) and carries the FSF's standard grant: "either version 3 of the License, or (at your option) any later version", with its warranty disclaimer and pointer to the license. - Module template README and module development guide: AGPL-3.0-or-later for Ekklesia and official modules. LICENSE is unchanged: it remains the canonical AGPLv3 text. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 13:53:56 -05:00
ekklesiaandClaude Opus 5.5	9a328f647e	chore: license Ekklesia under AGPL-3.0-only ... Ekklesia is open source under the GNU Affero General Public License, version 3 only. Module Package v1 (#66) bundles Ekklesia's SDK and contracts into distributable module packages, so the platform needs an explicit license before such artifacts are distributed. - LICENSE: the GNU AGPL v3 text, verbatim from https://www.gnu.org/licenses/agpl-3.0.txt (sha256 0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0). - "license": "AGPL-3.0-only" in the root package.json and every Ekklesia workspace package (13 packages), the module template included. Nothing else in any manifest changed. - README: a License section replacing the "no license selected yet" placeholder: AGPL v3 only, source available under its terms, section 13's network-use obligation, and the policy that official Ekklesia modules use AGPL-3.0-only. - Module template README and module development guide: the template declares the license; Module Package v1 does not yet record a module's own license, which needs a format change under ADR 0049. AGPL-3.0-only, not -or-later: the decision is AGPL-3.0, and nothing in the repository grants later versions. No runtime, ADR, package-format, Signage, or instance change. The packaged template is byte-identical before and after. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 13:38:33 -05:00
ekklesiaandClaude Opus 5.5	35ef31df9f	feat: Ekklesia Module Package v1, the canonical packager and verifier (ADR 0049) ... A separately versioned module is now distributed as one deterministic .tar.gz and its SHA-256, produced by an Ekklesia-owned packager and checked by Core before anything is installed. This slice implements the portable `any` target, with the module template as the end-to-end proof. ADR 0049 is accepted. @ekklesia/contracts: the Module Package v1 contract. The strict ekklesia.package.json schema (packageFormat 1, identity, target, runtime, provenance, incorporated Ekklesia packages, strict transitional facts, an exact byte-wise-sorted file list with size and SHA-256), target names, and the generated runtime package.json. @ekklesia/module-pack (new, tooling): `ekklesia-pack-module --module <dir> --target any --out <dir> --source-revision <commit>`. - Bundles server, schema, and jobs with esbuild, SDK, contracts, and Drizzle included; only Node built-ins remain imports. Any warning, unresolved import, external dependency, or native or platform-specific package fails. - Copies browser artifacts as built, after proving them current, and the migrations; generates package.json and ekklesia.package.json; never ships src, tests, declarations, source maps, or workspace ranges. - THIRD_PARTY_NOTICES: every third-party package traced from the bundles' own inputs, credited once with its declared licence and every licence, copying, copyright, and notice file it ships. A missing licence fails; a missing text fails unless its standard text is complete without copyright lines (Apache-2.0, vendored, needed by drizzle-orm). - Deterministic ustar and gzip: sorted paths, uid/gid 0, empty names, mtime 0, 0755/0644, no links. Byte-identical across runs and machines. - Writes only the archive and its .sha256; never deploys, links, or installs, so the workspace's install state is untouched. Core: verifyModulePackage and `verify-module-package.js <archive> [--sha256 | --sha256-file] [--extract-to <new dir>]`. Reads the archive in memory and refuses links, special entries, setuid/setgid/sticky modes, unsafe or escaping paths, and a second top-level directory; checks metadata, every file, identity, target, Node.js range, SDK, and the transitional Drizzle agreement; runs the platform's module and migration discovery; loads the backend once in a forked process with an empty environment; only then extracts, with normalized modes, into a new directory. Errors are sanitized. @ekklesia/module-ui-build: analyzeModuleUi reports each artifact's inputs and whether the built file is current. The nested stylesheet build now works from the module directory, so artifacts no longer depend on the caller's working directory. The split deploy smoke builds the package with the canonical packager (scripts/lib/build-module-package.Dockerfile replaces the test-only pnpm deploy packaging), verifies it with the same generic image, installs the verified tree, removes it, and reinstalls the exact same archive. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 12:44:54 -05:00
ekklesiaandClaude Opus 5.5	1119cc5fdf	docs: propose ADR 0049, Ekklesia Module Package v1 ... A separately versioned module is distributed as one immutable, self-contained, deterministic .tar.gz with a separately distributed SHA-256. The package contract is independent of hosting, registry, transport, and marketplace. ADR 0049 extends ADR 0048 with: - the package layout: one top-level module directory with a generated runtime package.json, the unchanged manifest, ekklesia.package.json, bundled backend entrypoints, built browser artifacts, migrations, THIRD_PARTY_NOTICES, and node_modules only for native dependencies; - backend bundling of all pure-JavaScript dependencies, with externals decided and validated by the canonical packager, never by module authors; - targets: `any`, or <platform>-<arch>[-<libc>] (linux-x64-glibc for Signage); - ekklesia.package.json (packageFormat 1): id, version, target, runtime needs, provenance, incorporated SDK versions, a `transitional` Drizzle requirement explicitly not the Module Database ABI, and per-file size and SHA-256; - archive safety: no links of any kind, no absolute or `..` paths, no special files or setuid/setgid; extraction normalizes ownership and modes; - the intended installation lifecycle and its rollback limit: code-only rollback only before new migrations apply, a backup restore after; - integrity, not authenticity; signing and trust roots deferred; - pnpm deploy explicitly not the packaging mechanism. Status Proposed, following the repository's usual lifecycle. ADR 0047 gains a cross-reference to consume canonical packages. The module development guide no longer recommends running pnpm deploy in a workspace, which corrupts that workspace's install state. No runtime, tooling, Docker, CI, Signage, or instance changes. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 10:13:34 -05:00
ekklesiaandClaude Opus 5.5	e36b70d8d4	feat: one generic image, with installed modules in installation-owned storage (ADR 0048) ... The production image now contains zero feature modules and is the same for every installation. Installed modules live in module storage that one Core resolver selects from EKKLESIA_MODULES_DIR: the checkout's modules/ when unset, an absolute path that must exist when set (/var/lib/ekklesia/modules in the image). A relative, blank, missing, or unreadable configured directory fails closed with a sanitized error that never contains the value. - Host configuration reads EKKLESIA_MODULES_DIR. The API, migration plan, apply and validate, module validation, module enablement, and Doctor all resolve it the same way; the test-only API override still takes precedence. - Doctor receives Core's migrations directory explicitly instead of deriving it from the modules directory's parent. - The migration runner retains and reports the applied history of a module that is not installed, and plans and applies Core's and present modules' migrations around it. Core's history and every installed module's history stay strict: a missing or changed applied migration, or a downgrade, still fails. No down migrations, no data deletion. - deploy/Dockerfile copies no module and installs nothing for the module template; .dockerignore excludes modules/ and the build refuses a context that contains it; the runtime has an empty root-owned /var/lib/ekklesia/modules and sets EKKLESIA_MODULES_DIR. - deploy/compose.yaml bind-mounts EKKLESIA_MODULES_HOST_DIR read-only into api and migrate, with create_host_path disabled. - scripts/check-image.sh proves the image holds no modules and that a populated modules/ directory leaves its runtime file system identical; CI runs it. - The split deploy smoke now uses the same generic image: it boots with no modules, installs a self-contained test module packaged from the template (test-only), migrates and restarts, removes it (Core runs, planning reports the retained history, data survives), and restores it with its data. Docs: deploy README (module storage, install/update/remove/restore, the runtime modules target), .env.example, API configuration, module development guide, testing, workflow, security, and the architecture overview. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-07 08:38:14 -05:00
ekklesiaandClaude Opus 5	ca3f37d5f9	feat: let a display survive its network — as code, not as authorization ... 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]>	2026-08-27 16:08:34 -05:00
ekklesiaandClaude Opus 5	e36485bf99	feat: let a module route stream an image-sized upload, explicitly and bounded ... ADR 0017 capped a module route at 1 MiB and said large media belonged to a future storage design. That design arrived — ADR 0030 gave modules a bucket, ADR 0031 took Ekklesia out of the read path — and it did not solve the write path: signed write URLs were deliberately declined, so the only way bytes reach a bucket is a module's own route, and a photograph is not 1 MiB. Extend the route contract rather than adding a second HTTP system. A route declares `bodyMode`: `buffered` (the default, and what every existing route already meant) keeps the 1 MiB ceiling and materializes the body before the handler runs; `streamed` raises the ceiling to 32 MiB and counts bytes as the handler consumes them, holding nothing. The mode is explicit rather than inferred from the size, because inferring it would mean an author who raised a limit silently changed how their own handler receives its body and when a 413 can reach their own code. 32 MiB holds one 25 MiB image plus bounded overhead and is also the platform's absolute ceiling: no route in any mode may declare more, and no unbounded option exists in the contract. The unit is one file per request — twenty images are twenty individually bounded requests, and nothing here can express a 500 MiB aggregate whose failure would waste everything already sent. Replace the buffering dependency with the platform's own limiter. A declared Content-Length over the limit is refused synchronously, before authorization and before a byte is read. Buffered mode now counts what actually arrives rather than trusting the header, which closes a gap the previous implementation had. Streamed mode wraps the body in a counting transform; on overflow the stream errors, the source is cancelled, and the response is replaced with the same sanitized 413 even if the handler swallowed the error — a limit a handler can swallow is not a limit. An unread body is cancelled so an abandoned upload releases its socket, and an abort stays an ordinary failed request rather than becoming a 413. Ordering is unchanged and now strictly better: in streamed mode no byte is read until the handler reads it, and the handler runs only after authorization succeeds, so an unauthorized caller cannot push an upload through at all. The live suite uploads a real 25 MiB body over a real socket end to end. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-27 15:57:44 -05:00
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
ekklesiaandClaude Opus 5	07835b7b56	feat: give module UI real stylesheets, and every artifact its own root ... ADR 0023 refused stylesheet imports for a good reason: esbuild would emit a `.css` sidecar beside the artifact, nothing would declare it, no host would fetch it, and it would work in a local test and silently do nothing in a real host. Inline style objects were the whole story. They cannot express `:hover`, `:focus-visible`, `:disabled`, `@media`, or `@keyframes` — so an accessible focus treatment was not expressible, and the shared elements added in the previous commit are built from real CSS for exactly that reason. Compile the stylesheet into the artifact instead of beside it. A module imports plain `.css`; the canonical builder resolves local `@import`s through a nested bundle and turns each file into its compiled text, which the author declares as `defineModuleUi({ styles })`. One declared file still contains everything: nothing extra to publish, nothing to fetch, and no way for CSS to become an asset nobody serves. The build additionally fails if a CSS output ever appears beside an artifact, so a future loader change cannot bring the sidecar back. Two rules are enforced with their own codes: a module stylesheet may reference `--ekklesia-*` and never declare one, and every `@import` must resolve locally or the artifact would fetch styles at run time. Plain `.css` only; other dialects are a toolchain decision needing their own ADR. Then make the isolation real. The generic loader mounts every browser artifact — primary, display, and later a contributed renderer — inside an open Shadow DOM root it creates, installs the artifact's stylesheet there, and hands the artifact an element inside it. Shadow DOM is the one mechanism a browser actually enforces; a class prefix or a "scope your selectors" instruction is a convention one mistake defeats, and the failure mode is a module silently restyling the Dashboard. It applies unconditionally, including to artifacts with no stylesheet, because a conditional boundary is one a module can fall out of by editing a source file. Both wrappers are `display: contents` through base rules installed before the artifact's own, so layout is unchanged and a full-viewport display can still override `:host`. Unmount removes the whole root in a `finally`, so a cleanup that throws cannot leave styles behind, and remounting cannot accumulate a second copy. This is a correctness boundary for styles and is not described as a sandbox: the root is `open` precisely because module code is trusted, same-realm code that could reach `document` anyway. An artifact's DOM is no longer a direct child of the host's element, so the mount ABI is versioned explicitly. `defineModuleUi` stamps `MODULE_UI_ABI_VERSION` so it can never drift from the SDK the artifact compiled against, and a version-1 artifact fails with its own code — "rebuild your module", not a typo hunt. No dual acceptance, matching every manifest cutover here. Migration is one `pnpm build`. `pnpm boundaries` allows `.css` only under `src/ui/` and `src/display/`: a stylesheet anywhere else in a module is the undeclared sidecar again, just relocated. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-27 07:21:14 -05:00
ekklesiaandClaude Opus 5	e03d38fcab	feat: give every Ekklesia screen one set of design tokens and elements ... Modules have owned their own UI since ADR 0021, but the platform has never said what that UI should look like. Every screen here — the Dashboard shell, the display host, the module template — invented its own hex colours, font stack, spacing, and radii, and they already disagreed. A module author had no vocabulary for "the ordinary panel background", so the only available answer was to invent one, and two modules would invent two. Add `@ekklesia/design-tokens`: one validated, enumerable registry of semantic tokens. A token declares a name, label, description, and default value; its category and `--ekklesia-*` identifier are derived from the name, so it can never claim one category while being named for another. Construction rejects duplicates, malformed names, unknown categories, empty or overlong text, and any value that is not a bounded literal — no declaration terminator, rule block, comment, at-rule, `url(`, `!important`, escape, control character, or markup. A registry that constructs can therefore be emitted as CSS without escaping, because nothing needing escaping can be in it. That validation is also what makes a future theme editor implementable rather than aspirational. Add `@ekklesia/ui`: button, icon button, text input, select, checkbox, field wrapper, panel, dialog, tabs, table and list primitives, badge, toast, and empty/error/loading states — every value a token reference, with real `:focus-visible` treatment and status that never depends on colour alone. Deliberately small: an element earns its place when two consumers need it. The stylesheet is a string rather than a `.css` file so the identical bytes install into a document or an isolated artifact root, and so hover, disabled, and focus-visible are real CSS rather than JavaScript approximations of them. `pnpm boundaries` opens exactly two shared roles to modules, by name — every other role stays rejected — and pins both design packages to the bottom of the presentation stack. Both are browser-safe by construction, proven by a real compile of module-shaped source in which `process.env` must fail to typecheck. The shell installs the defaults at its document root for the Dashboard and the display; custom properties inherit into module artifacts, so a module reads `var(--ekklesia-…)` with nothing to import at run time and nothing for a host to forget to pass. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-27 06:59:44 -05:00
ekklesiaandClaude Opus 5	2b4f0afb72	fix: give Doctor the host configuration the runtime receives ... `pnpm doctor` and `startApi` each read their own subset of the same environment variables, and the subsets had drifted. Doctor never read `S3_*` or module secrets at all, so a correctly configured installation was told its object storage was "not configured" and every module requiring a bucket or a secret was reported blocked -- while the runtime, from the identical environment, bound those buckets and ran the modules. Both executables now map the environment through one `loadHostConfiguration(env)` in Core, which takes the environment as an argument and never reads `process.env` itself. Validation stays with the existing per-domain validators, so each caller keeps its own failure behaviour: startup refuses a rejected value, Doctor reports it as a sanitized code. Doctor's storage option becomes raw input like its mail option, so a half-configured provider is reported as a blocking configuration failure instead of throwing before a report exists. The outbound-email check -- computed, counted toward the result, but absent from every rendered section -- is now printed, and the rendered set is asserted against a real report so a future check cannot go missing the same way. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-24 19:15:49 -05:00
ekklesia	2e0fe059c3	feat: add display kiosk host	2026-08-23 20:50:56 -05:00
ekklesia	fc6c8045c4	feat: add native module realtime transport	2026-08-23 18:47:18 -05:00
ekklesiaandClaude Opus 5	7ff063b87a	feat: deliver module objects directly to browsers through opaque read URLs ... ADR 0030 left exactly one way to get an image to a browser: read the object into the module's process and write it back out of a module HTTP route. Every byte of every asset travelled storage -> Ekklesia -> browser. For the slideshow this platform exists to replace that means Ekklesia in the path of every image on every display, permanently, for bytes that never change — and it would make Ekklesia responsible for re-implementing byte ranges, without which video seeking cannot work at all. A module can now ask a logical bucket for a temporary browser URL: const { url, expiresAt } = await assets.createReadUrl("slides/welcome.png"); The contract names intent, not mechanism. There is no signing, expiry format, endpoint, or bucket in it — a host with no S3 anywhere could satisfy the same method, which is what keeps a future single-module standalone host able to implement it. The URL is opaque to module code and a bearer capability to whoever holds it, so a module authorizes the request in its own route before asking: storage bounds reach, never identity. Lifetimes run one minute to six hours, fifteen by default, and out-of-range values are refused rather than clamped, so "expires forever" is unreachable. Logical keys stay canonical state; URLs are generated on demand and never persisted or logged. The provider endpoint and the browser delivery origin are separated because measurement showed they cannot be collapsed: an S3-compatible signature covers the request Host, so a URL signed for one origin and rewritten to another is rejected. The browser-facing origin is therefore a signing input (S3_DELIVERY_ENDPOINT), defaulting to S3_ENDPOINT — so the standard deployment configures nothing and delivery just works. The scheme is not signed, so a reverse proxy may terminate TLS provided it passes the original Host through; that is pinned by a test rather than described and hoped for. Read URLs are stable within a window of one third of their lifetime. Signing is a pure function of the clock, so naive re-signing yields a new URL per second — a guaranteed browser cache miss, and the reference client keys its <img> by URL, so an unchanged image would be torn down and re-downloaded continuously. Quantizing the signing timestamp makes repeated calls byte-identical while leaving at least two-thirds of the lifetime; Cache-Control is set at signing time to the guaranteed remainder, because the pinned SeaweedFS image sends none of its own. Verified against live SeaweedFS: byte ranges answered directly with 206 and a correct Content-Range, so no range proxy is needed in Core; signing is local (200 URLs in 66ms), so no batch API is needed; unsigned requests for the same object are refused, so delivery never depends on a public bucket; tampered signatures, swapped keys, and swapped buckets all rejected. Signed write and delete URLs are deliberately not built. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-23 17:12:07 -05:00
ekklesiaandClaude Opus 5	b9ca0d560d	feat: add host-provided module object storage ... `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]>	2026-08-23 08:45:53 -05:00
ekklesiaandClaude Opus 5	baa689b2a7	feat: add the module configuration and secrets contract ... 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]>	2026-08-22 21:44:43 -05:00
ekklesiaandClaude Opus 5	7729c99e24	feat: add the minimal operational module lifecycle ... Ekklesia had no notion of a module being on or off: the accepted module set was exactly "whatever discovery found on disk", and `ModuleLifecycleStage` named nine states nothing produced or consumed. This replaces that vocabulary with two axes that real code produces — persistent, administrator-owned configuration (`enabled`/`disabled`) and per-boot runtime observation (`running`/`disabled`/`blocked`) — and wires them through startup. - One Core table (`ekklesia_core_module_state`, migration 0004) holding only `module_id` and `enabled`. A module with no record is enabled by default, so deploying a module is still sufficient to run it and discovery never needs an initialization write. A record for an undeployed module is retained and ignored, so redeploying restores the decision. - `resolveModuleEligibility` is pure: a disabled module transitively blocks every module that *requires* it (module and capability edges alike) with a structured reason naming the provider; optional dependencies never block; and a missing, incompatible, or cyclic dependency stays discovery's concern. - `startApi` starts only the eligible set and builds the UI publication registry from that same list, so routes, artifacts, browser inventory, and Dashboard navigation all follow one authoritative set. A disabled module is never imported, so there is no per-request enablement check anywhere. - Startup stays all-or-nothing, deliberately; there is consequently no `failed` runtime state. `pnpm modules:enable`/`modules:disable` is the out-of-band recovery path for a module that breaks startup. - Changes take effect at the next start, and the read model reports configuration, runtime, and `restartRequired` separately rather than claiming a module stopped when it has not. - Migration participation and permission composition still span the deployed and discovered inventories respectively, unchanged. - New restricted platform permission `core.modules.lifecycle.manage` gates both reading and changing enablement, at a sibling prefix (`/api/v1/module-lifecycle`) that cannot collide with the module route namespace. - `pnpm doctor` gains a `modules.lifecycle` check so "why is this module unavailable?" is answerable without reading logs. See ADR 0028. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-22 14:45:34 -05:00
ekklesiaandClaude Opus 5	bd34c9c714	feat: add Dashboard navigation as presentation configuration ... Phase 6D pass 1. The shell's navigation was a flat list of module ids, which is not a usable experience — and the obvious fix carries an obvious trap. Letting a module declare its folder, or modelling "Media" as something Livestream and Video belong to, turns a rendering preference into architecture: a folder becomes an owner, membership starts to look like a dependency, and the flat module graph acquires a hierarchy nobody decided on. So the rule comes first: a Dashboard group is a label on a rendering bucket. No manifest, no version, no artifact, no API, no lifecycle; nothing depends on it. Livestream depends on Video because it calls Video's functionality, and that orders startup. Livestream is shown under Media, and that orders nothing. No parent module, child module, owning module, or group-derived dependency appears anywhere in the contracts. No manifest change and no version 5. `manifest.name` has been required since version 1 and already is the module's product identity, so the shell renders "Livestream" instead of `livestream` with nothing added. `suggestedGroup` is deliberately deferred rather than shipped: it would force a hard manifest-version cutover for a hint, and its only correct semantics needs initialization logic that risks a suggestion overwriting an administrator's decision. Defaulting and ownership are different things. Two Core tables (migration 0003) hold groups and placements — server-side, because a church configures its Dashboard rather than one browser; platform-global, because no organization model exists to scope them to. `group_id` is `on delete set null`, so deleting a group ungroups its modules and a dangling reference is impossible. `module_id` carries no foreign key, because modules are packages rather than rows, so a placement for an uninstalled module is retained and restores its position on reinstall. `resolveDashboardNavigation` is a pure function of configuration plus the mountable set: an unplaced module is ungrouped and visible with no initialization write, an absent module renders nothing, empty groups are kept, and ordering is total with the module id as final tie-break. `GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of the host-neutral module UI inventory rather than merged into it — each generic descriptor is embedded untouched, so a standalone host never inherits Dashboard semantics. Reading needs the permission the inventory already needs; organizing needs the new platform permission `core.dashboard.navigation.manage` through a narrow, idempotent, closed-validation mutation contract. No editor UI. The flatness rule is executable: a test discovers real fixtures with a genuine dependency, arranges them four ways including both in one folder and the dependency inverted in presentation, and asserts discovery order, dependency declarations, and the module set stay byte-identical. The end-to-end test organizes a real installation through the real API, mounts a module from inside a group, moves it, and asserts the navigation entry is byte-identical across the move and still mounts the same artifact. The shell's client for the generic inventory became dead code and was removed rather than kept speculatively; the endpoint itself is unchanged. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-22 12:44:40 -05:00
ekklesiaandClaude Opus 5	616c1d4834	feat: mount discovered module UI in a minimal Ekklesia browser host ... Phase 6C pass 2. Every link in the module UI chain existed except the one that closes it: a module could be authored, built, validated, published at a browser URL, and loaded by a generic loader — and nothing in Ekklesia did any of it. There was no browser application at all. Two pieces were missing. A browser could not discover what to mount, and it must not work that out for itself. GET /api/v1/module-ui is the inventory: per publishable module, its id and version, the server-produced artifact URL, the server-produced root of the module's own API, and the subset of that module's declared permissions the caller holds. Five fields, each because building a ModuleUiHostContext needs it — no filesystem paths, and no name/icon/folder/order, because navigation metadata is a design that does not exist yet. Its module set is the ADR 0025 publication registry rather than a rescan, so the inventory and the artifact route cannot disagree. It requires a new Core permission, core.modules.ui.read (baseline authenticated), because it is precisely the enumeration the anonymous artifact route deliberately withholds. Both URLs are server-produced. moduleUiArtifactUrl already existed; moduleApiBaseUrl is now exported and moduleRoutePath builds on it, so each URL shape has exactly one author. Without it the shell would hardcode /api/v1/modules/<id> — the prefix ADR 0022 forbids a module UI from spelling, reappearing in the host instead. surfaces/shell (@ekklesia/shell) is the repository's first surface: a small React application built to static files by its own esbuild script. It resolves the principal, fetches the inventory, builds the host context entirely from server-derived data, and hands the artifact URL to @ekklesia/module-ui-host. One frame per selection — keyed by module identity — defeats the stale-load race; the host owns the container, the loading state, and every failure, so a broken module costs its own panel rather than the shell. The shell statically imports no module, and both levels are checked: no source import may name a module, and the emitted bundle must contain exactly one dynamic import (the loader's) with no module id, no /api/v1/modules, no eval, and no blob URL. Permission hints come from Core's own evaluator and stay presentation-only — the end-to-end test has a UI holding no grant call its API anyway and still receive 403. Surfaces may now depend only on browser-safe shared roles; @ekklesia/contracts is deliberately excluded, since its barrel pulls Drizzle's types and Node's globals into the browser — the hole ADR 0024 closed one layer down. Not the Dashboard: no navigation, grouping, icons, ordering, design system, or routing. The selector is a list of module ids. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-22 08:55:44 -05:00
ekklesiaandClaude Opus 5	a02deb9433	feat: publish validated module UI artifacts at a platform-owned URL ... Phase 6C pass 1. ADR 0024 named the one thing missing between the module UI build pipeline and the generic host loader: Core resolves entrypoints.ui to an absolute server filesystem path, and a browser needs a URL. This adds that publication layer. Core owns the policy. createModuleUiPublicationRegistry builds, from the discovered and started module inventory, the answer to "may this be published, and which exact file is it?" — publishable means the module survived discovery and declares entrypoints.ui, with no new lifecycle state and no installer. apps/api owns the transport: GET /api/v1/module-ui/<module-id>/<version>. Both segments are lookup keys, not path components. An exact match yields the canonical artifact path discovery already validated; no request value is ever composed into a filesystem path, and the route declares no wildcard segment, so traversal, encoded separators, sibling chunks, package-root files, and source maps are unreachable by construction. An installed module directory never becomes a static file root. The prefix is a sibling of /api/v1/modules/, not a child: `ui` is a legal module route segment, so a module registering GET /ui/:version would otherwise compete with the platform for one URL with routing order deciding the winner. The route requires no authentication, deliberately. Fetching the bundle confers no authority, and a cookie-gated route would break cross-origin import(), which sends none. The cost is stated rather than hidden: a caller who knows a module id and its exact version can download that bundle. The three failure modes return one identical 404 so the route is not an enumeration oracle. Caching is no-cache with a strong SHA-256 ETag and RFC 9110 If-None-Match handling, not immutable: without an installer nothing stops a version being rebuilt with different bytes. The server reads bytes and writes bytes — never imports, evaluates, or transforms the artifact. Nothing mounts a module UI. A host could now obtain a URL, which was previously impossible; there is still no Dashboard shell, navigation, or metadata endpoint. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-22 08:11:53 -05:00
ekklesiaandClaude Opus 5	3f9b5e3cb0	fix: require a compiled artifact for entrypoints.jobs ... Module discovery gated the compiled-ESM rule on an allowlist, `["schema", "server", "ui"]`, so `entrypoints.jobs` accepted `./src/jobs/index.ts`. Every other executable entrypoint required a built `.js` or `.mjs`; `jobs` did not, purely because it was never added to that list. It is the second entrypoint to slip through the same way — `ui` did too, until Phase 6A added it explicitly — which is the argument against the allowlist rather than against `jobs`. The rule is now expressed as "every entrypoint except a directory entrypoint", with `migrations` the only member of that set. A new manifest entrypoint therefore defaults to the stricter validation instead of silently escaping it. The same constant replaces the two existing `=== "migrations"` special cases for the file/directory kind check and its message, so the one thing that distinguishes `migrations` is stated once. The directory message is now templated and produces byte-identical text. Every other entrypoint guarantee is untouched: package-relative paths, no traversal, inside-package before and after symlink resolution, the artifact must exist, and it must be a file. No runtime was added. `entrypoints.jobs` still has no consumer — it is declared, validated, and never executed — exactly as it has been since ADR 0006, and as `ui` was before its host loader existed. The manifest schema is unchanged and this stays within v4: the field, its type, and its optionality are all the same, and only discovery's validation of the declared path tightened. Compatibility impact is nil in first-party code: no module, template, or fixture declares a `jobs` entrypoint at all. A third-party module declaring a source-TypeScript path would now fail discovery, which is the intended correction. Tests cover accepted `.js` and `.mjs`, rejected `.ts`/`.tsx`/`.cjs`, a missing artifact, a directory, a symlink escaping the package, and that discovery still never evaluates the artifact. The three rejection cases were confirmed to fail against the previous implementation. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 22:07:54 -05:00
ekklesiaandClaude Opus 5	44e676f0df	feat: close the browser boundary and add the generic UI host loader ... Two gaps stood between the module UI contract and a host that could use it. ADR 0023 recorded the first honestly but never diagnosed it: a module UI file compiled with `"types": []` could still typecheck `process.env`. The second was simply missing — nothing imported a compiled artifact, checked its identity, mounted it, or tore it down. The leak was one type-only import, bisected against the real type graph rather than guessed. `@ekklesia/module-ui-sdk` imported `type { EkklesiaPrincipal } from "@ekklesia/contracts"`. Importing contracts/identity alone is clean and importing Zod alone is clean, but contracts exposes a single barrel entry, so that one import reached module-database, whose Drizzle types re-introduce Node's globals. The runtime was never affected — the import was erased and host-context.js is `export {}` — but a type-graph leak is still a real boundary failure, because it silently permits code that cannot run in its target environment. The fix is not a narrower import path. The SDK now has no dependencies at all, so there is no graph to leak through and no future contracts change can reopen this. It owns `ModuleUiPrincipal`: the same shape ADR 0022 chose, with the Zod brand dropped. That brand encodes a server-side parsing guarantee a browser cannot produce, and it is the same reason `permissions.has` already took a plain string. An Ekklesia host still passes its own `EkklesiaPrincipal` straight through — a branded string is assignable to `string` — while a standalone host builds the literal. Proven the way an author experiences it: two fixtures compiled under the exact project a module uses, one supported and one deliberately reaching for `process`, with the second required to fail on that specific name. `@ekklesia/module-ui-host` is the generic loader, in its own package because the SDK is bundled into every module artifact and host-only loader code has no business shipping there. The boundary checker enforces both directions: modules may not depend on the loader, and the loader may depend only on the SDK plus dev-time tooling. The distinction that shaped the design: Core resolves `entrypoints.ui` to an absolute path on the server's disk, and a browser needs a URL. A loader that accepted the path would test green on a server and fail in every real host, and would quietly own asset publication. So the loader takes a browser-loadable URL and knows nothing about how one is obtained. Ekklesia has no route that publishes installed artifacts, so this is precisely: loader complete, publication deferred. Nothing can mount an installed module UI yet, and the docs say so rather than implying otherwise. Dynamic import is `(url) => import(url)` with a non-analyzable specifier, kept as a runtime import so a host does not statically bundle every installed module or need a hardcoded registry. It is injectable for bundlers needing their own escape hatch, and deliberately not `eval` or `new Function`, which would cost a host `unsafe-eval` in its CSP. Identity is validated through the SDK's existing parser before `mount` runs, so a stale or mismatched bundle never renders. Contract violations propagate unwrapped; the loader adds only import and mount failure codes, sanitized, with the cause attached. Unmount is idempotent, safe when a module returned no cleanup, and marks an instance unmounted before running cleanup so a throwing cleanup surfaces once and never re-runs. A failed mount registers no cleanup. Each instance owns its own state, so two mounts coexist. The loader never mutates the host's container — not on success, failure, or unmount. Tests prove all of it against real module URLs (`data:`, which both browsers and Node import natively) rather than filesystem paths, including one artifact built by the canonical Pass 2 pipeline and run under both an Ekklesia-shaped and a standalone-shaped context. Core, apps/api, and the contracts package are untouched; discovery remains inert. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 21:44:42 -05:00
ekklesiaandClaude Opus 5	1e5866504e	feat: build module UI into its declared browser artifact ... ADR 0022 defined what a module UI is and selected React and TypeScript as the authoring model, but closed by recording that it was not buildable end to end: `browser.json` preserves JSX, bundler plugins are denied, and nothing turned a module's `.tsx` into the artifact its manifest declares. This closes exactly that gap. esbuild produces the artifact. It was already the right answer before it was chosen: this workspace resolves esbuild 0.28.1 through Vite/Vitest today and `pnpm-workspace.yaml` already carries `allowBuilds: esbuild`, so the pinned dependency adds no second copy and no new trust decision. It is also the smallest tool that covers TSX, ESM, browser platform, bundling, source maps, and a define-time constant with no plugin ecosystem. Vite library mode would drag in `@vitejs/plugin-react`, which the module boundary denies on purpose; `tsc` alone cannot bundle, so its output would carry bare `react/jsx-runtime` imports no browser resolves. React is bundled, not externalized. That follows from ADR 0022 rather than from convenience: `mount()` was made the ABI precisely so React would not be part of the host contract, and externalizing it would reverse that through the build system — every host would have to supply a compatible React, and a standalone host might not use React at all. The cost is real and accepted: duplicate runtimes and a ~570 KB unminified artifact. Sharing one runtime later is a build optimization that cannot change the contract, because the contract is a mount function. Output is browser ESM at `es2022`, unminified so an operator can review what they install, with `process.env.NODE_ENV` substituted — React reads it at module scope and would otherwise touch a Node global that does not exist in a browser. The output path is read from the module's own manifest rather than a build convention, so declared and produced artifacts cannot drift, and it is validated with the same `packageRelativePathSchema` discovery enforces, so a build can never write where discovery would later reject. `@ekklesia/module-ui-build` owns every option; modules own none. It uses the existing `tooling` role that modules could already depend on, so this pass required no boundary relaxation at all. Its `bin` points at a committed launcher rather than compiled output because pnpm links bins during install, before Turborepo builds anything — a bin targeting `dist/cli.js` fails to link on a fresh clone and breaks every module's UI build in CI. A module with no `entrypoints.ui` is not an error; the CLI reports nothing to build and exits zero, so one script serves both kinds of module. Styling is React inline style objects. A stylesheet import fails the build rather than emitting a sidecar `.css` that no manifest declares and no host loads — an undeclared asset would appear to work in tests and silently do nothing in a real host. `templates/module` is the canonical example and now ships optional UI. Its tests build the artifact from source, validate it with `parseModuleUiExport`, mount it into a real DOM, assert the rendered output, and unmount it; the artifact is rebuilt per run so the proof can never pass against stale output, and `dist/` stays gitignored. Because verify runs both `pnpm test` and `pnpm build`, a UI that cannot be produced fails CI through two independent paths. One correction worth stating plainly: the UI TypeScript project declares `"types": []`, and a UI file referencing `process` does fail in isolation, but TypeScript still pulls Node globals in transitively — a file importing `@ekklesia/module-ui-sdk` reaches `@ekklesia/contracts` and through its Zod and Drizzle types `process.env` typechecks again. The docs and ADR describe this as the convention it is rather than the guard it is not. Core is untouched. Building is an authoring step; discovery still only validates the artifact a module shipped and never executes or produces one. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 21:24:18 -05:00
ekklesiaandClaude Opus 5	8d651c427d	feat: define the module UI authoring model and host contract ... ADR 0021 established that a module may own UI and added a statically validated, never-executed `entrypoints.ui` path, but deliberately left five questions open: what the artifact exports, what a host provides, how one artifact runs under both Ekklesia and a standalone host, what the browser-side trust model is, and how module UI avoids being welded to a Dashboard that does not exist. This answers them. React and TypeScript are the supported module UI authoring model. The repository already leaned this way: `packages/typescript-config` ships a `browser.json` preset and a `react-native.json` preset with `"jsx": "react-jsx"`, and ADR 0002 names browser and React Native configurations. One framework is supported; every other stays rejected. React is deliberately not part of the contract. A module's compiled artifact default-exports `defineModuleUi({ id, version, mount })`, and `mount(container, context)` takes a DOM element and returns an unmount function. `id` and `version` are build-artifact identity markers a host verifies against the manifest, mirroring `defineModuleRuntime` exactly. A host needs an element and a context, never a matching rendering library, so a module's framework, a host's framework, and the platform boundary between them stay independent. The contract lives in a new `@ekklesia/module-ui-sdk` rather than in `@ekklesia/module-sdk`, for a concrete reason: that package re-exports all of `@ekklesia/contracts`, so routing module UI through it would drag Zod, Drizzle, and semver into every browser bundle. The new package has no runtime dependencies, and its one dependency on contracts is type-only — the emitted `host-context.js` is `export {};`, and a test pins that so it cannot regress. The host context is four members: `moduleId`, `api`, `principal`, and `permissions`. Navigation, theme, module configuration, organization context, and diagnostics are deliberately absent; each needs a design that does not exist. Module UI reaches its backend through `api.request(path)` with a path relative to its own API root and never constructs `/api/v1/modules/<id>/...`, which is Ekklesia's private deployment detail — a module that builds that URL is silently unhostable anywhere else. One fixture artifact is mounted under two hosts with different origins and URL shapes to prove it. Client-side permission hints are presentation only, and both the docs and a test say so plainly: a denied hint does not stop the module from calling its API, because server-side `requirePermission` is the only authority. Module UI is trusted code in the host's own browser realm — no iframe, no sandbox — which matches the backend model rather than overstating it, since a module's server half already holds the API's database authority. The boundary guard is narrowed precisely, not removed: `.tsx`, `react`, and `react-dom` are un-denied and modules may depend on the new `module-ui-sdk` role. `.jsx`, `.css`, every other framework, `react-router-dom`, `react-native`, and `@vitejs/plugin-react` stay denied, layer rules are untouched, and an unsupported framework aliased behind an allowed name (`"react": "npm:vue@3"`) is resolved and rejected by its real target. Fixtures prove each case, including that module UI source still cannot import Core. Core, apps/api, and the manifest contract are untouched. Discovery still validates the `entrypoints.ui` path and never evaluates it; hosts perform their own dynamic import and validate the result with `parseModuleUiExport`. No Dashboard shell, UI runtime, navigation, grouping, standalone host, build or styling pipeline, installer, hot-loading, or feature module is added. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 20:52:47 -05:00
ekklesiaandClaude Opus 5	44ba259f58	feat: establish the module product contract ... Ekklesia's module model has been backend-only since ADR 0001: a module owns domain behavior and data, and every presentation concern belongs to a surface. That prevents a module author — the person who knows the domain — from shipping the screen that makes their module useful, and it guarantees a module and its own UI drift apart. It also pushes toward two codebases for one domain the moment a module needs to run standalone. ADR 0021 replaces that rule. A module is an independently versioned product that owns its domain behavior, data, permissions, routes, migrations, and its own UI, hostable inside Ekklesia and — from the same implementation — by a later standalone host. Core keeps the containing application shell and every platform policy: authentication, authorization enforcement, platform context, top-level routing, navigation, global theme, error boundaries, and trusted-origin/CORS. The module graph stays flat: modules are peers, genuine module and capability dependencies remain the only relationships, and Dashboard folders are presentation configuration an administrator can reorganize, never module architecture. This pass implements the static contract only. `manifestVersion` moves to 4 and `entrypoints` gains one optional field, `ui`. Version 3's `entrypoints` is strict and rejects `ui`, so this is an incompatible shape change and version 3 is now rejected outright rather than reinterpreted, exactly as version 1 was by version 2 and version 2 by version 3. Every field version 4 adds is optional, so upgrading a backend-only manifest is a one-character edit. Discovery resolves and validates `ui` under the same rules as `server` and `schema` — package-relative, inside the package before and after symlink resolution, a real file, compiled ESM `.js`/`.mjs`, so source TypeScript is rejected rather than assumed to be compiled later. Discovery stays inert: nothing imports, evaluates, mounts, or renders a UI entrypoint, and a test proves a throwing artifact still discovers successfully. This follows `entrypoints.jobs`, declared and resolved since ADR 0006 with no runtime consumer. The name is `ui`, not `dashboard`, because a module's UI must be hostable by Ekklesia's shell and by a standalone host, so the contract cannot be named after one of them; and not `surface`, because `surfaces/*` is a separate ownership layer. No widget, route, icon, folder, menu, layout, or standalone-metadata field is added, and tests assert the manifest still rejects every unknown entrypoint key and offers no hierarchy field. Deliberately unchanged: `scripts/check-boundaries.ts` still enforces `modules-do-not-own-ui`. Relaxing that guard depends entirely on the UI authoring model a later pass chooses, and weakening a working protection before that decision exists would trade real coverage for nothing. A module may therefore declare `ui` today only for a framework-neutral compiled artifact, and the docs say so rather than implying otherwise. Restart-based discovery, explicit operator-invoked migrations, and the trusted compiled-module model are untouched — a module that ships UI is exactly as trusted as one that does not. No Dashboard shell, UI runtime, renderer, framework choice, navigation registry, grouping system, standalone host, installer, hot-loading, or feature module is added by this pass. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-08-21 20:20:41 -05:00
ekklesiaandClaude Opus 5	07a3c61083	docs: define deployment trust boundaries ... One canonical security document, linked from the README, platform architecture, and module-development guide, stating what the boundaries actually protect against — and, more importantly, what they do not. Installed modules are trusted compiled backend code. A module runs arbitrary JavaScript inside the API process and shares its PostgreSQL role and pool, so `ModuleDatabase.execute` gives it the API's full database authority over every table, including identity, grants, owner, bootstrap, and audit. Table prefixes, manifests, permission declarations, route validation, frozen contexts, typed facades, and the capability registry are correctness and coordination boundaries that assume a cooperative module; none of them constrains one that is not. There is no process, container, syscall, filesystem, network, database-role, schema, tenant, or resource sandbox between a module and Core, and the document says so in those words, along with what would have to be built before untrusted modules could be accepted. It also records the honest deployment state: Ekklesia is not deployed. There is no production instance, reverse proxy, public listener, or deployment automation anywhere in this repository, and no `.env` has ever been committed. The loopback listen default and the production signup refusal are real, but a config default is not a firewall, so the origin-reachability, proxy-overwrite, header-spoofing, and trusted-peer properties a public launch needs are written as a launch-blocking checklist rather than as guarantees. The per-process authentication limiter is described as exactly that, valid only while signup stays disabled and exactly one instance serves traffic. The CI section records the workflow's verified posture and deliberately stops there: a pull request can edit `runs-on`, so a workflow file cannot be the boundary, and the runner topology is not described as though it had been verified. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-07-28 19:49:12 -05:00
ekklesiaandClaude Opus 5	490b85b07c	fix: bound module lifecycle shutdown ... Nothing bounded shutdown, and a module that failed to start was never cleaned up. `startModules` appended to its rollback set only after `start()` resolved, so a hook that acquired a connection, registered a listener, or recorded partial initialization and then threw had its own `stop()` skipped, while every previously completed module was rolled back correctly. A module now joins the rollback set the moment its start hook is invoked: its own stop hook runs first, then earlier modules in reverse order. The original start issue stays first in the reported issues, and a failure stopping the failing module is appended without preventing the rest of the rollback. The consequence for module authors is explicit and documented — `stop()` may run after a partially completed `start()` and must be safe and idempotent about resources it may or may not hold. Neither stage of shutdown had a deadline. `shutdown()` awaited `server.close()` with no bound, so one open connection could hold it forever, and each stop or rollback hook was awaited without a bound, so a hook that never settled kept the pool open indefinitely. Both now have fixed, non-configurable defaults: 10 seconds per module hook and 30 seconds for the graceful HTTP drain. A hook that reaches its deadline records MODULE_STOP_TIMEOUT or MODULE_ROLLBACK_TIMEOUT and the sequence continues with the next module, so the whole stop sequence is finite in the started module count rather than one global ten-second bound. Timers that lose the race are cleared, the losing promise gets a permanent rejection handler so a late throw cannot become an unhandled rejection, and a timed-out hook is never awaited again. At the drain deadline the platform closes idle and then active connections through Node's own public closeIdleConnections/closeAllConnections, after server.close(), touching no private field, and stops waiting for the close callback. It then runs the bounded module stop sequence and closes the pool, so a drain timeout or a stop failure never skips later cleanup. Both are reported together as an ApiShutdownError carrying only fixed booleans and the already sanitized module error; a forced drain is a shutdown failure, not a success. Stated honestly rather than overstated: a deadline bounds how long the platform waits, not how long module code runs. An in-process promise cannot be canceled, and closing a socket does not prove a handler promise ended. What is guaranteed is that shutdown stops waiting and the pool closes afterwards, so late database work fails. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-07-26 23:12:18 -05:00
ekklesiaandClaude Opus 5	800ecfdb92	fix: reject ambiguous module routes ... A module can register both `GET /events/:id` and `GET /events/new`. Driven through the pinned router, `/events/new` reached the parameter handler under `demo.events.read` when the parameter route registered first, and the static handler under `demo.events.create` when it registered second. Nothing rejected the pair, so declaration order decided which permission guarded the path. That is a permission policy, not a routing preference, and it must not be inferred from array position. Two routes of one module now overlap when they share a method and a segment count and, at every position, either both segments are the same static literal or at least one is a parameter. Under this grammar — static literals or `:name` parameters, no wildcard, regex, optional, or catch-all — that is exactly "some concrete request path matches both". `moduleRoutesOverlap` implements it in the contracts package, where path semantics already live and Hono cannot reach. Core checks it during staged registration, after the existing duplicate check, so identical shapes (including paths differing only in parameter name) keep returning MODULE_ROUTE_DUPLICATE and a genuine intersection returns the new MODULE_ROUTE_OVERLAP. The rejected module publishes none of its staged routes or capabilities, no start hook runs, and no listener binds. Rejection rather than a specificity rule: ranking static above parameter would still silently pick which permission applies. Disjoint routes keep their order; different methods, different segment counts, and the same local path in two different modules (each has its own platform-owned mount prefix) all remain legal. The same requests also pinned down what handlers actually receive. Route declarations are validated; route *parameters* are not, and the two are unrelated. A single encoded segment arrives decoded as `/../admin`, `a\b`, an embedded NUL, CR/LF, `1; drop`, or non-ASCII text — none of which any declared path could contain. The contract now says so explicitly: decoded values are untrusted, module-owned input that a handler must validate against its own exact domain grammar before any database, filesystem, command, or identifier use, and re-encoding is not a substitute. No generic validator, path-normalization layer, or route field was added, because module parameters are module-owned domain types and one platform-wide pattern would either reject legitimate values or approve meaningless ones. Co-Authored-By: Claude Opus 5 <[email protected]>	2026-07-26 23:10:51 -05:00
ekklesiaandClaude Sonnet 5	d3c6bd73d3	fix: enforce API request limits ... Add a single platform-owned request-body policy (hono/body-limit) with small, named limits for Better Auth and Core's grant-mutation endpoint, and a new required maxBodyBytes field on the executable module route contract so every module route makes a conscious no-body-or-bounded-body choice, capped at a platform ceiling. Every oversized request gets one sanitized 413 contract and never reaches business logic, authorization, or a handler. Also configure finite Node header/request/keep-alive timeouts, including the non-obvious connectionsCheckingInterval needed for them to take effect promptly, so a slow-header or slow-body connection cannot hold a socket indefinitely. Co-Authored-By: Claude Sonnet 5 <[email protected]>	2026-07-26 12:29:24 -05:00
ekklesia	c38b572778	docs: document module database access ... Add ADR 0016 recording the accepted module database access design (ModuleDatabase, the frozen ModuleRuntimeServices boundary, one pool/one facade/one services-object identity, explicit migrations, and the trust model), with narrow cross-reference corrections to ADR 0006 and ADR 0015 where their original text is now inaccurate. Sweep docs/development/api.md, docs/development/authorization.md, docs/module-development/README.md, docs/development/testing.md, and docs/development/identity.md for the new database boundary and remaining Phase 4C staleness; correct the stale "Phase 4C is next" roadmap paragraph in platform-architecture.md and the matching gap in README's current-status narrative. Extend the module template with a permissioned GET /records route reading through context.services.database, using the canonical createModuleTable helper, with matching template tests.	2026-07-25 21:50:03 -05:00
ekklesiaandClaude Sonnet 5	dfaf324a65	feat: mount module HTTP routes ... Phase 5B, pass 2: production API mounting, authorization enforcement, and module-runtime lifecycle integration. apps/api now discovers the installed module inventory exactly once (prepareStartupModuleInventory), composes the platform permission registry from it, starts the module runtime from that same discovered list (startDiscoveredModuleRuntime, never rediscovering), and mounts StartedModuleRuntime's published routes under /api/v1/modules/<module-id> via a new apps/api-owned Hono adapter (module-http-routes.ts). Every module route is protected by the existing requirePermission middleware against the composed registry, state-changing methods additionally require a trusted Origin, OPTIONS remains entirely platform-owned, and a handler that throws, rejects, or returns a non-Response becomes a fixed, sanitized 500 MODULE_HANDLER_FAILED. Module-supplied CORS headers are stripped and every module response is forced to Cache-Control: no-store with Vary: Origin, Cookie. RunningApi shutdown now stops the module runtime between draining the HTTP server and closing the shared pool, and every startup failure path stops the runtime and/or closes the pool before propagating, without masking the original failure. Co-Authored-By: Claude Sonnet 5 <[email protected]>	2026-07-24 19:16:20 -05:00
ekklesiaandClaude Sonnet 5	e296e083ec	feat: define module HTTP routes ... 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]>	2026-07-24 18:36:23 -05:00
ekklesia	edd7148aa8	feat: integrate module authorization ... Wires composePlatformPermissionRegistry into apps/api's production startup: startApi() discovers every installed module, composes the one immutable platform permission registry (Core's own declarations plus every module's), and only then constructs the shared PostgreSQL pool, Better Auth, and the HTTP server. A discovery or composition failure — an invalid manifest, a reserved core.* namespace claim, or a duplicate declaration — propagates before anything exists to close; there is no Core-only registry fallback. apps/api/src/platform-permissions.ts resolves the repository root from its own file location, never process.cwd(), so package-scoped test runs discover the right modules/ directory. createApiApp/createGrantsRoutes now require the composed registry as an injected authorization option, replacing the previous hard-coded CORE_PERMISSION_REGISTRY; requirePermission continues to work identically for Core-owned and module-owned permissions, since it has no concept of the distinction. Extends pnpm doctor with a modules.permissions check (reusing the already-discovered module list, distinguishing reserved-namespace from generic-duplicate failures, never re-discovering modules) and pnpm modules:validate to compose the same registry before a module is considered installable. Adds focused coverage: startup-ordering and failure-isolation tests in apps/api/tests/lifecycle.test.ts, module-owned-declaration enforcement tests in apps/api/tests/authorization-middleware.test.ts, Doctor composition tests in core/tests/doctor.test.ts, and a live PostgreSQL end-to-end scenario proving a real installed module's permission is discoverable, grantable, and deniable once the module is absent again after a restart, without ever executing its server entrypoint.	2026-07-24 14:24:50 -05:00
ekklesia	d9dd409aa3	feat: declare module permissions ... Establishes the one canonical PermissionDeclaration contract (packages/contracts/src/authorization.ts) — id/baseline/description, strict, unknown-property-rejecting — consumed by both Core's authorization registry and module manifests, replacing Core's previously separate interface. Bumps the canonical module manifest to manifestVersion 3: permissions become complete declarations instead of bare identifier strings, with manifest-owned namespace and duplicate-id enforcement. Version 2 and bare string-array permissions are rejected outright; there is no compatibility adapter. Adds composePlatformPermissionRegistry (core/src/modules/permissions.ts), a pure, synchronous composer that builds one platform permission registry from Core's own declarations plus every already-discovered module's, in deterministic order, reusing createPermissionRegistry and rejecting any module-contributed permission in the reserved core.* namespace. core/src/authorization remains independent of core/src/modules; only the module integration layer depends on authorization. Updates the module template, module-development docs, authorization docs, and existing manifest fixtures for manifestVersion 3. Does not wire the combined registry into apps/api — that is pass 2.	2026-07-24 12:25:00 -05:00
ekklesia	02ee3ccd80	feat: add Ekklesia doctor command	2026-07-21 10:42:21 -05:00
ekklesia	831a48187c	test: add PostgreSQL migration integration coverage	2026-07-21 09:37:15 -05:00
ekklesia	0b282865cb	feat: add transactional module migration runner	2026-07-21 08:52:41 -05:00