docs: propose ADR 0049, Ekklesia Module Package v1
CI / verify (pull_request) Successful in 52s
CI / infrastructure-smoke (pull_request) Successful in 27s
CI / migration-smoke (pull_request) Successful in 1m50s
CI / image-build (pull_request) Successful in 22s
CI / deploy-smoke (same-origin) (pull_request) Successful in 49s
CI / deploy-smoke (split) (pull_request) Successful in 1m41s

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]>
This commit is contained in:
ekklesia
2026-10-07 10:13:34 -05:00
co-authored by Claude Opus 5.5
parent fbf8f6edac
commit 1119cc5fdf
4 changed files with 437 additions and 7 deletions
+8 -7
View File
@@ -106,13 +106,14 @@ a constraint of today's implementation, not a permanent contract.
Browser artifacts are already self-contained bundles, so nothing changes for them.
From a workspace, `pnpm --filter <your package> deploy --prod --legacy <directory>` produces such a
directory; remove the self-reference pnpm leaves at
`node_modules/.pnpm/node_modules/<your package>`, which points back into the workspace. The
repository's own smoke test packages the module template this way
(`scripts/lib/test-module-package.Dockerfile`). That is a test fixture, not a package format: the
format modules are delivered in, how they are signed, and how they reach an installation are not
decided yet.
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.
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