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

docs/architecture/decisions/0049-module-package-v1.md

@@ -1,6 +1,6 @@
 # 0049: A module release is one immutable, self-contained package: Ekklesia Module Package v1
 
-- Status: Proposed
+- Status: Accepted
 - Date: 2026-10-07
 - Supersedes: none
 - Extends: [0048](0048-generic-image-and-installed-module-storage.md)

docs/architecture/decisions/README.md

@@ -57,4 +57,4 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0046: Ekklesia's branding is never forced on an installation](0046-installation-owned-branding.md) — Proposed
 - [0047: Every module proves itself inside Ekklesia, with one harness the platform publishes](0047-module-ci-harness.md) — Proposed
 - [0048: Ekklesia ships one generic image, and installed modules live outside it](0048-generic-image-and-installed-module-storage.md) — Accepted
-- [0049: A module release is one immutable, self-contained package: Ekklesia Module Package v1](0049-module-package-v1.md) — Proposed
+- [0049: A module release is one immutable, self-contained package: Ekklesia Module Package v1](0049-module-package-v1.md) — Accepted

docs/architecture/platform-architecture.md

@@ -672,3 +672,18 @@ artifact from what an installation installs:
   module that lost or changed an applied migration is still refused.
 - **Trust is unchanged.** Installed modules are still trusted code; module storage is mounted
   read-only, which keeps Ekklesia from modifying installed code but does not sandbox it.
+
+[ADR 0049](decisions/0049-module-package-v1.md) defines how a module is distributed: one Ekklesia
+Module Package v1, a deterministic `.tar.gz` with its SHA-256.
+
+- **The packager.** `@ekklesia/module-pack` bundles the module's backend with every pure-JavaScript
+  dependency, the SDK, contracts, and Drizzle included. It copies the built browser artifacts and
+  migrations, generates the runtime `package.json`, `ekklesia.package.json` with every file's digest,
+  and `THIRD_PARTY_NOTICES`, and writes the archive.
+- **The verifier.** Core's `verifyModulePackage` reads the archive in memory and refuses links,
+  special files, and escaping paths. It checks every digest and identity, the target and runtime,
+  and the transitional Drizzle agreement, runs the platform's own module and migration validation,
+  and loads the backend once in a short-lived process with an empty environment. Only then does it
+  extract anything.
+- **What exists today.** Only the `any` target. Drizzle agreement is recorded as transitional, not a
+  database ABI.

docs/development/security.md

@@ -479,7 +479,12 @@ Installed modules come from installation-owned module storage, which the referen
 is an integrity property, not a sandbox: an installed module is still trusted code with the API's
 database role, exactly as above. The repository's boundary checks prove only source modules in a
 workspace, and an installed package usually ships none, so installing one means trusting that
-module's own CI and whoever placed it in module storage.
+module's own CI and whoever placed it in module storage. A Module Package v1 (ADR 0049) is verified
+before it is installed: its digest, its archive safety (no links, special files, setuid bits, or
+escaping paths), every file's digest, and its identity and compatibility. The digest proves
+integrity, not who published the package; signing is not implemented. The verifier loads the backend
+in a short-lived process with an empty environment, so module code never sees a database URL or a
+secret while it is being checked.
 
 Two production defaults are relevant but are **not** by themselves a deployment guarantee:
 

docs/development/testing.md

