Merge pull request 'fix: hand npm the release artifact's absolute path, so publishing finds it' (#83) from fix/publish-absolute-artifact-path into main

Reviewed-on: https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia/pulls/83
Reviewed-by: The_River <[email protected]>

.github/workflows/ci.yml

@@ -128,6 +128,129 @@ jobs:
         if: always()
         run: bash scripts/ci-sweep.sh --job
 
+  package-release:
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # What the gate proved, for the job that consumes its artifact to check it received exactly that.
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      revision: ${{ steps.release.outputs.revision }}
+      manifest_sha256: ${{ steps.release.outputs.manifest_sha256 }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # `actions/checkout` defaults to leaving the job token in `.git/config`, where any later
+          # step — including one a pull request added to this file — could read or reuse it. Nothing
+          # in this workflow pushes, so the credential is never needed after checkout.
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # ADR 0053's package release gate: build the public package train from this commit, build it
+      # again from a second checkout and require byte-identical artifacts, then install exactly those
+      # tarballs (offline, no registry) into a module outside this repository and prove it builds,
+      # packages, and verifies. Nothing is published and no credential exists here. A future publish
+      # job must depend on this job and publish only the artifacts it proved.
+      - name: Build, reproduce, and consume the public package train
+        run: pnpm test:package-release --keep package-train
+
+      - name: Describe the proven release train
+        id: release
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          manifest="$release/ekklesia-package-train.json"
+          {
+            echo "version=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).version' "$manifest")"
+            echo "revision=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).source.revision' "$manifest")"
+            echo "manifest_sha256=$(sha256sum "$manifest" | cut -d' ' -f1)"
+          } >>"$GITHUB_OUTPUT"
+          cat "$manifest"
+
+      # The exact release artifacts, for the jobs that consume them, from a directory whose name does
+      # not start with a dot: the artifact actions leave hidden files out. Version 3 of the artifact
+      # actions: version 4 refuses any server that is not github.com, which this Gitea is not, while
+      # Gitea implements the protocol version 3 uses. A consumer checks the files, not the wrapper.
+      - name: Hand the release train on
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train
+          path: package-train/
+          if-no-files-found: error
+          retention-days: 7
+
+  # The publication tool, given exactly the artifact the package-release job proved, against a
+  # disposable Gitea 1.27.2 (scripts/test-package-publication.sh). Never the real registry, and no
+  # credential: the disposable registry's accounts are created and discarded inside the job.
+  package-publication:
+    needs: package-release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # Names this job's stacks, so its final step removes exactly these (scripts/lib/ci-project.sh).
+      EKKLESIA_CI_JOB_KEY: package-publication
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      # A job the runner killed (cancelled, or past the runner's own time limit) never ran its
+      # cleanup. Anything a CI job left on this shared daemon more than three hours ago goes first.
+      - name: Sweep stale CI stacks from the runner
+        run: bash scripts/ci-sweep.sh --stale
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Receive the release train the gate proved
+        uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
+        with:
+          name: package-train
+          path: package-train/
+
+      - name: Check it is exactly that train
+        env:
+          EXPECTED_MANIFEST_SHA256: ${{ needs.package-release.outputs.manifest_sha256 }}
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          actual="$(sha256sum "$release/ekklesia-package-train.json" | cut -d' ' -f1)"
+          if [[ -z "$EXPECTED_MANIFEST_SHA256" || "$actual" != "$EXPECTED_MANIFEST_SHA256" ]]; then
+            echo "The received release manifest is not the one the package-release job proved." >&2
+            exit 1
+          fi
+          (cd "$release" && sha256sum --check --strict SHA256SUMS)
+
+      - name: Publish it to a disposable Gitea, and prove the round trip and recovery
+        run: bash scripts/test-package-publication.sh --release "$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+
+      # Whatever happened above, this job's own stacks do not outlive it.
+      - name: Remove this job's CI stacks
+        if: always()
+        run: bash scripts/ci-sweep.sh --job
+
   image-build:
     needs: verify
     runs-on: ubuntu-latest

.github/workflows/publish-packages.yml

@@ -0,0 +1,133 @@
+name: Publish packages
+
+# Publishes one public @ekklesia/* package train (ADR 0053, docs/development/releases.md) to the
+# npm registry: exactly the artifacts this run's package-release gate proves, and nothing else.
+#
+# Only ever started by hand, on `main`, by someone with write access to this repository: no pull
+# request or push can start it. It needs the version-set commit of a release (`version` must equal
+# the platform version there), and the repository secret EKKLESIA_PACKAGES_PUBLISH_TOKEN, a token of
+# the dedicated publisher account with only the `write:package` scope. Packages are publicly
+# readable (ADR 0054); publishing is what this protects.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: The package train version to publish, equal to the platform version on main.
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# Never cancel a publication part way, and never run two at once. A rerun resumes safely.
+concurrency:
+  group: publish-packages
+  cancel-in-progress: false
+
+env:
+  # The only registry-specific setting: where the train is published.
+  EKKLESIA_PACKAGES_REGISTRY: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/
+
+jobs:
+  package-release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      revision: ${{ steps.release.outputs.revision }}
+      manifest_sha256: ${{ steps.release.outputs.manifest_sha256 }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Activate pinned pnpm
+        run: |
+          corepack enable
+          corepack prepare [email protected] --activate
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # The same credential-free gate as CI: build, reproduce, and consume the train.
+      - name: Build, reproduce, and consume the public package train
+        run: pnpm test:package-release --keep package-train
+
+      - name: Describe the proven release train
+        id: release
+        run: |
+          release="$(find package-train -mindepth 1 -maxdepth 1 -type d)"
+          manifest="$release/ekklesia-package-train.json"
+          {
+            echo "version=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).version' "$manifest")"
+            echo "revision=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).source.revision' "$manifest")"
+            echo "manifest_sha256=$(sha256sum "$manifest" | cut -d' ' -f1)"
+          } >>"$GITHUB_OUTPUT"
+
+      # Artifact actions version 3: version 4 refuses any server that is not github.com. The directory
+      # name must not start with a dot: the artifact actions leave hidden files out.
+      - name: Hand the release train on
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train
+          path: package-train/
+          if-no-files-found: error
+          retention-days: 90
+
+  publish:
+    needs: package-release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      # Only for the publication tool itself: nothing is built or installed in this job.
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: .node-version
+
+      - name: Receive the release train the gate proved
+        uses: actions/download-artifact@ad191675b41f6a5b46da9a048cb6893812da158b # v3.1.0-node20
+        with:
+          name: package-train
+          path: package-train/
+
+      # The tool validates the whole train against its manifest, that manifest against the gate's,
+      # its version against the request, and its revision against this commit, before it sends
+      # anything; then publishes, verifies every package byte for byte, and moves `latest` last.
+      - name: Publish the exact release train
+        env:
+          EKKLESIA_PACKAGES_PUBLISH_TOKEN: ${{ secrets.EKKLESIA_PACKAGES_PUBLISH_TOKEN }}
+          TRAIN_VERSION: ${{ inputs.version }}
+          TRAIN_REVISION: ${{ github.sha }}
+          MANIFEST_SHA256: ${{ needs.package-release.outputs.manifest_sha256 }}
+        run: |
+          node scripts/publish-package-train.ts \
+            --release "$(find package-train -mindepth 1 -maxdepth 1 -type d)" \
+            --registry "$EKKLESIA_PACKAGES_REGISTRY" \
+            --version "$TRAIN_VERSION" \
+            --revision "$TRAIN_REVISION" \
+            --manifest-sha256 "$MANIFEST_SHA256" \
+            --record publication-record.json \
+            --require-public-read
+
+      - name: Keep the publication record
+        uses: actions/upload-artifact@c6a3b2bd78b3985e4b2f15397fec357f0fd808de # v3.2.2-node20
+        with:
+          name: package-train-publication-record
+          path: publication-record.json
+          if-no-files-found: error
+          retention-days: 90

.gitignore

@@ -1,4 +1,8 @@
 node_modules/
+# pnpm's content-addressed package store. pnpm keeps it beside node_modules on the same file system,
+# so when the checkout is its own mount (a CI runner's workspace volume, a bind-mounted container),
+# `pnpm install` creates it here, at the checkout's root. A package cache, never source.
+.pnpm-store/
 .turbo/
 coverage/
 dist/
@@ -19,3 +23,8 @@ core/.identity-schema-check-*
 
 # The packager tests copy fixture modules here (packages/module-pack/tests/support/fixture-module.ts).
 packages/module-pack/.fixtures/
+
+# `pnpm packages:release` writes package release trains here (scripts/package-release.ts).
+.package-release/
+# CI keeps the proven release here to hand it on as a workflow artifact (scripts/test-package-release.sh --keep).
+/package-train/

CLAUDE.md

@@ -78,6 +78,13 @@ ever disagree:
 - `pnpm test:migrations:integration` — live, disposable-PostgreSQL evidence: migration discovery,
   planning, and execution, plus the `apps/api` HTTP transport (signup, sign-in, principal
   resolution, sign-out). Requires Docker. Run this for any change touching either area.
+- `pnpm test:package-release` — builds the public `@ekklesia/*` package train, proves it
+  reproducible, and proves a standalone module consumes exactly those tarballs. Publishes nothing.
+  Run it for any change to the public packages or their release tooling.
+- `pnpm test:package-publication` — publishes a release train to a disposable Gitea (Docker) and
+  proves the publication tool. Never the real registry. The real publication is the manual
+  `Publish packages` workflow only; never run `scripts/publish-package-train.ts` against the real
+  registry without the user's explicit intent.
 - `pnpm doctor` — read-only local readiness report. Never treat it as a substitute for `pnpm
   verify` or the integration suite.
 - `pnpm migrations:plan` / `pnpm migrations:apply` — read-only planning vs. mutating execution

README.md

@@ -62,6 +62,18 @@ omits licence material, the packager may add reviewed licence supplements
 ([ADR 0052](docs/architecture/decisions/0052-reviewed-license-supplements.md)). Purge, other
 operating-system or CPU targets, signing, and any installer or marketplace do not exist yet.
 
+A module can be built in its own repository from Ekklesia's public module-development packages
+([ADR 0053](docs/architecture/decisions/0053-standalone-module-development-packages.md)):
+a curated `@ekklesia/module-sdk`, `@ekklesia/module-database`, the UI packages, and the build and
+packaging tools. They are released as one coordinated train of tarballs with a release manifest,
+and CI proves on every run that two builds of a commit are byte-identical and that a module outside
+the repository installs, builds, packages, and verifies from those artifacts alone. A manual
+workflow, the only way to publish, publishes exactly those artifacts to the npm registry and
+verifies every package byte for byte. Anyone may read and install the packages before launch
+([ADR 0054](docs/architecture/decisions/0054-public-package-reads-before-launch.md)). The first train
+published will be the next platform release
+([Releases and the public package train](docs/development/releases.md)).
+
 Phase 4A added Core-owned identity foundations: a Core-owned Better Auth database schema
 (`ekklesia_core_user`, `ekklesia_core_session`, `ekklesia_core_account`,
 `ekklesia_core_verification`), a first-class Core-owned migration source that coexists with

apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/api",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",

apps/api/src/app.ts

@@ -1,6 +1,5 @@
 import {
   isAuthenticatedPrincipal,
-  type ModuleRuntimeServices,
   type ModuleSecretSource,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -13,6 +12,7 @@ import type { DashboardStore } from "@ekklesia/core/dashboard";
 import type { DeviceStore } from "@ekklesia/core/devices";
 import { type EkklesiaIdentityRuntime, IdentityRuntimeError } from "@ekklesia/core/identity";
 import type {
+  AnyModuleRuntimeServices,
   DiscoveredModule,
   ModuleConfigurationLookup,
   ModuleConfigurationSettings,
@@ -66,7 +66,7 @@ export interface CreateApiAppOptions {
   /** The same per-module service lookup the caller's started module runtime used for every
    * module's `start`/`stop` hooks (`apps/api/src/server.ts`) — each handler receives its module's
    * reference-identical service object, never a fresh facade or executor built per request. */
-  readonly moduleServices: ModuleRuntimeServicesLookup | ModuleRuntimeServices;
+  readonly moduleServices: ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
   /** The platform's module UI publication policy — always the one Core builds from the exact
    * discovered inventory this runtime started (`createModuleUiPublicationRegistry`,
    * `apps/api/src/server.ts`). Required rather than defaulted, for the same reason `moduleRoutes`

apps/api/src/database.ts

@@ -1,4 +1,4 @@
-import type { ModuleDatabase, ModuleDatabaseExecutor, ModuleId } from "@ekklesia/contracts";
+import type { ModuleDatabaseExecutor, ModuleId } from "@ekklesia/contracts";
 import {
   type AuthorizationDrizzleDatabase,
   createAuthorizationDrizzleView,
@@ -16,6 +16,7 @@ import {
   createModuleDatabaseView,
   createModuleLifecycleView,
   type ModuleConfigurationDrizzleDatabase,
+  type ModuleDatabase,
   type ModuleLifecycleDrizzleDatabase,
 } from "@ekklesia/core/modules";
 

apps/api/src/module-http-routes.ts

@@ -1,15 +1,15 @@
 import {
   EMPTY_MODULE_CONFIGURATION,
   EMPTY_MODULE_STORAGE,
-  type ModuleDatabase,
   type ModuleDatabaseExecutor,
   type ModuleId,
   type ModuleRouteHandlerContext,
-  type ModuleRuntimeServices,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
 import type {
+  AnyModuleRuntimeServices,
   ModuleConfigurationLookup,
+  ModuleDatabase,
   ModuleRealtimeRegistry,
   ModuleRuntimeServicesLookup,
   ModuleStorageLookup,
@@ -40,7 +40,7 @@ export interface ModuleHttpRoutesOptions extends AuthorizationMiddlewareOptions
    * received for this API runtime — never a fresh one built per request, and never touched for a
    * denied, trusted-origin-rejected, or `OPTIONS` request, since a handler is only ever invoked
    * after authorization succeeds. */
-  readonly services: ModuleRuntimeServicesLookup | ModuleRuntimeServices;
+  readonly services: ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
   /**
    * Per-module frozen configuration snapshots — the exact map the module runtime started from
    * (ADR 0029), so a handler and that module's `start`/`stop` hooks receive the identical object

apps/api/src/server.ts

@@ -1,11 +1,7 @@
 import type { Socket } from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import {
+import { EMPTY_MODULE_SECRET_SOURCE, type ModuleSecretSource } from "@ekklesia/contracts";
-  type AnyModuleRuntimeServices,
-  EMPTY_MODULE_SECRET_SOURCE,
-  type ModuleSecretSource,
-} from "@ekklesia/contracts";
 import {
   createAuthorizationEvaluator,
   createAuthorizationStore,
@@ -21,6 +17,7 @@ import {
 } from "@ekklesia/core/identity";
 import { createSmtpMailProvider, type MailProvider } from "@ekklesia/core/mail";
 import {
+  type AnyModuleRuntimeServices,
   createModuleConfigurationStore,
   createModuleLifecycleStore,
   createModuleUiPublicationRegistry,

apps/api/tests/api-http.integration.ts

@@ -221,9 +221,9 @@ async function applyCoreMigrations(url: string): Promise<void> {
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory: emptyModulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     // Phase 4A's and Phase 4C pass 1's committed migrations must not have drifted while building
@@ -339,7 +339,7 @@ async function createGatedRouteModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: { server: "./dist/server/index.js" },
         id,
         manifestVersion: 8,
@@ -390,7 +390,7 @@ async function createFixtureModule(
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     permissions: [],
     entrypoints: { server: "./dist/server/index.js" },
     ...manifestOverrides,
@@ -521,7 +521,7 @@ async function createUiModule(
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
         id,
         manifestVersion: 8,
@@ -2592,9 +2592,9 @@ describe.sequential("live API — installed module permission end-to-end", () =>
     const report = await diagnoseEkklesia({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
       runtimeRange: ">=0.0.0",
       runtimeVersion: process.versions.node,
@@ -3906,9 +3906,9 @@ describe.sequential("live API — module lifecycle governs what actually runs",
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     expect(aggregate.discoveredModules.map((module) => module.manifest.id)).toEqual(["calendar"]);

apps/api/tests/app.test.ts

@@ -1,8 +1,6 @@
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   moduleIdSchema,
   parseEkklesiaUserId,
   parsePermissionId,
@@ -20,6 +18,8 @@ import { IdentityRuntimeError } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleUiPublicationRegistry,
   StagedModuleRealtimeRegistry,
 } from "@ekklesia/core/modules";
@@ -48,9 +48,9 @@ function fakeRuntime(overrides: Partial<EkklesiaIdentityRuntime> = {}): Ekklesia
   };
 }
 
-/** A small typed fake `ModuleRuntimeServices` — these tests exercise `createApiApp`'s own wiring,
+/** A small typed fake `LegacyModuleRuntimeServices` — these tests exercise `createApiApp`'s own wiring,
  * never real database behavior, so no PostgreSQL is required. */
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   const database = Object.freeze({
     delete: vi.fn(),
     execute: vi.fn(),

apps/api/tests/dashboard-host-routes.test.ts

@@ -1,9 +1,7 @@
 import { createHash } from "node:crypto";
 import {
   ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
   type ModuleRouteHandler,
-  type ModuleRuntimeServices,
   parsePermissionId,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -16,6 +14,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import { describe, expect, it, vi } from "vitest";
 
@@ -74,7 +74,7 @@ function fakeStore(): AuthorizationStore {
   };
 }
 
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 

apps/api/tests/dashboard-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -20,6 +18,8 @@ import {
   createModuleUiPublicationRegistry,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -147,7 +147,7 @@ async function install(options: InstallOptions = {}): Promise<{ app: Hono }> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(modules),
     moduleLifecycle: {
       snapshot: moduleLifecycleSnapshotFor(modules),

apps/api/tests/device-pairing.integration.ts

@@ -118,7 +118,7 @@ async function createDisplayModuleDirectory(): Promise<string> {
     writeFile(
       path.join(moduleDirectory, "ekklesia.module.json"),
       JSON.stringify({
-        compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+        compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
         entrypoints: {
           display: { artifact: "./dist/ui/display.js", permission: displayPermission },
           server: "./dist/server/index.js",

apps/api/tests/health-routes.test.ts

@@ -1,8 +1,6 @@
 import {
   ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
   type ModuleRouteHandler,
-  type ModuleRuntimeServices,
   parsePermissionId,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
@@ -15,6 +13,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApiApp } from "../src/app.js";
@@ -56,7 +56,7 @@ function fakeStore(): AuthorizationStore {
   };
 }
 
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 

apps/api/tests/lifecycle.test.ts

@@ -108,7 +108,7 @@ async function createFixtureModule(
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     permissions: [],
     entrypoints: { server: "./dist/server/index.js" },
     ...manifestOverrides,
@@ -267,7 +267,7 @@ function fakeDiscoveredModule(
 ): DiscoveredModule {
   const manifest = parseModuleManifest({
     capabilities: [],
-    compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+    compatibility: { moduleSdk: "^0.2.0", platform: "^0.2.0" },
     entrypoints: { server: "./dist/does-not-exist/index.js" },
     id,
     manifestVersion: 8,
@@ -1435,9 +1435,9 @@ describe("Ekklesia API module runtime startup and shutdown", () => {
     const recorder = createEventRecorder();
     await createWorkingFixtureModule(modulesDirectory, "calendar", recorder, { withRoute: true });
     const discovered = await (await import("@ekklesia/core/modules")).discoverModules({
-      moduleSdkVersion: "0.1.0",
+      moduleSdkVersion: "0.2.0",
       modulesDirectory,
-      platformVersion: "0.1.0",
+      platformVersion: "0.2.0",
     });
     mockPoolAndAuth();
     mockSuccessfulServe();

apps/api/tests/module-configuration-routes.test.ts

@@ -6,8 +6,6 @@ import {
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
   type ModuleConfigurationDeclarationInput,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -22,10 +20,12 @@ import {
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
   discoverModules,
+  type LegacyModuleRuntimeServices,
   type ModuleConfigurationRecord,
   type ModuleConfigurationStore,
   ModuleConfigurationStoreError,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type ModuleDatabase,
   resolveModuleEligibility,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
@@ -213,7 +213,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(eligibility.eligibleModules),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/module-database.integration.ts

@@ -212,9 +212,9 @@ async function applyCoreMigrations(url: string): Promise<void> {
     const aggregate = await discoverAllMigrations({
       coreMigrationsDirectory,
       moduleDiscovery: {
-        moduleSdkVersion: "0.1.0",
+        moduleSdkVersion: "0.2.0",
         modulesDirectory: emptyModulesDirectory,
-        platformVersion: "0.1.0",
+        platformVersion: "0.2.0",
       },
     });
     expect(aggregate.migrations.map((entry) => entry.identity)).toEqual([
@@ -241,9 +241,9 @@ async function applyMigrationsWithModule(url: string): Promise<void> {
   const aggregate = await discoverAllMigrations({
     coreMigrationsDirectory,
     moduleDiscovery: {
-      moduleSdkVersion: "0.1.0",
+      moduleSdkVersion: "0.2.0",
       modulesDirectory: fixtureModulesDirectory,
-      platformVersion: "0.1.0",
+      platformVersion: "0.2.0",
     },
   });
   // Core migrations aggregate first, exactly once each, and always before any module migration.

apps/api/tests/module-display-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -21,6 +19,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -155,7 +155,7 @@ interface Installation {
   readonly modules: readonly DiscoveredModule[];
 }
 
-function fakeServices(): ModuleRuntimeServices {
+function fakeServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as unknown as ModuleDatabase });
 }
 

apps/api/tests/module-http-routes.test.ts

@@ -1,10 +1,8 @@
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
   type ModuleRouteHandler,
   type ModuleRouteHandlerContext,
-  type ModuleRuntimeServices,
   moduleRoutesOverlap,
   type PermissionId,
   parsePermissionId,
@@ -20,6 +18,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   createModuleUiPublicationRegistry,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleRuntimeServicesLookup,
 } from "@ekklesia/core/modules";
 import { describe, expect, it, vi } from "vitest";
@@ -74,11 +74,11 @@ function moduleRoute(
   return Object.freeze({ bodyMode: "buffered", maxBodyBytes: 1024, ...fields });
 }
 
-/** A small typed fake `ModuleRuntimeServices` — these tests exercise route mounting,
+/** A small typed fake `LegacyModuleRuntimeServices` — these tests exercise route mounting,
  * authorization, and response sanitization, never real database behavior, so no PostgreSQL is
  * required. Each `database` method stays a distinct spy so a test can assert none of them were
  * ever called (denied, trusted-origin-rejected, and `OPTIONS` requests never reach a handler). */
-function fakeModuleServices(): ModuleRuntimeServices {
+function fakeModuleServices(): LegacyModuleRuntimeServices {
   const database = Object.freeze({
     delete: vi.fn(),
     execute: vi.fn(),
@@ -92,7 +92,7 @@ function fakeModuleServices(): ModuleRuntimeServices {
   return Object.freeze({ database });
 }
 
-function expectDatabaseFakeUntouched(services: ModuleRuntimeServices): void {
+function expectDatabaseFakeUntouched(services: LegacyModuleRuntimeServices): void {
   expect(vi.mocked(services.database.select)).not.toHaveBeenCalled();
   expect(vi.mocked(services.database.selectDistinct)).not.toHaveBeenCalled();
   expect(vi.mocked(services.database.selectDistinctOn)).not.toHaveBeenCalled();
@@ -108,7 +108,7 @@ function buildModuleApp(options: {
   readonly registry: PermissionRegistry;
   readonly routes: readonly RegisteredModuleHttpRoute[];
   readonly runtime?: EkklesiaIdentityRuntime;
-  readonly services?: ModuleRuntimeServices | ModuleRuntimeServicesLookup;
+  readonly services?: LegacyModuleRuntimeServices | ModuleRuntimeServicesLookup;
   readonly trustedOrigins?: readonly string[];
 }) {
   const evaluator = options.evaluator ?? {
@@ -539,7 +539,7 @@ describe("module route authorization", () => {
     expect(response.status).toBe(403);
     expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
     expect(handler).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services as ModuleRuntimeServices);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("does not invoke the handler when principal resolution fails", async () => {
@@ -668,7 +668,7 @@ describe("module route trusted-origin enforcement", () => {
     }
     expect(handler).not.toHaveBeenCalled();
     expect(evaluator.authorize).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services as ModuleRuntimeServices);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("allows a trusted-origin state-changing request through to the handler", async () => {
@@ -797,7 +797,7 @@ describe("module route CORS", () => {
 
     expect(handler).not.toHaveBeenCalled();
     expect(evaluator.authorize).not.toHaveBeenCalled();
-    expectDatabaseFakeUntouched(services as ModuleRuntimeServices);
+    expectDatabaseFakeUntouched(services as LegacyModuleRuntimeServices);
   });
 
   it("never reflects an untrusted origin for a module route", async () => {

apps/api/tests/module-lifecycle-routes.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -20,6 +18,8 @@ import {
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleLifecycleStore,
   ModuleLifecycleStoreError,
   EMPTY_MODULE_REALTIME_REGISTRY,
@@ -189,7 +189,7 @@ async function install(options: InstallOptions = {}): Promise<Installation> {
     moduleRealtime: EMPTY_MODULE_REALTIME_REGISTRY,
     moduleServices: Object.freeze({
       database: Object.freeze({}) as unknown as ModuleDatabase,
-    }) as ModuleRuntimeServices,
+    }) as LegacyModuleRuntimeServices,
     moduleUi: createModuleUiPublicationRegistry(eligibility.eligibleModules),
     runtime,
     trustedOrigins: [trustedOrigin],

apps/api/tests/module-realtime-live.test.ts

@@ -4,9 +4,7 @@ import path from "node:path";
 import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
-  type ModuleDatabase,
   type ModuleRealtimePublisher,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -18,6 +16,8 @@ import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
   composePlatformPermissionRegistry,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   type ModuleRealtimeRegistry,
   type ModuleRealtimeSubscription,
   startDiscoveredModuleRuntime,
@@ -226,7 +226,7 @@ async function createFixtureModule(control: FixtureControl): Promise<{
   return { directory, symbol };
 }
 
-function services(): ModuleRuntimeServices {
+function services(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as ModuleDatabase });
 }
 

apps/api/tests/module-ui-host-e2e.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -18,6 +16,8 @@ import {
   composePlatformPermissionRegistry,
   createModuleUiPublicationRegistry,
   discoverModules,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
   startDiscoveredModuleRuntime,
 } from "@ekklesia/core/modules";
 import {
@@ -241,7 +241,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
     modulesDirectory,
     platformVersion: "0.1.0",
   });
-  const services: ModuleRuntimeServices = Object.freeze({
+  const services: LegacyModuleRuntimeServices = Object.freeze({
     database: Object.freeze({}) as unknown as ModuleDatabase,
   });
   // The module's real runtime: its server entrypoint is imported, registered, and started, and the

apps/api/tests/module-ui-inventory.test.ts

@@ -5,8 +5,6 @@ import {
   ANONYMOUS_PRINCIPAL,
   createAuthenticatedPrincipal,
   type EkklesiaPrincipal,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
   parseEkklesiaUserId,
 } from "@ekklesia/contracts";
 import {
@@ -21,6 +19,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -192,7 +192,7 @@ async function install(options: InstallOptions): Promise<Installation> {
     revokeGrant: vi.fn(),
     revokePlatformOwner: vi.fn(),
   } as unknown as AuthorizationStore;
-  const services: ModuleRuntimeServices = Object.freeze({
+  const services: LegacyModuleRuntimeServices = Object.freeze({
     database: Object.freeze({}) as unknown as ModuleDatabase,
   });
   const permissionRegistry = composePlatformPermissionRegistry(modules);

apps/api/tests/module-ui-routes.test.ts

@@ -1,11 +1,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import {
+import { ANONYMOUS_PRINCIPAL } from "@ekklesia/contracts";
-  ANONYMOUS_PRINCIPAL,
-  type ModuleDatabase,
-  type ModuleRuntimeServices,
-} from "@ekklesia/contracts";
 import type { AuthorizationEvaluator, AuthorizationStore } from "@ekklesia/core/authorization";
 import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import {
@@ -14,6 +10,8 @@ import {
   type DiscoveredModule,
   discoverModules,
   EMPTY_MODULE_REALTIME_REGISTRY,
+  type LegacyModuleRuntimeServices,
+  type ModuleDatabase,
 } from "@ekklesia/core/modules";
 import { loadModuleUi } from "@ekklesia/module-ui-host";
 import { MODULE_UI_ABI_VERSION, NO_MODULE_UI_CONTRIBUTIONS } from "@ekklesia/module-ui-sdk";
@@ -215,7 +213,7 @@ async function install(
       : modules.filter((module) => publicationModuleIds.includes(module.manifest.id));
 
   const database = Object.freeze({}) as unknown as ModuleDatabase;
-  const services: ModuleRuntimeServices = Object.freeze({ database });
+  const services: LegacyModuleRuntimeServices = Object.freeze({ database });
   const runtime: EkklesiaIdentityRuntime = {
     handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
     // Anonymous, and every authorization decision denied: whatever this route does, it does it

core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",

core/src/modules/database.ts

@@ -1,7 +1,54 @@
-import type { ModuleDatabase } from "@ekklesia/contracts";
+import type { ModuleDatabaseAbiRuntimeServices, ModuleRuntimeServices } from "@ekklesia/contracts";
-import { drizzle } from "drizzle-orm/node-postgres";
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { Pool } from "pg";
 
+/**
+ * A trusted backend module's typed Drizzle query surface — the same query-building methods a
+ * platform-owned Drizzle instance exposes, restricted to exactly the operations a module needs to
+ * read and write its own tables. Derived with `Pick` from the real `drizzle-orm/node-postgres`
+ * database type rather than hand-declared, so every method keeps Drizzle's own table-aware
+ * argument and result inference exactly as-is — a module calling `database.select().from(table)`
+ * or `database.insert(table).values(...)` gets the identical typed builder a direct Drizzle caller
+ * would, with no `any`/`unknown` erasure anywhere in the chain.
+ *
+ * Deliberately excludes everything `NodePgDatabase` or the `drizzle(...)` factory otherwise
+ * exposes: `$client` (the raw `pg` client/pool), `_` (internal session/dialect/schema state),
+ * `query` (a relational-query builder tied to one schema, which would have to span every
+ * installed module's tables to exist here at all), `$cache`, `$count`, `$with`, `with`, and
+ * `refreshMaterializedView`. There is no connection string, pool, session, or dialect object
+ * reachable through this type. Carries no schema generic — a module brings its own Drizzle table
+ * objects to each call, so there is no global relational schema spanning every installed module for
+ * this type to leak.
+ *
+ * Core's own, private type (ADR 0053): it moved here from `@ekklesia/contracts` so no published
+ * package references Drizzle. New modules use the Module Database ABI v1 instead (ADR 0050), and
+ * the Module SDK never exposes this facade's type.
+ *
+ * This is an integration boundary, not a security sandbox: modules are trusted, compiled backend
+ * plugins that already run arbitrary code in this process, exactly like every other lifecycle hook
+ * and HTTP handler they define. `ModuleDatabase` exists to keep a module's code Drizzle-typed and
+ * decoupled from how the platform physically connects to PostgreSQL — not to defend against a
+ * malicious module, which this facade cannot do and does not attempt to do.
+ */
+export type ModuleDatabase = Pick<
+  NodePgDatabase,
+  | "select"
+  | "selectDistinct"
+  | "selectDistinctOn"
+  | "insert"
+  | "update"
+  | "delete"
+  | "execute"
+  | "transaction"
+>;
+
+/** The services a legacy module's hooks and handlers receive: the legacy facade. */
+export type LegacyModuleRuntimeServices = ModuleRuntimeServices<ModuleDatabase>;
+/** The services Core hands any started module: the legacy facade or the ABI v1 executor. */
+export type AnyModuleRuntimeServices =
+  | LegacyModuleRuntimeServices
+  | ModuleDatabaseAbiRuntimeServices;
+
 /**
  * A typed `ModuleDatabase` view over an externally owned pool — the module-facing counterpart to
  * `createIdentityDrizzleView` (`core/src/identity/database.ts`) and

core/src/modules/legacy-schema-definition.ts

@@ -1,15 +1,15 @@
+/**
+ * The legacy module schema definition (ADR 0007): a v8 module that declares no `database` default-
+ * exports `{ moduleId, tables }` with its Drizzle table objects themselves. Core alone validates it,
+ * for the legacy facade's deprecation window (ADR 0050). It lives here, beside Core's own Drizzle
+ * dependency, so that no package a module installs needs Drizzle at run time (ADR 0053).
+ *
+ * Erasable TypeScript with no relative imports: the verifier's probe imports this source file
+ * directly in tests (`module-package-probe.ts`).
+ */
 import { is } from "drizzle-orm";
 import { type AnyPgTable, PgTable } from "drizzle-orm/pg-core";
-import { type ModuleId, moduleIdSchema } from "./identifiers.js";
+import { type ModuleId, moduleIdSchema } from "@ekklesia/contracts";
-
-export {
-  moduleTableLocalNameSchema,
-  moduleTableName,
-  moduleTableNamespace,
-  moduleTablePrefix,
-  POSTGRES_IDENTIFIER_MAX_LENGTH,
-  physicalModuleTableNameSchema,
-} from "./module-schema-names.js";
 
 export interface ModuleSchemaDefinition<
   Tables extends Readonly<Record<string, AnyPgTable>> = Readonly<Record<string, AnyPgTable>>,

core/src/modules/module-package-probe.ts

@@ -9,14 +9,15 @@
 // The result travels over the IPC channel, never stdout, so nothing a module prints can forge it.
 // It carries fixed role and reason names only: never an error message, a path, or module output.
 //
-// Written as erasable TypeScript with no relative imports, so Node can run the source file directly
+// Written as erasable TypeScript, so Node can run the source file directly in tests as well as the
-// in tests as well as the compiled file in the image.
+// compiled file in the image. Its one relative import names the source file's own extension, which
+// the build rewrites to `.js` (`rewriteRelativeImportExtensions`); that file follows the same rules.
 import { pathToFileURL } from "node:url";
 import {
   parseModuleRuntimeDefinition,
-  parseModuleSchemaDefinition,
   parseModuleSchemaMetadataDefinition,
 } from "@ekklesia/contracts";
+import { parseModuleSchemaDefinition } from "./legacy-schema-definition.ts";
 
 interface ProbeRequest {
   readonly databaseAbi?: 1;

core/src/modules/runtime.ts

@@ -1,6 +1,5 @@
 import { pathToFileURL } from "node:url";
 import {
-  type AnyModuleRuntimeServices,
   type CapabilityId,
   type CapabilityRegistrar,
   type CapabilityResolver,
@@ -8,7 +7,6 @@ import {
   EMPTY_MODULE_CONFIGURATION,
   EMPTY_MODULE_STORAGE,
   type ModuleConfiguration,
-  type ModuleDatabase,
   type ModuleDatabaseExecutor,
   type ModuleHttpRouteRegistrar,
   type ModuleId,
@@ -19,7 +17,6 @@ import {
   type ModuleRouteHandler,
   type ModuleRuntimeContext,
   type ModuleRuntimeDefinition,
-  type ModuleRuntimeServices,
   type ModuleStorage,
   moduleRouteShapeKey,
   moduleRoutesOverlap,
@@ -28,6 +25,7 @@ import {
   type RegisteredModuleHttpRoute,
   safeParseModuleRouteDefinition,
 } from "@ekklesia/contracts";
+import type { AnyModuleRuntimeServices, ModuleDatabase } from "./database.js";
 import {
   type DiscoveredModule,
   discoverModules,
@@ -137,7 +135,7 @@ export type ModuleStorageLookup = ReadonlyMap<string, ModuleStorage>;
 /** One frozen service object per module id. Legacy modules may point at objects wrapping the same
  * facade; ABI-v1 modules each point at their own attributed executor. */
 export type ModuleRuntimeServicesLookup = ReadonlyMap<string, AnyModuleRuntimeServices>;
-export type ModuleRuntimeServicesSource = ModuleRuntimeServicesLookup | ModuleRuntimeServices;
+export type ModuleRuntimeServicesSource = ModuleRuntimeServicesLookup | AnyModuleRuntimeServices;
 
 function servicesFor(
   services: ModuleRuntimeServicesSource,
@@ -347,11 +345,11 @@ class StagedCapabilityRegistry {
   createRuntimeContext(
     module: DiscoveredModule,
     phase: "rollback" | "start" | "stop",
-    services: ModuleRuntimeServices,
+    services: AnyModuleRuntimeServices,
     config: ModuleConfiguration,
     storage: ModuleStorage,
     realtime: ModuleRealtimePublisher,
-  ): ModuleRuntimeContext {
+  ): ModuleRuntimeContext<ModuleDatabase | ModuleDatabaseExecutor> {
     const capabilities: CapabilityResolver = Object.freeze({
       resolve: (capabilityId: CapabilityId): RegisteredCapability | undefined => {
         this.#assertAccess(module, capabilityId, phase);
@@ -754,7 +752,7 @@ async function stopModules(
             registry.createRuntimeContext(
               module.discovered,
               phase,
-              servicesFor(services, module.discovered) as ModuleRuntimeServices,
+              servicesFor(services, module.discovered),
               configurationFor(configurations, moduleId),
               storageFor(storages, moduleId),
               realtimeRegistry.publisherFor(moduleId),
@@ -814,7 +812,7 @@ async function startModules(
         registry.createRuntimeContext(
           module.discovered,
           "start",
-          servicesFor(services, module.discovered) as ModuleRuntimeServices,
+          servicesFor(services, module.discovered),
           configurationFor(configurations, module.discovered.manifest.id),
           storageFor(storages, module.discovered.manifest.id),
           realtimeRegistry.publisherFor(module.discovered.manifest.id),

core/src/modules/schema-discovery.ts

@@ -1,14 +1,16 @@
 import { pathToFileURL } from "node:url";
 import {
   type ModuleId,
-  type ModuleSchemaDefinition,
   type ModuleSchemaMetadataDefinition,
   moduleTableLocalNameSchema,
   moduleTablePrefix,
-  parseModuleSchemaDefinition,
   parseModuleSchemaMetadataDefinition,
   physicalModuleTableNameSchema,
 } from "@ekklesia/contracts";
+import {
+  type ModuleSchemaDefinition,
+  parseModuleSchemaDefinition,
+} from "./legacy-schema-definition.js";
 import { is } from "drizzle-orm";
 import { type AnyPgTable, getTableConfig, PgColumn, PgTable } from "drizzle-orm/pg-core";
 import {

core/tests/fixtures/module-database-integration/db-facade/ekklesia.module.json

@@ -5,8 +5,8 @@
   "description": "Test-only installed module fixture proving ModuleDatabase against real PostgreSQL. Never discovered by production startup, Doctor, or normal migration aggregation — only apps/api/tests/module-database.integration.ts points discovery at it explicitly.",
   "version": "0.1.0",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
   },
   "permissions": [
     {

core/tests/legacy-schema-definition.test.ts

@@ -0,0 +1,34 @@
+import { alias, getTableConfig, integer, pgTable } from "drizzle-orm/pg-core";
+import { describe, expect, it } from "vitest";
+import { parseModuleSchemaDefinition } from "../src/modules/legacy-schema-definition.js";
+
+describe("the legacy module schema definition", () => {
+  it("normalizes and freezes a typed schema definition without freezing its tables", () => {
+    const records = pgTable("example_records", { id: integer().primaryKey() });
+    const definition = parseModuleSchemaDefinition({
+      moduleId: "example",
+      tables: { records },
+    });
+
+    expect(definition.tables.records).toBe(records);
+    expect(getTableConfig(records).name).toBe("example_records");
+    expect(Object.isFrozen(definition)).toBe(true);
+    expect(Object.isFrozen(definition.tables)).toBe(true);
+    expect(Object.isFrozen(records)).toBe(false);
+  });
+
+  it("rejects malformed, empty, unknown, and non-PostgreSQL table definitions", () => {
+    const records = pgTable("example_records", { id: integer() });
+    const disguisedRecords = alias(records, "example_disguised_records");
+    expect(() => parseModuleSchemaDefinition({ moduleId: "example", tables: {} })).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { records: {} } }),
+    ).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { records }, extra: true }),
+    ).toThrow();
+    expect(() =>
+      parseModuleSchemaDefinition({ moduleId: "example", tables: { disguisedRecords } }),
+    ).toThrow();
+  });
+});

core/tests/module-database-type.test.ts

@@ -1,8 +1,8 @@
 import { integer, pgTable, text } from "drizzle-orm/pg-core";
 import { describe, expect, it } from "vitest";
-import type { ModuleDatabase, ModuleRuntimeServices } from "../src/index.js";
+import type { LegacyModuleRuntimeServices, ModuleDatabase } from "../src/modules/database.js";
 
-const testTable = pgTable("contracts_module_database_test", {
+const testTable = pgTable("core_module_database_type_test", {
   id: integer("id").primaryKey(),
   name: text("name").notNull(),
 });
@@ -68,16 +68,17 @@ function typeOnlyExclusions(database: ModuleDatabase): void {
 }
 void typeOnlyExclusions;
 
-/** Never invoked — proves `ModuleRuntimeServices` has exactly one field, `database`, typed as
+/** Never invoked — proves a legacy module's `ModuleRuntimeServices` has exactly one field,
- * `ModuleDatabase`, with no storage/jobs/configuration/secrets/authorization field this phase. */
+ * `database`, typed as `ModuleDatabase`, with no storage/jobs/configuration/secrets/authorization
-function typeOnlyServicesShape(services: ModuleRuntimeServices): void {
+ * field this phase. */
+function typeOnlyServicesShape(services: LegacyModuleRuntimeServices): void {
   const database: ModuleDatabase = services.database;
   void database;
-  // @ts-expect-error `storage` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `storage` does not exist on the services yet.
   void services.storage;
-  // @ts-expect-error `jobs` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `jobs` does not exist on the services yet.
   void services.jobs;
-  // @ts-expect-error `authorization` does not exist on `ModuleRuntimeServices` yet.
+  // @ts-expect-error `authorization` does not exist on the services yet.
   void services.authorization;
 }
 void typeOnlyServicesShape;

core/tests/module-migration-discovery.test.ts

@@ -35,9 +35,9 @@ async function createModulesDirectory(): Promise<string> {
 
 function discoveryOptions(modulesDirectory: string) {
   return {
-    moduleSdkVersion: "0.1.0",
+    moduleSdkVersion: "0.2.0",
     modulesDirectory,
-    platformVersion: "0.1.0",
+    platformVersion: "0.2.0",
   };
 }
 

core/tests/module-package-verification.test.ts

@@ -18,8 +18,8 @@ import {
 
 const platform = {
   databaseRuntime: { "drizzle-orm": "0.45.2" },
-  moduleSdkVersion: "0.1.2",
+  moduleSdkVersion: "0.2.0",
-  platformVersion: "0.1.2",
+  platformVersion: "0.2.0",
 } as const;
 
 const temporaryDirectories: string[] = [];

core/tests/module-realtime-runtime.test.ts

@@ -1,11 +1,8 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import type {
+import type { ModuleRealtimePublisher } from "@ekklesia/contracts";
-  ModuleDatabase,
+import type { LegacyModuleRuntimeServices, ModuleDatabase } from "../src/modules/database.js";
-  ModuleRealtimePublisher,
-  ModuleRuntimeServices,
-} from "@ekklesia/contracts";
 import { afterEach, describe, expect, it } from "vitest";
 import { ModuleRuntimeError, startModuleRuntime } from "../src/modules/runtime.js";
 
@@ -22,7 +19,7 @@ afterEach(async () => {
   );
 });
 
-function fakeServices(): ModuleRuntimeServices {
+function fakeServices(): LegacyModuleRuntimeServices {
   return Object.freeze({ database: Object.freeze({}) as ModuleDatabase });
 }
 

core/tests/module-runtime.test.ts

@@ -1,13 +1,12 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import type { ModuleConfiguration, ModuleDatabaseExecutor } from "@ekklesia/contracts";
 import type {
   AnyModuleRuntimeServices,
-  ModuleConfiguration,
+  LegacyModuleRuntimeServices,
   ModuleDatabase,
-  ModuleDatabaseExecutor,
+} from "../src/modules/database.js";
-  ModuleRuntimeServices,
-} from "@ekklesia/contracts";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { discoverModules } from "../src/modules/discovery.js";
 import {
@@ -151,7 +150,7 @@ function fakeModuleDatabase(): ModuleDatabase {
 }
 
 function fakeModuleRuntimeServices(): ModuleRuntimeServicesLookup {
-  const services = new Map<string, ModuleRuntimeServices>();
+  const services = new Map<string, LegacyModuleRuntimeServices>();
   const database = fakeModuleDatabase();
   return new Proxy(services, {
     get(target, property, receiver) {

core/tests/postgres-migration.integration.ts

@@ -1905,7 +1905,7 @@ describe.sequential("live PostgreSQL migration timeout precedence", () => {
 describe.sequential("live PostgreSQL retained history for an uninstalled module", () => {
   const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
   const templateModule = path.join(repositoryRoot, "templates", "module");
-  const versions = { moduleSdkVersion: "0.1.0", platformVersion: "0.1.0" } as const;
+  const versions = { moduleSdkVersion: "0.2.0", platformVersion: "0.2.0" } as const;
 
   async function coreWithoutNewestMigration(directory: string): Promise<string> {
     const target = path.join(directory, "core-drizzle");

core/tests/support/migration-module-fixture.ts

@@ -54,7 +54,7 @@ export function manifestFor(
     id,
     name: `${id} module`,
     version: "0.1.0",
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     ...(options.dependencies ? { dependencies: options.dependencies } : {}),
     capabilities: [],
     permissions: [],

core/tests/support/module-package-fixture.ts

@@ -180,9 +180,9 @@ export async function modulePackageFixture(
     runtime: { node: ">=20" },
     provenance: {
       revision: "86ae907f59458508e3277666cdd214f5bd7c1078",
-      packager: { name: "@ekklesia/module-pack", version: "0.1.2" },
+      packager: { name: "@ekklesia/module-pack", version: "0.2.0" },
     },
-    incorporates: { "@ekklesia/module-sdk": "0.1.2" },
+    incorporates: { "@ekklesia/module-sdk": "0.2.0" },
     files: listed,
   };
   const metadata = options.metadata ? options.metadata(baseMetadata) : baseMetadata;

core/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../packages/typescript-config/node.json",
   "compilerOptions": {
     "noEmit": true,
-    "types": ["node", "vitest/globals"]
+    "types": ["node", "vitest/globals"],
+    "rewriteRelativeImportExtensions": true
   },
   "include": [
     "drizzle.config.ts",

deploy/README.md

@@ -500,10 +500,10 @@ finds its files:
 ```sh
 docker build \
   --file deploy/Dockerfile \
-  --build-arg VERSION=0.1.2 \
+  --build-arg VERSION=0.2.0 \
   --build-arg REVISION="$(git rev-parse HEAD)" \
   --build-arg SOURCE=https://git.example.org/your-org/ekklesia \
-  --tag ekklesia:0.1.2 \
+  --tag ekklesia:0.2.0 \
   .
 ```
 

docs/architecture/decisions/0053-standalone-module-development-packages.md

@@ -1,7 +1,9 @@
 # 0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol
 
-- Status: Proposed
+- Status: Accepted
 - Date: 2026-10-07
+- Superseded in part by: [0054](0054-public-package-reads-before-launch.md) — only where this ADR
+  describes the package phase before launch as private, or requires authenticated package reads.
 - Extends: [0049](0049-module-package-v1.md). This is the step ADR 0049 deferred: "publishing the
   Ekklesia SDK packages for module builds outside a platform workspace". A registry is used only to
   build a module. Installing one stays registry-free: an installed package is self-contained, as ADR

docs/architecture/decisions/0054-public-package-reads-before-launch.md

@@ -0,0 +1,85 @@
+# 0054: Ekklesia's module-development packages are publicly readable before launch
+
+- Status: Accepted
+- Date: 2026-10-08
+- Supersedes (partial): [0053](0053-standalone-module-development-packages.md) — only where it
+  describes the package phase before launch as private: "Gitea may host the private phase", the
+  read credential for module CI in "Registry access and the private phase", and its requirement
+  that packages not be served anonymously while Ekklesia is not public. Every other part of that ADR
+  remains accepted and unchanged: the npm registry protocol, the public package set and its
+  boundaries, the curated SDK, the dependency rules, the coordinated package train, exact release
+  artifacts, standalone module builds, provider portability, supply chain and immutability, and the
+  credential handling for publishing.
+- Related: [ADR 0049](0049-module-package-v1.md)
+
+## Context
+
+ADR 0053 decided how Ekklesia's module-development packages (`@ekklesia/*`) are built, released, and
+distributed over the npm registry protocol. It assumed that the phase before Ekklesia's public
+launch would be private: module CI would carry a read credential where reads needed one, and the
+first publication had to make sure the registry would not serve the packages anonymously.
+
+Checking the chosen host before the first publication showed what keeping the packages private would
+take:
+
+- Gitea 1.27.2 decides package read access by the package **owner's** visibility, never a
+  repository's. The `River_of_Glory_Church` owner is a public organization, so its packages are
+  readable anonymously.
+- That organization's repositories, Ekklesia's source among them, are already publicly readable.
+- The instance allows self-registration, so "limited" visibility, readable by any signed-in user,
+  is readable by anyone who creates an account.
+- Private packages would therefore need a separate private package owner, plus reader accounts and
+  read tokens for every module repository, every module's CI, and every developer.
+
+The project owner has decided that Ekklesia is not secret. Its source is public; the project is
+simply not being launched or promoted yet. Hiding the packages built from that public source would
+protect nothing, and would still cost every module author an account and a token.
+
+## Decision
+
+1. **Ekklesia's module-development packages may be anonymously readable before the project's public
+   launch.** This covers the public package set of ADR 0053: search, metadata, and download.
+2. **Readability is not a launch, and promises nothing more.** Public readability does not mean:
+   - that Ekklesia has been publicly launched;
+   - that the APIs are stable beyond the project's pre-1.0 SemVer policy;
+   - that third-party production use is supported;
+   - that a marketplace or public module ecosystem exists.
+3. **Reading needs no authentication in this phase.** Installing `@ekklesia/*` needs no account,
+   reader account, read token, or authenticated install workflow. A module repository configures only
+   the scope's registry.
+4. **Publication stays authenticated and tightly controlled.** Only Ekklesia's release process
+   publishes, with one dedicated publisher credential that holds nothing beyond package write
+   access, used only by that process, as ADR 0053's credential handling for publishing already
+   requires.
+5. **Published versions stay immutable by Ekklesia policy.** A published version is never deleted or
+   republished with other bytes, whatever the registry technically allows.
+6. **The current Gitea owner is an acceptable host.** The `River_of_Glory_Church` package namespace
+   on the current Gitea may host this phase, as long as publishing permission stays restricted to
+   the publisher. No private package organization is needed.
+7. **A public launch is a separate decision.** Launching or promoting Ekklesia publicly, and anything
+   that changes for its packages then, is a product and release decision this ADR does not make.
+
+## Consequences
+
+- **Module authors and module CI need no Ekklesia credential.** The committed `.npmrc` scope mapping
+  is the whole registry configuration. ADR 0053's example of a read credential in user or CI
+  configuration is no longer needed in this phase.
+- **ADR 0053's pre-publication access check changes meaning.** It now confirms that anonymous reads
+  work as intended and that publishing is refused without the publisher's permission, rather than
+  that reads are private. The disposable-registry suite proves both, and the publication tool can
+  require an anonymous download to match each published artifact.
+- **Restricting publishing is now the whole access boundary**, so the publisher credential's scope,
+  where it is held, and who can reach it matter all the more.
+- **Making the packages private again would be a new decision.** Package names, versions, and
+  contents already published stay public, because a published version is never deleted.
+
+## Alternatives considered
+
+- **A private package organization on the same Gitea.** Rejected: it hides nothing that is not
+  already public in the source, and it requires reader accounts and tokens for every module
+  repository, its CI, and every developer.
+- **"Limited" package visibility.** Rejected: with self-registration open, anyone can read anyway,
+  while the configuration suggests otherwise.
+- **Requiring sign-in for the whole instance.** Rejected: it would also hide the public
+  repositories.
+- **Another registry for a private phase.** Unnecessary once reads are public.

docs/architecture/decisions/README.md

@@ -61,4 +61,5 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0050: Module Database ABI v1: modules and Core exchange SQL, never ORM objects](0050-module-database-abi-v1.md) — Accepted
 - [0051: Module packages declare their own license and carry its text](0051-module-package-license-material.md) — Accepted
 - [0052: Reviewed license supplements cover redistributed dependencies whose packages omit required material](0052-reviewed-license-supplements.md) — Proposed
-- [0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol](0053-standalone-module-development-packages.md) — Proposed
+- [0053: A module builds outside the monorepo, from Ekklesia packages published over the npm registry protocol](0053-standalone-module-development-packages.md) — Accepted
+- [0054: Ekklesia's module-development packages are publicly readable before launch](0054-public-package-reads-before-launch.md) — Accepted

docs/architecture/repository-boundaries.md

@@ -139,10 +139,12 @@ These rules map platform ownership to filesystem and package boundaries. The exe
   stay beside it, but ordinarily never replaces it: a workspace package is linked into its consumers
   as a directory, so its imports resolve from its own `node_modules`, where a consumer never
   satisfies a peer, and a production install (`pnpm install --prod`, as the production image runs)
-  omits development dependencies. The one narrow exception is
+  omits development dependencies. There are two narrow exceptions, each for one package and one
-  `@ekklesia/module-database`'s `drizzle-orm` peer: modules choose that compatible runtime and the
+  peer. `@ekklesia/module-database`'s `drizzle-orm` peer: modules choose that compatible runtime and
-  Module Package v1 bundler incorporates it into their self-contained backend; Core never loads the
+  the Module Package v1 bundler incorporates it into their self-contained backend; Core never loads
-  adapter package. Type-only imports are exempt; a `.tsx`/`.jsx` file counts as importing `react`,
+  the adapter package. And `@ekklesia/ui`'s `react` peer (ADR 0053): the shared elements are only
+  ever bundled into browser artifacts, and the consumer's own React must be the one in the bundle;
+  no production Node.js process loads them. Type-only imports are exempt; a `.tsx`/`.jsx` file counts as importing `react`,
   because the automatic JSX runtime imports `react/jsx-runtime` implicitly
   (`runtime-imports-are-production-dependencies`).
 - Workspace aliases are forbidden because they obscure package ownership in the dependency graph.

docs/development/api.md

@@ -1403,7 +1403,8 @@ stays declarative and database-free. See
 contract; this section covers only how `apps/api` composes and wires it.
 
 - **`ModuleDatabase`.** A restricted, typed view over `NodePgDatabase`
-  (`packages/contracts/src/module-database.ts`), exposing exactly `select`, `selectDistinct`,
+  (`core/src/modules/database.ts`, Core's own type: no published package references Drizzle, per
+  ADR 0053), exposing exactly `select`, `selectDistinct`,
   `selectDistinctOn`, `insert`, `update`, `delete`, `execute`, and `transaction`, each preserving
   Drizzle's own table-aware argument and result inference. It exposes no `$client`, no internal
   session/dialect state, no schema-bound relational `query` builder, and no connection string,

docs/development/releases.md

@@ -0,0 +1,370 @@
+# Releases and the public package train
+
+An Ekklesia platform release is one version. The platform image, the private workspace packages,
+and the public `@ekklesia/*` module-development packages all carry it. This page covers the order a
+release happens in and the public package train
+([ADR 0053](../architecture/decisions/0053-standalone-module-development-packages.md)): how its
+artifacts are produced, what proves them, and how exactly those artifacts are published.
+
+> **The packages are publicly readable, on purpose**
+> ([ADR 0054](../architecture/decisions/0054-public-package-reads-before-launch.md)). Anyone can
+> search, read, and install `@ekklesia/*` from the registry with no account and no token, like any
+> public npm package. That is not a public launch: Ekklesia's source is already publicly readable,
+> and the project is simply not promoted yet. Only **publishing** is restricted, to one manual,
+> authenticated workflow. Before 1.0, the APIs may change between versions under the project's
+> SemVer policy: a 0.x minor version may break them.
+
+## Where each step sits
+
+```text
+version set ─▶ build ─▶ test ─▶ pack the public package train ─▶ standalone consumer proof
+                                                                          │
+     tag and release (maintainer) ◀─ publish the exact train (manual) ◀───┘
+```
+
+1. **Version set.** A `chore(release): prepare X` pull request sets the release version: the root
+   `package.json`, every platform workspace package (the module template versions as a module, not
+   with the platform), the image build example in `deploy/README.md`, and the standalone fixture's
+   exact `@ekklesia/module-pack` pin and `@ekklesia/*` ranges
+   (`tests/fixtures/standalone-module/package.json`). The tag must point at a commit that carries
+   the version it names.
+
+   A minor version (0.x → 0.(x+1)) is a breaking release before 1.0, so manifests that declare
+   `compatibility.platform` and `compatibility.moduleSdk` as `^0.x.0` no longer match it. In the
+   same pull request, move to the new range every module built for this release (the template, the
+   standalone fixture, the native proof module), the test fixtures that model a module of the
+   current release or the current platform, and the module-development guide's examples. A patch
+   version changes none of these.
+2. **Build and test.** `pnpm verify`, the integration suite, and the deploy smoke, as for any change.
+3. **Pack the public package train.** `pnpm packages:release` (below).
+4. **Standalone consumer proof.** A module outside the repository consumes exactly those
+   artifacts (below).
+5. **Publish the exact train.** By hand, with the `Publish packages` workflow on the version-set
+   commit on `main` ([Publishing the train](#publishing-the-train)). It publishes the artifacts its
+   own run's gate (steps 3 and 4) proved, and nothing else.
+6. **Tag and release.** Unchanged: the maintainer tags the merge commit of the version-set pull
+   request. Nothing here creates, moves, or requires a tag.
+
+Steps 2 to 4 run in CI on every pull request and on `main`, and CI also publishes each proven train
+to a disposable registry (`package-publication`), never the real one. Step 5 runs only when a
+maintainer starts it.
+
+## The public package train
+
+| Package | Role |
+| --- | --- |
+| `@ekklesia/module-sdk`, `@ekklesia/module-database`, `@ekklesia/module-ui-sdk`, `@ekklesia/design-tokens` | author API |
+| `@ekklesia/module-ui-build`, `@ekklesia/module-pack`, `@ekklesia/typescript-config` | tooling |
+| `@ekklesia/ui` | publishable, pre-1.0 component API |
+| `@ekklesia/contracts` | implementation dependency of the packages above: published only because they need it, never a supported direct dependency of a module |
+
+The list lives in `scripts/package-release.ts` (`PUBLIC_PACKAGES`). Every other workspace package is
+`private`, and the release builder refuses to run if a package outside the list is publishable or
+carries the `module-development` distribution marker.
+
+- **One version.** Every package in the train has the platform release version.
+- **One train.** Every `@ekklesia/*` dependency in a packed manifest names a package of the same
+  train at exactly that version. `workspace:` ranges become those exact versions when packed.
+- **No independent versions.** A package cannot be released on its own.
+
+## Producing the release artifacts
+
+```bash
+pnpm packages:release          # writes .package-release/ekklesia-packages-<version>/
+```
+
+`scripts/package-release.ts`:
+
+1. **Refuses a modified source tree, before it builds anything.** A release is built from a
+   commit. A tree is clean when `git status` shows no change to a tracked file and no untracked file
+   that Git does not ignore. Ignored files are build output and package-manager state:
+   `node_modules`, `dist`, `.turbo`, and pnpm's `.pnpm-store`, which pnpm creates at the checkout's
+   root when the checkout is its own mount (a CI runner's workspace volume). The failure lists every
+   change. `--allow-modified` exists for local development only; its manifest then says
+   `"modified": true`, and such a release must never be published.
+2. **Checks the release set and versions** in the workspace.
+3. **Rebuilds from clean output.** It removes each public package's `dist/` and rebuilds without the
+   build cache, so output from a deleted source file can never ship. It then checks the source tree
+   again: a build that changed a tracked file, or wrote an untracked one Git does not ignore, fails
+   the release, because what is packed must be exactly the commit.
+4. **Packs each package with `pnpm pack`.** Pack-only pnpm hooks (`scripts/lib/pack-hooks.cjs`)
+   apply, never the workspace's install settings ([Reproducibility](#reproducibility)).
+5. **Inspects every tarball.** It checks:
+   - the expected name, version, and file name;
+   - a `LICENSE`, and only the `files` the manifest declares, each built file with the source it
+     came from, and no source, test, or configuration file;
+   - no `workspace:` range, no `devDependencies`, no `publishConfig`, and no install-time lifecycle
+     script;
+   - only public `@ekklesia/*` dependencies, at the train's version;
+   - the distribution marker;
+   - no local path (the checkout, the home directory, or the temporary directory) in any file.
+6. **Checks the set.** The release must hold exactly the expected tarballs: none missing, none extra.
+7. **Writes the release directory only when everything passed,** in one step. It refuses to
+   overwrite one that exists.
+
+```text
+ekklesia-packages-<version>/
+├── ekklesia-contracts-<version>.tgz
+├── ekklesia-design-tokens-<version>.tgz
+├── … one .tgz per package in the train
+├── SHA256SUMS                     `sha256sum -c SHA256SUMS` compatible
+└── ekklesia-package-train.json    the release manifest
+```
+
+### The release manifest
+
+`ekklesia-package-train.json` describes the train by content. It is provider-neutral: it names no
+registry and is not a registry catalog.
+
+```json
+{
+  "packageTrain": 1,
+  "version": "0.2.0",
+  "source": { "modified": false, "revision": "<full commit id>" },
+  "packages": [
+    {
+      "file": "ekklesia-contracts-0.2.0.tgz",
+      "integrity": "sha512-<base64>",
+      "name": "@ekklesia/contracts",
+      "role": "implementation",
+      "sha256": "<hex>",
+      "size": 87379,
+      "version": "0.2.0"
+    }
+  ]
+}
+```
+
+`integrity` is the npm `dist.integrity` form: a registry computes the same value from the same
+bytes, and a module's lockfile records it. The packages are sorted by name, and the file's bytes
+depend only on the commit.
+
+## Proving the artifacts
+
+```bash
+pnpm test:package-release      # scripts/test-package-release.sh
+```
+
+1. **Builds the train** from this checkout. Nothing is built before it.
+2. **Builds it again** from a second worktree of the same commit at another absolute path, and
+   requires both release directories to be byte-identical: every tarball, `SHA256SUMS`, and the
+   manifest.
+3. **Builds Core's verifier**, then **runs the standalone consumer proof** (`scripts/test-standalone-module.sh --release <dir>`) on
+   that release:
+   - **The release is checked first.** Every artifact must match the manifest's size, SHA-256, and
+     integrity, and the release must not be built from a modified tree.
+   - **The fixture module installs from those tarballs alone.** It is
+     `tests/fixtures/standalone-module`, copied outside the repository. Every `@ekklesia/*`
+     package, direct or transitive, resolves to its release tarball. There is no workspace link and
+     no Ekklesia source checkout. The install runs offline: third-party packages come from the
+     workspace install's own pnpm store, named explicitly because pnpm otherwise picks a store per
+     file system, so no registry is involved at all.
+   - **The lockfile matches the release.** It must record each artifact's own integrity. The module
+     then reinstalls from the lockfile alone with `--frozen-lockfile`.
+   - **The install has the right shape.** There is no `drizzle-orm`, and exactly one `react`, which
+     `@ekklesia/ui` resolves to as well. `@ekklesia/contracts` is installed only transitively: it is
+     not in the module's `package.json` and not directly under `node_modules/@ekklesia`. Every
+     installed `@ekklesia/*` package, `module-pack` included, is exactly the release version, and
+     the fixture pins `module-pack` exactly.
+   - **The module builds.** It typechecks with `skipLibCheck: false`, so every published declaration
+     it reaches is checked, then builds its backend and UI.
+   - **It packages and verifies.** It is packed with the release's own `ekklesia-pack-module`, with
+     no workspace file present. Core's verifier then verifies it. The package must:
+     - incorporate the train's packages at the release version;
+     - name the release's module-pack as its packager;
+     - credit no Ekklesia package and exactly one React;
+     - contain no local path.
+
+## Reproducibility
+
+Two builds of the same commit produce byte-identical tarballs, and CI proves it on every run.
+
+- **pnpm normalizes the tar entries.** Every entry gets the fixed modification time 1985-10-26, owner
+  0, and a mode of 0644, or 0755 when executable. The gzip header records no time.
+- **The build output is deterministic,** and source maps use relative paths.
+- **One nondeterminism came from pnpm itself.** pnpm rewrites `workspace:` ranges concurrently and
+  inserts each dependency as its lookup resolves. A package with more than one `workspace:`
+  dependency in one field could therefore be packed with those keys in a different order. Builds
+  from two checkouts of one commit differed in exactly that way: `@ekklesia/module-pack`'s
+  `package.json` ordered `@ekklesia/module-sdk` and `@ekklesia/module-database` differently.
+  - **The fix is pnpm's own hook.** The pack-only `beforePacking` hook puts each dependency map back
+    in the source `package.json`'s key order. It changes no name, range, or field. The tarball stays
+    an ordinary `pnpm pack` tarball.
+  - **The inspection enforces it.** It fails any packed map whose order differs from its source.
+- **The hook also drops `devDependencies`** from packed manifests. A consumer never installs them,
+  and a tooling package's test-only development dependencies named private workspace packages
+  outside the train.
+
+**What reproducibility does not cover:**
+- The module package the consumer proof builds is deterministic only for a fixed install layout.
+  pnpm names a `file:` tarball's install directory after its path, and bundlers keep those names in
+  comments. So the proof always installs from the same relative path. From a registry, the directory
+  is simply `<name>@<version>`.
+- Byte identity is proven for the pinned toolchain: Node.js from `.node-version`, and pnpm from
+  `packageManager`. Another Node.js or zlib build may compress differently. Each artifact's
+  integrity is recorded either way, and that, not byte identity, is what a publication step must
+  verify.
+
+## Publishing the train
+
+The registry is the Gitea npm registry under the `River_of_Glory_Church` owner:
+
+```text
+https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/
+```
+
+| Who | May |
+| --- | --- |
+| Anyone, signed in or not | search, read metadata, download, and install `@ekklesia/*` |
+| The publisher account, through the publish workflow | publish new versions and move dist-tags |
+| Anyone else | nothing more: publishing needs the publisher team's package write permission |
+
+### The workflow
+
+`.github/workflows/publish-packages.yml` (Actions → Publish packages → Run workflow, on `main`,
+with the release version). Nothing else can start it: no pull request or push does, and CI holds no
+registry credential at all.
+
+1. **The gate.** `package-release` runs the same credential-free gate as CI (build, reproduce,
+   consume) and hands the proven release on as a workflow artifact, with its manifest's SHA-256.
+2. **The publish job.** It builds and installs nothing. It downloads the artifact and runs
+   `scripts/publish-package-train.ts` with the secret `EKKLESIA_PACKAGES_PUBLISH_TOKEN`, which only
+   this step receives.
+3. **The publication record** is kept as an artifact of the run.
+
+### What the publication tool does
+
+`scripts/publish-package-train.ts` publishes exactly the `.tgz` files in the release directory. It
+never builds, packs, or edits a package, and it never deletes, unpublishes, or overwrites anything.
+
+1. **Validates the whole train before sending anything.** The manifest must be the one the gate
+   proved (`--manifest-sha256`), for the requested version and this commit (`--revision`), from a
+   clean tree (`"modified": false`), with exactly the nine expected packages. Every artifact's file
+   name, size, SHA-256, integrity, `SHA256SUMS` line, and the `package.json` inside it must match.
+2. **Publishes in dependency order.** Each package comes after the train packages it depends on,
+   then alphabetically. For each package:
+   - **absent:** `npm publish <file.tgz>` under the staging dist-tag `ekklesia-staging`, given the
+     artifact's absolute path (npm runs in a temporary directory of its own), after the file is
+     checked once more against the manifest. npm sends the file's own bytes and runs no script for a
+     file; the registry checks them against their integrity and stores them as they are;
+   - **present with the same bytes:** accepted as already published, and verified;
+   - **present with other bytes:** a hard stop. Nothing is deleted or overwritten, nothing after it
+     is published, and the version is burned ([Immutability](#immutability)).
+3. **Reads every package back.** The registry's metadata must name the package and version, report
+   the artifact's integrity, and list the same `dependencies`, `peerDependencies`,
+   `optionalDependencies`, and `bin` as the tarball's `package.json` (npm writes `bin` paths without
+   a leading `./`). Its tarball URL must be on the configured registry, and the tarball it serves must
+   be the release artifact, byte for byte. With `--require-public-read`, an anonymous download must
+   give the same bytes too. A package is published only once all of that holds.
+4. **Moves `latest` last.** Only when all nine are verified does `latest` move to the train, never
+   backwards past a newer version. The train is published when every package's `latest` agrees.
+5. **Writes the publication record** (`--record`).
+
+A rerun is always safe. It publishes only what is missing, accepts what is already there and
+identical, and moves only the tags that are not yet right. A train interrupted after five packages,
+or after four tags, finishes on the next run. No retry ever deletes anything.
+
+### The publication record
+
+Evidence that one train was published, not a second package catalog, and never a secret:
+
+```json
+{
+  "publicationRecord": 1,
+  "packageTrain": { "version": "0.2.0", "revision": "<commit>", "manifestSha256": "<hex>" },
+  "registry": "https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/",
+  "finalTag": "latest",
+  "completedAt": "<ISO time>",
+  "packages": [
+    {
+      "name": "@ekklesia/contracts",
+      "version": "0.2.0",
+      "file": "ekklesia-contracts-0.2.0.tgz",
+      "outcome": "published",
+      "artifact": { "sha256": "<hex>", "integrity": "sha512-…", "size": 87379 },
+      "registry": { "tarball": "<url>", "sha256": "<hex>", "integrity": "sha512-…", "publicRead": true },
+      "finalTag": "moved",
+      "distTags": { "ekklesia-staging": "0.2.0", "latest": "0.2.0" }
+    }
+  ]
+}
+```
+
+`outcome` is `published` or `already-present`. `finalTag` is `moved`, `already-current`, or
+`kept-newer` (a newer version already holds `latest`).
+
+### Credentials
+
+- **One credential:** `EKKLESIA_PACKAGES_PUBLISH_TOKEN`, a repository Actions secret, used only by
+  the publish step. Nobody needs a token to read or install.
+- **The publisher** is a dedicated account, member only of a `River_of_Glory_Church` team whose one
+  permission is Packages: Write. Its token has only the `write:package` scope. Gitea's
+  `write:package` also allows deleting packages; the tool never does, and nothing else uses the
+  token.
+- **No token in git or in an `.npmrc`.** The tool writes a temporary npm configuration that refers to
+  the variable (`_authToken=${EKKLESIA_PACKAGES_PUBLISH_TOKEN}`), ignores every user, global, and
+  project npm configuration, sends the token only to the registry itself, and removes the
+  configuration afterwards.
+- **What remains trusted:** Gitea gives repository secrets to workflows run for pull requests from
+  branches of this same repository, so anyone who can push a branch here could read the secret
+  through a changed workflow. Keep write access to this repository to the maintainers.
+
+### Immutability
+
+Gitea refuses to upload a version that exists (409). But it lets anyone with package write
+permission delete a version, deletion leaves nothing behind, and an owner's package cleanup rules
+can delete versions on a schedule. So immutability is Ekklesia's policy, not the registry's
+guarantee:
+
+- **A published version is never deleted,** by anyone, for any reason short of a security incident.
+- **A version number is never reused with other bytes.** A version found on the registry with other
+  bytes is burned: investigate how it got there, and publish the train under a new version.
+- **No package cleanup rule** may be configured for the `River_of_Glory_Church` owner.
+- **The publisher never deletes.** The tool has no delete, unpublish, or overwrite, and its tests
+  check that.
+
+Module lockfiles record each package's integrity, so a replaced package would fail every install of
+it, rather than install silently.
+
+### Moving to another registry
+
+Only configuration changes: the registry URL (the workflow's `EKKLESIA_PACKAGES_REGISTRY`), the
+publisher credential, and modules' `@ekklesia:registry`. Modules then regenerate their lockfiles,
+because Gitea's tarball URLs are its own. Package sources, the train, its manifests, and every
+artifact already built stay as they are; the same bytes keep the same integrity.
+
+### Proving the publication machinery
+
+`pnpm test:package-publication` (`scripts/test-package-publication.sh`, the CI `package-publication`
+job) publishes a real release train to a disposable Gitea 1.27.2 configured like the real one:
+public owners, a publisher team, and an outsider. In CI it publishes the very artifact the
+`package-release` job handed on, after checking its manifest hash. It proves:
+
+- anonymous search, metadata, and download work;
+- publishing without credentials, or by a user outside the publisher team, fails;
+- the round trip is byte-identical, also anonymously;
+- the registry refuses a second upload of a published version;
+- a train interrupted before its sixth package resumes, verifying the five and publishing the rest,
+  with `latest` untouched until all nine are verified;
+- a version already published with other bytes stops the train, deleting and overwriting nothing,
+  and publishing nothing after it, on every retry;
+- a train interrupted while moving `latest` converges on a rerun, moving only the missing tags.
+
+### The first publication
+
+The first train published is **0.2.0**, the next platform release, not 0.1.2. The `v0.1.2` tag
+predates the curated SDK and this release tooling, so packages built now and called 0.1.2 would
+claim to be source that 0.1.2 never contained.
+
+Before it, an administrator of the Gitea instance:
+
+1. creates the dedicated publisher account;
+2. creates a `River_of_Glory_Church` team, for example `package-publishers`, with only the Packages
+   unit at Write, and adds the account to it;
+3. creates a token for the account with only `write:package`, and stores it as the repository
+   Actions secret `EKKLESIA_PACKAGES_PUBLISH_TOKEN`;
+4. checks that the owner has no package cleanup rule.
+
+Then the release proceeds as usual: the version-set pull request merges, a maintainer starts
+Publish packages on `main` with that version, and tags the commit once the train is published.
+

docs/development/testing.md

@@ -649,6 +649,24 @@ Ekklesia Module Package v1 (ADR 0049) is proven at three levels, all in `pnpm ve
   builds the template and Core first, and runs the template's own tests (which rebuild its UI in
   place) before these.
 
+## The public package train
+
+`pnpm test:package-release` (the CI `package-release` job) builds the public `@ekklesia/*` package
+train, proves a second build from another checkout of the commit byte-identical, and installs
+exactly those tarballs into the standalone fixture module, offline, which must typecheck with
+`skipLibCheck: false`, build, package, and verify. It needs a clean source tree; pass
+`-- --allow-modified` to try uncommitted changes locally. The release rules themselves (set,
+versions, manifest inspection, release directory, manifest bytes, the pack hook) are unit-tested in
+`tests/public-packages.test.ts`, part of `pnpm verify`. See
+[Releases and the public package train](releases.md).
+
+`pnpm test:package-publication` (the CI `package-publication` job, given the `package-release` job's
+artifact) publishes a release train to a disposable Gitea 1.27.2 with Docker, never the real
+registry, and proves the publication tool: byte-identical round trips, anonymous reads, refused
+unauthorized publishing, partial-train recovery, the hard stop on a burned version, and dist-tag
+convergence (`tests/package-publication.integration.ts`). The tool's own rules are unit-tested in
+`tests/package-publication.test.ts`, part of `pnpm verify`.
+
 ## The generic platform image and the reference deployment
 
 These need Docker and build images locally; nothing is pushed or published.

docs/module-development/README.md

@@ -66,8 +66,126 @@ module with no migration history omits `entrypoints.migrations` and needs no pla
 }
 ```
 
-The package version must match the manifest and runtime-definition versions. Internal package
+The package version must match the manifest and runtime-definition versions. Inside this
-dependencies use `workspace:` ranges and supported public package entrypoints.
+repository, Ekklesia package dependencies use `workspace:` ranges and supported public package
+entrypoints. A module in its own repository depends on the published packages instead
+([Developing a module in its own repository](#developing-a-module-in-its-own-repository)).
+
+### Developing a module in its own repository
+
+> **Status:** the packages are published by release
+> ([ADR 0053](../architecture/decisions/0053-standalone-module-development-packages.md),
+> [Releases and the public package train](../development/releases.md)). The first published train
+> is 0.2.0, the platform release after 0.1.2.
+
+A module does not need an Ekklesia checkout. Do not clone Ekklesia and put your module in its
+`modules/` directory: your module is its own repository, and it depends on Ekklesia's
+module-development packages like any other npm packages.
+
+The packages are **publicly readable**
+([ADR 0054](../architecture/decisions/0054-public-package-reads-before-launch.md)): installing them
+needs no account, no token, and no access to Ekklesia's Gitea. That is not a public launch, and it
+promises no API stability beyond the pre-1.0 SemVer policy. Only Ekklesia's release workflow can publish them. Point the `@ekklesia` scope at
+the registry in your repository's committed `.npmrc`; that is all the configuration there is:
+
+```ini
+@ekklesia:registry=https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/
+```
+
+Then the module builds and packages like any other:
+
+```bash
+pnpm install
+pnpm build
+pnpm exec ekklesia-pack-module --module . --target any --out ../packages \
+  --license-file ./LICENSE --source-revision "$(git rev-parse HEAD)"
+```
+
+Before 1.0, a minor version may change these APIs (the project's SemVer policy). Pin the train you
+build against with ranges in `package.json` and exact versions in your lockfile.
+
+| Package | Where it goes | What it is |
+| --- | --- | --- |
+| `@ekklesia/module-sdk` | `dependencies` | `defineModuleRuntime`, routes, configuration, storage, realtime, principals |
+| `@ekklesia/module-database` | `dependencies` | Module Database ABI v1 types, `sql`, schema metadata; `/drizzle` for Drizzle |
+| `@ekklesia/module-ui-sdk` | `dependencies` | `defineModuleUi` and the host context |
+| `@ekklesia/design-tokens` | `dependencies` | design-token names and helpers |
+| `@ekklesia/ui` | `dependencies` | shared elements; a pre-1.0 API that may still change |
+| `react`, `react-dom`, your ORM if any | `dependencies` | your own copies, bundled into your artifacts |
+| `@ekklesia/module-ui-build` | `devDependencies` | `ekklesia-build-module-ui` |
+| `@ekklesia/module-pack` | `devDependencies`, **exact version** | `ekklesia-pack-module` |
+| `@ekklesia/typescript-config` | `devDependencies` | `node.json`, `browser-react.json`, ... |
+
+`@ekklesia/contracts` is not a direct dependency. The packages above install it; never add or
+import it yourself, because what it exports is the platform's, not a supported author API.
+
+```json
+{
+  "name": "@acme/notes",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-or-later",
+  "private": true,
+  "type": "module",
+  "engines": { "node": ">=24.11.0 <25" },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui"
+  },
+  "dependencies": {
+    "@ekklesia/module-database": "^0.2.0",
+    "@ekklesia/module-sdk": "^0.2.0",
+    "@ekklesia/module-ui-sdk": "^0.2.0",
+    "@ekklesia/ui": "^0.2.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@ekklesia/module-pack": "0.2.0",
+    "@ekklesia/module-ui-build": "^0.2.0",
+    "@ekklesia/typescript-config": "^0.2.0",
+    "typescript": "7.0.2"
+  }
+}
+```
+
+- **One coordinated version.** Every Ekklesia module-development package has the same version,
+  equal to the Ekklesia release it belongs to, and the platform checks your manifest's
+  `compatibility.moduleSdk` against it. Ranges in your `package.json` are fine; your lockfile pins
+  exact artifacts, and you install with a frozen lockfile.
+- **Pin `@ekklesia/module-pack` exactly** in `package.json`, not only in the lockfile: its version
+  decides the package it produces.
+- **`engines.node` is required.** The packager records your module's supported Node.js range from
+  `engines.node` in your `package.json`, and refuses to package without it
+  (`MODULE_PACK_RUNTIME_UNKNOWN`). It never looks for a workspace file.
+- **No Drizzle unless you use it.** The Module SDK does not install Drizzle. A module that uses the
+  Drizzle adapter, `@ekklesia/module-database/drizzle`, adds `drizzle-orm` to its own
+  dependencies; it is an optional peer of that adapter only.
+- **One React.** `@ekklesia/ui` takes React as a peer, so your bundle contains one React, your own.
+  Your UI artifacts still bundle it
+  ([ADR 0023](../architecture/decisions/0023-module-ui-build-pipeline.md)).
+- **esbuild's install script.** The UI build and the packager use esbuild, which runs an install
+  script. With pnpm, allow it in your repository's `pnpm-workspace.yaml`:
+
+  ```yaml
+  allowBuilds:
+    esbuild: true
+  ```
+- **Lockfiles name the registry.** pnpm records Gitea's tarball URLs in your lockfile. If the
+  packages ever move to another registry, change `@ekklesia:registry` and regenerate the lockfile;
+  nothing else changes, and the integrity of every package stays the same.
+- **TypeScript.** Extend the shared configurations by package name, for example
+  `"extends": "@ekklesia/typescript-config/node.json"` for the backend and
+  `@ekklesia/typescript-config/browser-react.json` for the UI.
+
+Packaging and verification work exactly as for a module in this repository
+([Packaging your module](#packaging-your-module)). The packager recognizes Ekklesia's packages by
+their identity, not by where they are installed, so they are recorded under `incorporates` and never
+credited as third-party software, wherever they came from.
+
+Ekklesia proves this on every CI run: `pnpm test:package-release` builds the public packages of a
+release as one train of tarballs, proves two builds identical, and installs exactly those tarballs
+into a module outside the repository (`tests/fixtures/standalone-module`), with no workspace link
+and no registry, then typechecks, builds, packages, and verifies it. Those exact artifacts are what
+the release publishes ([Releases and the public package train](../development/releases.md)).
 
 ### An installed module is self-contained
 
@@ -92,8 +210,9 @@ through no link, `NODE_PATH`, loader hook, or alias. The packager therefore bund
 
 #### Packaging your module
 
-Build your module, then run the packager from the workspace your module is built in. It is a
+Build your module, then run the packager from your module's directory. It is a development
-development dependency like `@ekklesia/module-ui-build`:
+dependency like `@ekklesia/module-ui-build`, and it takes your module's supported Node.js range from
+`engines.node` in its `package.json`:
 
 ```bash
 pnpm exec ekklesia-pack-module --module . --target any --out ../packages \
@@ -163,7 +282,10 @@ The archive holds one directory named with your module id:
   licence's standard text is complete without a copyright line (Apache-2.0, which the packager then
   supplies and says so). The module itself is not added to this notice file. Bundled Ekklesia
   packages remain listed in `ekklesia.package.json` under `incorporates`; one applicable AGPL text
-  is sufficient for current official modules.
+  is sufficient for current official modules. An Ekklesia package is one named `@ekklesia/*` whose
+  `package.json` also carries `"ekklesia": { "distribution": "module-development" }`, whether it is
+  linked from this repository or installed from a registry; a package with only the name is
+  third-party.
 - **Reviewed licence supplements.** Some dependencies omit material that redistribution requires.
   For one of those, the packager adds material from a reviewed supplement checked in with it, after
   the package's own material and labelled as such
@@ -244,8 +366,8 @@ without executing module code:
   "name": "Calendar",
   "version": "0.1.0",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
   },
   "dependencies": {
     "modules": {
@@ -1458,27 +1580,27 @@ export const events = moduleTable("events", {
 });
 ```
 
-The production schema entrypoint in `src/schema/index.ts` wraps those same objects with the Module
+The production schema entrypoint in `src/schema/index.ts` turns those same objects into the plain
-SDK ownership marker:
+schema metadata an ABI-v1 module declares:
 
 ```ts
-import { defineModuleSchema } from "@ekklesia/module-sdk";
+import { moduleDrizzleSchemaMetadata } from "@ekklesia/module-database/drizzle";
 import { events } from "./tables.js";
 
 export { events } from "./tables.js";
 
-export default defineModuleSchema({
+export default moduleDrizzleSchemaMetadata("calendar", { events });
-  moduleId: "calendar",
-  tables: { events }
-});
 ```
 
+A module without an ORM declares the same metadata directly with `defineModuleSchemaMetadata` from
+`@ekklesia/module-database`. A legacy-v8 module's schema entrypoint default-exports
+`{ moduleId, tables }` with the Drizzle table objects themselves.
+
 The prefix callback converts the module ID to a snake-case namespace and prefixes every local table
 name. Here the physical PostgreSQL name is `calendar_events`; `care-team` plus `members` becomes
 `care_team_members`. Local names must be lowercase snake case, and the complete physical identifier
-must not exceed 63 characters. The SDK's `createModuleTable` provides the same convenience when a
+must not exceed 63 characters. `createModuleTable` from `@ekklesia/module-database/drizzle` provides
-generator-facing pure declaration file is not needed; Core validates built metadata independently
+the same convenience; Core validates built metadata independently of either helper.
-of either helper.
 
 Schema definitions use PostgreSQL tables in the platform-managed default/public schema. They must
 be side-effect-free: do not connect to a database, read configuration, or perform I/O during import.
@@ -1511,8 +1633,8 @@ export default defineConfig({
 Keep `tables.ts` limited to Drizzle declarations so the stable generator can load it without
 executing the ESM module wrapper. For an ABI-v1 module, `src/schema/index.ts` remains the production
 compiled schema entrypoint and converts those same table objects to plain metadata with
-`moduleDrizzleSchemaMetadata`; tables are not declared twice. A legacy-v8 module continues to wrap
+`moduleDrizzleSchemaMetadata`; tables are not declared twice. A legacy-v8 module continues to export
-them with `defineModuleSchema` while that facade exists.
+them as `{ moduleId, tables }` while that facade exists.
 
 Run the module's `migration:generate` script with a lowercase snake-case name, review the generated
 SQL and snapshot, and add the matching entry to `drizzle/meta/_ekklesia.json`. Every entry must
@@ -1636,6 +1758,15 @@ not Core.
 
 ## Legacy database access
 
+> **New modules use [Module Database ABI v1](#module-database-abi-v1).** Core still serves the
+> legacy facade described here for its deprecation window
+> ([ADR 0050](../architecture/decisions/0050-module-database-abi-v1.md)), so existing legacy modules
+> keep running. But the Module SDK no longer exposes the facade's type
+> ([ADR 0053](../architecture/decisions/0053-standalone-module-development-packages.md)): built
+> against the current SDK, a module that declares no database sees `services.database` as `never`,
+> and the example below no longer typechecks. Migrate to ABI v1 rather than reaching for the type
+> elsewhere.
+
 For a version 8 manifest that omits `database`, `context.services.database` — available in `start`, `stop`, and every authorized route handler,
 never in `register` — is a `ModuleDatabase`: a typed Drizzle query surface over exactly `select`,
 `selectDistinct`, `selectDistinctOn`, `insert`, `update`, `delete`, `execute`, and `transaction`,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ekklesia",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",
@@ -38,9 +38,12 @@
     "modules:pack": "turbo run build && node packages/module-pack/bin/ekklesia-pack-module.mjs",
     "modules:validate": "turbo run build && node core/dist/cli/validate-modules.js",
     "modules:verify-package": "turbo run build && node core/dist/cli/verify-module-package.js",
+    "packages:release": "node scripts/package-release.ts --out .package-release",
     "test": "turbo run test test:root",
     "test:migrations:integration": "pnpm build && bash scripts/test-migrations-integration.sh",
     "test:root": "vitest run --config vitest.config.ts",
+    "test:package-release": "bash scripts/test-package-release.sh",
+    "test:package-publication": "bash scripts/test-package-publication.sh",
     "test:watch": "vitest",
     "typecheck": "turbo run typecheck typecheck:root",
     "typecheck:root": "tsc --noEmit --project tsconfig.json",

packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/contracts",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -19,12 +19,10 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/contracts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "drizzle-orm": "0.45.2",
     "semver": "7.8.5",
     "spdx-expression-parse": "5.0.0",
     "zod": "4.4.3"
@@ -38,6 +36,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "contracts"
+    "layer": "contracts",
+    "distribution": "module-development"
   }
 }

packages/contracts/src/index.ts

@@ -11,7 +11,6 @@ export * from "./module-manifest.js";
 export * from "./module-migration.js";
 export * from "./module-realtime.js";
 export * from "./module-runtime.js";
-export * from "./module-schema.js";
 export * from "./module-schema-metadata.js";
 export * from "./module-schema-names.js";
 export * from "./module-storage.js";

packages/contracts/src/module-database.ts

@@ -1,59 +1,19 @@
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { ModuleDatabaseExecutor } from "./module-database-abi.js";
 
-/**
- * A trusted backend module's typed Drizzle query surface — the same query-building methods a
- * platform-owned Drizzle instance exposes, restricted to exactly the operations a module needs to
- * read and write its own tables. Derived with `Pick` from the real `drizzle-orm/node-postgres`
- * database type rather than hand-declared, so every method keeps Drizzle's own table-aware
- * argument and result inference exactly as-is — a module calling `database.select().from(table)`
- * or `database.insert(table).values(...)` gets the identical typed builder a direct Drizzle caller
- * would, with no `any`/`unknown` erasure anywhere in the chain.
- *
- * Deliberately excludes everything `NodePgDatabase` or the `drizzle(...)` factory otherwise
- * exposes: `$client` (the raw `pg` client/pool), `_` (internal session/dialect/schema state),
- * `query` (a relational-query builder tied to one schema, which would have to span every
- * installed module's tables to exist here at all), `$cache`, `$count`, `$with`, `with`, and
- * `refreshMaterializedView`. There is no connection string, pool, session, or dialect object
- * reachable through this type. Carries no schema generic — a module brings its own Drizzle table
- * objects (`@ekklesia/module-sdk`'s `defineModuleSchema`) to each call, so there is no global
- * relational schema spanning every installed module for this type to leak.
- *
- * This is an integration boundary, not a security sandbox: modules are trusted, compiled backend
- * plugins that already run arbitrary code in this process, exactly like every other lifecycle hook
- * and HTTP handler they define. `ModuleDatabase` exists to keep a module's code Drizzle-typed and
- * decoupled from how the platform physically connects to PostgreSQL — not to defend against a
- * malicious module, which this facade cannot do and does not attempt to do.
- */
-export type ModuleDatabase = Pick<
-  NodePgDatabase,
-  | "select"
-  | "selectDistinct"
-  | "selectDistinctOn"
-  | "insert"
-  | "update"
-  | "delete"
-  | "execute"
-  | "transaction"
->;
-
 /**
  * The complete set of platform-provided services a trusted module's `start`/`stop` lifecycle hooks
- * and authorized HTTP route handlers receive — for this phase, exactly one: `database`. Frozen, and
+ * and authorized HTTP route handlers receive — for this phase, exactly one: `database`. For a
+ * module that declares `database: { abi: 1 }` it is the Module Database ABI v1 executor; for a
+ * legacy module it is Core's legacy facade, whose type Core alone owns, so this package never
+ * references an ORM (ADR 0053). Frozen, and
  * never handed to a module's `register` hook (`ModuleRegistrationContext` has no `services` field):
  * registration stays declarative and database-free, exactly as before this contract existed.
  * Deliberately has no storage, jobs, configuration, secrets, or authorization field yet — those
  * remain out of scope until a later phase explicitly adds them here, one at a time, the same way
  * `database` was added.
  */
-export interface ModuleRuntimeServices<
+export interface ModuleRuntimeServices<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly database: Database;
 }
 
-export type LegacyModuleRuntimeServices = ModuleRuntimeServices<ModuleDatabase>;
 export type ModuleDatabaseAbiRuntimeServices = ModuleRuntimeServices<ModuleDatabaseExecutor>;
-export type AnyModuleRuntimeServices =
-  | LegacyModuleRuntimeServices
-  | ModuleDatabaseAbiRuntimeServices;

packages/contracts/src/module-http.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { type ModuleId, type PermissionId, permissionIdSchema } from "./identifiers.js";
 import type { EkklesiaPrincipal } from "./identity.js";
 import type { ModuleConfiguration } from "./module-configuration.js";
-import type { ModuleDatabase, ModuleRuntimeServices } from "./module-database.js";
+import type { ModuleRuntimeServices } from "./module-database.js";
 import type { ModuleDatabaseExecutor } from "./module-database-abi.js";
 import type { ModuleRealtimePublisher } from "./module-realtime.js";
 import type { ModuleStorage } from "./module-storage.js";
@@ -272,9 +272,7 @@ export function moduleRoutesOverlap(
  * behavior, and uncaught-handler sanitization; permission enforcement always completes before a
  * handler — and therefore any parameter validation it performs — can run.
  */
-export interface ModuleRouteHandlerContext<
+export interface ModuleRouteHandlerContext<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly moduleId: ModuleId;
   readonly principal: EkklesiaPrincipal;
   readonly params: Readonly<Record<string, string>>;
@@ -296,9 +294,10 @@ export interface ModuleRouteHandlerContext<
 /** A framework-neutral Fetch handler: standard `Request` in, standard `Response` out. The full
  * query string remains available through `Request.url`; there is no competing query or body
  * abstraction. */
-export type ModuleRouteHandler<
+export type ModuleRouteHandler<Database = ModuleDatabaseExecutor> = (
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
+  request: Request,
-> = (request: Request, context: ModuleRouteHandlerContext<Database>) => Awaitable<Response>;
+  context: ModuleRouteHandlerContext<Database>,
+) => Awaitable<Response>;
 
 /**
  * What a module passes to `http.route(...)` during `register`. `permission` is a plain string here
@@ -313,9 +312,7 @@ export type ModuleRouteHandler<
  * path, CORS/origin policy, authentication behavior, grant/platform-owner state, middleware, audit
  * metadata, another module's namespace, or an unprotected/no-permission route.
  */
-export interface ModuleRouteDefinitionInput<
+export interface ModuleRouteDefinitionInput<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly method: ModuleHttpMethod;
   readonly path: string;
   readonly permission: string;
@@ -331,9 +328,7 @@ export interface ModuleRouteDefinitionInput<
 
 /** The validated, canonical form of a `ModuleRouteDefinitionInput` — what `http.route` produces
  * only after every field passes its own grammar. */
-export interface ModuleRouteDefinition<
+export interface ModuleRouteDefinition<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly method: ModuleHttpMethod;
   readonly path: ModuleRoutePath;
   readonly permission: PermissionId;
@@ -346,9 +341,7 @@ export interface ModuleRouteDefinition<
 
 /** The Fetch-based registrar exposed as `context.http` during `register` only — never on
  * `ModuleRuntimeContext`, so `start`/`stop` cannot register a route after the fact. */
-export interface ModuleHttpRouteRegistrar<
+export interface ModuleHttpRouteRegistrar<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   route(definition: ModuleRouteDefinitionInput<Database>): void;
 }
 

packages/contracts/src/module-runtime.ts

@@ -1,7 +1,7 @@
 import type { CapabilityId, ModuleId } from "./identifiers.js";
 import { moduleIdSchema } from "./identifiers.js";
 import type { ModuleConfiguration } from "./module-configuration.js";
-import type { ModuleDatabase, ModuleRuntimeServices } from "./module-database.js";
+import type { ModuleRuntimeServices } from "./module-database.js";
 import type { ModuleDatabaseExecutor } from "./module-database-abi.js";
 import type { ModuleHttpRouteRegistrar } from "./module-http.js";
 import type { ModuleRealtimeChannelRegistrar, ModuleRealtimePublisher } from "./module-realtime.js";
@@ -25,9 +25,7 @@ export interface CapabilityRegistrar extends CapabilityResolver {
   provide(capabilityId: CapabilityId, implementation: unknown): void;
 }
 
-export interface ModuleRegistrationContext<
+export interface ModuleRegistrationContext<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly capabilities: CapabilityRegistrar;
   /** Available only during `register` — never on `ModuleRuntimeContext` — so a route can only ever
    * be declared while Core is still building the immutable startup snapshot, never added or removed
@@ -52,9 +50,7 @@ export interface ModuleRegistrationContext<
  * same frozen `services` object identity as the other, for a given API runtime — never a fresh
  * `ModuleRuntimeServices` built per hook invocation. Unlike `ModuleRegistrationContext`, this never
  * carries `http`: a route can only ever be declared during `register`. */
-export interface ModuleRuntimeContext<
+export interface ModuleRuntimeContext<Database = ModuleDatabaseExecutor> {
-  Database extends ModuleDatabase | ModuleDatabaseExecutor = ModuleDatabase,
-> {
   readonly capabilities: CapabilityResolver;
   readonly moduleId: ModuleId;
   readonly services: ModuleRuntimeServices<Database>;
@@ -87,7 +83,7 @@ export interface ModuleRuntimeContext<
   readonly config: ModuleConfiguration;
 }
 
-interface ModuleRuntimeDefinitionBase<Database extends ModuleDatabase | ModuleDatabaseExecutor> {
+interface ModuleRuntimeDefinitionBase<Database> {
   readonly id: ModuleId;
   readonly register?: (context: ModuleRegistrationContext<Database>) => Awaitable<void>;
   readonly start?: (context: ModuleRuntimeContext<Database>) => Awaitable<void>;
@@ -95,7 +91,10 @@ interface ModuleRuntimeDefinitionBase<Database extends ModuleDatabase | ModuleDa
   readonly version: string;
 }
 
-export interface LegacyModuleRuntimeDefinition extends ModuleRuntimeDefinitionBase<ModuleDatabase> {
+/** A module on the legacy database facade (ADR 0016), until its deprecation window ends (ADR 0050).
+ * The facade's type is Core's own, so here its database is opaque: Core specializes `Database`. */
+export interface LegacyModuleRuntimeDefinition<Database = unknown>
+  extends ModuleRuntimeDefinitionBase<Database> {
   readonly database?: never;
 }
 

packages/contracts/tests/module-schema.test.ts

@@ -1,11 +1,5 @@
-import { alias, getTableConfig, integer } from "drizzle-orm/pg-core";
 import { describe, expect, it } from "vitest";
-import {
+import { moduleTableName, physicalModuleTableNameSchema } from "../src/index.js";
-  moduleTableName,
-  parseModuleSchemaDefinition,
-  physicalModuleTableNameSchema,
-} from "../src/index.js";
-import { pgTable } from "drizzle-orm/pg-core";
 
 describe("module schema contract", () => {
   it("creates deterministic physical names from module and local identifiers", () => {
@@ -22,33 +16,4 @@ describe("module schema contract", () => {
       "The namespaced PostgreSQL table name is invalid or too long.",
     );
   });
-
-  it("normalizes and freezes a typed schema definition without freezing its tables", () => {
-    const records = pgTable("example_records", { id: integer().primaryKey() });
-    const definition = parseModuleSchemaDefinition({
-      moduleId: "example",
-      tables: { records },
-    });
-
-    expect(definition.tables.records).toBe(records);
-    expect(getTableConfig(records).name).toBe("example_records");
-    expect(Object.isFrozen(definition)).toBe(true);
-    expect(Object.isFrozen(definition.tables)).toBe(true);
-    expect(Object.isFrozen(records)).toBe(false);
-  });
-
-  it("rejects malformed, empty, unknown, and non-PostgreSQL table definitions", () => {
-    const records = pgTable("example_records", { id: integer() });
-    const disguisedRecords = alias(records, "example_disguised_records");
-    expect(() => parseModuleSchemaDefinition({ moduleId: "example", tables: {} })).toThrow();
-    expect(() =>
-      parseModuleSchemaDefinition({ moduleId: "example", tables: { records: {} } }),
-    ).toThrow();
-    expect(() =>
-      parseModuleSchemaDefinition({ moduleId: "example", tables: { records }, extra: true }),
-    ).toThrow();
-    expect(() =>
-      parseModuleSchemaDefinition({ moduleId: "example", tables: { disguisedRecords } }),
-    ).toThrow();
-  });
 });

packages/design-tokens/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/design-tokens",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -15,7 +15,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/design-tokens",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json"
   },
@@ -28,6 +27,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "design-tokens"
+    "layer": "design-tokens",
+    "distribution": "module-development"
   }
 }

packages/module-database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/module-database",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -19,7 +19,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-database",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
@@ -34,7 +33,8 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "module-sdk"
+    "layer": "module-sdk",
+    "distribution": "module-development"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.45.2 <0.46.0"

packages/module-database/src/drizzle.ts

@@ -6,8 +6,12 @@ import type {
   ModuleId,
   ModuleSchemaMetadataDefinition,
 } from "@ekklesia/contracts";
-import { parseModuleSchemaMetadataDefinition } from "@ekklesia/contracts";
+import {
-import { type AnyPgTable, getTableConfig } from "drizzle-orm/pg-core";
+  moduleTableName,
+  moduleTablePrefix,
+  parseModuleSchemaMetadataDefinition,
+} from "@ekklesia/contracts";
+import { type AnyPgTable, getTableConfig, pgTableCreator } from "drizzle-orm/pg-core";
 import { drizzle, type PgRemoteDatabase } from "drizzle-orm/pg-proxy";
 import type { DrizzleConfig } from "drizzle-orm/utils";
 
@@ -110,3 +114,13 @@ export function moduleDrizzleSchemaMetadata(
     });
   return parseModuleSchemaMetadataDefinition({ moduleId, tables: metadata });
 }
+
+/**
+ * A Drizzle table factory for this module's tables: every table it creates gets the module's
+ * mandatory namespace (ADR 0007), so `createModuleTable("care-team")("members", …)` is the physical
+ * table `care_team_members`.
+ */
+export function createModuleTable(moduleId: ModuleId) {
+  moduleTablePrefix(moduleId);
+  return pgTableCreator((localName) => moduleTableName(moduleId, localName));
+}

packages/module-database/src/index.ts

@@ -3,8 +3,54 @@ import {
   type ModuleDatabaseError,
   type ModuleDatabaseParameter,
   type ModuleDatabaseQuery,
+  type ModuleSchemaMetadataDefinition,
+  parseModuleSchemaMetadataDefinition,
 } from "@ekklesia/contracts";
 
+/**
+ * `@ekklesia/module-database`: everything a module needs for the Module Database ABI v1 (ADR 0050),
+ * with no ORM. Drizzle support lives in the `@ekklesia/module-database/drizzle` subpath, the only
+ * place that needs Drizzle (ADR 0053).
+ */
+export {
+  isModuleDatabaseError,
+  MODULE_DATABASE_ABI_VERSION,
+  MODULE_DATABASE_ERROR_CODES,
+  type ModuleDatabaseAbiVersion,
+  type ModuleDatabaseArrayRow,
+  ModuleDatabaseError,
+  type ModuleDatabaseErrorCode,
+  type ModuleDatabaseExecutor,
+  type ModuleDatabaseField,
+  type ModuleDatabaseIsolationLevel,
+  type ModuleDatabaseObjectRow,
+  type ModuleDatabaseParameter,
+  type ModuleDatabaseQuery,
+  type ModuleDatabaseQueryable,
+  type ModuleDatabaseQueryResult,
+  type ModuleDatabaseRowMode,
+  type ModuleDatabaseScalar,
+  type ModuleDatabaseTransaction,
+  type ModuleDatabaseTransactionOptions,
+  type ModuleDatabaseValue,
+  type ModuleSchemaForeignKeyMetadata,
+  type ModuleSchemaMetadataDefinition,
+  type ModuleSchemaTableMetadata,
+  moduleTableName,
+  moduleTablePrefix,
+} from "@ekklesia/contracts";
+
+/**
+ * A module's plain schema metadata (ADR 0050): the tables it owns and their foreign keys, with no
+ * ORM object. Validated and frozen; a Drizzle module derives the same data with
+ * `moduleDrizzleSchemaMetadata` from `@ekklesia/module-database/drizzle`.
+ */
+export function defineModuleSchemaMetadata<const Definition extends ModuleSchemaMetadataDefinition>(
+  definition: Definition,
+): Readonly<Definition> {
+  return parseModuleSchemaMetadataDefinition(definition) as Readonly<Definition>;
+}
+
 /** SQL text and values ready to pass directly to a Module Database ABI v1 executor. */
 export type ModuleSqlQuery = Readonly<Required<Pick<ModuleDatabaseQuery, "text" | "values">>>;
 

packages/module-database/tests/create-module-table.test.ts

@@ -1,20 +1,17 @@
 import { getTableConfig, integer } from "drizzle-orm/pg-core";
 import { describe, expect, it } from "vitest";
-import { createModuleTable, defineModuleSchema } from "../src/index.js";
+import { createModuleTable, moduleDrizzleSchemaMetadata } from "../src/drizzle.js";
 
-describe("module schema authoring", () => {
+describe("Drizzle module tables", () => {
-  it("creates namespaced PostgreSQL tables and a typed frozen definition", () => {
+  it("creates namespaced PostgreSQL tables that become plain schema metadata", () => {
     const moduleTable = createModuleTable("care-team");
     const members = moduleTable("members", { id: integer().primaryKey() });
-    const definition = defineModuleSchema({
-      moduleId: "care-team",
-      tables: { members },
-    });
 
     expect(getTableConfig(members).name).toBe("care_team_members");
-    expect(definition.tables.members).toBe(members);
+    expect(moduleDrizzleSchemaMetadata("care-team", { members })).toEqual({
-    expect(Object.isFrozen(definition)).toBe(true);
+      moduleId: "care-team",
-    expect(Object.isFrozen(definition.tables)).toBe(true);
+      tables: [{ foreignKeys: [], name: "care_team_members" }],
+    });
   });
 
   it("rejects invalid module and logical table names", () => {

packages/module-pack/LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

packages/module-pack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/module-pack",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -21,7 +21,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-pack",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
@@ -45,6 +44,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "tooling"
+    "layer": "tooling",
+    "distribution": "module-development"
   }
 }

packages/module-pack/src/pack-module.ts

@@ -20,10 +20,10 @@ import { build, type Message, type Plugin } from "esbuild";
 import { minVersion, satisfies, subset, validRange } from "semver";
 import {
   NATIVE_TARGETS,
-  type NativePackage,
-  type NativeTarget,
   NativeError,
   type NativeErrorCode,
+  type NativePackage,
+  type NativeTarget,
   nativeClosure,
   nativeRuntime,
 } from "./native.js";
@@ -130,7 +130,7 @@ const messages: Readonly<Record<ModulePackErrorCode, string>> = Object.freeze({
     "A package path is not portable printable ASCII that fits the archive format.",
   MODULE_PACK_REVISION_INVALID: "The source revision must be a full 40- or 64-character commit id.",
   MODULE_PACK_RUNTIME_UNKNOWN:
-    "The Node.js range could not be determined. Run inside an Ekklesia workspace, or pass one.",
+    "The module's package.json must declare the Node.js versions it supports in engines.node.",
   MODULE_PACK_SDK_INCOMPATIBLE:
     "The bundled Module SDK is outside the manifest's own compatibility.moduleSdk range.",
   MODULE_PACK_TARGET_UNSUPPORTED:
@@ -170,8 +170,7 @@ export interface PackModuleOptions {
   readonly sourceRevision: string;
   /** Informational only; recorded as given. */
   readonly repository?: string;
-  /** The Node.js range the package is built for. Defaults to the enclosing workspace's
+  /** The Node.js range the package is built for. Defaults to the module's own `engines.node`. */
-   * `engines.node`, the toolchain the module was built and tested with. */
   readonly nodeRange?: string;
   /** Reviewed license supplements (ADR 0052). Defaults to the ones this packager ships. */
   readonly supplementsDirectory?: string;
@@ -234,27 +233,16 @@ async function packagerIdentity(): Promise<{ readonly name: string; readonly ver
   return { name: String(manifest.name), version: String(manifest.version) };
 }
 
-async function workspaceNodeRange(moduleDirectory: string): Promise<string> {
+/** The Node.js range a module declares for itself, in its own package.json `engines.node` (ADR
-  let directory = moduleDirectory;
+ * 0053). Read from the module, never from an enclosing workspace: a standalone module repository has
-  for (;;) {
+ * none. */
-    try {
+function moduleNodeRange(developmentPackage: Readonly<Record<string, unknown>>): string {
-      await lstat(path.join(directory, "pnpm-workspace.yaml"));
+  const engines = developmentPackage.engines;
-      const manifest = await readJson(path.join(directory, "package.json"));
-      const engines = isRecord(manifest) ? manifest.engines : undefined;
   const range = isRecord(engines) ? engines.node : undefined;
-      if (typeof range === "string") {
+  if (typeof range !== "string" || range.trim() === "") {
-        return range;
-      }
-      break;
-    } catch {
-      const parent = path.dirname(directory);
-      if (parent === directory) {
-        break;
-      }
-      directory = parent;
-    }
-  }
     throw new ModulePackError("MODULE_PACK_RUNTIME_UNKNOWN");
+  }
+  return range;
 }
 
 /** `./dist/server/index.js` → `dist/server/index.js`, inside the module directory. */
@@ -537,7 +525,7 @@ export async function packModule(options: PackModuleOptions): Promise<ModulePack
     throw new ModulePackError("MODULE_PACK_MODULE_LICENSE_FILE_INVALID");
   }
 
-  const nodeRange = options.nodeRange ?? (await workspaceNodeRange(moduleDirectory));
+  const nodeRange = options.nodeRange ?? moduleNodeRange(developmentPackage);
   if (validRange(nodeRange) === null) {
     throw new ModulePackError("MODULE_PACK_RUNTIME_UNKNOWN");
   }
@@ -624,14 +612,17 @@ export async function packModule(options: PackModuleOptions): Promise<ModulePack
     if (bundled === undefined || bundled.root === moduleDirectory) {
       continue;
     }
-    if (!bundled.thirdParty) {
+    if (bundled.ekklesiaOwned) {
-      if (bundled.name.startsWith("@ekklesia/")) {
+      // An Ekklesia module-development package, recognized by its identity, not by where it was
+      // installed (ADR 0053): recorded under incorporates, never credited as third-party software.
       const known = incorporates.get(bundled.name);
       if (known !== undefined && known !== bundled.version) {
         throw new ModulePackError("MODULE_PACK_INCORPORATED_CONFLICT", bundled.name);
       }
       incorporates.set(bundled.name, bundled.version);
+      continue;
     }
+    if (!bundled.thirdParty) {
       continue;
     }
     if (use === "backend" && bundled.name === "drizzle-orm") {
@@ -657,6 +648,7 @@ export async function packModule(options: PackModuleOptions): Promise<ModulePack
         manifest: nativePackage.manifest,
         name: nativePackage.name,
         root: nativePackage.root,
+        ekklesiaOwned: false,
         thirdParty: true,
         version: nativePackage.version,
       },

packages/module-pack/src/packages.ts

@@ -3,18 +3,42 @@ import path from "node:path";
 
 /**
  * What the packager knows about a package whose files were bundled: where it is, what it is called,
- * and whether it is third-party software. A package installed under a `node_modules` directory is
+ * and whose code it is.
- * third-party; one that is not (a workspace package, or the module itself) is the platform's or the
+ *
- * module's own code.
+ * - **Ekklesia-owned** (`ekklesiaOwned`): it identifies itself as a published Ekklesia
+ *   module-development package (`isEkklesiaPackage`), wherever it was installed from: a workspace
+ *   link or a registry copy under `node_modules` (ADR 0053). It is recorded under `incorporates`,
+ *   never credited as third-party software.
+ * - **Third-party** (`thirdParty`): anything else installed under a `node_modules` directory.
+ * - Otherwise it is the module's own code, or a local package of the module's own repository.
  */
 export interface BundledPackage {
   readonly root: string;
   readonly name: string;
   readonly version: string;
+  readonly ekklesiaOwned: boolean;
   readonly thirdParty: boolean;
   readonly manifest: Readonly<Record<string, unknown>>;
 }
 
+/** The marker every published Ekklesia module-development package carries in its package.json. */
+export const EKKLESIA_PACKAGE_DISTRIBUTION = "module-development";
+
+/**
+ * Whether a package is an Ekklesia module-development package: its name is in the `@ekklesia` scope
+ * **and** its package.json says so explicitly (`"ekklesia": { "distribution": "module-development" }`).
+ * Neither a path nor a scope name alone is enough.
+ */
+export function isEkklesiaPackage(manifest: Readonly<Record<string, unknown>>): boolean {
+  const ekklesia = manifest.ekklesia;
+  return (
+    typeof manifest.name === "string" &&
+    manifest.name.startsWith("@ekklesia/") &&
+    isRecord(ekklesia) &&
+    ekklesia.distribution === EKKLESIA_PACKAGE_DISTRIBUTION
+  );
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -48,11 +72,13 @@ export class BundledPackageIndex {
       visited.push(directory);
       const manifest = await readManifest(directory);
       if (manifest && typeof manifest.name === "string" && typeof manifest.version === "string") {
+        const ekklesiaOwned = isEkklesiaPackage(manifest);
         found = Object.freeze({
+          ekklesiaOwned,
           manifest: Object.freeze(manifest),
           name: manifest.name,
           root: directory,
-          thirdParty: directory.split(path.sep).includes("node_modules"),
+          thirdParty: !ekklesiaOwned && directory.split(path.sep).includes("node_modules"),
           version: manifest.version,
         });
         break;

packages/module-pack/tests/fixtures/native-module/ekklesia.module.json

@@ -5,8 +5,8 @@
   "description": "A minimal native module: its backend uses sharp, so it packages for linux-x64-glibc.",
   "version": "0.1.0",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
   },
   "database": {
     "abi": 1

packages/module-pack/tests/native-target.test.ts

@@ -183,8 +183,8 @@ describe.runIf(onTargetHost)("the linux-x64-glibc target, proven with sharp", ()
         extractTo,
         platform: {
           databaseRuntime: { "drizzle-orm": "0.45.2" },
-          moduleSdkVersion: "0.1.2",
+          moduleSdkVersion: "0.2.0",
-          platformVersion: "0.1.2",
+          platformVersion: "0.2.0",
         },
       }),
     ).resolves.toMatchObject({ moduleId: "native-proof", target: "linux-x64-glibc" });

packages/module-pack/tests/pack-module.test.ts

@@ -23,7 +23,6 @@ async function pack(options: FixtureModuleOptions = {}, overrides: Record<string
   const result = await packModule({
     licenseFile: path.join(moduleDirectory, "LICENSE"),
     moduleDirectory,
-    nodeRange: ">=24.11.0 <25",
     outDirectory,
     sourceRevision: SOURCE_REVISION,
     target: "any",
@@ -379,6 +378,23 @@ describe("packModule: identity and inputs", () => {
     await packRejection({}, "MODULE_PACK_REVISION_INVALID", { sourceRevision: "86ae907" });
   });
 
+  it("takes the supported Node.js range from the module's own engines.node", async () => {
+    const { archive } = await pack({ engines: { node: ">=24.12.0 <25" } });
+    const metadata = JSON.parse(
+      fileEntries(archive).get("example/ekklesia.package.json")?.toString("utf8") ?? "",
+    );
+    expect(metadata.runtime).toEqual({ node: ">=24.12.0 <25" });
+  });
+
+  it("refuses a module that does not declare engines.node, without looking for a workspace", async () => {
+    for (const engines of [null, {}, { node: "" }, { node: 24 }]) {
+      const error = await packRejection({ engines }, "MODULE_PACK_RUNTIME_UNKNOWN");
+      expect(error.message).toBe(
+        "The module's package.json must declare the Node.js versions it supports in engines.node.",
+      );
+    }
+  });
+
   it("refuses an incorporated SDK outside the manifest's own range", async () => {
     await packRejection(
       {
@@ -392,6 +408,67 @@ describe("packModule: identity and inputs", () => {
   });
 });
 
+describe("packModule: recognising Ekklesia's packages by identity (ADR 0053)", () => {
+  async function metadataAndNotices(options: FixtureModuleOptions) {
+    const { archive } = await pack(options);
+    const files = fileEntries(archive);
+    return {
+      metadata: JSON.parse(files.get("example/ekklesia.package.json")?.toString("utf8") ?? ""),
+      notices: files.get("example/THIRD_PARTY_NOTICES")?.toString("utf8") ?? "",
+    };
+  }
+
+  it("incorporates registry-installed Ekklesia packages exactly as workspace-linked ones", async () => {
+    const options: FixtureModuleOptions = { databaseAbi: 1, withSchema: true };
+    const linked = await metadataAndNotices(options);
+    const installed = await metadataAndNotices({ ...options, ekklesiaInstall: "registry" });
+    expect(Object.keys(installed.metadata.incorporates).sort()).toEqual([
+      "@ekklesia/contracts",
+      "@ekklesia/module-database",
+      "@ekklesia/module-sdk",
+    ]);
+    expect(installed.metadata.incorporates).toEqual(linked.metadata.incorporates);
+    // Never credited as third-party code, however they were installed.
+    expect(installed.notices).not.toContain("@ekklesia/");
+    expect(linked.notices).not.toContain("@ekklesia/");
+  });
+
+  it("still checks a registry-installed SDK against the manifest's moduleSdk range", async () => {
+    await packRejection(
+      {
+        ekklesiaInstall: "registry",
+        manifest: (manifest) => ({
+          ...manifest,
+          compatibility: { platform: "^0.1.0", moduleSdk: "^9.0.0" },
+        }),
+      },
+      "MODULE_PACK_SDK_INCOMPATIBLE",
+    );
+  });
+
+  it("treats a package that only borrows the @ekklesia scope, or only the marker, as third-party", async () => {
+    const { metadata, notices } = await metadataAndNotices({
+      fakePackages: [
+        {
+          files: { "index.js": "export default 1;\n", LICENSE: MIT },
+          name: "@ekklesia/squatter",
+          packageJson: { ekklesia: { layer: "package" } },
+        },
+        {
+          files: { "index.js": "export default 2;\n", LICENSE: MIT },
+          name: "not-ekklesia",
+          packageJson: { ekklesia: { distribution: "module-development" } },
+        },
+      ],
+      serverSource:
+        'import a from "@ekklesia/squatter";\nimport b from "not-ekklesia";\nexport default { id: "example", version: "0.1.0", register() { return a + b; } };\n',
+    });
+    expect(metadata.incorporates).toEqual({});
+    expect(notices).toContain("\n@ekklesia/squatter 1.0.0\nLicense: MIT\n");
+    expect(notices).toContain("\nnot-ekklesia 1.0.0\nLicense: MIT\n");
+  });
+});
+
 describe("packModule: THIRD_PARTY_NOTICES", () => {
   const usesFake = (name: string) =>
     `import value from "${name}";\nexport default { id: "example", version: "0.1.0", register() { return value; } };\n`;

packages/module-pack/tests/support/fixture-module.ts

@@ -1,4 +1,14 @@
-import { cp, mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import {
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -30,6 +40,12 @@ export interface FixtureModuleOptions {
   readonly serverSource?: string;
   readonly withModuleDatabase?: boolean;
   readonly withSchema?: boolean;
+  /** The module's `engines` field; omitted from `package.json` when `null`. */
+  readonly engines?: Record<string, unknown> | null;
+  /** How the module's `@ekklesia/*` dependencies are installed: linked to this workspace's packages
+   * (the default), or copied as real directories into a flat `node_modules`, as a registry install
+   * lays them out. */
+  readonly ekklesiaInstall?: "workspace" | "registry";
   readonly fakePackages?: readonly FakePackage[];
   readonly manifest?: (manifest: Record<string, unknown>) => Record<string, unknown>;
 }
@@ -63,12 +79,9 @@ const defaultServer = (
 export default defineModuleRuntime({ ${databaseAbi === 1 ? "database: { abi: 1 }, " : ""}id: ${JSON.stringify(id)}, version: ${JSON.stringify(version)}, register() {} });
 `;
 
-const schemaSource = (id: string, databaseAbi?: 1) => `${
+const schemaSource = (id: string, databaseAbi?: 1) => `import { createModuleTable${
-  databaseAbi === 1
+  databaseAbi === 1 ? ", moduleDrizzleSchemaMetadata" : ""
-    ? 'import { moduleDrizzleSchemaMetadata } from "@ekklesia/module-database/drizzle";'
+} } from "@ekklesia/module-database/drizzle";
-    : 'import { defineModuleSchema } from "@ekklesia/module-sdk";'
-}
-import { createModuleTable } from "@ekklesia/module-sdk";
 import { text, uuid } from "drizzle-orm/pg-core";
 export const records = createModuleTable(${JSON.stringify(id)})("records", {
   id: uuid("id").primaryKey(),
@@ -77,7 +90,7 @@ export const records = createModuleTable(${JSON.stringify(id)})("records", {
 export default ${
   databaseAbi === 1
     ? `moduleDrizzleSchemaMetadata(${JSON.stringify(id)}, { records })`
-    : `defineModuleSchema({ moduleId: ${JSON.stringify(id)}, tables: { records } })`
+    : `{ moduleId: ${JSON.stringify(id)}, tables: { records } }`
 };
 `;
 
@@ -87,14 +100,16 @@ export async function fixtureModule(options: FixtureModuleOptions = {}): Promise
   const root = await scratchDirectory("ekklesia-pack-fixture-");
   const moduleDirectory = path.join(root, id);
   const tableName = `${id.replaceAll("-", "_")}_records`;
-  const usesModuleDatabase = options.withModuleDatabase || options.databaseAbi === 1;
+  const usesModuleDatabase =
+    options.withModuleDatabase || options.withSchema || options.databaseAbi === 1;
+  const engines = options.engines === undefined ? { node: ">=24.11.0 <25" } : options.engines;
 
   const baseManifest: Record<string, unknown> = {
     manifestVersion: 8,
     id,
     name: `${id} module`,
     version,
-    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
+    compatibility: { platform: "^0.2.0", moduleSdk: "^0.2.0" },
     ...(options.databaseAbi === 1 ? { database: { abi: 1 } } : {}),
     capabilities: [],
     permissions: [],
@@ -119,6 +134,7 @@ export async function fixtureModule(options: FixtureModuleOptions = {}): Promise
         license: Object.hasOwn(options, "license") ? options.license : "MIT",
         private: true,
         type: "module",
+        ...(engines === null ? {} : { engines }),
         scripts: { build: "tsc" },
         dependencies: {
           "@ekklesia/module-sdk": "workspace:*",
@@ -185,19 +201,24 @@ export async function fixtureModule(options: FixtureModuleOptions = {}): Promise
     }),
   );
 
-  // The module's dependencies, as a workspace links them: the real packages this package depends on.
+  // The module's dependencies: the real packages this package depends on, either linked as a
+  // workspace links them, or copied as a registry install would place them.
   const modules = path.join(moduleDirectory, "node_modules");
   await mkdir(path.join(modules, "@ekklesia"), { recursive: true });
+  const ekklesiaPackages = [
+    "module-sdk",
+    ...(usesModuleDatabase ? ["module-database"] : []),
+  ] as const;
+  if (options.ekklesiaInstall === "registry") {
+    await installLikeARegistry(modules, [...ekklesiaPackages, "contracts"]);
+  } else {
+    for (const name of ekklesiaPackages) {
       await symlink(
-    await realpath(path.join(packageRoot, "node_modules", "@ekklesia", "module-sdk")),
+        await realpath(path.join(packageRoot, "node_modules", "@ekklesia", name)),
-    path.join(modules, "@ekklesia", "module-sdk"),
+        path.join(modules, "@ekklesia", name),
-  );
-  if (usesModuleDatabase) {
-    await symlink(
-      await realpath(path.join(packageRoot, "node_modules", "@ekklesia", "module-database")),
-      path.join(modules, "@ekklesia", "module-database"),
       );
     }
+  }
   await symlink(
     await realpath(path.join(packageRoot, "node_modules", "drizzle-orm")),
     path.join(modules, "drizzle-orm"),
@@ -222,6 +243,45 @@ export async function fixtureModule(options: FixtureModuleOptions = {}): Promise
   return moduleDirectory;
 }
 
+/**
+ * Copies each `@ekklesia/*` package's published files (`package.json`, `dist`, `LICENSE`) into a flat
+ * `node_modules` as real directories, and links the third-party packages they depend on beside them:
+ * the layout a registry install produces, with nothing pointing back into the workspace's sources.
+ */
+async function installLikeARegistry(modules: string, names: readonly string[]): Promise<void> {
+  for (const name of names) {
+    const source = await realpath(path.join(packageRoot, "..", name));
+    const target = path.join(modules, "@ekklesia", name);
+    await mkdir(target, { recursive: true });
+    for (const entry of ["package.json", "dist", "LICENSE"]) {
+      await cp(path.join(source, entry), path.join(target, entry), {
+        force: false,
+        recursive: true,
+      }).catch((error: NodeJS.ErrnoException) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+    const manifest = JSON.parse(
+      await readFile(path.join(source, "package.json"), "utf8"),
+    ) as Record<string, Record<string, string> | undefined>;
+    for (const dependency of Object.keys(manifest.dependencies ?? {})) {
+      const link = path.join(modules, ...dependency.split("/"));
+      if (dependency.startsWith("@ekklesia/") || (await exists(link))) continue;
+      await mkdir(path.dirname(link), { recursive: true });
+      await symlink(await realpath(path.join(source, "node_modules", dependency)), link);
+    }
+  }
+}
+
+async function exists(file: string): Promise<boolean> {
+  try {
+    await lstat(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export const SOURCE_REVISION = "86ae907f59458508e3277666cdd214f5bd7c1078";
 
 const nativeFixtureSource = path.join(packageRoot, "tests", "fixtures", "native-module");

packages/module-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/module-sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -15,13 +15,11 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-sdk",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@ekklesia/contracts": "workspace:*",
+    "@ekklesia/contracts": "workspace:*"
-    "drizzle-orm": "0.45.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
@@ -30,9 +28,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "module-sdk"
+    "layer": "module-sdk",
-  },
+    "distribution": "module-development"
-  "peerDependencies": {
-    "drizzle-orm": "0.45.2"
   }
 }

packages/module-sdk/src/define-module-runtime.ts

@@ -1,18 +1,69 @@
 import {
-  type LegacyModuleRuntimeDefinition,
+  type Awaitable,
+  type CapabilityRegistrar,
+  type CapabilityResolver,
+  type ModuleRegistrationContext as ContractModuleRegistrationContext,
+  type ModuleRuntimeContext as ContractModuleRuntimeContext,
+  type ModuleRuntimeServices as ContractModuleRuntimeServices,
+  type ModuleConfiguration,
   type ModuleDatabaseAbiRuntimeDefinition,
-  type ModuleRuntimeDefinition,
+  type ModuleDatabaseExecutor,
+  type ModuleId,
   parseModuleRuntimeDefinition,
 } from "@ekklesia/contracts";
 
-export function defineModuleRuntime<const Definition extends ModuleDatabaseAbiRuntimeDefinition>(
+/**
-  definition: Definition,
+ * What a module's `register` hook receives. `Database` is what `services.database` is for the
-): Readonly<Definition>;
+ * module: the Module Database ABI v1 executor when it declares `database: { abi: 1 }`, and `never`
-export function defineModuleRuntime<const Definition extends LegacyModuleRuntimeDefinition>(
+ * when it declares no database, so code cannot reach a database it never declared.
-  definition: Definition,
+ */
-): Readonly<Definition>;
+export type ModuleRegistrationContext<
-export function defineModuleRuntime<const Definition extends ModuleRuntimeDefinition>(
+  Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor,
-  definition: Definition,
+> = ContractModuleRegistrationContext<Database>;
-): Readonly<Definition> {
+
-  return parseModuleRuntimeDefinition(definition) as Readonly<Definition>;
+/** What a module's `start` and `stop` hooks receive. */
+export type ModuleRuntimeContext<Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor> =
+  ContractModuleRuntimeContext<Database>;
+
+/** The platform services every hook and handler receives. `database` is the ABI v1 executor for a
+ * module that declares one, and `never` otherwise. */
+export type ModuleRuntimeServices<
+  Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor,
+> = ContractModuleRuntimeServices<Database>;
+
+/** A module that declares the Module Database ABI v1 (ADR 0050). Its hooks and route handlers see
+ * `services.database` as the ABI v1 executor. */
+export interface ModuleRuntimeDefinitionWithDatabase extends ModuleDatabaseAbiRuntimeDefinition {}
+
+/** A module that uses no database. Its hooks see `services.database` as `never`. */
+export interface ModuleRuntimeDefinitionWithoutDatabase {
+  readonly id: ModuleId;
+  readonly version: string;
+  readonly database?: never;
+  readonly register?: (context: ModuleRegistrationContext<never>) => Awaitable<void>;
+  readonly start?: (context: ModuleRuntimeContext<never>) => Awaitable<void>;
+  readonly stop?: (context: ModuleRuntimeContext<never>) => Awaitable<void>;
 }
+
+/** Every runtime definition the Module SDK supports. The legacy Drizzle database facade is not one
+ * of them: a module that uses a database declares `database: { abi: 1 }` (ADR 0053). */
+export type ModuleRuntimeDefinition =
+  | ModuleRuntimeDefinitionWithDatabase
+  | ModuleRuntimeDefinitionWithoutDatabase;
+
+/**
+ * Validates and freezes a module's server runtime. The result is typed as one of this package's own
+ * named interfaces, so a module that emits declarations can always name its runtime's type through
+ * `@ekklesia/module-sdk`, without depending on the packages behind it.
+ */
+export function defineModuleRuntime(
+  definition: ModuleRuntimeDefinitionWithDatabase,
+): ModuleRuntimeDefinitionWithDatabase;
+export function defineModuleRuntime(
+  definition: ModuleRuntimeDefinitionWithoutDatabase,
+): ModuleRuntimeDefinitionWithoutDatabase;
+export function defineModuleRuntime(definition: ModuleRuntimeDefinition): ModuleRuntimeDefinition {
+  return parseModuleRuntimeDefinition(definition) as ModuleRuntimeDefinition;
+}
+
+export type { Awaitable, CapabilityRegistrar, CapabilityResolver, ModuleConfiguration };

packages/module-sdk/src/define-module-schema.ts

@@ -1,19 +0,0 @@
-import {
-  type ModuleId,
-  type ModuleSchemaDefinition,
-  moduleTableName,
-  moduleTablePrefix,
-  parseModuleSchemaDefinition,
-} from "@ekklesia/contracts";
-import { pgTableCreator } from "drizzle-orm/pg-core";
-
-export function createModuleTable(moduleId: ModuleId) {
-  moduleTablePrefix(moduleId);
-  return pgTableCreator((localName) => moduleTableName(moduleId, localName));
-}
-
-export function defineModuleSchema<const Definition extends ModuleSchemaDefinition>(
-  definition: Definition,
-): Readonly<Definition> {
-  return parseModuleSchemaDefinition(definition) as Readonly<Definition>;
-}

packages/module-sdk/src/http.ts

@@ -0,0 +1,24 @@
+import type {
+  ModuleHttpRouteRegistrar as ContractModuleHttpRouteRegistrar,
+  ModuleRouteDefinitionInput as ContractModuleRouteDefinitionInput,
+  ModuleRouteHandler as ContractModuleRouteHandler,
+  ModuleRouteHandlerContext as ContractModuleRouteHandlerContext,
+  ModuleDatabaseExecutor,
+} from "@ekklesia/contracts";
+
+/** What a route handler receives. `services.database` is the module's ABI v1 executor, or `never`
+ * for a module that declares no database. */
+export type ModuleRouteHandlerContext<
+  Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor,
+> = ContractModuleRouteHandlerContext<Database>;
+
+export type ModuleRouteHandler<Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor> =
+  ContractModuleRouteHandler<Database>;
+
+export type ModuleRouteDefinitionInput<
+  Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor,
+> = ContractModuleRouteDefinitionInput<Database>;
+
+export type ModuleHttpRouteRegistrar<
+  Database extends ModuleDatabaseExecutor = ModuleDatabaseExecutor,
+> = ContractModuleHttpRouteRegistrar<Database>;

packages/module-sdk/src/index.ts

@@ -1,3 +1,102 @@
-export * from "@ekklesia/contracts";
+/**
-export * from "./define-module-runtime.js";
+ * `@ekklesia/module-sdk`: the supported module-author API (ADR 0053).
-export * from "./define-module-schema.js";
+ *
+ * Every export is chosen. The platform's internal contracts (identity parsing, authorization,
+ * lifecycle, manifest internals beyond what a module validates about itself) are not re-exported,
+ * and neither is the legacy Drizzle database facade. A module that uses a database declares
+ * `database: { abi: 1 }` and gets its database types and helpers from `@ekklesia/module-database`.
+ * Nothing here loads or requires Drizzle.
+ */
+
+export type {
+  Awaitable,
+  CapabilityId,
+  CapabilityRegistrar,
+  CapabilityResolver,
+  ModuleId,
+  RegisteredCapability,
+} from "@ekklesia/contracts";
+// HTTP routes (ADR 0015, ADR 0042).
+// Who is calling (ADR 0013, ADR 0036): only what a route handler receives and branches on.
+// Configuration (ADR 0029).
+// Object storage (ADR 0030, ADR 0031).
+// Realtime (ADR 0032).
+// The module's own static artifacts, for a module's tests to validate them the way Core does.
+export {
+  ANONYMOUS_PRINCIPAL,
+  type EkklesiaAnonymousPrincipal,
+  type EkklesiaAuthenticatedPrincipal,
+  type EkklesiaDeviceId,
+  type EkklesiaDevicePrincipal,
+  type EkklesiaPrincipal,
+  type EkklesiaUserId,
+  EMPTY_MODULE_CONFIGURATION,
+  EMPTY_MODULE_STORAGE,
+  isAnonymousPrincipal,
+  isAuthenticatedPrincipal,
+  isDevicePrincipal,
+  isModuleHttpMethod,
+  isModuleRouteBodyMode,
+  isValidModuleStorageKey,
+  isValidModuleStorageReadUrlFilename,
+  MODULE_HTTP_BODY_MODES,
+  MODULE_HTTP_METHODS,
+  MODULE_REALTIME_CHANNEL_MAX_LENGTH,
+  MODULE_REALTIME_ERROR_CODES,
+  MODULE_REALTIME_MAX_CHANNELS_PER_MODULE,
+  MODULE_REALTIME_MAX_PAYLOAD_BYTES,
+  MODULE_REALTIME_MAX_SUBSCRIBERS_PER_CHANNEL,
+  MODULE_ROUTE_ABSOLUTE_MAX_BODY_BYTES,
+  MODULE_ROUTE_MAX_BODY_BYTES_CEILING,
+  MODULE_ROUTE_STREAMED_MAX_BODY_BYTES_CEILING,
+  MODULE_STORAGE_ERROR_CODES,
+  MODULE_STORAGE_KEY_MAX_BYTES,
+  MODULE_STORAGE_READ_URL_DEFAULT_SECONDS,
+  MODULE_STORAGE_READ_URL_FILENAME_MAX_LENGTH,
+  MODULE_STORAGE_READ_URL_MAX_SECONDS,
+  MODULE_STORAGE_READ_URL_MIN_SECONDS,
+  type ModuleConfiguration,
+  type ModuleConfigurationValue,
+  type ModuleHttpMethod,
+  type ModuleManifest,
+  type ModuleRealtimeChannel,
+  type ModuleRealtimeChannelDefinitionInput,
+  type ModuleRealtimeChannelRegistrar,
+  ModuleRealtimeError,
+  type ModuleRealtimeErrorCode,
+  type ModuleRealtimeJsonPrimitive,
+  type ModuleRealtimeJsonValue,
+  type ModuleRealtimePublisher,
+  type ModuleRouteBodyMode,
+  type ModuleRoutePath,
+  type ModuleStorage,
+  type ModuleStorageBody,
+  type ModuleStorageBucket,
+  ModuleStorageError,
+  type ModuleStorageErrorCode,
+  type ModuleStorageListing,
+  type ModuleStorageListOptions,
+  type ModuleStorageObject,
+  type ModuleStorageObjectMetadata,
+  type ModuleStoragePutOptions,
+  type ModuleStorageReadUrl,
+  type ModuleStorageReadUrlOptions,
+  parseDrizzleMigrationJournal,
+  parseModuleManifest,
+  parseModuleMigrationPolicy,
+} from "@ekklesia/contracts";
+export {
+  defineModuleRuntime,
+  type ModuleRegistrationContext,
+  type ModuleRuntimeContext,
+  type ModuleRuntimeDefinition,
+  type ModuleRuntimeDefinitionWithDatabase,
+  type ModuleRuntimeDefinitionWithoutDatabase,
+  type ModuleRuntimeServices,
+} from "./define-module-runtime.js";
+export type {
+  ModuleHttpRouteRegistrar,
+  ModuleRouteDefinitionInput,
+  ModuleRouteHandler,
+  ModuleRouteHandlerContext,
+} from "./http.js";

packages/module-sdk/tests/define-module-runtime.test.ts

@@ -6,10 +6,12 @@ import {
   MODULE_HTTP_METHODS,
   type ModuleHttpRouteRegistrar,
   type ModuleRegistrationContext,
+  type ModuleRuntimeDefinitionWithDatabase,
+  type ModuleRuntimeDefinitionWithoutDatabase,
 } from "../src/index.js";
 
 describe("defineModuleRuntime", () => {
-  it("types each database mode without exposing a legacy-or-ABI union", () => {
+  it("types the ABI executor for a database module, and no database at all otherwise", () => {
     defineModuleRuntime({
       database: { abi: 1 },
       id: "example",
@@ -35,16 +37,27 @@ describe("defineModuleRuntime", () => {
     });
 
     defineModuleRuntime({
-      id: "legacy",
+      id: "no-database",
       version: "0.1.0",
       start({ services }) {
-        expectTypeOf(services.database.select).toBeFunction();
+        // The SDK never types the legacy Drizzle facade (ADR 0053): a module without the ABI has
-        // @ts-expect-error Legacy modules do not receive the ABI executor.
+        // no database to reach.
-        services.database.abiVersion;
+        expectTypeOf(services.database).toBeNever();
       },
     });
   });
 
+  it("types the result as the SDK's own named interfaces, so a module's declarations can name it", () => {
+    // A module that emits declarations names its default export's type; with an inferred literal
+    // type that would reach into packages a standalone module does not depend on directly.
+    expectTypeOf(
+      defineModuleRuntime({ database: { abi: 1 }, id: "example", version: "0.1.0" }),
+    ).toEqualTypeOf<ModuleRuntimeDefinitionWithDatabase>();
+    expectTypeOf(
+      defineModuleRuntime({ id: "example", version: "0.1.0" }),
+    ).toEqualTypeOf<ModuleRuntimeDefinitionWithoutDatabase>();
+  });
+
   it("defines a frozen server runtime without duplicating the static manifest", async () => {
     const start = vi.fn();
     const runtime = defineModuleRuntime({

packages/module-ui-build/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/module-ui-build",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -19,7 +19,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-ui-build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
@@ -34,6 +33,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "tooling"
+    "layer": "tooling",
+    "distribution": "module-development"
   }
 }

packages/module-ui-host/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@ekklesia/module-ui-host",
-  "version": "0.1.2",
+  "version": "0.2.0",
+  "private": true,
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -15,7 +16,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-ui-host",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json"
   },

packages/module-ui-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/module-ui-sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -15,7 +15,6 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/module-ui-sdk",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json"
   },
@@ -26,6 +25,7 @@
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "module-ui-sdk"
+    "layer": "module-ui-sdk",
+    "distribution": "module-development"
   }
 }

packages/module-ui-sdk/tests/browser-safety.test.ts

@@ -11,9 +11,9 @@ async function sourceFiles(): Promise<string[]> {
 }
 
 /**
- * This package is bundled into a browser. `@ekklesia/module-sdk` re-exports all of
+ * This package is bundled into a browser. `@ekklesia/module-sdk` is built on `@ekklesia/contracts`,
- * `@ekklesia/contracts`, which pulls Zod, Drizzle, and semver behind one barrel export, so a single
+ * which pulls Zod and semver behind one barrel export, so a single value import from a backend
- * value import from a backend package here would drag that whole graph into every module UI bundle
+ * package here would drag that whole graph into every module UI bundle
  * (ADR 0022). ADR 0024 removed even the former type-only contracts dependency because its type graph
  * leaked Node globals into browser programs; this package must remain completely dependency-free.
  */

packages/typescript-config/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@ekklesia/typescript-config",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
-  "private": true,
   "files": [
     "base.json",
     "browser-react.json",
@@ -18,6 +17,7 @@
     "./react-native.json": "./react-native.json"
   },
   "ekklesia": {
-    "layer": "tooling"
+    "layer": "tooling",
+    "distribution": "module-development"
   }
 }

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/ui",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -15,16 +15,14 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "lint": "biome lint .",
-    "prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/ui",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.test.json"
   },
   "dependencies": {
-    "@ekklesia/design-tokens": "workspace:*",
+    "@ekklesia/design-tokens": "workspace:*"
-    "react": "19.2.8"
   },
   "peerDependencies": {
-    "react": "19.2.8"
+    "react": "^19.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.3",
@@ -33,11 +31,13 @@
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
     "happy-dom": "20.0.11",
+    "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "7.0.2",
     "vitest": "4.1.10"
   },
   "ekklesia": {
-    "layer": "ui"
+    "layer": "ui",
+    "distribution": "module-development"
   }
 }

packages/ui/tests/tokens.test.ts

@@ -65,13 +65,18 @@ describe("the shared elements consume design tokens, never hardcoded theme value
   it("depends only on the design tokens and React", async () => {
     const manifest = JSON.parse(
       await readFile(path.join(packageDirectory, "package.json"), "utf8"),
-    ) as { dependencies?: Record<string, string>; peerDependencies?: Record<string, string> };
+    ) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      peerDependencies?: Record<string, string>;
+    };
 
-    // React is both a production dependency and a peer: the peer states that the consumer's React
+    // React is a peer only (ADR 0053): the consumer's React is the one in every bundle these
-    // must be the same one, and the production declaration is what makes the package's own imports
+    // elements are built into. The development dependency resolves the package's own imports for its
-    // resolve, since a consumer never satisfies a linked workspace package's peer
+    // builds and tests; nothing loads it from this workspace in a production Node.js process
-    // (`runtime-imports-are-production-dependencies`).
+    // (`runtime-imports-are-production-dependencies` allows exactly this peer).
-    expect(Object.keys(manifest.dependencies ?? {})).toEqual(["@ekklesia/design-tokens", "react"]);
+    expect(Object.keys(manifest.dependencies ?? {})).toEqual(["@ekklesia/design-tokens"]);
+    expect(manifest.devDependencies?.react).toBeDefined();
     expect(Object.keys(manifest.peerDependencies ?? {})).toEqual(["react"]);
   });
 

pnpm-lock.yaml

@@ -149,9 +149,6 @@ importers:
 
   packages/contracts:
     dependencies:
-      drizzle-orm:
-        specifier: 0.45.2
-        version: 0.45.2(@types/[email protected])([email protected])([email protected])
       semver:
         specifier: 7.8.5
         version: 7.8.5
@@ -278,9 +275,6 @@ importers:
       '@ekklesia/contracts':
         specifier: workspace:*
         version: link:../contracts
-      drizzle-orm:
-        specifier: 0.45.2
-        version: 0.45.2(@types/[email protected])([email protected])([email protected])
     devDependencies:
       '@biomejs/biome':
         specifier: 2.5.3
@@ -364,9 +358,6 @@ importers:
       '@ekklesia/design-tokens':
         specifier: workspace:*
         version: link:../design-tokens
-      react:
-        specifier: 19.2.8
-        version: 19.2.8
     devDependencies:
       '@biomejs/biome':
         specifier: 2.5.3
@@ -386,6 +377,9 @@ importers:
       happy-dom:
         specifier: 20.0.11
         version: 20.0.11
+      react:
+        specifier: 19.2.8
+        version: 19.2.8
       react-dom:
         specifier: 19.2.8
         version: 19.2.8([email protected])

scripts/check-boundaries.ts

@@ -149,13 +149,17 @@ const DEPENDENCY_FIELDS = [
 ] as const;
 
 /**
- * Runtime peers whose identity is deliberately supplied by the final consumer. The sole entry is
+ * Runtime peers whose identity is deliberately supplied by the final consumer, and which no
- * the module-side Drizzle adapter: a module chooses and bundles its own compatible Drizzle runtime,
+ * production Node.js process loads from this workspace. The module-side Drizzle adapter: a module
- * while Core must never select one for it. Keep this exception package-and-dependency specific;
+ * chooses and bundles its own compatible Drizzle runtime, while Core must never select one for it.
- * ordinary workspace packages still need production dependencies for runtime imports.
+ * And the shared UI elements' React (ADR 0053): `@ekklesia/ui` is only ever bundled into browser
+ * artifacts, by the shell's build and by module UI builds, and the consumer's own React must be the
+ * one in that bundle. Keep this exception package-and-dependency specific; ordinary workspace
+ * packages still need production dependencies for runtime imports.
  */
 const CONSUMER_SELECTED_RUNTIME_PEERS = new Map<string, ReadonlySet<string>>([
   ["@ekklesia/module-database", new Set(["drizzle-orm"])],
+  ["@ekklesia/ui", new Set(["react"])],
 ]);
 const SHARED_PACKAGE_ROLES = new Set([
   "api-client",

scripts/lib/pack-hooks.cjs

@@ -0,0 +1,56 @@
+// pnpm hooks for packing the public package train, and nothing else: passed to `pnpm pack` with
+// `--pnpmfile` by scripts/package-release.ts, never installed as the workspace's .pnpmfile.cjs, so
+// installs and the lockfile are unaffected.
+//
+// `beforePacking` runs after pnpm has rewritten `workspace:` ranges into exact versions, and does two
+// things to the packed package.json only:
+//
+// - It drops `devDependencies`. A consumer never installs them, and a tooling package's test-only
+//   development dependencies name private workspace packages (Core, the module template) that are
+//   not part of the public package train.
+// - It puts every remaining dependency map back in the source package.json's own key order. pnpm
+//   rewrites `workspace:` ranges concurrently and inserts each entry as its lookup resolves, so two
+//   packs of the same commit could order those keys differently, the one difference that made
+//   otherwise byte-identical tarballs differ. No name or range changes.
+"use strict";
+
+const { readFileSync } = require("node:fs");
+const path = require("node:path");
+
+const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "optionalDependencies",
+  "peerDependencies",
+  "peerDependenciesMeta",
+];
+
+function inSourceOrder(packed, source) {
+  if (
+    packed === null ||
+    typeof packed !== "object" ||
+    source === null ||
+    typeof source !== "object"
+  ) {
+    return packed;
+  }
+  const ordered = {};
+  for (const key of Object.keys(source)) {
+    if (Object.hasOwn(packed, key)) ordered[key] = packed[key];
+  }
+  for (const key of Object.keys(packed)) {
+    if (!Object.hasOwn(ordered, key)) ordered[key] = packed[key];
+  }
+  return ordered;
+}
+
+function beforePacking(manifest, directory) {
+  const source = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8"));
+  const packed = { ...manifest };
+  delete packed.devDependencies;
+  for (const field of DEPENDENCY_FIELDS) {
+    if (packed[field] !== undefined) packed[field] = inSourceOrder(packed[field], source[field]);
+  }
+  return packed;
+}
+
+module.exports = { hooks: { beforePacking }, inSourceOrder };

scripts/lib/pack-hooks.d.cts

@@ -0,0 +1,8 @@
+/** Types for `pack-hooks.cjs`, the pnpm hooks applied to `pnpm pack` by scripts/package-release.ts. */
+type Manifest = Record<string, unknown>;
+
+export declare const hooks: {
+  beforePacking(manifest: Manifest, directory: string): Manifest;
+};
+
+export declare function inSourceOrder(packed: unknown, source: unknown): unknown;

scripts/lib/package-registry.compose.yaml

@@ -0,0 +1,25 @@
+# A disposable Gitea, the same version as the real one, whose npm registry the package publication
+# tests run against (scripts/test-package-publication.sh). Never the real registry: it starts empty,
+# keeps everything in the container, and is removed with its volumes when the test ends.
+services:
+  gitea:
+    image: docker.gitea.com/gitea:1.27.2@sha256:d20286ca2b2e170fdf628e7231b8a31a3220ade39ff462b55041d43d1fc757dd
+    environment:
+      GITEA__security__INSTALL_LOCK: "true"
+      GITEA__database__DB_TYPE: sqlite3
+      # The URL clients reach it by: package metadata names tarballs under it.
+      GITEA__server__ROOT_URL: ${GITEA_ROOT_URL:?GITEA_ROOT_URL is required}
+      GITEA__server__HTTP_PORT: "3000"
+      GITEA__server__OFFLINE_MODE: "true"
+      GITEA__service__DISABLE_REGISTRATION: "true"
+      GITEA__packages__ENABLED: "true"
+      GITEA__actions__ENABLED: "false"
+      GITEA__mailer__ENABLED: "false"
+      GITEA__log__LEVEL: warn
+    ports:
+      - "127.0.0.1:${GITEA_PORT:?GITEA_PORT is required}:3000"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/healthz"]
+      interval: 2s
+      timeout: 3s
+      retries: 60

scripts/package-release.ts

@@ -0,0 +1,622 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+/**
+ * The public package release train (ADR 0053): the canonical way to produce the exact
+ * `@ekklesia/*` package tarballs of one platform release. It publishes nothing.
+ *
+ *   node scripts/package-release.ts --out <directory> [--allow-modified]
+ *
+ * From a clean source tree, it removes the public packages' build output, rebuilds them without the
+ * build cache, packs each with `pnpm pack`, inspects every tarball, and only when everything passed
+ * writes the release directory `<directory>/ekklesia-packages-<version>/`:
+ *
+ *   ekklesia-<name>-<version>.tgz        one per public package, exactly the expected set
+ *   SHA256SUMS                          `sha256sum -c` compatible
+ *   ekklesia-package-train.json         the release manifest (`packageTrainManifest`)
+ *
+ * Those files are what a future registry publication step publishes, unchanged, after checking them
+ * against the manifest. `--allow-modified` builds from a source tree with uncommitted changes, for
+ * local development only; the manifest then says so, and such a release must never be published.
+ */
+
+const execFileAsync = promisify(execFile);
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+/** pnpm hooks applied to `pnpm pack` only (see the file itself). */
+const PACK_HOOKS = path.join(repositoryRoot, "scripts", "lib", "pack-hooks.cjs");
+
+export type PublicPackageRole = "author-api" | "tooling" | "pre-1.0" | "implementation";
+
+export interface PublicPackage {
+  readonly name: string;
+  /** Relative to the repository root. */
+  readonly directory: string;
+  readonly role: PublicPackageRole;
+}
+
+/** ADR 0053's public set. Every other workspace package is private and never published. */
+export const PUBLIC_PACKAGES: readonly PublicPackage[] = Object.freeze([
+  { directory: "packages/module-sdk", name: "@ekklesia/module-sdk", role: "author-api" },
+  { directory: "packages/module-database", name: "@ekklesia/module-database", role: "author-api" },
+  { directory: "packages/module-ui-sdk", name: "@ekklesia/module-ui-sdk", role: "author-api" },
+  { directory: "packages/design-tokens", name: "@ekklesia/design-tokens", role: "author-api" },
+  { directory: "packages/module-ui-build", name: "@ekklesia/module-ui-build", role: "tooling" },
+  { directory: "packages/module-pack", name: "@ekklesia/module-pack", role: "tooling" },
+  {
+    directory: "packages/typescript-config",
+    name: "@ekklesia/typescript-config",
+    role: "tooling",
+  },
+  { directory: "packages/ui", name: "@ekklesia/ui", role: "pre-1.0" },
+  // A dependency of the packages above, never a supported direct module-author dependency.
+  { directory: "packages/contracts", name: "@ekklesia/contracts", role: "implementation" },
+]);
+
+/** `ekklesia.distribution` in a public package's manifest: the identity the canonical packager
+ * recognizes an installed Ekklesia package by (`packages/module-pack/src/packages.ts`). */
+export const PUBLIC_PACKAGE_DISTRIBUTION = "module-development";
+
+/** The release manifest's file name, and its format version. */
+export const PACKAGE_TRAIN_MANIFEST = "ekklesia-package-train.json";
+export const PACKAGE_TRAIN_FORMAT = 1;
+
+/** `@ekklesia/module-sdk` → `ekklesia-module-sdk-<version>.tgz`, the name `pnpm pack` writes. */
+export function tarballName(name: string, version: string): string {
+  return `${name.replace(/^@/u, "").replace("/", "-")}-${version}.tgz`;
+}
+
+/** The directory one release's artifacts are written to, inside `--out`. */
+export function releaseDirectoryName(version: string): string {
+  return `ekklesia-packages-${version}`;
+}
+
+/** Scripts a package manager runs on a consumer's machine when it installs, packs, or publishes. */
+const LIFECYCLE_SCRIPTS = Object.freeze([
+  "preinstall",
+  "install",
+  "postinstall",
+  "prepare",
+  "prepack",
+  "postpack",
+  "prepublish",
+  "prepublishOnly",
+  "publish",
+  "postpublish",
+]);
+
+const DEPENDENCY_FIELDS = Object.freeze([
+  "dependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "devDependencies",
+]);
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * What is wrong with a packed `package.json`, or nothing. `source` is the package's own source
+ * manifest, when there is one to compare with: a packed dependency map must keep its key order.
+ */
+export function packedManifestProblems(
+  manifest: Readonly<Record<string, unknown>>,
+  expected: { readonly name: string; readonly version: string },
+  source?: Readonly<Record<string, unknown>>,
+): string[] {
+  const problems: string[] = [];
+  if (manifest.name !== expected.name) problems.push(`is named ${String(manifest.name)}`);
+  if (manifest.version !== expected.version) {
+    problems.push(
+      `has version ${String(manifest.version)}, not the coordinated ${expected.version}`,
+    );
+  }
+  if (manifest.private !== undefined) problems.push("declares private");
+  if (manifest.license !== "AGPL-3.0-or-later") problems.push("does not declare its licence");
+  if (JSON.stringify(manifest).includes("workspace:")) problems.push("keeps a workspace: range");
+  // A registry belongs to the publication step's configuration, never to an artifact.
+  if (manifest.publishConfig !== undefined) problems.push("names a publishConfig");
+  if (manifest.devDependencies !== undefined) problems.push("keeps devDependencies");
+  const ekklesia = manifest.ekklesia;
+  if (!isRecord(ekklesia) || ekklesia.distribution !== PUBLIC_PACKAGE_DISTRIBUTION) {
+    problems.push("lacks the module-development distribution marker");
+  }
+  const scripts = isRecord(manifest.scripts) ? manifest.scripts : {};
+  for (const script of LIFECYCLE_SCRIPTS) {
+    if (Object.hasOwn(scripts, script)) problems.push(`runs a ${script} script`);
+  }
+  const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
+  for (const field of DEPENDENCY_FIELDS) {
+    const dependencies = manifest[field];
+    if (!isRecord(dependencies)) continue;
+    for (const [name, range] of Object.entries(dependencies)) {
+      if (!name.startsWith("@ekklesia/")) continue;
+      if (!publicNames.has(name)) problems.push(`${field} names the private ${name}`);
+      else if (range !== expected.version) {
+        problems.push(`${field} names ${name}@${String(range)}, not ${expected.version}`);
+      }
+    }
+    const sourceOrder = source?.[field];
+    if (isRecord(sourceOrder)) {
+      const order = Object.keys(sourceOrder).filter((key) => Object.hasOwn(dependencies, key));
+      if (JSON.stringify(order) !== JSON.stringify(Object.keys(dependencies))) {
+        problems.push(`orders ${field} differently from its source`);
+      }
+    }
+  }
+  return problems;
+}
+
+const BUILT_FILE = /^dist\/(.+?)(?:\.d\.ts|\.js)(?:\.map)?$/u;
+
+/**
+ * What is wrong with a tarball's file list, or nothing. Every file is `package.json`, `LICENSE`, or
+ * under one of the manifest's `files` entries; nothing is a source, test, or configuration file; and
+ * every built file has the source it was compiled from, so stale output from a deleted source fails.
+ */
+export function tarballFileProblems(
+  files: readonly string[],
+  manifest: Readonly<Record<string, unknown>>,
+  hasSource: (relativeWithoutExtension: string) => boolean,
+): string[] {
+  const problems: string[] = [];
+  const declared = Array.isArray(manifest.files) ? manifest.files.map(String) : [];
+  if (!files.includes("LICENSE")) problems.push("has no LICENSE");
+  if (!files.includes("package.json")) problems.push("has no package.json");
+  for (const file of files) {
+    if (file === "package.json" || file === "LICENSE") continue;
+    if (!declared.some((entry) => file === entry || file.startsWith(`${entry}/`))) {
+      problems.push(`ships ${file}, which its files field does not name`);
+      continue;
+    }
+    if (
+      /(?:^|\/)(?:src|tests?|node_modules)\//u.test(file) ||
+      /\.test\.[cm]?[jt]sx?$/u.test(file)
+    ) {
+      problems.push(`ships ${file}`);
+      continue;
+    }
+    const built = BUILT_FILE.exec(file);
+    if (file.startsWith("dist/") && (built === null || !hasSource(built[1] ?? ""))) {
+      problems.push(`ships ${file}, which no source produces`);
+    }
+  }
+  return problems;
+}
+
+export interface WorkspacePackage {
+  readonly name: string;
+  /** Relative to the repository root. */
+  readonly directory: string;
+  readonly manifest: Readonly<Record<string, unknown>>;
+}
+
+/** Every package `pnpm-workspace.yaml` names, read without a YAML dependency: the file lists
+ * literal directories and `<directory>/*` patterns only. */
+export async function workspacePackages(root = repositoryRoot): Promise<WorkspacePackage[]> {
+  const workspace = await readFile(path.join(root, "pnpm-workspace.yaml"), "utf8");
+  const block = /^packages:\n((?:[ \t]+-[^\n]*\n)+)/mu.exec(workspace)?.[1] ?? "";
+  const patterns = [...block.matchAll(/-\s*["']?([^"'\n]+?)["']?\s*$/gmu)].map(
+    (match) => match[1] ?? "",
+  );
+  const packages: WorkspacePackage[] = [];
+  for (const pattern of patterns) {
+    const directories = pattern.endsWith("/*")
+      ? (
+          await readdir(path.join(root, pattern.slice(0, -2)), { withFileTypes: true }).catch(
+            () => [],
+          )
+        )
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => `${pattern.slice(0, -2)}/${entry.name}`)
+      : [pattern];
+    for (const directory of directories) {
+      const manifest = await readJson(path.join(root, directory, "package.json")).catch(
+        () => undefined,
+      );
+      if (manifest && typeof manifest.name === "string") {
+        packages.push({ directory, manifest, name: manifest.name });
+      }
+    }
+  }
+  return packages.sort((left, right) => (left.name < right.name ? -1 : 1));
+}
+
+/**
+ * What is wrong with the workspace's release set, or nothing: every public package exists where the
+ * list says, carries the marker and the platform version, and is not private; every other package is
+ * private and unmarked, so nothing can enter the train unnoticed.
+ */
+export function releaseSetProblems(
+  packages: readonly WorkspacePackage[],
+  platformVersion: string,
+): string[] {
+  const problems: string[] = [];
+  const byName = new Map(packages.map((entry) => [entry.name, entry]));
+  const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
+  for (const expected of PUBLIC_PACKAGES) {
+    const found = byName.get(expected.name);
+    if (found === undefined || found.directory !== expected.directory) {
+      problems.push(`${expected.name} is missing from ${expected.directory}.`);
+      continue;
+    }
+    if (found.manifest.version !== platformVersion) {
+      problems.push(
+        `${expected.name} is version ${String(found.manifest.version)}, not the platform's ${platformVersion}.`,
+      );
+    }
+    if (found.manifest.private !== undefined) problems.push(`${expected.name} is private.`);
+  }
+  for (const entry of packages) {
+    if (publicNames.has(entry.name)) continue;
+    const ekklesia = entry.manifest.ekklesia;
+    if (isRecord(ekklesia) && ekklesia.distribution === PUBLIC_PACKAGE_DISTRIBUTION) {
+      problems.push(`${entry.name} carries the distribution marker but is not in the release set.`);
+    }
+    if (entry.manifest.private !== true) {
+      problems.push(`${entry.name} is publishable but not in the release set.`);
+    }
+  }
+  return problems;
+}
+
+export interface TrainPackage {
+  readonly name: string;
+  readonly version: string;
+  readonly role: PublicPackageRole;
+  readonly file: string;
+  readonly size: number;
+  /** Hexadecimal SHA-256 of the tarball. */
+  readonly sha256: string;
+  /** The npm `dist.integrity` of the tarball: `sha512-<base64>`. */
+  readonly integrity: string;
+}
+
+/** The release manifest: what one train is, by content. Provider-neutral, and no registry catalog. */
+export interface PackageTrainManifest {
+  readonly packageTrain: typeof PACKAGE_TRAIN_FORMAT;
+  /** The platform release version, and every package's version. */
+  readonly version: string;
+  readonly source: {
+    readonly revision: string;
+    /** True only for a local `--allow-modified` build, which must never be published. */
+    readonly modified: boolean;
+  };
+  readonly packages: readonly TrainPackage[];
+}
+
+/** What is wrong with a release directory's contents against its manifest, or nothing. */
+export function releaseDirectoryProblems(
+  manifest: PackageTrainManifest,
+  files: ReadonlyMap<string, Uint8Array>,
+): string[] {
+  const problems: string[] = [];
+  if (manifest.packageTrain !== PACKAGE_TRAIN_FORMAT) problems.push("unknown manifest format.");
+  const expected = new Map(
+    PUBLIC_PACKAGES.map((entry) => [tarballName(entry.name, manifest.version), entry.name]),
+  );
+  const listed = new Map(manifest.packages.map((entry) => [entry.file, entry]));
+  for (const [file, name] of expected) {
+    if (!listed.has(file)) problems.push(`the manifest does not list ${name}.`);
+    if (!files.has(file)) problems.push(`${file} is missing.`);
+  }
+  for (const file of files.keys()) {
+    if (!expected.has(file) && file !== PACKAGE_TRAIN_MANIFEST && file !== "SHA256SUMS") {
+      problems.push(`${file} is not part of the release.`);
+    }
+  }
+  for (const entry of manifest.packages) {
+    if (!expected.has(entry.file) || expected.get(entry.file) !== entry.name) {
+      problems.push(`the manifest lists ${entry.name} as ${entry.file}, which is not expected.`);
+      continue;
+    }
+    if (entry.version !== manifest.version) {
+      problems.push(`the manifest lists ${entry.name} at ${entry.version}.`);
+    }
+    const data = files.get(entry.file);
+    if (data === undefined) continue;
+    const digests = artifactDigests(data);
+    if (
+      data.length !== entry.size ||
+      digests.sha256 !== entry.sha256 ||
+      digests.integrity !== entry.integrity
+    ) {
+      problems.push(`${entry.file} does not match its size, SHA-256, or integrity.`);
+    }
+  }
+  return problems;
+}
+
+export function artifactDigests(data: Uint8Array): { sha256: string; integrity: string } {
+  return {
+    integrity: `sha512-${createHash("sha512").update(data).digest("base64")}`,
+    sha256: createHash("sha256").update(data).digest("hex"),
+  };
+}
+
+/** The manifest's exact bytes: sorted packages, two-space JSON, one trailing newline. */
+export function serializeManifest(manifest: PackageTrainManifest): string {
+  const packages = [...manifest.packages]
+    .sort((left, right) => (left.name < right.name ? -1 : 1))
+    .map((entry) => ({
+      file: entry.file,
+      integrity: entry.integrity,
+      name: entry.name,
+      role: entry.role,
+      sha256: entry.sha256,
+      size: entry.size,
+      version: entry.version,
+    }));
+  return `${JSON.stringify(
+    {
+      packageTrain: manifest.packageTrain,
+      version: manifest.version,
+      source: { modified: manifest.source.modified, revision: manifest.source.revision },
+      packages,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+async function readJson(file: string): Promise<Record<string, unknown>> {
+  return JSON.parse(await readFile(file, "utf8")) as Record<string, unknown>;
+}
+
+async function filesUnder(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { recursive: true, withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) =>
+      path.relative(directory, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"),
+    )
+    .sort();
+}
+
+async function sourceExists(packageDirectory: string, relative: string): Promise<boolean> {
+  for (const extension of [".ts", ".tsx"]) {
+    try {
+      await stat(path.join(packageDirectory, "src", `${relative}${extension}`));
+      return true;
+    } catch {}
+  }
+  return false;
+}
+
+async function run(command: string, arguments_: readonly string[], cwd: string): Promise<string> {
+  const { stdout } = await execFileAsync(command, [...arguments_], {
+    cwd,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+async function inspectTarball(
+  entry: PublicPackage,
+  version: string,
+  tarball: string,
+  scratch: string,
+): Promise<string[]> {
+  const directory = path.join(repositoryRoot, entry.directory);
+  const extracted = path.join(scratch, entry.name.replace("/", "+"));
+  await mkdir(extracted, { recursive: true });
+  await run("tar", ["-xzf", tarball, "-C", extracted], repositoryRoot);
+  const root = path.join(extracted, "package");
+  const files = await filesUnder(root);
+  const manifest = await readJson(path.join(root, "package.json"));
+  const source = await readJson(path.join(directory, "package.json"));
+
+  const sources = new Map<string, boolean>();
+  for (const file of files) {
+    const built = BUILT_FILE.exec(file)?.[1];
+    if (built !== undefined && !sources.has(built)) {
+      sources.set(built, await sourceExists(directory, built));
+    }
+  }
+  const problems = [
+    ...packedManifestProblems(manifest, { name: entry.name, version }, source),
+    ...tarballFileProblems(files, manifest, (relative) => sources.get(relative) === true),
+  ];
+  // Nothing the package says may name the machine or checkout it was packed on.
+  for (const file of files) {
+    const text = (await readFile(path.join(root, file))).toString("latin1");
+    for (const local of [repositoryRoot, homedir(), tmpdir()]) {
+      if (text.includes(local)) problems.push(`${file} names a local path`);
+    }
+  }
+  return [...new Set(problems)].map((problem) => `${entry.name} ${problem}.`);
+}
+
+/**
+ * Every uncommitted change in the source tree, as `git status --short` lines followed by
+ * `git diff --stat`, all relative to the repository root; empty for a clean tree. Ignored files
+ * (build output, `node_modules`) are not source and never count.
+ */
+async function sourceTreeChanges(): Promise<string[]> {
+  const status = (
+    await run("git", ["status", "--short", "--untracked-files=all"], repositoryRoot)
+  ).trimEnd();
+  if (status === "") return [];
+  const stat = (await run("git", ["diff", "--stat"], repositoryRoot)).trimEnd();
+  return [...status.split("\n"), ...(stat === "" ? [] : stat.split("\n"))];
+}
+
+export class PackageReleaseError extends Error {
+  readonly problems: readonly string[];
+
+  constructor(problems: readonly string[]) {
+    super("The package release failed its checks.");
+    this.name = "PackageReleaseError";
+    this.problems = problems;
+  }
+}
+
+export interface PackageReleaseOptions {
+  /** The parent of the release directory, which must not exist yet. */
+  readonly outDirectory: string;
+  readonly allowModified?: boolean;
+}
+
+/**
+ * Builds, packs, and inspects the public package train, and writes the release directory only when
+ * every check passed. Returns its path and manifest; throws `PackageReleaseError` with every problem
+ * found otherwise.
+ */
+export async function buildPackageRelease(
+  options: PackageReleaseOptions,
+): Promise<{ readonly directory: string; readonly manifest: PackageTrainManifest }> {
+  const version = String((await readJson(path.join(repositoryRoot, "package.json"))).version);
+  const setProblems = releaseSetProblems(await workspacePackages(), version);
+  if (setProblems.length > 0) throw new PackageReleaseError(setProblems);
+
+  const revision = (await run("git", ["rev-parse", "HEAD"], repositoryRoot)).trim();
+  const dirty = await sourceTreeChanges();
+  const modified = dirty.length > 0;
+  if (modified && options.allowModified !== true) {
+    throw new PackageReleaseError([
+      "The source tree has uncommitted changes. A release is built from a clean commit.",
+      ...dirty,
+    ]);
+  }
+
+  const release = path.join(path.resolve(options.outDirectory), releaseDirectoryName(version));
+  try {
+    await stat(release);
+    throw new PackageReleaseError([`${release} already exists. A release is written once.`]);
+  } catch (error) {
+    if (error instanceof PackageReleaseError) throw error;
+  }
+
+  // Stale output from a deleted source would otherwise ship: the build only ever adds files, and
+  // Turbo's cache would restore whatever an earlier build left behind.
+  for (const entry of PUBLIC_PACKAGES) {
+    await rm(path.join(repositoryRoot, entry.directory, "dist"), { force: true, recursive: true });
+  }
+  await run(
+    "pnpm",
+    [
+      "exec",
+      "turbo",
+      "run",
+      "build",
+      "--force",
+      "--output-logs=errors-only",
+      ...PUBLIC_PACKAGES.map((entry) => `--filter=${entry.name}`),
+    ],
+    repositoryRoot,
+  );
+  // The source was clean before the build; it must still be, so what is packed is the commit. A build
+  // that wrote a tracked file, or an untracked file Git does not ignore, fails the release here.
+  const changedByBuild = (await sourceTreeChanges()).filter((line) => !dirty.includes(line));
+  if (changedByBuild.length > 0) {
+    throw new PackageReleaseError([
+      "The build changed the source tree. A release packs exactly its commit.",
+      ...changedByBuild,
+    ]);
+  }
+
+  const scratch = await mkdtemp(path.join(tmpdir(), "ekklesia-package-release-"));
+  try {
+    const staging = path.join(scratch, "release");
+    await mkdir(staging);
+    const problems: string[] = [];
+    const packages: TrainPackage[] = [];
+    for (const entry of PUBLIC_PACKAGES) {
+      const report = JSON.parse(
+        await run(
+          "pnpm",
+          [`--config.pnpmfile=${PACK_HOOKS}`, "pack", "--json", "--pack-destination", staging],
+          path.join(repositoryRoot, entry.directory),
+        ),
+      ) as { filename: string };
+      const file = path.basename(report.filename);
+      if (file !== tarballName(entry.name, version)) {
+        problems.push(`${entry.name} packed as ${file}.`);
+        continue;
+      }
+      problems.push(...(await inspectTarball(entry, version, report.filename, scratch)));
+      const data = await readFile(report.filename);
+      packages.push({
+        file,
+        name: entry.name,
+        role: entry.role,
+        size: data.length,
+        version,
+        ...artifactDigests(data),
+      });
+    }
+    const manifest: PackageTrainManifest = {
+      packageTrain: PACKAGE_TRAIN_FORMAT,
+      packages,
+      source: { modified, revision },
+      version,
+    };
+    const contents = new Map<string, Uint8Array>();
+    for (const file of await readdir(staging)) {
+      contents.set(file, await readFile(path.join(staging, file)));
+    }
+    problems.push(...releaseDirectoryProblems(manifest, contents));
+    if (problems.length > 0) throw new PackageReleaseError(problems);
+
+    const sorted = [...manifest.packages].sort((left, right) => (left.file < right.file ? -1 : 1));
+    await writeFile(
+      path.join(staging, "SHA256SUMS"),
+      sorted.map((entry) => `${entry.sha256}  ${entry.file}\n`).join(""),
+    );
+    await writeFile(path.join(staging, PACKAGE_TRAIN_MANIFEST), serializeManifest(manifest));
+    await mkdir(path.dirname(release), { recursive: true });
+    // Into place in one step: the release directory either holds a whole, checked release or does
+    // not exist. A rename across file systems is not atomic, so copy then, never half a release.
+    try {
+      await rename(staging, release);
+    } catch {
+      await run("cp", ["-R", staging, release], repositoryRoot);
+    }
+    return { directory: release, manifest };
+  } finally {
+    await rm(scratch, { force: true, recursive: true });
+  }
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  const allowModified = argv.includes("--allow-modified");
+  const rest = argv.filter((argument) => argument !== "--allow-modified");
+  if (rest.length !== 2 || rest[0] !== "--out" || !rest[1]) {
+    process.stderr.write(
+      "Usage: node scripts/package-release.ts --out <directory> [--allow-modified]\n",
+    );
+    return 64;
+  }
+  try {
+    const { directory, manifest } = await buildPackageRelease({
+      allowModified,
+      outDirectory: rest[1],
+    });
+    for (const entry of manifest.packages) {
+      process.stdout.write(`${entry.file}: ${entry.size} bytes, sha256 ${entry.sha256}\n`);
+    }
+    process.stdout.write(
+      `Built and inspected the ${manifest.version} package train (${manifest.packages.length} packages${
+        manifest.source.modified ? ", from a modified source tree: never publish it" : ""
+      }) in ${directory}\n`,
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof PackageReleaseError) {
+      for (const problem of error.problems) process.stderr.write(`${problem}\n`);
+      return 1;
+    }
+    process.stderr.write("Building the package release failed while building or packing.\n");
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main(process.argv.slice(2));
+}

scripts/publish-package-train.ts

@@ -0,0 +1,911 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
+import {
+  artifactDigests,
+  PACKAGE_TRAIN_FORMAT,
+  PACKAGE_TRAIN_MANIFEST,
+  type PackageTrainManifest,
+  releaseDirectoryProblems,
+  type TrainPackage,
+} from "./package-release.ts";
+
+/**
+ * Publishes one package release train (ADR 0053) to an npm-protocol registry: exactly the `.tgz`
+ * files `pnpm packages:release` produced, as `ekklesia-package-train.json` records them, and nothing
+ * else. It never builds, packs, or edits a package, and never deletes or unpublishes anything.
+ *
+ *   EKKLESIA_PACKAGES_PUBLISH_TOKEN=… node scripts/publish-package-train.ts \
+ *     --release <release directory> --registry <npm registry URL> --version <train version> \
+ *     [--revision <full commit id>] [--manifest-sha256 <hex>] [--record <file>] \
+ *     [--staging-tag <tag>] [--final-tag <tag>] [--require-public-read]
+ *
+ * 1. The whole local train is validated before anything is sent: the manifest, every artifact's
+ *    name, size, SHA-256, integrity, and the package.json inside it.
+ * 2. Packages go out in dependency order. For each: absent from the registry, it is published with
+ *    `npm publish <file.tgz>` under a staging dist-tag; present with the same bytes, it is accepted
+ *    as already published; present with other bytes, publication stops for good (the version is
+ *    burned). Every package is then read back: its metadata, and its tarball, which must be the
+ *    release artifact byte for byte.
+ * 3. Only when all of them are verified does the final dist-tag (`latest`) move, and the train is
+ *    published once every tag agrees. A rerun converges: it publishes only what is missing and moves
+ *    only tags that are not yet right.
+ *
+ * The publish token is read from the environment only, and reaches npm through a temporary npm
+ * configuration that refers to the variable, never the value; the configuration is removed after.
+ */
+
+const execFileAsync = promisify(execFile);
+
+export const PUBLISH_TOKEN_VARIABLE = "EKKLESIA_PACKAGES_PUBLISH_TOKEN";
+export const DEFAULT_STAGING_TAG = "ekklesia-staging";
+export const DEFAULT_FINAL_TAG = "latest";
+export const PUBLICATION_RECORD_FORMAT = 1;
+const DEPENDENCY_FIELDS = Object.freeze([
+  "dependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const);
+
+export type PublicationErrorCode =
+  | "INVALID_OPTIONS"
+  | "INVALID_RELEASE"
+  | "BURNED_VERSION"
+  | "REGISTRY_UNAVAILABLE"
+  | "PUBLISH_FAILED"
+  | "VERIFICATION_FAILED"
+  | "TAGS_NOT_CONVERGED";
+
+export class PublicationError extends Error {
+  readonly code: PublicationErrorCode;
+  readonly problems: readonly string[];
+
+  constructor(code: PublicationErrorCode, message: string, problems: readonly string[] = []) {
+    super(message);
+    this.name = "PublicationError";
+    this.code = code;
+    this.problems = problems;
+  }
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------------------------
+// The local train
+// ---------------------------------------------------------------------------------------------
+
+/** The `package/package.json` inside an npm tarball, read without unpacking anything to disk. */
+export function tarballPackageJson(tarball: Uint8Array): Record<string, unknown> {
+  const data = gunzipSync(tarball);
+  for (let offset = 0; offset + 512 <= data.length; ) {
+    const header = data.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const field = (start: number, length: number) =>
+      header
+        .subarray(start, start + length)
+        .toString("utf8")
+        .replace(/\0.*$/su, "");
+    const name = field(0, 100);
+    const prefix = header.subarray(257, 262).toString("latin1") === "ustar" ? field(345, 155) : "";
+    const size = Number.parseInt(field(124, 12).trim() || "0", 8);
+    const type = field(156, 1);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    if ((type === "0" || type === "") && fullName === "package/package.json") {
+      const body = data.subarray(offset + 512, offset + 512 + size);
+      return JSON.parse(body.toString("utf8")) as Record<string, unknown>;
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  throw new Error("The tarball holds no package/package.json.");
+}
+
+export interface LocalPackage {
+  readonly entry: TrainPackage;
+  /** The artifact's absolute path: the exact file validated against the release manifest. */
+  readonly path: string;
+  readonly data: Buffer;
+  readonly packageJson: Readonly<Record<string, unknown>>;
+}
+
+export interface LocalTrain {
+  readonly manifest: PackageTrainManifest;
+  /** SHA-256 of `ekklesia-package-train.json`'s exact bytes. */
+  readonly manifestSha256: string;
+  readonly packages: readonly LocalPackage[];
+}
+
+/**
+ * Reads and validates a release directory completely, or throws `INVALID_RELEASE` with every
+ * problem: nothing may be published from a train that is not whole and unchanged.
+ */
+export async function loadReleaseTrain(
+  releaseDirectory: string,
+  expected: { readonly version: string; readonly revision?: string },
+): Promise<LocalTrain> {
+  // Resolved once, here: every artifact path from now on is absolute, so the file npm is handed
+  // is the file validated below, whatever directory npm itself runs in.
+  const directory = path.resolve(releaseDirectory);
+  const files = new Map<string, Buffer>();
+  for (const file of await readdir(directory)) {
+    files.set(file, await readFile(path.join(directory, file)));
+  }
+  const manifestBytes = files.get(PACKAGE_TRAIN_MANIFEST);
+  if (manifestBytes === undefined) {
+    throw new PublicationError("INVALID_RELEASE", `The release has no ${PACKAGE_TRAIN_MANIFEST}.`);
+  }
+  let manifest: PackageTrainManifest;
+  try {
+    manifest = JSON.parse(manifestBytes.toString("utf8")) as PackageTrainManifest;
+  } catch {
+    throw new PublicationError("INVALID_RELEASE", `${PACKAGE_TRAIN_MANIFEST} is not JSON.`);
+  }
+  const problems = trainProblems(manifest, files, expected);
+  if (problems.length > 0) {
+    throw new PublicationError("INVALID_RELEASE", "The release train failed validation.", problems);
+  }
+  return {
+    manifest,
+    manifestSha256: createHash("sha256").update(manifestBytes).digest("hex"),
+    packages: manifest.packages.map((entry) => {
+      const data = files.get(entry.file) as Buffer;
+      return {
+        data,
+        entry,
+        packageJson: tarballPackageJson(data),
+        path: path.join(directory, entry.file),
+      };
+    }),
+  };
+}
+
+/** Every reason a release directory's contents may not be published, or nothing. */
+export function trainProblems(
+  manifest: PackageTrainManifest,
+  files: ReadonlyMap<string, Uint8Array>,
+  expected: { readonly version: string; readonly revision?: string },
+): string[] {
+  if (
+    !isRecord(manifest) ||
+    manifest.packageTrain !== PACKAGE_TRAIN_FORMAT ||
+    !Array.isArray(manifest.packages) ||
+    !isRecord(manifest.source)
+  ) {
+    return ["The release manifest is not a package train manifest."];
+  }
+  const problems = releaseDirectoryProblems(manifest, files);
+  if (manifest.source.modified !== false) {
+    problems.push("The release was built from a modified source tree; it is never published.");
+  }
+  if (manifest.version !== expected.version) {
+    problems.push(
+      `The release is version ${String(manifest.version)}, not the requested ${expected.version}.`,
+    );
+  }
+  if (!/^[0-9a-f]{40}([0-9a-f]{24})?$/u.test(String(manifest.source.revision))) {
+    problems.push("The release names no full source revision.");
+  }
+  if (expected.revision !== undefined && manifest.source.revision !== expected.revision) {
+    problems.push(
+      `The release was built from ${String(manifest.source.revision)}, not the expected ${expected.revision}.`,
+    );
+  }
+  const sums = files.get("SHA256SUMS");
+  const expectedSums = [...manifest.packages]
+    .sort((left, right) => (left.file < right.file ? -1 : 1))
+    .map((entry) => `${entry.sha256}  ${entry.file}\n`)
+    .join("");
+  if (sums === undefined || Buffer.from(sums).toString("utf8") !== expectedSums) {
+    problems.push("SHA256SUMS does not match the release manifest.");
+  }
+  for (const entry of manifest.packages) {
+    const data = files.get(entry.file);
+    if (data === undefined) continue;
+    try {
+      const packageJson = tarballPackageJson(data);
+      if (packageJson.name !== entry.name || packageJson.version !== entry.version) {
+        problems.push(
+          `${entry.file} holds ${String(packageJson.name)}@${String(packageJson.version)}, not ${entry.name}@${entry.version}.`,
+        );
+      }
+    } catch {
+      problems.push(`${entry.file} is not a readable npm package tarball.`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The order packages are published in: every package after the train packages it depends on (in
+ * `dependencies`, `peerDependencies`, or `optionalDependencies`), and otherwise by name, so the order
+ * never depends on how a directory happens to list its files.
+ */
+export function publicationOrder<
+  Package extends {
+    readonly entry: { readonly name: string };
+    readonly packageJson: Readonly<Record<string, unknown>>;
+  },
+>(packages: readonly Package[]): Package[] {
+  const byName = new Map(packages.map((entry) => [entry.entry.name, entry]));
+  const dependsOn = new Map<string, Set<string>>();
+  for (const entry of packages) {
+    const names = new Set<string>();
+    for (const field of DEPENDENCY_FIELDS) {
+      const dependencies = entry.packageJson[field];
+      if (!isRecord(dependencies)) continue;
+      for (const name of Object.keys(dependencies)) {
+        if (byName.has(name) && name !== entry.entry.name) names.add(name);
+      }
+    }
+    dependsOn.set(entry.entry.name, names);
+  }
+  const order: Package[] = [];
+  const done = new Set<string>();
+  while (order.length < packages.length) {
+    const ready = [...byName.keys()]
+      .filter((name) => !done.has(name))
+      .filter((name) =>
+        [...(dependsOn.get(name) ?? [])].every((dependency) => done.has(dependency)),
+      )
+      .sort();
+    const next = ready[0];
+    if (next === undefined) {
+      throw new PublicationError(
+        "INVALID_RELEASE",
+        "The release's packages depend on each other in a cycle.",
+      );
+    }
+    done.add(next);
+    order.push(byName.get(next) as Package);
+  }
+  return order;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Comparing a registry copy with the release
+// ---------------------------------------------------------------------------------------------
+
+/** `bin` as npm publishes it: a string becomes `{ <package name without scope>: path }`, and paths
+ * lose a leading `./`. The tarball keeps the author's form; the registry metadata gets this one. */
+export function normalizeBin(bin: unknown, packageName: string): Record<string, string> {
+  const entries: [string, string][] =
+    typeof bin === "string"
+      ? [[packageName.replace(/^@[^/]+\//u, ""), bin]]
+      : isRecord(bin)
+        ? Object.entries(bin).map(([name, target]) => [name, String(target)])
+        : [];
+  return Object.fromEntries(
+    entries
+      .map(([name, target]): [string, string] => [name, target.replace(/^(?:\.\/)+/u, "")])
+      .sort(([left], [right]) => (left < right ? -1 : 1)),
+  );
+}
+
+function sortedRecord(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, value[key]]),
+  );
+}
+
+/** Whether `url` is the registry itself or below it: same origin, same path prefix. */
+export function isUnderRegistry(url: string, registry: string): boolean {
+  try {
+    const target = new URL(url);
+    const base = new URL(registry);
+    return target.origin === base.origin && target.pathname.startsWith(base.pathname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every way a registry's copy of a package differs from the release artifact, or nothing:
+ * the version metadata the registry serves, and the bytes it serves for it.
+ */
+export function registryCopyProblems(
+  local: Pick<LocalPackage, "entry" | "packageJson" | "data">,
+  version: Readonly<Record<string, unknown>>,
+  downloaded: Uint8Array,
+  registry: string,
+): string[] {
+  const problems: string[] = [];
+  const { entry, packageJson } = local;
+  if (version.name !== entry.name || version.version !== entry.version) {
+    problems.push(`the registry names ${String(version.name)}@${String(version.version)}`);
+  }
+  const dist = isRecord(version.dist) ? version.dist : {};
+  if (dist.integrity !== entry.integrity) {
+    problems.push("the registry reports a different integrity");
+  }
+  const sha1 = createHash("sha1").update(local.data).digest("hex");
+  if (dist.shasum !== undefined && dist.shasum !== sha1) {
+    problems.push("the registry reports a different shasum");
+  }
+  if (typeof dist.tarball !== "string" || !isUnderRegistry(dist.tarball, registry)) {
+    problems.push("the registry's tarball URL is not on the configured registry");
+  }
+  for (const field of DEPENDENCY_FIELDS) {
+    if (
+      JSON.stringify(sortedRecord(version[field])) !==
+      JSON.stringify(sortedRecord(packageJson[field]))
+    ) {
+      problems.push(`the registry's ${field} differ from the package's`);
+    }
+  }
+  if (
+    JSON.stringify(normalizeBin(version.bin, entry.name)) !==
+    JSON.stringify(normalizeBin(packageJson.bin, entry.name))
+  ) {
+    problems.push("the registry's bin differs from the package's");
+  }
+  const digests = artifactDigests(downloaded);
+  if (
+    !Buffer.from(downloaded).equals(local.data) ||
+    digests.sha256 !== entry.sha256 ||
+    digests.integrity !== entry.integrity
+  ) {
+    problems.push("the registry serves different bytes from the release artifact");
+  }
+  return problems;
+}
+
+/** SemVer 2.0.0 precedence: negative, zero, or positive. Build metadata is ignored. */
+export function compareSemver(left: string, right: string): number {
+  const parse = (version: string) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(version);
+    if (match === null) throw new Error(`Not a semantic version: ${version}`);
+    return {
+      core: [Number(match[1]), Number(match[2]), Number(match[3])],
+      pre: match[4] === undefined ? [] : match[4].split("."),
+    };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (a.core[index] ?? 0) - (b.core[index] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  if (a.pre.length === 0 || b.pre.length === 0) return Math.sign(b.pre.length - a.pre.length);
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    const x = a.pre[index];
+    const y = b.pre[index];
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    if (x === y) continue;
+    const xNumber = /^\d+$/u.test(x);
+    const yNumber = /^\d+$/u.test(y);
+    if (xNumber && yNumber) return Math.sign(Number(x) - Number(y));
+    if (xNumber !== yNumber) return xNumber ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The registry: read over HTTP, written with npm
+// ---------------------------------------------------------------------------------------------
+
+/** The registry URL, validated, with exactly one trailing slash. */
+export function normalizeRegistry(registry: string, allowHttp = false): string {
+  let url: URL;
+  try {
+    url = new URL(registry);
+  } catch {
+    throw new PublicationError("INVALID_OPTIONS", "The registry is not a URL.");
+  }
+  if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
+    throw new PublicationError(
+      "INVALID_OPTIONS",
+      "The registry URL may hold no credentials, query, or fragment.",
+    );
+  }
+  if (url.protocol !== "https:" && !(allowHttp && url.protocol === "http:")) {
+    throw new PublicationError("INVALID_OPTIONS", "The registry must be reached over HTTPS.");
+  }
+  url.pathname = url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`;
+  return url.toString();
+}
+
+/** The npm configuration a publish uses: the scope and registry, and the token by reference. */
+export function npmConfiguration(registry: string): string {
+  const url = new URL(registry);
+  return [
+    `registry=${registry}`,
+    `@ekklesia:registry=${registry}`,
+    `//${url.host}${url.pathname}:_authToken=\${${PUBLISH_TOKEN_VARIABLE}}`,
+    "",
+  ].join("\n");
+}
+
+/** `@ekklesia/module-sdk` → `<registry>@ekklesia%2fmodule-sdk`, the npm packument path. */
+export function packumentUrl(registry: string, name: string): string {
+  return `${registry}${name.replace("/", "%2f")}`;
+}
+
+export interface RegistryReader {
+  /** The package's packument, or `undefined` when the registry has no such package. */
+  packument(name: string): Promise<Record<string, unknown> | undefined>;
+  /** A tarball's bytes; authenticated only when the URL is on the registry itself. */
+  download(url: string, anonymous?: boolean): Promise<Buffer>;
+}
+
+export function registryReader(
+  registry: string,
+  token: string | undefined,
+  fetchImplementation: typeof fetch = fetch,
+): RegistryReader {
+  const headers = (url: string, anonymous: boolean): Record<string, string> =>
+    !anonymous && token && isUnderRegistry(url, registry)
+      ? { authorization: `Bearer ${token}` }
+      : {};
+  const get = async (url: string, accept: string, anonymous: boolean) => {
+    try {
+      return await fetchImplementation(url, {
+        headers: { accept, ...headers(url, anonymous) },
+        redirect: "error",
+      });
+    } catch {
+      throw new PublicationError("REGISTRY_UNAVAILABLE", "The registry could not be reached.");
+    }
+  };
+  return {
+    async download(url, anonymous = false) {
+      const response = await get(url, "application/octet-stream", anonymous);
+      if (!response.ok) {
+        throw new PublicationError(
+          "REGISTRY_UNAVAILABLE",
+          `The registry answered ${response.status} for a package tarball.`,
+        );
+      }
+      return Buffer.from(await response.arrayBuffer());
+    },
+    async packument(name) {
+      const response = await get(packumentUrl(registry, name), "application/json", false);
+      if (response.status === 404) return undefined;
+      if (!response.ok) {
+        throw new PublicationError(
+          "REGISTRY_UNAVAILABLE",
+          `The registry answered ${response.status} for ${name}.`,
+        );
+      }
+      return (await response.json()) as Record<string, unknown>;
+    },
+  };
+}
+
+function versionOf(
+  packument: Record<string, unknown> | undefined,
+  version: string,
+): Record<string, unknown> | undefined {
+  const versions = packument?.versions;
+  const found = isRecord(versions) ? versions[version] : undefined;
+  return isRecord(found) ? { ...found } : undefined;
+}
+
+function distTagsOf(packument: Record<string, unknown> | undefined): Record<string, string> {
+  const tags = packument?.["dist-tags"];
+  return isRecord(tags)
+    ? Object.fromEntries(Object.entries(tags).map(([tag, version]) => [tag, String(version)]))
+    : {};
+}
+
+interface NpmSession {
+  publish(file: string, tag: string): Promise<void>;
+  addTag(name: string, version: string, tag: string): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+/** npm with only a temporary configuration: no user or global npmrc, no project directory. */
+async function npmSession(registry: string, token: string, npm: string): Promise<NpmSession> {
+  const home = await mkdtemp(path.join(tmpdir(), "ekklesia-publish-"));
+  const userconfig = path.join(home, "npmrc");
+  const globalconfig = path.join(home, "global-npmrc");
+  await writeFile(userconfig, npmConfiguration(registry), { mode: 0o600 });
+  await writeFile(globalconfig, "", { mode: 0o600 });
+  const environment = {
+    [PUBLISH_TOKEN_VARIABLE]: token,
+    HOME: home,
+    PATH: process.env.PATH ?? "",
+    npm_config_audit: "false",
+    npm_config_cache: path.join(home, "cache"),
+    npm_config_fund: "false",
+    npm_config_globalconfig: globalconfig,
+    npm_config_update_notifier: "false",
+    npm_config_userconfig: userconfig,
+  };
+  const run = async (args: readonly string[], what: string) => {
+    try {
+      await execFileAsync(npm, [...args], { cwd: home, env: environment, maxBuffer: 16 << 20 });
+    } catch (error) {
+      const stderr = String((error as { stderr?: unknown }).stderr ?? "");
+      const summary = stderr
+        .split("\n")
+        .filter((line) => /^npm error (?:code|path|syscall|errno|enoent|\d{3}|[A-Z])/u.test(line))
+        .filter((line) => !line.includes("complete log"))
+        .slice(0, 5)
+        .join(" / ")
+        .replaceAll(token, "***")
+        .replaceAll(home, "<npm home>");
+      throw new PublicationError(
+        "PUBLISH_FAILED",
+        `${what} failed${summary ? `: ${summary}` : "."}`,
+      );
+    }
+  };
+  return {
+    addTag: (name, version, tag) =>
+      run(["dist-tag", "add", `${name}@${version}`, tag], `Moving ${tag} to ${name}@${version}`),
+    dispose: () => rm(home, { force: true, recursive: true }),
+    publish: async (file, tag) => {
+      // npm runs in its own temporary home, so a relative path would name a file there, not the
+      // release artifact. Only the artifact's absolute path is ever passed.
+      if (!path.isAbsolute(file)) {
+        throw new PublicationError(
+          "PUBLISH_FAILED",
+          `Refusing to publish ${file}: npm is only ever given an artifact's absolute path.`,
+        );
+      }
+      await run(
+        // A file spec runs no lifecycle script and sends the file's own bytes; --ignore-scripts
+        // says so explicitly. --access public is what a scoped package needs on a public registry.
+        ["publish", file, "--tag", tag, "--access", "public", "--ignore-scripts"],
+        `Publishing ${path.basename(file)} from ${file}`,
+      );
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Publishing a train
+// ---------------------------------------------------------------------------------------------
+
+export type PackageOutcome = "published" | "already-present";
+export type TagOutcome = "moved" | "already-current" | "kept-newer";
+
+export interface PublicationHooks {
+  /** Called before each package is published (not for one already present). Tests use it to
+   * interrupt a train part way. */
+  beforePublish?(name: string, index: number): void | Promise<void>;
+  /** Called before each final dist-tag is moved. */
+  beforeTag?(name: string, index: number): void | Promise<void>;
+}
+
+export interface PublishOptions {
+  readonly releaseDirectory: string;
+  readonly registry: string;
+  readonly version: string;
+  readonly revision?: string;
+  /** SHA-256 of the release manifest the package-release gate proved, which binds the artifact a
+   * publish job received to that gate. */
+  readonly manifestSha256?: string;
+  readonly token: string;
+  readonly stagingTag?: string;
+  readonly finalTag?: string;
+  readonly requirePublicRead?: boolean;
+  /** Only for a disposable test registry. */
+  readonly allowHttp?: boolean;
+  readonly npm?: string;
+  readonly fetch?: typeof fetch;
+  readonly hooks?: PublicationHooks;
+  readonly log?: (line: string) => void;
+  readonly now?: () => Date;
+}
+
+export interface PublishedPackage {
+  readonly name: string;
+  readonly version: string;
+  readonly file: string;
+  readonly outcome: PackageOutcome;
+  readonly artifact: { readonly sha256: string; readonly integrity: string; readonly size: number };
+  readonly registry: {
+    readonly tarball: string;
+    readonly sha256: string;
+    readonly integrity: string;
+    readonly publicRead: boolean;
+  };
+  readonly finalTag: TagOutcome;
+  readonly distTags: Readonly<Record<string, string>>;
+}
+
+/** Evidence that one train was published: not a package catalog, and never a secret. */
+export interface PublicationRecord {
+  readonly publicationRecord: typeof PUBLICATION_RECORD_FORMAT;
+  readonly packageTrain: {
+    readonly version: string;
+    readonly revision: string;
+    readonly manifestSha256: string;
+  };
+  readonly registry: string;
+  readonly finalTag: string;
+  readonly completedAt: string;
+  readonly packages: readonly PublishedPackage[];
+}
+
+export function serializeRecord(record: PublicationRecord): string {
+  return `${JSON.stringify(record, null, 2)}\n`;
+}
+
+const TOKEN_FORMAT = /^[\x21-\x7e]{8,}$/u;
+
+export async function publishPackageTrain(options: PublishOptions): Promise<PublicationRecord> {
+  const log = options.log ?? (() => {});
+  const stagingTag = options.stagingTag ?? DEFAULT_STAGING_TAG;
+  const finalTag = options.finalTag ?? DEFAULT_FINAL_TAG;
+  if (!TOKEN_FORMAT.test(options.token)) {
+    throw new PublicationError(
+      "INVALID_OPTIONS",
+      `${PUBLISH_TOKEN_VARIABLE} must hold the publish token.`,
+    );
+  }
+  for (const tag of [stagingTag, finalTag]) {
+    if (!/^[a-z][a-z0-9-]*$/u.test(tag)) {
+      throw new PublicationError("INVALID_OPTIONS", `${tag} is not a usable dist-tag.`);
+    }
+  }
+  if (stagingTag === finalTag) {
+    throw new PublicationError("INVALID_OPTIONS", "The staging and final tags must differ.");
+  }
+  const registry = normalizeRegistry(options.registry, options.allowHttp);
+
+  // Nothing is sent until the whole local train is valid.
+  const train = await loadReleaseTrain(options.releaseDirectory, {
+    version: options.version,
+    ...(options.revision === undefined ? {} : { revision: options.revision }),
+  });
+  if (options.manifestSha256 !== undefined && options.manifestSha256 !== train.manifestSha256) {
+    throw new PublicationError(
+      "INVALID_RELEASE",
+      "The release manifest is not the one the package-release gate proved.",
+    );
+  }
+  const order = publicationOrder(train.packages);
+  log(
+    `Package train ${train.manifest.version} (${train.manifest.source.revision}) validated: ${order
+      .map((entry) => entry.entry.name)
+      .join(", ")}`,
+  );
+
+  const reader = registryReader(registry, options.token, options.fetch);
+  const npm = await npmSession(registry, options.token, options.npm ?? "npm");
+  try {
+    const verified: {
+      local: LocalPackage;
+      outcome: PackageOutcome;
+      tarball: string;
+      publicRead: boolean;
+      downloaded: { sha256: string; integrity: string };
+    }[] = [];
+    for (const [index, local] of order.entries()) {
+      const { name, version } = local.entry;
+      let outcome: PackageOutcome = "already-present";
+      let existing = versionOf(await reader.packument(name), version);
+      if (existing === undefined) {
+        await options.hooks?.beforePublish?.(name, index);
+        // The file npm reads must still be the validated artifact, byte for byte.
+        const current = await readFile(local.path).catch(() => undefined);
+        if (current === undefined || !current.equals(local.data)) {
+          throw new PublicationError(
+            "INVALID_RELEASE",
+            `${local.path} is missing or no longer the artifact validated against the release manifest.`,
+          );
+        }
+        log(`${name}@${version}: publishing ${local.path} (sha256 ${local.entry.sha256})`);
+        try {
+          await npm.publish(local.path, stagingTag);
+          outcome = "published";
+        } catch (error) {
+          // Someone may have published it meanwhile; what is there now decides.
+          if (versionOf(await reader.packument(name), version) === undefined) throw error;
+        }
+        existing = versionOf(await reader.packument(name), version);
+        if (existing === undefined) {
+          throw new PublicationError(
+            "VERIFICATION_FAILED",
+            `${name}@${version} is not on the registry after publishing it.`,
+          );
+        }
+      }
+      const tarball = isRecord(existing.dist) ? String(existing.dist.tarball) : "";
+      if (!isUnderRegistry(tarball, registry)) {
+        throw new PublicationError(
+          "VERIFICATION_FAILED",
+          `${name}@${version}'s tarball is not on the configured registry.`,
+        );
+      }
+      const downloaded = await reader.download(tarball);
+      if (!downloaded.equals(local.data)) {
+        throw new PublicationError(
+          "BURNED_VERSION",
+          `${name}@${version} is already on the registry with different bytes. It is never deleted or replaced: the version is burned, publication stops here, and the train needs a new version after an investigation.`,
+        );
+      }
+      const problems = registryCopyProblems(local, existing, downloaded, registry);
+      if (problems.length > 0) {
+        throw new PublicationError(
+          "VERIFICATION_FAILED",
+          `${name}@${version} does not match the release artifact.`,
+          problems,
+        );
+      }
+      const publicRead = await reader
+        .download(tarball, true)
+        .then((anonymous) => anonymous.equals(local.data))
+        .catch(() => false);
+      if (options.requirePublicRead === true && !publicRead) {
+        throw new PublicationError(
+          "VERIFICATION_FAILED",
+          `${name}@${version} cannot be downloaded anonymously.`,
+        );
+      }
+      log(`${name}@${version}: ${outcome}, verified byte for byte`);
+      verified.push({
+        downloaded: artifactDigests(downloaded),
+        local,
+        outcome,
+        publicRead,
+        tarball,
+      });
+    }
+
+    // Every package is there and verified: only now does the final tag move.
+    const tagOutcomes = new Map<string, TagOutcome>();
+    for (const [index, { local }] of verified.entries()) {
+      const { name, version } = local.entry;
+      const current = distTagsOf(await reader.packument(name))[finalTag];
+      if (current === version) {
+        tagOutcomes.set(name, "already-current");
+      } else if (current !== undefined && compareSemver(current, version) > 0) {
+        tagOutcomes.set(name, "kept-newer");
+      } else {
+        await options.hooks?.beforeTag?.(name, index);
+        await npm.addTag(name, version, finalTag);
+        tagOutcomes.set(name, "moved");
+      }
+      log(`${name}: ${finalTag} ${tagOutcomes.get(name)}`);
+    }
+
+    const packages: PublishedPackage[] = [];
+    const unconverged: string[] = [];
+    for (const { downloaded, local, outcome, publicRead, tarball } of verified) {
+      const { name, version } = local.entry;
+      const distTags = distTagsOf(await reader.packument(name));
+      const finalVersion = distTags[finalTag];
+      const converged =
+        finalVersion === version ||
+        (tagOutcomes.get(name) === "kept-newer" &&
+          finalVersion !== undefined &&
+          compareSemver(finalVersion, version) > 0);
+      if (!converged) unconverged.push(`${name}: ${finalTag} is ${finalVersion ?? "unset"}`);
+      packages.push({
+        artifact: {
+          integrity: local.entry.integrity,
+          sha256: local.entry.sha256,
+          size: local.entry.size,
+        },
+        distTags: Object.fromEntries(Object.entries(distTags).sort()),
+        file: local.entry.file,
+        finalTag: tagOutcomes.get(name) ?? "moved",
+        name,
+        outcome,
+        registry: { ...downloaded, publicRead, tarball },
+        version,
+      });
+    }
+    if (unconverged.length > 0) {
+      throw new PublicationError(
+        "TAGS_NOT_CONVERGED",
+        "The final dist-tags did not converge.",
+        unconverged,
+      );
+    }
+    return {
+      completedAt: (options.now ?? (() => new Date()))().toISOString(),
+      finalTag,
+      packageTrain: {
+        manifestSha256: train.manifestSha256,
+        revision: train.manifest.source.revision,
+        version: train.manifest.version,
+      },
+      packages,
+      publicationRecord: PUBLICATION_RECORD_FORMAT,
+      registry,
+    };
+  } finally {
+    await npm.dispose();
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Command line
+// ---------------------------------------------------------------------------------------------
+
+const VALUE_OPTIONS = Object.freeze({
+  "--final-tag": "finalTag",
+  "--manifest-sha256": "manifestSha256",
+  "--record": "record",
+  "--registry": "registry",
+  "--release": "release",
+  "--revision": "revision",
+  "--staging-tag": "stagingTag",
+  "--version": "version",
+} as const);
+const FLAG_OPTIONS = Object.freeze({
+  "--allow-http": "allowHttp",
+  "--require-public-read": "requirePublicRead",
+} as const);
+
+const USAGE = `Usage: ${PUBLISH_TOKEN_VARIABLE}=… node scripts/publish-package-train.ts --release <directory> --registry <url> --version <version> [--revision <commit>] [--manifest-sha256 <hex>] [--record <file>] [--staging-tag <tag>] [--final-tag <tag>] [--require-public-read]`;
+
+export function parsePublishArguments(argv: readonly string[]): {
+  values: Partial<Record<(typeof VALUE_OPTIONS)[keyof typeof VALUE_OPTIONS], string>>;
+  flags: Partial<Record<(typeof FLAG_OPTIONS)[keyof typeof FLAG_OPTIONS], true>>;
+} {
+  const values: Partial<Record<(typeof VALUE_OPTIONS)[keyof typeof VALUE_OPTIONS], string>> = {};
+  const flags: Partial<Record<(typeof FLAG_OPTIONS)[keyof typeof FLAG_OPTIONS], true>> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index] ?? "";
+    if (Object.hasOwn(FLAG_OPTIONS, argument)) {
+      flags[FLAG_OPTIONS[argument as keyof typeof FLAG_OPTIONS]] = true;
+      continue;
+    }
+    const key = Object.hasOwn(VALUE_OPTIONS, argument)
+      ? VALUE_OPTIONS[argument as keyof typeof VALUE_OPTIONS]
+      : undefined;
+    const value = argv[index + 1];
+    if (key === undefined || value === undefined || value.startsWith("--") || key in values) {
+      throw new PublicationError("INVALID_OPTIONS", USAGE);
+    }
+    values[key] = value;
+    index += 1;
+  }
+  if (!values.release || !values.registry || !values.version) {
+    throw new PublicationError("INVALID_OPTIONS", USAGE);
+  }
+  return { flags, values };
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  try {
+    const { flags, values } = parsePublishArguments(argv);
+    const record = await publishPackageTrain({
+      allowHttp: flags.allowHttp === true,
+      log: (line) => process.stdout.write(`${line}\n`),
+      registry: values.registry ?? "",
+      releaseDirectory: values.release ?? "",
+      requirePublicRead: flags.requirePublicRead === true,
+      token: process.env[PUBLISH_TOKEN_VARIABLE] ?? "",
+      version: values.version ?? "",
+      ...(values.revision === undefined ? {} : { revision: values.revision }),
+      ...(values.manifestSha256 === undefined ? {} : { manifestSha256: values.manifestSha256 }),
+      ...(values.stagingTag === undefined ? {} : { stagingTag: values.stagingTag }),
+      ...(values.finalTag === undefined ? {} : { finalTag: values.finalTag }),
+    });
+    if (values.record !== undefined) await writeFile(values.record, serializeRecord(record));
+    process.stdout.write(
+      `Published package train ${record.packageTrain.version}: ${record.packages.length} packages verified, ${record.finalTag} converged.\n`,
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof PublicationError) {
+      process.stderr.write(`${error.message}\n`);
+      for (const problem of error.problems) process.stderr.write(`  ${problem}\n`);
+      if (error.code === "INVALID_OPTIONS") return 64;
+      return error.code === "BURNED_VERSION" ? 3 : 1;
+    }
+    process.stderr.write("Publishing the package train failed unexpectedly.\n");
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main(process.argv.slice(2));
+}

scripts/test-package-publication.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# The package train publication proof (ADR 0053), against a disposable Gitea of the same version as
+# the real registry, never the real one: the publication tool publishes one exact release train,
+# and the suite proves the round trip, partial-train recovery, the hard stop on a burned version,
+# dist-tag convergence, and that the registry's public owner serves packages anonymously while only
+# the publisher team may publish.
+#
+#   bash scripts/test-package-publication.sh [--release <release directory>]
+#
+# With --release, it publishes that release (CI hands it the package-release job's artifact).
+# Without, it builds one from a worktree of HEAD, so local changes to the tool are tested against a
+# release of the committed packages.
+set -Eeuo pipefail
+
+repository_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repository_root"
+
+# shellcheck source=scripts/lib/compose-job-network.sh
+source "$repository_root/scripts/lib/compose-job-network.sh"
+# shellcheck source=scripts/lib/compose-diagnostics.sh
+source "$repository_root/scripts/lib/compose-diagnostics.sh"
+# shellcheck source=scripts/lib/ci-project.sh
+source "$repository_root/scripts/lib/ci-project.sh"
+
+fail() {
+  echo "package publication proof failed: $*" >&2
+  exit 1
+}
+
+release=""
+while (($#)); do
+  case "$1" in
+  --release)
+    release="${2:-}"
+    shift 2 || fail "--release needs a directory"
+    ;;
+  *) fail "usage: test-package-publication.sh [--release <release directory>]" ;;
+  esac
+done
+
+command -v docker >/dev/null || fail "Docker is required"
+docker compose version >/dev/null 2>&1 || fail "Docker Compose is required"
+compose_job_network_initialize || fail "the current Docker job container could not be identified"
+
+project="$(ci_project_name package-registry)"
+work="$(mktemp -d "${TMPDIR:-/tmp}/ekklesia-package-publication-XXXXXX")"
+worktree="$work/release-checkout"
+
+if [[ "$COMPOSE_JOB_NETWORK_RUNNING_IN_CONTAINER" == "true" ]]; then
+  export GITEA_PORT="0" GITEA_ROOT_URL="http://gitea:3000/"
+else
+  GITEA_PORT="$(node -e 'const s = require("net").createServer().listen(0, "127.0.0.1", () => { console.log(s.address().port); s.close(); })')"
+  export GITEA_PORT GITEA_ROOT_URL="http://127.0.0.1:$GITEA_PORT/"
+fi
+compose=(docker compose --project-name "$project" --file scripts/lib/package-registry.compose.yaml)
+
+cleanup() {
+  local exit_status=$?
+  trap - EXIT INT TERM
+  compose_job_network_disconnect || exit_status=1
+  "${compose[@]}" down --volumes --remove-orphans --timeout 10 >/dev/null 2>&1 || exit_status=1
+  if [[ -d "$worktree" ]]; then
+    git -C "$repository_root" worktree remove --force "$worktree" >/dev/null 2>&1 || true
+  fi
+  rm -rf "$work"
+  exit "$exit_status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+if [[ -z "$release" ]]; then
+  echo "==> Building a release of HEAD to publish"
+  store="$(dirname "$(pnpm store path)")"
+  git worktree add --detach --quiet "$worktree" HEAD
+  (cd "$worktree" && pnpm install --offline --frozen-lockfile --store-dir "$store" --reporter=silent)
+  node "$worktree/scripts/package-release.ts" --out "$work/release" >/dev/null
+  release="$(find "$work/release" -mindepth 1 -maxdepth 1 -type d)"
+fi
+release="$(cd "$release" && pwd)"
+
+# Masked in any Compose diagnostics below.
+COMPOSE_DIAGNOSTICS_SECRETS=()
+
+echo "==> Starting a disposable Gitea 1.27.2"
+"${compose[@]}" config --quiet || fail "the disposable registry's configuration is invalid"
+if ! up_output="$("${compose[@]}" up --detach --wait --wait-timeout 180 gitea 2>&1)"; then
+  compose_report_not_ready "$up_output" "${compose[@]}"
+  fail "the disposable Gitea did not become ready"
+fi
+if [[ "$COMPOSE_JOB_NETWORK_RUNNING_IN_CONTAINER" == "true" ]]; then
+  compose_job_network_connect gitea "${compose[@]}" || fail "the job could not join the registry's network"
+fi
+origin="${GITEA_ROOT_URL%/}"
+
+admin_password="admin-$RANDOM$RANDOM$RANDOM-$RANDOM"
+publisher_password="publisher-$RANDOM$RANDOM$RANDOM-$RANDOM"
+outsider_password="outsider-$RANDOM$RANDOM$RANDOM-$RANDOM"
+"${compose[@]}" exec -T -u git gitea gitea admin user create --admin --username ekklesia-admin \
+  --password "$admin_password" --email [email protected] --must-change-password=false >/dev/null
+
+api() {
+  local method="$1" path="$2" body="${3:-}" auth="${4:-ekklesia-admin:$admin_password}"
+  curl -fsS -X "$method" -u "$auth" -H "Content-Type: application/json" \
+    ${body:+--data "$body"} "$origin/api/v1$path"
+}
+
+echo "==> Creating public package owners, the publisher team, and an outsider"
+for user in publisher outsider; do
+  password_variable="${user}_password"
+  api POST /admin/users "{\"username\":\"$user\",\"password\":\"${!password_variable}\",\"email\":\"$user@example.invalid\",\"must_change_password\":false}" >/dev/null
+done
+owners=(River_of_Glory_Church ekklesia-burned-version ekklesia-tag-retry ekklesia-artifact-layout)
+for owner in "${owners[@]}"; do
+  api POST /orgs "{\"username\":\"$owner\",\"visibility\":\"public\"}" >/dev/null
+  team="$(api POST "/orgs/$owner/teams" '{"name":"package-publishers","includes_all_repositories":false,"can_create_org_repo":false,"units":["repo.packages"],"units_map":{"repo.packages":"write"}}' |
+    node -e 'process.stdout.write(String(JSON.parse(require("fs").readFileSync(0, "utf8")).id))')"
+  api PUT "/teams/$team/members/publisher" >/dev/null
+done
+token_for() {
+  local user="$1" password="$2"
+  api POST "/users/$user/tokens" "{\"name\":\"publish-$RANDOM\",\"scopes\":[\"write:package\"]}" "$user:$password" |
+    node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(0, "utf8")).sha1)'
+}
+publish_token="$(token_for publisher "$publisher_password")"
+outsider_token="$(token_for outsider "$outsider_password")"
+
+echo "==> Publishing the release train to it"
+EKKLESIA_TEST_REGISTRY_ORIGIN="$origin" \
+EKKLESIA_TEST_RELEASE="$release" \
+EKKLESIA_TEST_PUBLISH_TOKEN="$publish_token" \
+EKKLESIA_TEST_OUTSIDER_TOKEN="$outsider_token" \
+EKKLESIA_TEST_OWNERS="${owners[*]}" \
+  pnpm exec vitest run --config vitest.packages.integration.config.ts
+
+echo "Package publication proof passed."

scripts/test-package-release.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# The package release gate (ADR 0053): what must pass before a future step may publish a package
+# train. It publishes nothing.
+#
+#   bash scripts/test-package-release.sh [--allow-modified] [--keep <directory>]
+#
+# 1. Builds the public package train from this checkout (`scripts/package-release.ts`): clean build
+#    output, pack, inspect, release manifest.
+# 2. Builds it again from a separate worktree of the same commit, at another absolute path, and
+#    requires the two release directories to be byte-identical: every tarball, SHA256SUMS, and the
+#    manifest.
+# 3. Builds Core's verifier, then installs the release into the standalone fixture and proves it
+#    builds, packages, and verifies (`scripts/test-standalone-module.sh`).
+#
+# Nothing is built before step 1: the release builder asserts a clean source tree first, builds, and
+# asserts the build changed none of it. Every offline install uses the workspace install's own store.
+#
+# `--allow-modified` is for local development on a modified source tree. The second build is then
+# made in this checkout again, because a worktree of the commit would not hold the modifications.
+set -euo pipefail
+
+repository_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+allow_modified=() keep=""
+while (($#)); do
+  case "$1" in
+  --allow-modified)
+    allow_modified=(--allow-modified)
+    shift
+    ;;
+  --keep)
+    keep="${2:-}"
+    [[ -n "$keep" ]] || { echo "usage: --keep <directory>" >&2; exit 64; }
+    shift 2
+    ;;
+  *)
+    echo "usage: test-package-release.sh [--allow-modified] [--keep <directory>]" >&2
+    exit 64
+    ;;
+  esac
+done
+
+# The workspace install's own pnpm store. pnpm chooses a store per file system, so an install in a
+# temporary directory would otherwise look in another, empty one; every install here is offline.
+store="$(dirname "$(cd "$repository_root" && pnpm store path)")"
+export EKKLESIA_PNPM_STORE="$store"
+
+work="$(mktemp -d "${TMPDIR:-/tmp}/ekklesia-package-release-XXXXXX")"
+worktree="$work/second-checkout"
+cleanup() {
+  if [[ -d "$worktree" ]]; then
+    git -C "$repository_root" worktree remove --force "$worktree" >/dev/null 2>&1 || true
+  fi
+  rm -rf "$work"
+}
+trap cleanup EXIT
+
+echo "==> Building the package train"
+node "$repository_root/scripts/package-release.ts" --out "$work/first" "${allow_modified[@]}"
+release="$(find "$work/first" -mindepth 1 -maxdepth 1 -type d)"
+
+echo "==> Building it again, to prove the artifacts are reproducible"
+if ((${#allow_modified[@]})); then
+  node "$repository_root/scripts/package-release.ts" --out "$work/second" "${allow_modified[@]}" >/dev/null
+else
+  git -C "$repository_root" worktree add --detach --quiet "$worktree" HEAD
+  (cd "$worktree" && pnpm install --offline --frozen-lockfile --store-dir "$store" --reporter=silent)
+  node "$worktree/scripts/package-release.ts" --out "$work/second" >/dev/null
+fi
+if ! diff -r "$release" "$(find "$work/second" -mindepth 1 -maxdepth 1 -type d)"; then
+  echo "package release gate failed: two builds of the same commit produced different artifacts" >&2
+  exit 1
+fi
+echo "    byte-identical: $(ls "$release" | wc -l) files"
+
+# The consumer proof verifies with Core's own verifier. Built only now, after both releases: the
+# release builder asserts a clean source tree before it builds anything.
+echo "==> Building Core's verifier"
+(cd "$repository_root" && pnpm exec turbo run build --filter=@ekklesia/core --output-logs=errors-only >/dev/null)
+
+echo "==> Consuming the release from a standalone module"
+bash "$repository_root/scripts/test-standalone-module.sh" --release "$release" "${allow_modified[@]}"
+
+# The release this gate proved, for a later job to publish exactly (`--keep`): copied only now, after
+# every check passed, into a directory that must not hold an earlier one.
+if [[ -n "$keep" ]]; then
+  mkdir -p "$keep"
+  [[ ! -e "$keep/$(basename "$release")" ]] || { echo "$keep already holds this release" >&2; exit 1; }
+  cp -R "$release" "$keep/"
+  echo "    kept in $keep/$(basename "$release")"
+fi
+
+echo "Package release gate passed."

scripts/test-standalone-module.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# The standalone consumer proof (ADR 0053): a module outside this repository consumes one package
+# release train, the exact tarballs `scripts/package-release.ts` produced, and nothing else.
+#
+#   bash scripts/test-standalone-module.sh --release <release directory> [--allow-modified]
+#
+# The release directory is checked against its manifest first; then every @ekklesia/* package, the
+# module's own and the ones they depend on, installs from those tarballs, with no workspace link, no
+# Ekklesia source checkout, and no registry: third-party packages come from the local pnpm store the
+# workspace install already filled (`--offline`). The module then installs again from its lockfile
+# alone, type-checks every declaration it reaches (`skipLibCheck: false`), builds its backend and
+# UI, packages with the release's own `@ekklesia/module-pack`, and verifies with Core's verifier.
+#
+# `--allow-modified` accepts a release built from a modified source tree, for local development.
+# Core must be built (`core/dist`): the module is verified with Core's own verifier.
+set -euo pipefail
+
+repository_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+fail() {
+  echo "standalone consumer proof failed: $*" >&2
+  exit 1
+}
+
+release="" allow_modified=""
+while (($#)); do
+  case "$1" in
+  --release)
+    release="${2:-}"
+    shift 2 || fail "--release needs a directory"
+    ;;
+  --allow-modified)
+    allow_modified=1
+    shift
+    ;;
+  *) fail "usage: test-standalone-module.sh --release <release directory> [--allow-modified]" ;;
+  esac
+done
+[[ -n "$release" && -d "$release" ]] || fail "no release directory given"
+
+# Third-party packages come from the workspace install's own pnpm store, offline. pnpm chooses a
+# store per file system, so the module, in a temporary directory, is pointed at it explicitly.
+store="${EKKLESIA_PNPM_STORE:-$(dirname "$(cd "$repository_root" && pnpm store path)")}"
+
+work="$(mktemp -d "${TMPDIR:-/tmp}/ekklesia-standalone-XXXXXX")"
+trap 'rm -rf "$work"' EXIT
+
+# The module installs from a copy beside it, named by a fixed relative path. pnpm names a file:
+# tarball's install directory after that path, and the bundler keeps those names in its comments, so
+# an absolute path would make the module package depend on where the release happened to sit. (From
+# a registry, the directory is simply `<name>@<version>`.) The copy is what is checked and installed.
+cp -R "$release" "$work/release"
+release="$work/release"
+
+echo "==> Checking the release against its manifest"
+# Prints the train version, then one `name<TAB>file<TAB>integrity` line per package.
+node --input-type=module - "$repository_root" "$release" "$allow_modified" >"$work/train.tsv" <<'EOF'
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [repositoryRoot, release, allowModified] = process.argv.slice(2);
+const { PACKAGE_TRAIN_MANIFEST, releaseDirectoryProblems } = await import(
+  pathToFileURL(path.join(repositoryRoot, "scripts", "package-release.ts")).href
+);
+const manifest = JSON.parse(readFileSync(path.join(release, PACKAGE_TRAIN_MANIFEST), "utf8"));
+const files = new Map(readdirSync(release).map((file) => [file, readFileSync(path.join(release, file))]));
+const problems = releaseDirectoryProblems(manifest, files);
+if (manifest.source?.modified !== false && allowModified !== "1") {
+  problems.push("the release was built from a modified source tree.");
+}
+if (problems.length > 0) {
+  console.error(problems.join("\n"));
+  process.exit(1);
+}
+console.log(manifest.version);
+for (const entry of manifest.packages) console.log(`${entry.name}\t${entry.file}\t${entry.integrity}`);
+EOF
+version="$(head -1 "$work/train.tsv")"
+echo "    package train $version, $(($(wc -l <"$work/train.tsv") - 1)) packages"
+
+module="$work/standalone-proof"
+cp -R "$repository_root/tests/fixtures/standalone-module" "$module"
+cp "$repository_root/LICENSE" "$module/LICENSE"
+
+# The fixture pins the release's module-pack exactly, as every module repository must.
+pinned="$(node -p 'require(process.argv[1]).devDependencies["@ekklesia/module-pack"]' "$module/package.json")"
+[[ "$pinned" == "$version" ]] ||
+  fail "the fixture pins @ekklesia/module-pack $pinned, not the release's $version"
+
+# A module repository's own pnpm settings: esbuild (used by the UI build and the packager) runs its
+# install script. And, for this proof only, every @ekklesia/* package resolves to its release
+# tarball, exactly as it would to the published version.
+{
+  echo "allowBuilds:"
+  echo "  esbuild: true"
+  echo "overrides:"
+  tail -n +2 "$work/train.tsv" | while IFS=$'\t' read -r name file _; do
+    echo "  \"$name\": \"file:../release/$file\""
+  done
+} >"$module/pnpm-workspace.yaml"
+
+echo "==> Installing the module from the release tarballs, offline"
+(cd "$module" && pnpm install --offline --store-dir "$store" --reporter=append-only >"$work/install.log" 2>&1) ||
+  {
+    tail -40 "$work/install.log" >&2
+    fail "install (third-party packages come from the local store: run pnpm install in the workspace first)"
+  }
+
+echo "==> Checking the lockfile records each release artifact's own integrity"
+node --input-type=module - "$module/pnpm-lock.yaml" "$work/train.tsv" <<'EOF'
+import { readFileSync } from "node:fs";
+
+const [lockfile, train] = process.argv.slice(2);
+const lock = readFileSync(lockfile, "utf8");
+const failures = [];
+for (const line of readFileSync(train, "utf8").trim().split("\n").slice(1)) {
+  const [name, file, integrity] = line.split("\t");
+  // pnpm records a file: tarball under `<name>@file:<path>` with its computed integrity.
+  const at = lock.indexOf(`\n  '${name}@file:`);
+  const entry = at === -1 ? "" : lock.slice(at, lock.indexOf("\n\n", at));
+  if (!entry.includes(file)) failures.push(`${name} is not installed from ${file}`);
+  else if (!entry.includes(`integrity: ${integrity}`)) failures.push(`${name}'s integrity differs from the release manifest`);
+}
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+EOF
+
+echo "==> Reinstalling from the lockfile alone (--frozen-lockfile)"
+rm -rf "$module/node_modules"
+(cd "$module" && pnpm install --offline --frozen-lockfile --store-dir "$store" --reporter=append-only >"$work/frozen.log" 2>&1) ||
+  { tail -40 "$work/frozen.log" >&2; fail "frozen-lockfile install"; }
+
+echo "==> Checking what the install resolved"
+(cd "$module" && node --input-type=module - "$module" "$version" <<'EOF')
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const [moduleDirectory, version] = process.argv.slice(2);
+const modules = path.join(moduleDirectory, "node_modules");
+const store = readdirSync(path.join(modules, ".pnpm"));
+const failures = [];
+// The Module SDK and its dependencies never pull Drizzle into a module that does not ask for it.
+if (store.some((entry) => entry.startsWith("drizzle-orm@"))) failures.push("drizzle-orm is installed");
+// One React, the module's own, shared by @ekklesia/ui.
+const reacts = store.filter((entry) => /^react@/u.test(entry));
+if (reacts.length !== 1) failures.push(`${reacts.length} copies of react are installed`);
+const fromModule = createRequire(path.join(moduleDirectory, "package.json"));
+const ui = realpathSync(path.join(modules, "@ekklesia", "ui", "package.json"));
+if (realpathSync(fromModule.resolve("react")) !== realpathSync(createRequire(ui).resolve("react"))) {
+  failures.push("@ekklesia/ui resolves a different react");
+}
+// @ekklesia/contracts is installed only because the packages above depend on it: never a direct
+// dependency, and never reachable by name from the module's own code.
+const own = JSON.parse(readFileSync(path.join(moduleDirectory, "package.json"), "utf8"));
+for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+  if (own[field]?.["@ekklesia/contracts"] !== undefined) failures.push(`the module lists contracts in ${field}`);
+}
+if (existsSync(path.join(modules, "@ekklesia", "contracts"))) failures.push("contracts is a direct install");
+if (!store.some((entry) => entry.startsWith("@ekklesia+contracts@"))) failures.push("contracts is not installed");
+// Every Ekklesia package came from a tarball into the module's own store, never from a link, and
+// each one, module-pack included, is exactly the release's version.
+for (const name of readdirSync(path.join(modules, "@ekklesia"))) {
+  const real = realpathSync(path.join(modules, "@ekklesia", name));
+  if (!real.startsWith(path.join(modules, ".pnpm") + path.sep)) {
+    failures.push(`@ekklesia/${name} is linked from outside the module`);
+  }
+  const installed = JSON.parse(readFileSync(path.join(real, "package.json"), "utf8"));
+  if (installed.version !== version) failures.push(`@ekklesia/${name} is ${installed.version}`);
+}
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+EOF
+
+# The published declarations must stand on their own: no package may name a module a consumer has
+# not installed (Drizzle above all), and the fixture checks every declaration it reaches.
+for project in tsconfig.json tsconfig.ui.json; do
+  (cd "$module" && ./node_modules/.bin/tsc --showConfig --project "$project") |
+    node -e 'const c = JSON.parse(require("fs").readFileSync(0, "utf8")); if (c.compilerOptions.skipLibCheck !== false) process.exit(1);' ||
+    fail "$project does not typecheck with skipLibCheck: false"
+done
+
+echo "==> Typechecking (skipLibCheck: false) and building"
+(cd "$module" && pnpm run typecheck && pnpm run build) >"$work/build.log" 2>&1 ||
+  { tail -40 "$work/build.log" >&2; fail "typecheck or build"; }
+
+# The packager needs no workspace file: the module's Node.js range is its own engines.node. The
+# binary is run directly, because pnpm would re-resolve the module without the proof's overrides.
+rm "$module/pnpm-workspace.yaml"
+
+echo "==> Packaging with the release's @ekklesia/module-pack"
+(cd "$module" && ./node_modules/.bin/ekklesia-pack-module --module . --target any --out "$work/out" \
+  --license-file LICENSE --source-revision 86ae907f59458508e3277666cdd214f5bd7c1078)
+archive="$work/out/standalone-proof-0.1.0-any.tar.gz"
+
+echo "==> Verifying with the platform verifier"
+(cd "$repository_root" && node core/dist/cli/verify-module-package.js "$archive" \
+  --sha256-file "$archive.sha256" --extract-to "$work/verified")
+
+echo "==> Checking the package's own description"
+node --input-type=module - "$work/verified" "$version" "$repository_root" "$work" "$release" <<'EOF'
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const [verified, version, repositoryRoot, work, release] = process.argv.slice(2);
+const read = (file) => readFileSync(path.join(verified, file), "utf8");
+const metadata = JSON.parse(read("ekklesia.package.json"));
+const failures = [];
+const incorporates = metadata.incorporates ?? {};
+for (const name of ["@ekklesia/contracts", "@ekklesia/module-database", "@ekklesia/module-sdk"]) {
+  if (incorporates[name] !== version) failures.push(`incorporates ${name}@${incorporates[name]}`);
+}
+const packager = metadata.provenance?.packager ?? {};
+if (packager.name !== "@ekklesia/module-pack" || packager.version !== version) {
+  failures.push(`packed by ${packager.name}@${packager.version}, not the release's module-pack`);
+}
+if (metadata.runtime?.node !== ">=24.11.0 <25") failures.push("runtime.node is not engines.node");
+if (metadata.transitional !== undefined) failures.push("records transitional database facts");
+const notices = read("THIRD_PARTY_NOTICES");
+if (notices.includes("@ekklesia/")) failures.push("credits Ekklesia as third-party");
+// The UI bundle holds one React, the module's own.
+const reacts = notices.split("\n").filter((line) => /^react \d/u.test(line));
+if (reacts.length !== 1) failures.push(`credits ${reacts.length} copies of react`);
+for (const entry of readdirSync(verified, { recursive: true, withFileTypes: true })) {
+  if (!entry.isFile()) continue;
+  const text = readFileSync(path.join(entry.parentPath, entry.name), "latin1");
+  for (const local of [repositoryRoot, work, release]) {
+    if (text.includes(local)) failures.push(`${entry.name} names a local path`);
+  }
+  if (/drizzle-orm/u.test(text) && entry.name.endsWith(".js")) failures.push(`${entry.name} bundles Drizzle`);
+  // A file: install directory's name keeps the path pnpm installed it from: only the fixed one.
+  for (const match of text.matchAll(/@file\+([^/"'\s]*)/gu)) {
+    if (!match[1]?.startsWith("..+release+")) failures.push(`${entry.name} names an install path`);
+  }
+}
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+console.log(`incorporates ${JSON.stringify(incorporates)}`);
+EOF
+
+echo "Standalone consumer proof passed for package train $version."

surfaces/shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekklesia/shell",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",

templates/module/ekklesia.module.json

@@ -5,8 +5,8 @@
   "description": "A minimal Ekklesia module template with backend behavior and optional primary and display UI.",
   "version": "0.1.0",
   "compatibility": {
-    "platform": "^0.1.0",
+    "platform": "^0.2.0",
-    "moduleSdk": "^0.1.0"
+    "moduleSdk": "^0.2.0"
   },
   "database": {
     "abi": 1

templates/module/package.json

@@ -4,6 +4,9 @@
   "license": "AGPL-3.0-or-later",
   "private": true,
   "type": "module",
+  "engines": {
+    "node": ">=24.11.0 <25"
+  },
   "files": [
     "dist",
     "drizzle",

templates/module/src/schema/tables.ts

@@ -1,4 +1,4 @@
-import { createModuleTable } from "@ekklesia/module-sdk";
+import { createModuleTable } from "@ekklesia/module-database/drizzle";
 import { text, uuid } from "drizzle-orm/pg-core";
 
 const moduleTable = createModuleTable("example");

templates/module/src/server/index.ts

@@ -27,7 +27,7 @@ export default defineModuleRuntime({
       // make this choice consciously: 0 means "no body accepted" (a non-empty declared or streamed
       // body is rejected before this handler ever runs); a route that does accept a body declares
       // its own explicit byte maximum instead, up to the platform's ceiling
-      // (`MODULE_ROUTE_MAX_BODY_BYTES_CEILING`, `@ekklesia/contracts`).
+      // (`MODULE_ROUTE_MAX_BODY_BYTES_CEILING`, `@ekklesia/module-sdk`).
       maxBodyBytes: 0,
       async handler(_request, context) {
         const database = moduleDrizzle(context.services.database);