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
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:
co-authored by
Claude Opus 5.5
parent
fbf8f6edac
commit
1119cc5fdf
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user