@@ -564,6 +564,29 @@ the following pull-request status context to `main` branch protection:
 CI / migration-smoke (pull_request)
 ```
 
+## Module packages
+
+Ekklesia Module Package v1 (ADR 0049) is proven at three levels, all in `pnpm verify`:
+
+- `packages/contracts/tests/module-package.test.ts`: the `ekklesia.package.json` schema, target
+  names, and the generated runtime `package.json`.
+- `core/tests/module-package-verification.test.ts`: the verifier against hand-built archives,
+  including what the packager never produces. A valid package verifies and extracts with normalized
+  modes. A wrong digest, a corrupted or missing or unlisted file, disagreeing identities, an unknown
+  format, unknown transitional metadata, an incompatible target, Node.js range, SDK, or database
+  runtime, a missing entrypoint, a backend that imports something the package lacks, absolute and
+  `..` paths, symbolic and hard links, device nodes and FIFOs, setuid and setgid entries, a second
+  top-level directory, and a duplicate entry each fail with their own sanitized code. The backend
+  load check runs in a real child process.
+- `packages/module-pack/tests/`: the packager against generated fixture modules (payload contents,
+  generated `package.json`, metadata, bundled backend with only built-in imports, refusal of native
+  and platform-specific dependencies and of unknown or textless licences, notices, byte-identical
+  archives, normalized tar and gzip headers), and end to end against the built module template:
+  packed twice to identical bytes without changing the workspace's install state, verified by Core's
+  verifier, extracted elsewhere, and loaded with Node's own resolution hooks proving nothing outside
+  the package is resolved. Turbo builds the template and Core first, and runs the template's own
+  tests (which rebuild its UI in place) before these.
+
 ## The generic platform image and the reference deployment
 
 These need Docker and build images locally; nothing is pushed or published.
@@ -581,13 +604,13 @@ These need Docker and build images locally; nothing is pushed or published.
 - `pnpm deploy:smoke` (`scripts/smoke-deploy.sh`) runs the reference deployment end to end on the
   generic image with empty module storage. With `EKKLESIA_SMOKE_TOPOLOGY=split`, the same image also
   runs the installed-module lifecycle:
-  - the module template, packaged as a self-contained test module
-    (`scripts/lib/test-module-package.Dockerfile`, test-only), is installed into module storage;
+  - the module template is packaged by the canonical packager (Module Package v1, ADR 0049),
+    verified by the image's own verifier, and installed into module storage;
   - its migration is planned and explicitly applied, and the API restarted;
   - a real browser mounts it;
   - it is removed and the API restarted, and Core still runs, migrations still plan and apply, and
     its data survives;
-  - it is restored, with its data.
+  - the exact same package is verified and installed again, and the module returns with its data.
 
   See [deploy/README.md](../../deploy/README.md#testing-this-deployment).
 

docs/module-development/README.md

@@ -78,42 +78,79 @@ names (`/var/lib/ekklesia/modules` in the production image, the checkout's `modu
 unset). Discovery reads it only when a process starts. Nothing is hot loaded, and an installed module
 is read-only to the platform.
 
-An installed module directory is **self-contained for runtime use**. Everything the platform reads
-or loads from it, and everything those files import at run time, resolves inside it:
-
-- `package.json`, with no `workspace:` range needed at run time, and `ekklesia.module.json`;
-- every built artifact the manifest declares: `dist/server`, `dist/schema`, jobs, and the UI,
-  display, and contribution bundles;
-- the `drizzle/` migrations directory, with its journal and `_ekklesia.json`;
-- a `node_modules` holding the production dependencies of your server, schema, and jobs code,
-  including your own copies of `@ekklesia/module-sdk`, `@ekklesia/contracts`, and `drizzle-orm`.
+An installed module directory is **self-contained for runtime use**: everything the platform reads
+or loads from it, and everything those files import at run time, resolves inside it. You never
+assemble that directory by hand. You build your module, and the canonical packager turns it into an
+**Ekklesia Module Package v1**
+([ADR 0049](../architecture/decisions/0049-module-package-v1.md)): one deterministic archive and its
+SHA-256, which an installation verifies and extracts into module storage.
 
 **Copying `dist/` is not an installed module.** Your compiled server code imports
 `@ekklesia/module-sdk` and `drizzle-orm` by name, and Node resolves those only from your module's
 own directory upwards. The platform's `node_modules` is never on that path, and Ekklesia adds it
-through no link, `NODE_PATH`, loader hook, or alias. A module whose imports do not resolve stops the
-API from starting with a sanitized `MODULE_RUNTIME_IMPORT_FAILED`, so test the directory you ship,
-not your workspace.
+through no link, `NODE_PATH`, loader hook, or alias. The packager therefore bundles your backend.
 
-**Native dependencies** must match the platform image's runtime: Node.js 24.18.0 on Debian 13
-(glibc), on the image's CPU architecture.
+#### Packaging your module
+
+Build your module, then run the packager from the workspace your module is built in. It is a
+development dependency like `@ekklesia/module-ui-build`:
+
+```bash
+pnpm exec ekklesia-pack-module --module . --target any --out ../packages \
+  --source-revision "$(git rev-parse HEAD)"
+```
+
+It writes `<id>-<version>-any.tar.gz` and its `.sha256` line, and nothing else anywhere: it never
+installs, links, or deploys, so your workspace is left exactly as it was. Never run `pnpm deploy` in
+a workspace instead: it rewrites that workspace's install state to production-only.
+
+The archive holds one directory named with your module id:
+
+```text
+<id>/
+├── package.json            generated: name, version, private, "type": "module", the layer marker
+├── ekklesia.module.json    your manifest, byte for byte
+├── ekklesia.package.json   package metadata: target, runtime, provenance, file digests
+├── THIRD_PARTY_NOTICES     licence and notice text of every third-party package bundled
+├── dist/server/index.js    your backend entrypoints, bundled
+├── dist/schema/index.js
+├── dist/chunks/            code your backend entrypoints share
+├── dist/ui/ … dist/display/ … dist/contributions/   your browser artifacts, exactly as built
+└── drizzle/                your migrations
+```
+
+- **Bundled backend.** Your server, schema, and jobs entrypoints are bundled with every
+  pure-JavaScript dependency they use, the Module SDK, the contracts, and Drizzle included. The only
+  imports left are Node.js built-ins. A dependency the bundle cannot resolve fails packaging; nothing
+  is left to be found at run time.
+- **Never shipped:** `src/`, tests, TypeScript declarations, source maps, development dependencies,
+  your development `package.json`, any `workspace:` range, and links of any kind.
+- **Browser artifacts must be current.** The packager rebuilds them in memory and refuses an artifact
+  on disk that differs, so run your build first.
+- **`any` is the only target today.** A dependency that is native or platform-specific (a compiled
+  addon, a package that declares an operating system or CPU, or one that loads a per-platform binary
+  such as `sharp`) cannot be in an `any` package, and packaging fails. Native targets come later.
+- **Licences.** `THIRD_PARTY_NOTICES` credits every third-party package your bundles contain, with
+  its declared licence and the licence and notice files it ships. A package that declares no licence
+  fails packaging, and so does one that ships no licence text, unless its licence's standard text is
+  complete without a copyright line (Apache-2.0, which the packager then supplies and says so). The
+  Ekklesia platform's own packages are listed in `ekklesia.package.json` under `incorporates`.
+- **Deterministic.** The same packager version and the same built inputs produce the same archive,
+  byte for byte, wherever the checkout is.
 
 **Drizzle, for now.** You define tables with your own copy of Drizzle, and Core runs your queries
 through the platform's Drizzle instance (see [Database access](#database-access)). Objects from two
 copies interoperate only when the copies are interchangeable, so the current implementation requires
-**exactly the Drizzle version the platform uses**: the one `@ekklesia/module-sdk` depends on. This is
-a constraint of today's implementation, not a permanent contract.
+**exactly the Drizzle version the platform uses**: the one `@ekklesia/module-sdk` depends on. The
+package records it under `transitional`, and an installation refuses a package whose Drizzle differs.
+This is a constraint of today's implementation, not a permanent contract.
 
-Browser artifacts are already self-contained bundles, so nothing changes for them.
+#### Verifying a package
 
-The format modules are delivered in is proposed in
-[ADR 0049](../architecture/decisions/0049-module-package-v1.md): one deterministic archive per
-target, with bundled backend code, produced by an Ekklesia-owned packager that does not exist yet.
-Until it does, the repository's smoke test packages the module template with `pnpm deploy` in a
-disposable Docker build (`scripts/lib/test-module-package.Dockerfile`), a test fixture and not a
-package format. Never run `pnpm deploy` in your own workspace: it rewrites that workspace's install
-state to production-only, and the next build or `pnpm verify` then fails until a normal
-`pnpm install` repairs it.
+`node core/dist/cli/verify-module-package.js <archive> --sha256-file <archive>.sha256`, run from an
+Ekklesia installation (`/opt/ekklesia` in the image), checks a package against that platform without
+installing it. Pass `--extract-to <new directory>` to receive the verified module directory.
+[deploy/README.md](../../deploy/README.md#installed-modules) shows the whole installation.
 
 The repository's boundary checks (`pnpm boundaries`) prove only source modules in a workspace. An
 installed package normally has no source, so the platform cannot check it the same way. Your