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]>
fix: hand npm the release artifact's absolute path, so publishing finds it
2026-10-08 23:22:00 +00:00 · 2026-10-08 17:51:22 -05:00 · 2026-10-08 22:36:19 +00:00 · 2026-10-08 17:26:13 -05:00 · 2026-10-08 16:31:57 +00:00 · 2026-10-08 10:24:17 -05:00
57 changed files with 4054 additions and 449 deletions
@@ -128,10 +128,15 @@ jobs:
        if: always()
        run: bash scripts/ci-sweep.sh --job

-  standalone-module:
+  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
@@ -154,10 +159,97 @@ jobs:
      - name: Install dependencies
        run: pnpm install --frozen-lockfile

-      # ADR 0053: pack and inspect the public packages, then install them into a module outside this
-      # repository and prove it builds, packages, and verifies. Nothing is published.
-      - name: Build a standalone module from the packed public packages
-        run: pnpm test:standalone-module
+      # 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
@@ -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
@@ -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/
@@ -20,5 +24,7 @@ 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:pack` writes the packed public packages here (scripts/pack-public-packages.ts).
-.public-packages/
+# `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/
@@ -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
@@ -63,11 +63,16 @@ omits licence material, the packager may add reviewed licence supplements
 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), Proposed):
+([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. CI packs and inspects those packages and proves a module outside the repository
-installs, builds, packages, and verifies from the tarballs alone. They are not published to any
-registry yet.
+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`,
@@ -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",
@@ -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"]);
@@ -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",
@@ -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();
@@ -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.
@@ -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",
@@ -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",
-    "moduleSdk": "^0.1.0"
+    "platform": "^0.2.0",
+    "moduleSdk": "^0.2.0"
  },
  "permissions": [
    {
@@ -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",
  };
 }

@@ -18,8 +18,8 @@ import {

 const platform = {
  databaseRuntime: { "drizzle-orm": "0.45.2" },
-  moduleSdkVersion: "0.1.2",
-  platformVersion: "0.1.2",
+  moduleSdkVersion: "0.2.0",
+  platformVersion: "0.2.0",
 } as const;

 const temporaryDirectories: string[] = [];
@@ -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");
@@ -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: [],
@@ -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;
@@ -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 \
  .
 ```

@@ -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
@@ -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.
@@ -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
@@ -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.
+
@@ -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.
@@ -73,16 +73,37 @@ entrypoints. A module in its own repository depends on the published packages in

 ### Developing a module in its own repository

-> **Status:** the public packages are ready for a standalone module, and a release check proves it
-> from locally packed tarballs. They are **not published yet**, and there is no registry URL to use
-> yet: registry publication is the next slice
-> ([ADR 0053](../architecture/decisions/0053-standalone-module-development-packages.md)). This
-> section describes the workflow that publication enables.
+> **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 |
@@ -110,17 +131,17 @@ import it yourself, because what it exports is the platform's, not a supported a
    "build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui"
  },
  "dependencies": {
-    "@ekklesia/module-database": "^0.1.2",
-    "@ekklesia/module-sdk": "^0.1.2",
-    "@ekklesia/module-ui-sdk": "^0.1.2",
-    "@ekklesia/ui": "^0.1.2",
+    "@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.1.2",
-    "@ekklesia/module-ui-build": "^0.1.2",
-    "@ekklesia/typescript-config": "^0.1.2",
+    "@ekklesia/module-pack": "0.2.0",
+    "@ekklesia/module-ui-build": "^0.2.0",
+    "@ekklesia/typescript-config": "^0.2.0",
    "typescript": "7.0.2"
  }
 }
@@ -148,6 +169,9 @@ import it yourself, because what it exports is the platform's, not a supported a
  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.
@@ -157,10 +181,11 @@ Packaging and verification work exactly as for a module in this repository
 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 before any release: `pnpm packages:pack` builds, packs, and inspects the public
-packages, and `bash scripts/test-standalone-module.sh` installs them into a module outside the
-repository (`tests/fixtures/standalone-module`), with no workspace link and no Ekklesia registry,
-then typechecks, builds, packages, and verifies it.
+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

@@ -341,8 +366,8 @@ without executing module code:
  "name": "Calendar",
  "version": "0.1.0",
  "compatibility": {
-    "platform": "^0.1.0",
-    "moduleSdk": "^0.1.0"
+    "platform": "^0.2.0",
+    "moduleSdk": "^0.2.0"
  },
  "dependencies": {
    "modules": {
@@ -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,11 +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:pack": "node scripts/pack-public-packages.ts --out .public-packages",
+    "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:standalone-module": "pnpm build && bash scripts/test-standalone-module.sh",
+    "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",
@@ -1,6 +1,6 @@
 {
  "name": "@ekklesia/contracts",
-  "version": "0.1.2",
+  "version": "0.2.0",
  "license": "AGPL-3.0-or-later",
  "type": "module",
  "files": [
@@ -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": [
@@ -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": [
@@ -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": [
@@ -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",
-    "moduleSdk": "^0.1.0"
+    "platform": "^0.2.0",
+    "moduleSdk": "^0.2.0"
  },
  "database": {
    "abi": 1
@@ -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",
-          platformVersion: "0.1.2",
+          moduleSdkVersion: "0.2.0",
+          platformVersion: "0.2.0",
        },
      }),
    ).resolves.toMatchObject({ moduleId: "native-proof", target: "linux-x64-glibc" });
@@ -109,7 +109,7 @@ export async function fixtureModule(options: FixtureModuleOptions = {}): Promise
    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: [],
@@ -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": [
@@ -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": [
@@ -1,6 +1,6 @@
 {
  "name": "@ekklesia/module-ui-host",
-  "version": "0.1.2",
+  "version": "0.2.0",
  "private": true,
  "license": "AGPL-3.0-or-later",
  "type": "module",
@@ -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": [
@@ -1,6 +1,6 @@
 {
  "name": "@ekklesia/typescript-config",
-  "version": "0.1.2",
+  "version": "0.2.0",
  "license": "AGPL-3.0-or-later",
  "files": [
    "base.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": [
@@ -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 };
@@ -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;
@@ -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
@@ -1,304 +0,0 @@
-import { execFile } from "node:child_process";
-import { mkdir, mkdtemp, readdir, readFile, realpath, rm, stat } 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 module-development package set (ADR 0053), and the release check that packs it.
- *
- *   node scripts/pack-public-packages.ts --out <directory>
- *
- * Rebuilds each public package from clean output, packs it with `pnpm pack`, and inspects every
- * tarball before anything may consume it: only the package's built files, its declarations, and a
- * `LICENSE`; a manifest with no `workspace:` range, no install-time lifecycle script, the explicit
- * distribution marker, and the one coordinated version. It publishes nothing.
- */
-
-const execFileAsync = promisify(execFile);
-const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-
-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";
-
-/** 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",
-]);
-
-/** The fields a consumer's install resolves. `devDependencies` are never installed from a published
- * package, so a tooling package's test-only use of a private package is not a problem there. */
-const INSTALLED_DEPENDENCY_FIELDS = Object.freeze([
-  "dependencies",
-  "peerDependencies",
-  "optionalDependencies",
-]);
-
-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. */
-export function packedManifestProblems(
-  manifest: Readonly<Record<string, unknown>>,
-  expected: { readonly name: string; readonly version: string },
-): 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");
-  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 INSTALLED_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}`);
-      }
-    }
-  }
-  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;
-}
-
-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;
-}
-
-export interface PackedPackage {
-  readonly name: string;
-  readonly tarball: string;
-  readonly files: number;
-  readonly bytes: number;
-}
-
-async function pnpm(arguments_: readonly string[], cwd: string): Promise<string> {
-  const { stdout } = await execFileAsync("pnpm", [...arguments_], {
-    cwd,
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  return stdout;
-}
-
-async function packOne(
-  entry: PublicPackage,
-  version: string,
-  outDirectory: string,
-  scratch: string,
-): Promise<{ packed: PackedPackage; problems: string[] }> {
-  const directory = path.join(repositoryRoot, entry.directory);
-  const report = JSON.parse(
-    await pnpm(["pack", "--json", "--pack-destination", outDirectory], directory),
-  ) as { filename: string };
-  const tarball = report.filename;
-  const extracted = path.join(scratch, entry.name.replace("/", "+"));
-  await mkdir(extracted, { recursive: true });
-  await execFileAsync("tar", ["-xzf", tarball, "-C", extracted]);
-  const root = path.join(extracted, "package");
-  const files = await filesUnder(root);
-  const manifest = await readJson(path.join(root, "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 }),
-    ...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()]) {
-      if (text.includes(local)) problems.push(`${file} names a local path`);
-    }
-  }
-  return {
-    packed: { bytes: (await stat(tarball)).size, files: files.length, name: entry.name, tarball },
-    problems: [...new Set(problems)],
-  };
-}
-
-/** Rebuilds the public set from clean output, packs it into `outDirectory`, and inspects it. */
-export async function packPublicPackages(outDirectory: string): Promise<{
-  readonly packed: readonly PackedPackage[];
-  readonly problems: readonly string[];
-}> {
-  const version = String((await readJson(path.join(repositoryRoot, "package.json"))).version);
-  await mkdir(outDirectory, { recursive: true });
-  const out = await realpath(outDirectory);
-
-  // 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 pnpm(
-    [
-      "exec",
-      "turbo",
-      "run",
-      "build",
-      "--force",
-      "--output-logs=errors-only",
-      ...PUBLIC_PACKAGES.map((entry) => `--filter=${entry.name}`),
-    ],
-    repositoryRoot,
-  );
-
-  const scratch = await mkdtemp(path.join(tmpdir(), "ekklesia-public-packages-"));
-  try {
-    const packed: PackedPackage[] = [];
-    const problems: string[] = [];
-    for (const entry of PUBLIC_PACKAGES) {
-      const result = await packOne(entry, version, out, scratch);
-      packed.push(result.packed);
-      problems.push(...result.problems.map((problem) => `${entry.name} ${problem}.`));
-    }
-    return { packed, problems };
-  } finally {
-    await rm(scratch, { force: true, recursive: true });
-  }
-}
-
-async function main(argv: readonly string[]): Promise<number> {
-  if (argv.length !== 2 || argv[0] !== "--out" || !argv[1]) {
-    process.stderr.write("Usage: node scripts/pack-public-packages.ts --out <directory>\n");
-    return 64;
-  }
-  try {
-    const { packed, problems } = await packPublicPackages(path.resolve(argv[1]));
-    for (const entry of packed) {
-      process.stdout.write(
-        `${path.basename(entry.tarball)}: ${entry.files} files, ${entry.bytes} bytes\n`,
-      );
-    }
-    if (problems.length > 0) {
-      for (const problem of problems) process.stderr.write(`${problem}\n`);
-      return 1;
-    }
-    process.stdout.write(`Packed and inspected ${packed.length} public packages.\n`);
-    return 0;
-  } catch {
-    process.stderr.write("Packing the public packages 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));
-}
@@ -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));
+}
@@ -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));
+}
@@ -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."
@@ -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."
@@ -1,77 +1,175 @@
 #!/usr/bin/env bash
-# The standalone module-development proof (ADR 0053): a module outside this repository, installed
-# from locally packed @ekklesia/* tarballs, with no workspace link and no Ekklesia registry, must
-# install, typecheck, build its backend and UI, package with the canonical packager, and verify with
-# the platform's own verifier.
+# 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
+#   bash scripts/test-standalone-module.sh --release <release directory> [--allow-modified]
 #
-# Third-party packages (React, TypeScript, esbuild, ...) come from the public npm registry as usual.
-# Nothing is published, and nothing outside a temporary directory is written except the packed
-# public packages' rebuilt dist/ output.
+# 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)"
-work="$(mktemp -d "${TMPDIR:-/tmp}/ekklesia-standalone-XXXXXX")"
-trap 'rm -rf "$work"' EXIT

 fail() {
-  echo "standalone module proof failed: $*" >&2
+  echo "standalone consumer proof failed: $*" >&2
  exit 1
 }

-version="$(node -p 'require(process.argv[1]).version' "$repository_root/package.json")"
+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"

-echo "==> Packing and inspecting the public package set ($version)"
-node "$repository_root/scripts/pack-public-packages.ts" --out "$work/tarballs"
+# 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, the module's own and the ones
-# they depend on, resolves to its packed tarball, exactly as it would to a published version.
+# 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:"
-  for tarball in "$work"/tarballs/*.tgz; do
-    name="$(tar -xzOf "$tarball" package/package.json | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).name')"
-    echo "  \"$name\": \"file:$tarball\""
+  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 tarballs"
-(cd "$module" && pnpm install --reporter=append-only >"$work/install.log" 2>&1) ||
-  { tail -40 "$work/install.log" >&2; fail "install"; }
+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" <<'EOF')
-import { readdirSync, realpathSync } from "node:fs";
+(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] = process.argv.slice(2);
-const store = readdirSync(path.join(moduleDirectory, "node_modules", ".pnpm"));
+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 use it.
+// 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(moduleDirectory, "node_modules", "@ekklesia", "ui", "package.json"));
-const fromUi = createRequire(ui);
-if (realpathSync(fromModule.resolve("react")) !== realpathSync(fromUi.resolve("react"))) {
+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");
 }
-// Every Ekklesia package came from a tarball into the module's own store, never from a link.
-for (const name of readdirSync(path.join(moduleDirectory, "node_modules", "@ekklesia"))) {
-  const real = realpathSync(path.join(moduleDirectory, "node_modules", "@ekklesia", name));
-  if (!real.startsWith(path.join(moduleDirectory, "node_modules", ".pnpm") + path.sep)) {
+// @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"));
@@ -95,7 +193,7 @@ echo "==> Typechecking (skipLibCheck: false) and building"
 # 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 canonical packager"
+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"
@@ -105,11 +203,11 @@ echo "==> Verifying with the platform verifier"
  --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" <<'EOF'
+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] = process.argv.slice(2);
+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 = [];
@@ -117,6 +215,10 @@ 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");
@@ -127,8 +229,14 @@ 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");
-  if (text.includes(repositoryRoot) || text.includes(work)) failures.push(`${entry.name} names a local path`);
+  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"));
@@ -137,4 +245,4 @@ if (failures.length > 0) {
 console.log(`incorporates ${JSON.stringify(incorporates)}`);
 EOF

-echo "Standalone module proof passed."
+echo "Standalone consumer proof passed for package train $version."
@@ -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",
@@ -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",
-    "moduleSdk": "^0.1.0"
+    "platform": "^0.2.0",
+    "moduleSdk": "^0.2.0"
  },
  "database": {
    "abi": 1
@@ -97,12 +97,18 @@ describe("CI scripts on a shared Docker daemon", () => {
      >;
    };
    const startsStacks =
-      /smoke-infrastructure\.sh|test:migrations:integration|smoke-deploy\.sh|check-image\.sh|docker build/u;
+      /smoke-infrastructure\.sh|test:migrations:integration|smoke-deploy\.sh|check-image\.sh|test-package-publication\.sh|docker build/u;
    const jobs = Object.entries(workflow.jobs).filter(([, job]) =>
      job.steps.some((step) => startsStacks.test(step.run ?? "")),
    );
    expect(jobs.map(([id]) => id).sort()).toEqual(
-      ["deploy-smoke", "image-build", "infrastructure-smoke", "migration-smoke"].sort(),
+      [
+        "deploy-smoke",
+        "image-build",
+        "infrastructure-smoke",
+        "migration-smoke",
+        "package-publication",
+      ].sort(),
    );
    for (const [id, job] of jobs) {
      expect(job.env?.EKKLESIA_CI_JOB_KEY, id).toBeTruthy();
@@ -5,8 +5,8 @@
  "description": "Proves a module builds, packages, and verifies from published Ekklesia packages alone.",
  "version": "0.1.0",
  "compatibility": {
-    "platform": "^0.1.0",
-    "moduleSdk": "^0.1.0"
+    "platform": "^0.2.0",
+    "moduleSdk": "^0.2.0"
  },
  "database": {
    "abi": 1
@@ -13,18 +13,18 @@
    "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json"
  },
  "dependencies": {
-    "@ekklesia/design-tokens": "^0.1.2",
-    "@ekklesia/module-database": "^0.1.2",
-    "@ekklesia/module-sdk": "^0.1.2",
-    "@ekklesia/module-ui-sdk": "^0.1.2",
-    "@ekklesia/ui": "^0.1.2",
+    "@ekklesia/design-tokens": "^0.2.0",
+    "@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.1.2",
-    "@ekklesia/module-ui-build": "^0.1.2",
-    "@ekklesia/typescript-config": "^0.1.2",
+    "@ekklesia/module-pack": "0.2.0",
+    "@ekklesia/module-ui-build": "^0.2.0",
+    "@ekklesia/typescript-config": "^0.2.0",
    "@types/node": "24.13.3",
    "@types/react": "19.2.18",
    "@types/react-dom": "19.2.4",
@@ -0,0 +1,359 @@
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  type LocalTrain,
+  loadReleaseTrain,
+  normalizeRegistry,
+  type PublicationRecord,
+  PUBLISH_TOKEN_VARIABLE,
+  packumentUrl,
+  publicationOrder,
+  publishPackageTrain,
+} from "../scripts/publish-package-train.js";
+
+/**
+ * The publication tool against a disposable Gitea 1.27.2 (scripts/test-package-publication.sh),
+ * configured as the real registry is meant to be: public package owners anyone may read from, and a
+ * publisher team that alone may publish. Each scenario uses its own owner, so they never interfere.
+ */
+
+const execFileAsync = promisify(execFile);
+/** Set by scripts/test-package-publication.sh for the disposable registry it started. */
+const setting = (name: string): string => process.env[name] ?? "";
+const origin = setting("EKKLESIA_TEST_REGISTRY_ORIGIN");
+const releaseDirectory = setting("EKKLESIA_TEST_RELEASE");
+const publishToken = setting("EKKLESIA_TEST_PUBLISH_TOKEN");
+const outsiderToken = setting("EKKLESIA_TEST_OUTSIDER_TOKEN");
+const [mainOwner, burnedOwner, tagOwner, layoutOwner] = setting("EKKLESIA_TEST_OWNERS").split(" ");
+if (!origin || !releaseDirectory || !publishToken || !outsiderToken || !layoutOwner) {
+  throw new Error("Run this suite with scripts/test-package-publication.sh.");
+}
+const registryOf = (owner: string | undefined) =>
+  normalizeRegistry(`${origin}/api/packages/${owner}/npm/`, true);
+
+let train: LocalTrain;
+let order: string[];
+const scratch: string[] = [];
+
+beforeAll(async () => {
+  const manifest = JSON.parse(
+    await readFile(path.join(releaseDirectory, "ekklesia-package-train.json"), "utf8"),
+  ) as { version: string; source: { revision: string } };
+  train = await loadReleaseTrain(releaseDirectory, {
+    revision: manifest.source.revision,
+    version: manifest.version,
+  });
+  order = publicationOrder(train.packages).map((entry) => entry.entry.name);
+});
+
+afterAll(async () => {
+  await Promise.all(scratch.splice(0).map((dir) => rm(dir, { force: true, recursive: true })));
+});
+
+function publish(
+  owner: string | undefined,
+  hooks?: Parameters<typeof publishPackageTrain>[0]["hooks"],
+) {
+  return publishPackageTrain({
+    allowHttp: true,
+    registry: registryOf(owner),
+    releaseDirectory,
+    requirePublicRead: true,
+    revision: train.manifest.source.revision,
+    token: publishToken,
+    version: train.manifest.version,
+    ...(hooks === undefined ? {} : { hooks }),
+  });
+}
+
+/** What anyone, signed in or not, gets for a package: its packument, or undefined on 404. */
+async function anonymousPackument(owner: string | undefined, name: string) {
+  const response = await fetch(packumentUrl(registryOf(owner), name));
+  if (response.status === 404) return undefined;
+  expect(response.status).toBe(200);
+  return (await response.json()) as {
+    versions: Record<string, { dist: { tarball: string; integrity: string } }>;
+    "dist-tags": Record<string, string>;
+  };
+}
+
+async function anonymousBytes(url: string): Promise<Buffer> {
+  const response = await fetch(url);
+  expect(response.status).toBe(200);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function local(name: string) {
+  const found = train.packages.find((entry) => entry.entry.name === name);
+  if (!found) throw new Error(name);
+  return found;
+}
+
+/** `npm publish <file>` outside the tool, as an operator or an attacker might run it. */
+async function npmPublish(owner: string | undefined, file: string, token: string): Promise<string> {
+  const home = await mkdtemp(path.join(tmpdir(), "ekklesia-npm-"));
+  scratch.push(home);
+  const registry = registryOf(owner);
+  const url = new URL(registry);
+  await writeFile(
+    path.join(home, "npmrc"),
+    `registry=${registry}\n//${url.host}${url.pathname}:_authToken=\${${PUBLISH_TOKEN_VARIABLE}}\n`,
+  );
+  try {
+    await execFileAsync(
+      "npm",
+      ["publish", file, "--tag", "manual", "--access", "public", "--ignore-scripts"],
+      {
+        cwd: home,
+        env: {
+          [PUBLISH_TOKEN_VARIABLE]: token,
+          HOME: home,
+          PATH: process.env.PATH ?? "",
+          npm_config_globalconfig: path.join(home, "none"),
+          npm_config_userconfig: path.join(home, "npmrc"),
+        },
+      },
+    );
+    return "published";
+  } catch (error) {
+    return String((error as { stderr?: unknown }).stderr ?? "failed");
+  }
+}
+
+describe("the registry's access model", () => {
+  it("lets anyone search and read package metadata, with no account at all", async () => {
+    const search = await fetch(`${registryOf(mainOwner)}-/v1/search?text=ekklesia`);
+    expect(search.status).toBe(200);
+    // An absent package is 404 to an anonymous reader, not 401: reading is open.
+    expect(await anonymousPackument(mainOwner, "@ekklesia/contracts")).toBeUndefined();
+  });
+
+  it("refuses publishing without credentials, and from a user outside the publisher team", async () => {
+    const contracts = local("@ekklesia/contracts").path;
+    expect(await npmPublish(mainOwner, contracts, "")).toMatch(/ENEEDAUTH|E401|401/u);
+    expect(await npmPublish(mainOwner, contracts, outsiderToken)).toMatch(/E401|E403|40[13]/u);
+    expect(await anonymousPackument(mainOwner, "@ekklesia/contracts")).toBeUndefined();
+  });
+});
+
+describe("publishing a train, interrupted and resumed", () => {
+  let record: PublicationRecord;
+
+  it("run 1: stops before the sixth package, with five published and no final tag", async () => {
+    await expect(
+      publish(mainOwner, {
+        beforePublish: (_name, index) => {
+          if (index === 5) throw new Error("injected failure before the sixth package");
+        },
+      }),
+    ).rejects.toThrow("injected failure");
+    for (const [index, name] of order.entries()) {
+      const packument = await anonymousPackument(mainOwner, name);
+      if (index < 5) {
+        const version = packument?.versions[train.manifest.version];
+        expect(version, name).toBeDefined();
+        expect(packument?.["dist-tags"].latest, name).toBeUndefined();
+        expect(packument?.["dist-tags"]["ekklesia-staging"], name).toBe(train.manifest.version);
+        expect((await anonymousBytes(version?.dist.tarball ?? "")).equals(local(name).data)).toBe(
+          true,
+        );
+      } else {
+        expect(packument, name).toBeUndefined();
+      }
+    }
+  });
+
+  it("run 2: verifies the five as they are, publishes the other four, and only then moves latest", async () => {
+    record = await publish(mainOwner);
+    expect(record.packages.map((entry) => entry.name)).toEqual(order);
+    expect(record.packages.map((entry) => entry.outcome)).toEqual([
+      ...Array(5).fill("already-present"),
+      ...Array(4).fill("published"),
+    ]);
+    expect(record.packages.every((entry) => entry.finalTag === "moved")).toBe(true);
+    expect(record.packageTrain).toEqual({
+      manifestSha256: train.manifestSha256,
+      revision: train.manifest.source.revision,
+      version: train.manifest.version,
+    });
+    expect(JSON.stringify(record)).not.toContain(publishToken);
+  });
+
+  it("serves every package anonymously, byte for byte the release artifact", async () => {
+    for (const name of order) {
+      const packument = await anonymousPackument(mainOwner, name);
+      const version = packument?.versions[train.manifest.version];
+      expect(packument?.["dist-tags"].latest, name).toBe(train.manifest.version);
+      expect(version?.dist.integrity, name).toBe(local(name).entry.integrity);
+      expect(
+        (await anonymousBytes(version?.dist.tarball ?? "")).equals(local(name).data),
+        name,
+      ).toBe(true);
+      const entry = record.packages.find((candidate) => candidate.name === name);
+      expect(entry?.registry.sha256).toBe(local(name).entry.sha256);
+      expect(entry?.registry.publicRead).toBe(true);
+    }
+  });
+
+  it("run 3: a rerun of a published train changes nothing", async () => {
+    const again = await publish(mainOwner);
+    expect(again.packages.every((entry) => entry.outcome === "already-present")).toBe(true);
+    expect(again.packages.every((entry) => entry.finalTag === "already-current")).toBe(true);
+  });
+
+  it("the registry itself refuses a second upload of a published version", async () => {
+    const name = "@ekklesia/module-sdk";
+    const packument = await anonymousPackument(mainOwner, name);
+    const tarballUrl = packument?.versions[train.manifest.version]?.dist.tarball ?? "";
+    // A raw upload, past npm's own client-side check, with the publisher's own token.
+    const { data, entry, packageJson } = local(name);
+    const response = await fetch(packumentUrl(registryOf(mainOwner), name), {
+      body: JSON.stringify({
+        _attachments: {
+          [path.basename(new URL(tarballUrl).pathname)]: {
+            content_type: "application/octet-stream",
+            data: data.toString("base64"),
+            length: data.length,
+          },
+        },
+        _id: name,
+        "dist-tags": { manual: entry.version },
+        name,
+        versions: { [entry.version]: { ...packageJson, dist: { integrity: entry.integrity } } },
+      }),
+      headers: { authorization: `Bearer ${publishToken}`, "content-type": "application/json" },
+      method: "PUT",
+    });
+    expect(response.status).toBe(409);
+    expect((await anonymousBytes(tarballUrl)).equals(data)).toBe(true);
+  });
+});
+
+describe("a version already published with other bytes", () => {
+  it("stops the train for good at that package, deleting and overwriting nothing", async () => {
+    const poisonedName = "@ekklesia/module-sdk";
+    const index = order.indexOf(poisonedName);
+    expect(index).toBeGreaterThan(0);
+    expect(index).toBeLessThan(order.length - 1);
+
+    // Same name and version, other bytes: the release tarball with one extra file.
+    const work = await mkdtemp(path.join(tmpdir(), "ekklesia-burned-"));
+    scratch.push(work);
+    await execFileAsync("tar", ["-xzf", local(poisonedName).path, "-C", work]);
+    await writeFile(path.join(work, "package", "UNEXPECTED"), "not the release\n");
+    const poisoned = path.join(work, "poisoned.tgz");
+    await execFileAsync("tar", ["-czf", poisoned, "-C", work, "package"]);
+    expect(await npmPublish(burnedOwner, poisoned, publishToken)).toBe("published");
+    const poisonedBytes = await readFile(poisoned);
+
+    await expect(publish(burnedOwner)).rejects.toMatchObject({ code: "BURNED_VERSION" });
+
+    for (const [position, name] of order.entries()) {
+      const packument = await anonymousPackument(burnedOwner, name);
+      if (position < index) {
+        expect(packument?.versions[train.manifest.version], name).toBeDefined();
+      } else if (position === index) {
+        const url = packument?.versions[train.manifest.version]?.dist.tarball ?? "";
+        expect((await anonymousBytes(url)).equals(poisonedBytes)).toBe(true);
+      } else {
+        expect(packument, `${name} must not be published after the stop`).toBeUndefined();
+      }
+      expect(packument?.["dist-tags"].latest, name).toBeUndefined();
+    }
+
+    // A retry stops in exactly the same place, and still changes nothing.
+    await expect(publish(burnedOwner)).rejects.toMatchObject({ code: "BURNED_VERSION" });
+    expect(await anonymousPackument(burnedOwner, order[index + 1] ?? "")).toBeUndefined();
+  });
+});
+
+describe("moving the final tag, interrupted and resumed", () => {
+  it("leaves the train unfinished when moving latest fails part way", async () => {
+    await expect(
+      publish(tagOwner, {
+        beforeTag: (_name, index) => {
+          if (index === 4) throw new Error("injected failure before the fifth tag");
+        },
+      }),
+    ).rejects.toThrow("injected failure");
+    for (const [index, name] of order.entries()) {
+      const packument = await anonymousPackument(tagOwner, name);
+      expect(packument?.versions[train.manifest.version], name).toBeDefined();
+      expect(packument?.["dist-tags"].latest, name).toBe(
+        index < 4 ? train.manifest.version : undefined,
+      );
+    }
+  });
+
+  it("a retry republishes nothing and moves only the tags still missing", async () => {
+    const record = await publish(tagOwner);
+    expect(record.packages.every((entry) => entry.outcome === "already-present")).toBe(true);
+    expect(record.packages.map((entry) => entry.finalTag)).toEqual([
+      ...Array(4).fill("already-current"),
+      ...Array(5).fill("moved"),
+    ]);
+    for (const name of order) {
+      expect((await anonymousPackument(tagOwner, name))?.["dist-tags"].latest).toBe(
+        train.manifest.version,
+      );
+    }
+  });
+});
+
+describe("the publish workflow's own invocation", () => {
+  it("publishes from the Actions artifact layout, given a relative release path from another directory", async () => {
+    // Exactly as .github/workflows/publish-packages.yml runs it: the artifact unpacked under
+    // `package-train/` in the job's workspace, and `--release "$(find package-train …)"`.
+    const workspace = await mkdtemp(path.join(tmpdir(), "ekklesia-publish-workspace-"));
+    scratch.push(workspace);
+    const releaseName = path.basename(releaseDirectory);
+    await mkdir(path.join(workspace, "package-train"), { recursive: true });
+    await cp(releaseDirectory, path.join(workspace, "package-train", releaseName), {
+      recursive: true,
+    });
+    const record = path.join(workspace, "publication-record.json");
+    const { stdout } = await execFileAsync(
+      process.execPath,
+      [
+        path.resolve("scripts/publish-package-train.ts"),
+        "--release",
+        `package-train/${releaseName}`,
+        "--registry",
+        registryOf(layoutOwner),
+        "--version",
+        train.manifest.version,
+        "--revision",
+        train.manifest.source.revision,
+        "--manifest-sha256",
+        train.manifestSha256,
+        "--record",
+        record,
+        "--require-public-read",
+        "--allow-http",
+      ],
+      {
+        cwd: workspace,
+        env: { [PUBLISH_TOKEN_VARIABLE]: publishToken, PATH: process.env.PATH ?? "" },
+      },
+    );
+    expect(stdout).toContain(
+      `publishing ${path.join(workspace, "package-train", releaseName, local("@ekklesia/contracts").entry.file)}`,
+    );
+    expect(stdout).not.toContain(publishToken);
+    const published = JSON.parse(await readFile(record, "utf8")) as PublicationRecord;
+    expect(published.packages.map((entry) => entry.outcome)).toEqual(Array(9).fill("published"));
+    for (const name of order) {
+      const version = (await anonymousPackument(layoutOwner, name))?.versions[
+        train.manifest.version
+      ];
+      expect(
+        (await anonymousBytes(version?.dist.tarball ?? "")).equals(local(name).data),
+        name,
+      ).toBe(true);
+    }
+  });
+});
@@ -0,0 +1,659 @@
+import { chmod, cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+import { afterEach, describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import {
+  artifactDigests,
+  PACKAGE_TRAIN_MANIFEST,
+  type PackageTrainManifest,
+  PUBLIC_PACKAGES,
+  serializeManifest,
+  tarballName,
+} from "../scripts/package-release.js";
+import {
+  compareSemver,
+  isUnderRegistry,
+  loadReleaseTrain,
+  normalizeBin,
+  normalizeRegistry,
+  npmConfiguration,
+  PUBLISH_TOKEN_VARIABLE,
+  PublicationError,
+  packumentUrl,
+  parsePublishArguments,
+  publicationOrder,
+  publishPackageTrain,
+  registryCopyProblems,
+  registryReader,
+  tarballPackageJson,
+  trainProblems,
+} from "../scripts/publish-package-train.js";
+
+/**
+ * The package train publication tool's own rules (ADR 0053), without a registry: what it accepts
+ * as a publishable train, the order it publishes in, how it compares a registry copy with the
+ * release, and what it refuses before it ever reaches the network. The registry behaviour itself is
+ * proven against a disposable Gitea by `scripts/test-package-publication.sh`.
+ */
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = "0.1.2";
+const REVISION = "86ae907f59458508e3277666cdd214f5bd7c1078";
+const REGISTRY = "https://registry.example/api/packages/owner/npm/";
+const scratch: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(scratch.splice(0).map((dir) => rm(dir, { force: true, recursive: true })));
+});
+
+/** A minimal npm tarball: gzip of a ustar archive holding the given files under `package/`. */
+function tarball(files: Record<string, string>): Buffer {
+  const blocks: Buffer[] = [];
+  for (const [name, contents] of Object.entries(files)) {
+    const body = Buffer.from(contents);
+    const header = Buffer.alloc(512);
+    header.write(`package/${name}`, 0, "utf8");
+    header.write("0000644\0", 100);
+    header.write("0000000\0", 108);
+    header.write("0000000\0", 116);
+    header.write(`${body.length.toString(8).padStart(11, "0")}\0`, 124);
+    header.write("00000000000\0", 136);
+    header.write("        ", 148);
+    header.write("0", 156);
+    header.write("ustar\0", 257);
+    header.write("00", 263);
+    let checksum = 0;
+    for (const byte of header) checksum += byte;
+    header.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148);
+    blocks.push(header, body, Buffer.alloc((512 - (body.length % 512)) % 512));
+  }
+  blocks.push(Buffer.alloc(1024));
+  return gzipSync(Buffer.concat(blocks));
+}
+
+const TRAIN_DEPENDENCIES: Record<string, string[]> = {
+  "@ekklesia/contracts": [],
+  "@ekklesia/design-tokens": [],
+  "@ekklesia/module-database": ["@ekklesia/contracts"],
+  "@ekklesia/module-pack": ["@ekklesia/contracts", "@ekklesia/module-ui-build"],
+  "@ekklesia/module-sdk": ["@ekklesia/contracts"],
+  "@ekklesia/module-ui-build": ["@ekklesia/contracts"],
+  "@ekklesia/module-ui-sdk": [],
+  "@ekklesia/typescript-config": [],
+  "@ekklesia/ui": ["@ekklesia/design-tokens"],
+};
+
+function packageJsonFor(name: string): Record<string, unknown> {
+  return {
+    dependencies: Object.fromEntries((TRAIN_DEPENDENCIES[name] ?? []).map((dep) => [dep, VERSION])),
+    name,
+    version: VERSION,
+    ...(name === "@ekklesia/module-pack"
+      ? { bin: { "ekklesia-pack-module": "./bin/ekklesia-pack-module.mjs" } }
+      : {}),
+  };
+}
+
+async function releaseDirectory(
+  mutate?: (files: Map<string, Buffer>, manifest: PackageTrainManifest) => PackageTrainManifest,
+): Promise<string> {
+  const directory = await mkdtemp(path.join(tmpdir(), "ekklesia-publication-test-"));
+  scratch.push(directory);
+  const files = new Map<string, Buffer>();
+  for (const entry of PUBLIC_PACKAGES) {
+    files.set(
+      tarballName(entry.name, VERSION),
+      tarball({ "package.json": JSON.stringify(packageJsonFor(entry.name)), LICENSE: "AGPL\n" }),
+    );
+  }
+  let manifest: PackageTrainManifest = {
+    packageTrain: 1,
+    packages: PUBLIC_PACKAGES.map((entry) => {
+      const file = tarballName(entry.name, VERSION);
+      const data = files.get(file) as Buffer;
+      return {
+        file,
+        name: entry.name,
+        role: entry.role,
+        size: data.length,
+        version: VERSION,
+        ...artifactDigests(data),
+      };
+    }),
+    source: { modified: false, revision: REVISION },
+    version: VERSION,
+  };
+  files.set(
+    "SHA256SUMS",
+    Buffer.from(
+      [...manifest.packages]
+        .sort((left, right) => (left.file < right.file ? -1 : 1))
+        .map((entry) => `${entry.sha256}  ${entry.file}\n`)
+        .join(""),
+    ),
+  );
+  manifest = mutate ? mutate(files, manifest) : manifest;
+  files.set(PACKAGE_TRAIN_MANIFEST, Buffer.from(serializeManifest(manifest)));
+  for (const [file, data] of files) await writeFile(path.join(directory, file), data);
+  return directory;
+}
+
+describe("the local train", () => {
+  it("reads package.json from inside an npm tarball", () => {
+    const data = tarball({
+      LICENSE: "x",
+      "package.json": '{"name":"@ekklesia/x","version":"1.0.0"}',
+    });
+    expect(tarballPackageJson(data)).toEqual({ name: "@ekklesia/x", version: "1.0.0" });
+    expect(() => tarballPackageJson(tarball({ LICENSE: "x" }))).toThrow();
+  });
+
+  it("accepts a whole, unchanged train and records its manifest's own hash", async () => {
+    const directory = await releaseDirectory();
+    const train = await loadReleaseTrain(directory, { revision: REVISION, version: VERSION });
+    expect(train.packages).toHaveLength(9);
+    expect(train.manifestSha256).toBe(
+      artifactDigests(await readFile(path.join(directory, PACKAGE_TRAIN_MANIFEST))).sha256,
+    );
+  });
+
+  it("refuses a modified build, another version or revision, and any changed, missing, or extra file", async () => {
+    const cases: Record<string, Parameters<typeof releaseDirectory>[0]> = {
+      altered: (files, manifest) => {
+        files.set(tarballName("@ekklesia/ui", VERSION), tarball({ "package.json": "{}" }));
+        return manifest;
+      },
+      extra: (files, manifest) => {
+        files.set("ekklesia-core-0.1.2.tgz", Buffer.from("x"));
+        return manifest;
+      },
+      missing: (files, manifest) => {
+        files.delete(tarballName("@ekklesia/module-sdk", VERSION));
+        return manifest;
+      },
+      modified: (_files, manifest) => ({
+        ...manifest,
+        source: { ...manifest.source, modified: true },
+      }),
+      sums: (files, manifest) => {
+        files.set("SHA256SUMS", Buffer.from("0  x\n"));
+        return manifest;
+      },
+      wrongInside: (files, manifest) => {
+        // Bytes that match the manifest, but a package.json that names another package.
+        const file = tarballName("@ekklesia/ui", VERSION);
+        const data = tarball({
+          "package.json": JSON.stringify({ name: "@ekklesia/other", version: VERSION }),
+        });
+        files.set(file, data);
+        return {
+          ...manifest,
+          packages: manifest.packages.map((entry) =>
+            entry.file === file ? { ...entry, size: data.length, ...artifactDigests(data) } : entry,
+          ),
+        };
+      },
+    };
+    for (const [name, mutate] of Object.entries(cases)) {
+      const directory = await releaseDirectory(mutate);
+      await expect(
+        loadReleaseTrain(directory, { revision: REVISION, version: VERSION }),
+        name,
+      ).rejects.toMatchObject({ code: "INVALID_RELEASE" });
+    }
+    const valid = await releaseDirectory();
+    await expect(loadReleaseTrain(valid, { version: "0.1.3" })).rejects.toMatchObject({
+      code: "INVALID_RELEASE",
+    });
+    await expect(
+      loadReleaseTrain(valid, { revision: "f".repeat(40), version: VERSION }),
+    ).rejects.toMatchObject({ code: "INVALID_RELEASE" });
+  });
+
+  it("explains every problem at once", () => {
+    const problems = trainProblems(
+      {
+        packageTrain: 1,
+        packages: [],
+        source: { modified: true, revision: "abc" },
+        version: "9.9.9",
+      },
+      new Map(),
+      { version: VERSION },
+    );
+    expect(problems.join(" ")).toContain("modified source tree");
+    expect(problems.join(" ")).toContain("not the requested 0.1.2");
+    expect(problems.join(" ")).toContain("no full source revision");
+    expect(problems.join(" ")).toContain("is missing");
+  });
+});
+
+describe("the publication order", () => {
+  const entries = (names: readonly string[]) =>
+    names.map((name) => ({ entry: { name }, packageJson: packageJsonFor(name) }));
+
+  it("puts every package after the train packages it depends on, and is otherwise alphabetical", () => {
+    const order = publicationOrder(entries(Object.keys(TRAIN_DEPENDENCIES))).map(
+      (e) => e.entry.name,
+    );
+    expect(order).toEqual([
+      "@ekklesia/contracts",
+      "@ekklesia/design-tokens",
+      "@ekklesia/module-database",
+      "@ekklesia/module-sdk",
+      "@ekklesia/module-ui-build",
+      "@ekklesia/module-pack",
+      "@ekklesia/module-ui-sdk",
+      "@ekklesia/typescript-config",
+      "@ekklesia/ui",
+    ]);
+  });
+
+  it("does not depend on the order the files are listed in", () => {
+    const names = Object.keys(TRAIN_DEPENDENCIES);
+    const forward = publicationOrder(entries(names)).map((e) => e.entry.name);
+    const backward = publicationOrder(entries([...names].reverse())).map((e) => e.entry.name);
+    expect(backward).toEqual(forward);
+  });
+
+  it("follows the real packages' own dependencies", async () => {
+    const real = await Promise.all(
+      PUBLIC_PACKAGES.map(async (entry) => ({
+        entry: { name: entry.name },
+        packageJson: JSON.parse(
+          await readFile(path.join(repositoryRoot, entry.directory, "package.json"), "utf8"),
+        ) as Record<string, unknown>,
+      })),
+    );
+    const order = publicationOrder(real).map((e) => e.entry.name);
+    for (const { entry, packageJson } of real) {
+      for (const dependency of Object.keys((packageJson.dependencies as object) ?? {})) {
+        if (!dependency.startsWith("@ekklesia/")) continue;
+        expect(order.indexOf(dependency), `${dependency} before ${entry.name}`).toBeLessThan(
+          order.indexOf(entry.name),
+        );
+      }
+    }
+  });
+
+  it("refuses a dependency cycle", () => {
+    expect(() =>
+      publicationOrder([
+        { entry: { name: "a" }, packageJson: { dependencies: { b: "1" } } },
+        { entry: { name: "b" }, packageJson: { dependencies: { a: "1" } } },
+      ]),
+    ).toThrow(PublicationError);
+  });
+});
+
+describe("comparing a registry copy with the release", () => {
+  const data = tarball({ "package.json": JSON.stringify(packageJsonFor("@ekklesia/module-pack")) });
+  const digests = artifactDigests(data);
+  const local = {
+    data,
+    entry: {
+      file: "ekklesia-module-pack-0.1.2.tgz",
+      name: "@ekklesia/module-pack",
+      role: "tooling" as const,
+      size: data.length,
+      version: VERSION,
+      ...digests,
+    },
+    packageJson: packageJsonFor("@ekklesia/module-pack"),
+  };
+  const registryVersion = {
+    // npm normalizes bin paths in the metadata it uploads; the tarball keeps the author's form.
+    bin: { "ekklesia-pack-module": "bin/ekklesia-pack-module.mjs" },
+    dependencies: { "@ekklesia/module-ui-build": VERSION, "@ekklesia/contracts": VERSION },
+    dist: {
+      integrity: digests.integrity,
+      tarball: `${REGISTRY}%40ekklesia%2Fmodule-pack/-/0.1.2/module-pack-0.1.2.tgz`,
+    },
+    name: "@ekklesia/module-pack",
+    version: VERSION,
+  };
+
+  it("accepts the same bytes and metadata, however npm normalized bin", () => {
+    expect(registryCopyProblems(local, registryVersion, data, REGISTRY)).toEqual([]);
+    expect(normalizeBin("./cli.js", "@ekklesia/tool")).toEqual({ tool: "cli.js" });
+  });
+
+  it("refuses other bytes, integrity, dependencies, bin, or a tarball elsewhere", () => {
+    const other = tarball({ "package.json": "{}" });
+    expect(registryCopyProblems(local, registryVersion, other, REGISTRY).join(" ")).toContain(
+      "different bytes",
+    );
+    const cases = [
+      { ...registryVersion, dist: { ...registryVersion.dist, integrity: "sha512-AAAA" } },
+      { ...registryVersion, dependencies: { "@ekklesia/contracts": "0.1.1" } },
+      { ...registryVersion, bin: { other: "bin/other.mjs" } },
+      {
+        ...registryVersion,
+        dist: { ...registryVersion.dist, tarball: "https://elsewhere.example/x.tgz" },
+      },
+      { ...registryVersion, version: "0.1.3" },
+    ];
+    for (const version of cases) {
+      expect(
+        registryCopyProblems(local, version, data, REGISTRY),
+        JSON.stringify(version),
+      ).not.toEqual([]);
+    }
+  });
+
+  it("orders versions by SemVer precedence", () => {
+    expect(compareSemver("0.1.10", "0.1.9")).toBe(1);
+    expect(compareSemver("0.2.0", "0.10.0")).toBe(-1);
+    expect(compareSemver("1.0.0-rc.1", "1.0.0")).toBe(-1);
+    expect(compareSemver("1.0.0-rc.2", "1.0.0-rc.10")).toBe(-1);
+    expect(compareSemver("1.0.0-alpha", "1.0.0-1")).toBe(1);
+    expect(compareSemver("0.1.2", "0.1.2+build")).toBe(0);
+  });
+});
+
+describe("the registry and its credentials", () => {
+  it("accepts an HTTPS registry, adds the trailing slash, and refuses anything else", () => {
+    expect(normalizeRegistry("https://registry.example/api/packages/o/npm")).toBe(
+      "https://registry.example/api/packages/o/npm/",
+    );
+    expect(() => normalizeRegistry("http://registry.example/npm/")).toThrow(PublicationError);
+    expect(normalizeRegistry("http://gitea:3000/npm/", true)).toBe("http://gitea:3000/npm/");
+    expect(() => normalizeRegistry("https://user:[email protected]/npm/")).toThrow(
+      PublicationError,
+    );
+  });
+
+  it("refers to the token by its variable in npm's configuration, never by value", () => {
+    const configuration = npmConfiguration(REGISTRY);
+    expect(configuration).toContain(
+      `//registry.example/api/packages/owner/npm/:_authToken=\${${PUBLISH_TOKEN_VARIABLE}}`,
+    );
+    expect(configuration).toContain(`@ekklesia:registry=${REGISTRY}`);
+    expect(packumentUrl(REGISTRY, "@ekklesia/module-sdk")).toBe(
+      `${REGISTRY}@ekklesia%2fmodule-sdk`,
+    );
+  });
+
+  it("sends the token only to the registry itself", async () => {
+    const seen: Record<string, string | undefined> = {};
+    const fake = (async (url: string, init?: RequestInit) => {
+      seen[url] = ((init?.headers ?? {}) as Record<string, string>).authorization;
+      return new Response(new Uint8Array([1]), { status: 200 });
+    }) as typeof fetch;
+    const reader = registryReader(REGISTRY, "token-value", fake);
+    await reader.download(`${REGISTRY}x.tgz`);
+    await reader.download("https://elsewhere.example/x.tgz");
+    await reader.download(`${REGISTRY}y.tgz`, true);
+    expect(seen[`${REGISTRY}x.tgz`]).toBe("Bearer token-value");
+    expect(seen["https://elsewhere.example/x.tgz"]).toBeUndefined();
+    expect(seen[`${REGISTRY}y.tgz`]).toBeUndefined();
+    expect(isUnderRegistry("https://registry.example/api/packages/other/npm/x", REGISTRY)).toBe(
+      false,
+    );
+  });
+
+  it("refuses to start without a token, or with an invalid train, before any request", async () => {
+    let requests = 0;
+    const counting = (async () => {
+      requests += 1;
+      return new Response("{}");
+    }) as typeof fetch;
+    const directory = await releaseDirectory();
+    await expect(
+      publishPackageTrain({
+        fetch: counting,
+        registry: REGISTRY,
+        releaseDirectory: directory,
+        token: "",
+        version: VERSION,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_OPTIONS" });
+    const invalid = await releaseDirectory((_files, manifest) => ({
+      ...manifest,
+      source: { ...manifest.source, modified: true },
+    }));
+    await expect(
+      publishPackageTrain({
+        fetch: counting,
+        npm: "/nonexistent/npm",
+        registry: REGISTRY,
+        releaseDirectory: invalid,
+        token: "publish-token-value",
+        version: VERSION,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_RELEASE" });
+    const valid = await releaseDirectory();
+    await expect(
+      publishPackageTrain({
+        fetch: counting,
+        manifestSha256: "0".repeat(64),
+        npm: "/nonexistent/npm",
+        registry: REGISTRY,
+        releaseDirectory: valid,
+        token: "publish-token-value",
+        version: VERSION,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_RELEASE" });
+    expect(requests).toBe(0);
+  });
+
+  it("parses its command line, and takes no token from it", () => {
+    expect(
+      parsePublishArguments([
+        "--release",
+        "r",
+        "--registry",
+        REGISTRY,
+        "--version",
+        VERSION,
+        "--require-public-read",
+      ]),
+    ).toEqual({
+      flags: { requirePublicRead: true },
+      values: { registry: REGISTRY, release: "r", version: VERSION },
+    });
+    expect(() => parsePublishArguments(["--release", "r", "--token", "x"])).toThrow(
+      PublicationError,
+    );
+    expect(() => parsePublishArguments(["--release", "r"])).toThrow(PublicationError);
+  });
+});
+
+describe("the artifact npm is given", () => {
+  /**
+   * The release where the Actions artifact puts it, `<workspace>/package-train/<release>`, named
+   * relatively from the current directory, which is not the release directory: exactly how the
+   * publish workflow called the tool when npm was handed a path relative to its own temporary home.
+   */
+  async function nestedRelease(): Promise<{ relative: string; absolute: string }> {
+    const workspace = await mkdtemp(path.join(tmpdir(), "ekklesia-workspace-"));
+    scratch.push(workspace);
+    const absolute = path.join(workspace, "package-train", `ekklesia-packages-${VERSION}`);
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await cp(await releaseDirectory(), absolute, { recursive: true });
+    const relative = path.relative(process.cwd(), absolute);
+    expect(path.isAbsolute(relative)).toBe(false);
+    expect(process.cwd()).not.toBe(absolute);
+    return { absolute, relative };
+  }
+
+  /** An npm that records what it was given, and where it ran, then fails as a registry would. */
+  async function recordingNpm(): Promise<{
+    npm: string;
+    calls: () => Promise<{ argv: string[]; cwd: string; exists: boolean }[]>;
+  }> {
+    const directory = await mkdtemp(path.join(tmpdir(), "ekklesia-fake-npm-"));
+    scratch.push(directory);
+    const log = path.join(directory, "calls.jsonl");
+    const npm = path.join(directory, "npm");
+    await writeFile(
+      npm,
+      `#!/usr/bin/env node
+const { appendFileSync, existsSync } = require("node:fs");
+const argv = process.argv.slice(2);
+appendFileSync(${JSON.stringify(log)}, JSON.stringify({ argv, cwd: process.cwd(), exists: existsSync(argv[1] ?? "") }) + "\\n");
+process.stderr.write("npm error code E503\\nnpm error 503 Service Unavailable\\n");
+process.exit(1);
+`,
+    );
+    await chmod(npm, 0o755);
+    return {
+      calls: async () =>
+        (await readFile(log, "utf8").catch(() => ""))
+          .split("\n")
+          .filter(Boolean)
+          .map((line) => JSON.parse(line)),
+      npm,
+    };
+  }
+
+  const notFound = (async () => new Response("{}", { status: 404 })) as typeof fetch;
+
+  it("resolves a relative, nested release to absolute artifact paths when it loads the train", async () => {
+    const { absolute, relative } = await nestedRelease();
+    const train = await loadReleaseTrain(relative, { revision: REVISION, version: VERSION });
+    for (const local of train.packages) {
+      expect(local.path).toBe(path.join(absolute, local.entry.file));
+      expect(path.isAbsolute(local.path)).toBe(true);
+      expect((await readFile(local.path)).equals(local.data)).toBe(true);
+    }
+  });
+
+  it("hands npm the exact validated tarball by its absolute path, from npm's own directory, and says which", async () => {
+    const { absolute, relative } = await nestedRelease();
+    const { calls, npm } = await recordingNpm();
+    const error = await publishPackageTrain({
+      fetch: notFound,
+      npm,
+      registry: REGISTRY,
+      releaseDirectory: relative,
+      revision: REVISION,
+      token: "publish-token-value",
+      version: VERSION,
+    }).catch((caught: unknown) => caught);
+    expect(error).toMatchObject({ code: "PUBLISH_FAILED" });
+    const first = tarballName("@ekklesia/contracts", VERSION);
+    const expected = path.join(absolute, first);
+    // The failure names the exact file npm was given, and never the token.
+    expect((error as Error).message).toContain(expected);
+    expect((error as Error).message).toContain("E503");
+    expect((error as Error).message).not.toContain("publish-token-value");
+
+    const [call] = await calls();
+    expect(call?.argv.slice(0, 2)).toEqual(["publish", expected]);
+    expect(call?.exists).toBe(true);
+    // npm ran in a directory of its own, where a relative path would have named nothing.
+    expect(call?.cwd).not.toBe(absolute);
+    expect(path.isAbsolute(call?.cwd ?? "")).toBe(true);
+    expect(JSON.stringify(call)).not.toContain("publish-token-value");
+  });
+
+  it("refuses to publish an artifact that changed after it was validated, before npm runs", async () => {
+    const { absolute, relative } = await nestedRelease();
+    const { calls, npm } = await recordingNpm();
+    const file = path.join(absolute, tarballName("@ekklesia/contracts", VERSION));
+    await expect(
+      publishPackageTrain({
+        fetch: notFound,
+        hooks: {
+          beforePublish: async (_name, index) => {
+            if (index === 0) await writeFile(file, "changed after validation");
+          },
+        },
+        npm,
+        registry: REGISTRY,
+        releaseDirectory: relative,
+        revision: REVISION,
+        token: "publish-token-value",
+        version: VERSION,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_RELEASE" });
+    expect(await calls()).toEqual([]);
+  });
+});
+
+describe("what the publisher may do to a registry", () => {
+  it("never deletes, unpublishes, or overwrites: it only publishes new versions and moves a tag", async () => {
+    // Code only: the tool's comments may say what it never does.
+    const source = (
+      await readFile(path.join(repositoryRoot, "scripts/publish-package-train.ts"), "utf8")
+    )
+      .replace(/\/\*[\s\S]*?\*\//gu, "")
+      .replace(/^\s*\/\/.*$/gmu, "");
+    expect(source).not.toMatch(
+      /unpublish|deprecate|"DELETE"|method:\s*"(?:PUT|DELETE|POST)"|-rev\/|--force/u,
+    );
+    const npmCommands = [...source.matchAll(/\["(publish|dist-tag)"/gu)].map((match) => match[1]);
+    expect([...new Set(npmCommands)].sort()).toEqual(["dist-tag", "publish"]);
+    expect(source).toMatch(/\["dist-tag", "add",/u);
+  });
+});
+
+describe("when the real registry can be written to", () => {
+  type Workflow = {
+    on: Record<string, unknown>;
+    jobs: Record<
+      string,
+      {
+        if?: string;
+        needs?: string | string[];
+        steps: { run?: string; env?: Record<string, string>; uses?: string }[];
+      }
+    >;
+  };
+  const workflow = async (file: string) =>
+    parse(await readFile(path.join(repositoryRoot, ".github/workflows", file), "utf8")) as Workflow;
+
+  it("never from CI: no pull request or push job holds the publish secret or publishes", async () => {
+    const ci = await readFile(path.join(repositoryRoot, ".github/workflows/ci.yml"), "utf8");
+    expect(ci).not.toContain("EKKLESIA_PACKAGES_PUBLISH_TOKEN");
+    expect(ci).not.toContain("secrets.");
+    expect(ci).not.toContain("publish-package-train.ts");
+    // CI publishes only to the disposable registry its own job starts.
+    expect(ci).toContain("bash scripts/test-package-publication.sh --release");
+  });
+
+  it("only by hand, on main, after this run's own gate, with the secret in the publish step alone", async () => {
+    const publish = await workflow("publish-packages.yml");
+    expect(Object.keys(publish.on)).toEqual(["workflow_dispatch"]);
+    for (const [name, job] of Object.entries(publish.jobs)) {
+      expect(job.if, name).toBe("github.ref == 'refs/heads/main'");
+    }
+    expect(publish.jobs.publish?.needs).toBe("package-release");
+    const steps = Object.entries(publish.jobs).flatMap(([job, { steps }]) =>
+      steps.map((step) => ({ job, step })),
+    );
+    const withSecret = steps.filter(({ step }) => JSON.stringify(step).includes("secrets."));
+    expect(withSecret).toHaveLength(1);
+    expect(withSecret[0]?.job).toBe("publish");
+    expect(withSecret[0]?.step.env?.EKKLESIA_PACKAGES_PUBLISH_TOKEN).toBe(
+      "${{ secrets.EKKLESIA_PACKAGES_PUBLISH_TOKEN }}",
+    );
+    const command = withSecret[0]?.step.run ?? "";
+    for (const option of ["--revision", "--manifest-sha256", "--require-public-read", "--record"]) {
+      expect(command).toContain(option);
+    }
+    expect(command).not.toContain("--allow-http");
+    // The publish job never builds or packs: it installs nothing and runs no package script.
+    const publishRuns = (publish.jobs.publish?.steps ?? [])
+      .map((step) => step.run ?? "")
+      .join("\n");
+    expect(publishRuns).not.toMatch(/pnpm|npm (?:install|ci|run|pack)|package-release\.ts/u);
+  });
+
+  it("uses the artifact actions that work on this Gitea, pinned by commit, on visible paths", async () => {
+    for (const file of ["ci.yml", "publish-packages.yml"]) {
+      const text = await readFile(path.join(repositoryRoot, ".github/workflows", file), "utf8");
+      for (const use of text.matchAll(/uses: (actions\/(?:up|down)load-artifact)@(\S+)/gu)) {
+        expect(use[2], `${file} ${use[1]}`).toMatch(/^[0-9a-f]{40}$/u);
+      }
+      // The artifact actions leave hidden files out: a path starting with a dot uploads nothing.
+      for (const artifactPath of text.matchAll(/^\s+path: (\S+)$/gmu)) {
+        expect(artifactPath[1], file).not.toMatch(/^\.|\/\./u);
+      }
+    }
+  });
+});
@@ -1,20 +1,29 @@
+import { spawnSync } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
 import {
+  artifactDigests,
+  PACKAGE_TRAIN_MANIFEST,
+  type PackageTrainManifest,
  PUBLIC_PACKAGE_DISTRIBUTION,
  PUBLIC_PACKAGES,
  packedManifestProblems,
+  releaseDirectoryProblems,
+  releaseSetProblems,
+  serializeManifest,
  tarballFileProblems,
-} from "../scripts/pack-public-packages.js";
+  tarballName,
+  workspacePackages as releaseWorkspacePackages,
+} from "../scripts/package-release.js";

 /**
- * The public module-development package boundary (ADR 0053): which packages may be published, what
- * their manifests may say, and what the author-facing SDK exposes. The tarballs themselves are
- * inspected by `pnpm packages:pack` and installed into a standalone module by
- * `scripts/test-standalone-module.sh`.
+ * The public module-development package boundary and its release train (ADR 0053): which packages
+ * may be published, what their manifests may say, what the author-facing SDK exposes, and what a
+ * release directory must hold. The tarballs themselves are built and inspected by
+ * `pnpm packages:release` (`scripts/package-release.ts`), and proven by `pnpm test:package-release`.
 */

 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -78,6 +87,41 @@ describe("the public package set", () => {
    expect(packages.get("@ekklesia/module-template")?.manifest.private).toBe(true);
  });

+  it("is what the release builder itself accepts, read without a YAML parser", async () => {
+    const platformVersion = (await readJson("package.json")).version;
+    const read = await releaseWorkspacePackages(repositoryRoot);
+    expect(read.map((entry) => entry.name).sort()).toEqual(
+      [...(await workspacePackages()).keys()].sort(),
+    );
+    expect(releaseSetProblems(read, platformVersion)).toEqual([]);
+  });
+
+  it("refuses a missing, mis-versioned, or private public package, and anything else publishable", async () => {
+    const read = await releaseWorkspacePackages(repositoryRoot);
+    const without = read.filter((entry) => entry.name !== "@ekklesia/ui");
+    expect(releaseSetProblems(without, "0.1.2").join(" ")).toContain("@ekklesia/ui is missing");
+    const changed = read.map((entry) =>
+      entry.name === "@ekklesia/module-sdk"
+        ? { ...entry, manifest: { ...entry.manifest, private: true, version: "0.2.0" } }
+        : entry.name === "@ekklesia/core"
+          ? { ...entry, manifest: { ...entry.manifest, private: undefined } }
+          : entry.name === "@ekklesia/module-ui-host"
+            ? {
+                ...entry,
+                manifest: {
+                  ...entry.manifest,
+                  ekklesia: { distribution: PUBLIC_PACKAGE_DISTRIBUTION },
+                },
+              }
+            : entry,
+    );
+    const problems = releaseSetProblems(changed, "0.1.2").join(" ");
+    expect(problems).toContain("@ekklesia/module-sdk is version 0.2.0");
+    expect(problems).toContain("@ekklesia/module-sdk is private");
+    expect(problems).toContain("@ekklesia/core is publishable but not in the release set");
+    expect(problems).toContain("@ekklesia/module-ui-host carries the distribution marker");
+  });
+
  it("uses one coordinated version, and depends only on other public packages through the workspace", async () => {
    const platformVersion = (await readJson("package.json")).version;
    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
@@ -208,10 +252,11 @@ describe("module authors' dependencies", () => {
    }
  });

-  it("pin module-pack exactly and declare engines.node in the standalone fixture", async () => {
+  it("pin module-pack exactly, at this release, and declare engines.node in the standalone fixture", async () => {
    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
    const devDependencies = fixture.devDependencies as Record<string, string>;
-    expect(devDependencies["@ekklesia/module-pack"]).toMatch(/^\d+\.\d+\.\d+$/u);
+    // Part of setting a release version: the fixture consumes exactly this release's module-pack.
+    expect(devDependencies["@ekklesia/module-pack"]).toBe((await readJson("package.json")).version);
    expect((fixture.engines as Record<string, string>).node).toBeTruthy();
  });
 });
@@ -231,7 +276,6 @@ describe("@ekklesia/typescript-config", () => {
 describe("the tarball inspection", () => {
  const good = {
    dependencies: { "@ekklesia/contracts": "0.1.2", zod: "4.4.3" },
-    devDependencies: { "@ekklesia/core": "0.1.2" },
    ekklesia: { distribution: PUBLIC_PACKAGE_DISTRIBUTION, layer: "module-sdk" },
    files: ["dist"],
    license: "AGPL-3.0-or-later",
@@ -255,6 +299,10 @@ describe("the tarball inspection", () => {
      { ...good, dependencies: { "@ekklesia/contracts": "0.1.1" } },
      { ...good, peerDependencies: { "@ekklesia/core": "0.1.2" } },
      { ...good, version: "0.1.3" },
+      // Development dependencies never ship: they name private packages outside the train.
+      { ...good, devDependencies: { "@ekklesia/core": "0.1.2" } },
+      // A registry is the publication step's configuration, never part of an artifact.
+      { ...good, publishConfig: { registry: "https://registry.example/" } },
    ];
    for (const manifest of cases) {
      expect(packedManifestProblems(manifest, expected), JSON.stringify(manifest)).not.toEqual([]);
@@ -280,4 +328,122 @@ describe("the tarball inspection", () => {
      expect(tarballFileProblems(files, good, hasSource), files.join(" ")).not.toEqual([]);
    }
  });
+
+  it("refuses a dependency map whose order differs from its source", () => {
+    const source = { dependencies: { "@ekklesia/contracts": "workspace:*", zod: "4.4.3" } };
+    expect(packedManifestProblems(good, expected, source)).toEqual([]);
+    const reordered = { ...good, dependencies: { zod: "4.4.3", "@ekklesia/contracts": "0.1.2" } };
+    expect(packedManifestProblems(reordered, expected, source)).toEqual([
+      "orders dependencies differently from its source",
+    ]);
+  });
+});
+
+describe("the pack hook", () => {
+  it("drops devDependencies and restores the source's key order, changing nothing else", async () => {
+    const { hooks } = await import("../scripts/lib/pack-hooks.cjs");
+    const directory = path.join(repositoryRoot, "packages", "module-pack");
+    const source = await readJson("packages/module-pack/package.json");
+    const dependencies = Object.fromEntries(
+      Object.keys(source.dependencies ?? {})
+        .reverse()
+        .map((name) => [name, name.startsWith("@ekklesia/") ? "0.1.2" : "1.0.0"]),
+    );
+    const packed = hooks.beforePacking(
+      { ...source, dependencies, devDependencies: { "@ekklesia/core": "0.1.2" } },
+      directory,
+    );
+    expect(packed.devDependencies).toBeUndefined();
+    expect(Object.keys(packed.dependencies as object)).toEqual(
+      Object.keys(source.dependencies ?? {}),
+    );
+    expect(packed.dependencies).toEqual(dependencies);
+    expect(packed.name).toBe(source.name);
+  });
+});
+
+describe("a clean source tree", () => {
+  it("ignores pnpm's package store, which pnpm creates in a checkout that is its own mount", () => {
+    // In CI the checkout is a workspace volume, so `pnpm install` puts `.pnpm-store/` at its root:
+    // a package cache, never source, which must not make the release builder's clean tree dirty.
+    const ignored = spawnSync("git", ["check-ignore", "--quiet", ".pnpm-store/v11/index.db"], {
+      cwd: repositoryRoot,
+    });
+    expect(ignored.status).toBe(0);
+  });
+});
+
+describe("the release directory", () => {
+  const version = "0.1.2";
+  function release(mutate?: (files: Map<string, Uint8Array>) => void) {
+    const files = new Map<string, Uint8Array>();
+    for (const entry of PUBLIC_PACKAGES) {
+      files.set(tarballName(entry.name, version), Buffer.from(`tarball of ${entry.name}`));
+    }
+    const manifest: PackageTrainManifest = {
+      packageTrain: 1,
+      packages: PUBLIC_PACKAGES.map((entry) => {
+        const file = tarballName(entry.name, version);
+        const data = files.get(file) ?? new Uint8Array();
+        return {
+          file,
+          name: entry.name,
+          role: entry.role,
+          size: data.length,
+          version,
+          ...artifactDigests(data),
+        };
+      }),
+      source: { modified: false, revision: "86ae907f59458508e3277666cdd214f5bd7c1078" },
+      version,
+    };
+    mutate?.(files);
+    files.set(PACKAGE_TRAIN_MANIFEST, Buffer.from(serializeManifest(manifest)));
+    return { files, manifest };
+  }
+
+  it("names each tarball as pnpm pack does", () => {
+    expect(tarballName("@ekklesia/module-sdk", "0.1.2")).toBe("ekklesia-module-sdk-0.1.2.tgz");
+  });
+
+  it("records npm-compatible integrity and SHA-256 for each artifact", () => {
+    const digests = artifactDigests(Buffer.from("abc"));
+    expect(digests.sha256).toBe("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+    expect(digests.integrity).toMatch(/^sha512-[A-Za-z0-9+/]{86}==$/u);
+  });
+
+  it("accepts exactly the expected train, matching its manifest", () => {
+    const { files, manifest } = release();
+    expect(releaseDirectoryProblems(manifest, files)).toEqual([]);
+  });
+
+  it("refuses a missing, extra, or altered artifact", () => {
+    const missing = release((files) => files.delete(tarballName("@ekklesia/ui", version)));
+    expect(releaseDirectoryProblems(missing.manifest, missing.files).join(" ")).toContain(
+      "ekklesia-ui-0.1.2.tgz is missing",
+    );
+    const extra = release((files) =>
+      files.set("ekklesia-module-ui-host-0.1.2.tgz", Buffer.from("x")),
+    );
+    expect(releaseDirectoryProblems(extra.manifest, extra.files).join(" ")).toContain(
+      "ekklesia-module-ui-host-0.1.2.tgz is not part of the release",
+    );
+    const altered = release((files) =>
+      files.set(tarballName("@ekklesia/module-pack", version), Buffer.from("changed")),
+    );
+    expect(releaseDirectoryProblems(altered.manifest, altered.files).join(" ")).toContain(
+      "does not match its size, SHA-256, or integrity",
+    );
+  });
+
+  it("serializes the manifest the same way every time, packages sorted by name", () => {
+    const { manifest } = release();
+    const reversed = { ...manifest, packages: [...manifest.packages].reverse() };
+    expect(serializeManifest(reversed)).toBe(serializeManifest(manifest));
+    const parsed = JSON.parse(serializeManifest(manifest)) as PackageTrainManifest;
+    expect(parsed.packages.map((entry) => entry.name)).toEqual(
+      [...PUBLIC_PACKAGES.map((entry) => entry.name)].sort(),
+    );
+    expect(Object.keys(parsed)).toEqual(["packageTrain", "version", "source", "packages"]);
+  });
 });
@@ -1,13 +1,15 @@
 {
  "extends": "./packages/typescript-config/node.json",
  "compilerOptions": {
-    "noEmit": true
+    "noEmit": true,
+    "allowImportingTsExtensions": true
  },
  "include": [
    "scripts/**/*.ts",
    "tests/**/*.ts",
    "vitest.config.ts",
-    "vitest.migrations.integration.config.ts"
+    "vitest.migrations.integration.config.ts",
+    "vitest.packages.integration.config.ts"
  ],
  "exclude": ["node_modules", "tests/fixtures"]
 }
@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+/** The package train publication suite, run only by `scripts/test-package-publication.sh` against
+ * the disposable Gitea it starts. */
+export default defineConfig({
+  test: {
+    fileParallelism: false,
+    hookTimeout: 60_000,
+    include: ["tests/package-publication.integration.ts"],
+    passWithNoTests: false,
+    sequence: { concurrent: false },
+    testTimeout: 180_000,
+  },
+});
Author	SHA1	Message	Date
The_River	1788d17f0a	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 CI / verify (push) Successful in 1m6s Details CI / infrastructure-smoke (push) Successful in 36s Details CI / migration-smoke (push) Successful in 1m56s Details CI / package-release (push) Successful in 34s Details CI / image-build (push) Successful in 11s Details CI / deploy-smoke (same-origin) (push) Successful in 49s Details CI / deploy-smoke (split) (push) Successful in 1m22s Details CI / package-publication (push) Successful in 47s Details Reviewed-on: https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia/pulls/83 Reviewed-by: The_River <[email protected]>	2026-10-08 23:22:00 +00:00
ekklesiaandClaude Opus 5.5	1caffc5f26	fix: hand npm the release artifact's absolute path, so publishing finds it CI / verify (pull_request) Successful in 1m5s Details CI / infrastructure-smoke (pull_request) Successful in 37s Details CI / migration-smoke (pull_request) Successful in 1m52s Details CI / package-release (pull_request) Successful in 34s Details CI / image-build (pull_request) Successful in 24s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 50s Details CI / deploy-smoke (split) (pull_request) Successful in 1m30s Details CI / package-publication (pull_request) Successful in 49s Details The first real 0.2.0 publish failed on its first package with ENOENT: "Publishing ekklesia-contracts-0.2.0.tgz failed: npm error code ENOENT". The publish workflow passes a relative release path, --release "$(find package-train …)", which is package-train/ekklesia-packages-0.2.0. The tool validated the artifacts relative to the job's working directory, but ran npm in its own temporary home (cwd /tmp/ekklesia-publish-XXXXXX) with the same relative path, package-train/ekklesia-packages-0.2.0/ekklesia-contracts-0.2.0.tgz, which there names nothing. The disposable-registry suite always passed an absolute path, so it never saw this. - loadReleaseTrain resolves the release directory once; every artifact path is absolute from validation on, and npm is given only that exact file's absolute path (anything else is refused at the npm boundary). - Just before each upload the file is checked against the validated bytes once more; the tool logs the absolute path it publishes, and a failure names it with npm's path/syscall lines (npm's temporary home masked, the token never shown). - Regression tests: unit tests with a recording npm (relative nested release from another cwd; npm's argv, cwd, and the file's existence; a changed artifact refused before npm runs), which fail on the previous tool; and a disposable-Gitea test that runs the CLI exactly as the workflow does, from the Actions artifact layout, round-tripping all nine packages byte for byte. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 17:51:22 -05:00
The_River	debb8df3ce	Merge pull request 'chore(release): prepare 0.2.0' (#82 ) from chore/release-0.2.0 into main CI / verify (push) Successful in 1m6s Details CI / infrastructure-smoke (push) Successful in 36s Details CI / migration-smoke (push) Successful in 1m55s Details CI / package-release (push) Successful in 35s Details CI / image-build (push) Successful in 11s Details CI / deploy-smoke (same-origin) (push) Successful in 49s Details CI / deploy-smoke (split) (push) Successful in 1m22s Details CI / package-publication (push) Successful in 41s Details Reviewed-on: https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia/pulls/82 Reviewed-by: The_River <[email protected]>	2026-10-08 22:36:19 +00:00
ekklesiaandClaude Opus 5.5	98e59d4ba0	chore(release): prepare 0.2.0 CI / verify (pull_request) Successful in 1m5s Details CI / infrastructure-smoke (pull_request) Successful in 35s Details CI / migration-smoke (pull_request) Successful in 1m52s Details CI / package-release (pull_request) Successful in 35s Details CI / image-build (pull_request) Successful in 31s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 45s Details CI / deploy-smoke (split) (pull_request) Successful in 1m30s Details CI / package-publication (pull_request) Successful in 44s Details Every platform workspace package and every public @ekklesia/* package declares 0.2.0, and the deploy README's image build example names it. templates/module keeps its own version. 0.2.0, not 0.1.3: before 1.0 a minor version is the breaking one (docs/development/releases.md, ADR 0054), and since 0.1.2 main has broken modules, module authors, and operators: - #64 (ADR 0048): one generic image; installed modules live outside it; - #66, #72 (ADR 0049, 0050): modules install as Module Package v1, and move to the Module Database ABI; - #71: the manifest v8 cutover; v7 manifests are refused; - #79 (ADR 0053): the curated SDK drops defineModuleSchema and the legacy ModuleDatabase type; plus #67 (AGPL), #74, #77 (licensing, native targets), and the public package train (#80, #81). It is also the first package train to publish: 0.1.2 never will be. Because 0.2.0 is outside ^0.1.0, the same change moves to ^0.2.0: - the standalone fixture's @ekklesia ranges and its exact module-pack pin; - the compatibility ranges of the modules built for this release: the template, the standalone fixture, and the native proof module; - the test fixtures that model a module of the current release, or the current platform's versions; - the module-development guide's examples, and the release guide, which now names what a minor bump moves. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 17:26:13 -05:00
The_River	22404ea2d4	Merge pull request 'feat: publish the exact @ekklesia package train to the npm registry (ADR 0053)' (#81 ) from feat/package-train-publication into main CI / verify (push) Successful in 1m1s Details CI / infrastructure-smoke (push) Successful in 36s Details CI / migration-smoke (push) Successful in 1m53s Details CI / package-release (push) Successful in 32s Details CI / image-build (push) Successful in 11s Details CI / deploy-smoke (same-origin) (push) Successful in 42s Details CI / deploy-smoke (split) (push) Successful in 1m22s Details CI / package-publication (push) Successful in 42s Details Reviewed-on: https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia/pulls/81 Reviewed-by: The_River <[email protected]>	2026-10-08 16:31:57 +00:00
ekklesiaandClaude Opus 5.5	486356a01e	docs: ADR 0054, Ekklesia's module-development packages are publicly readable before launch CI / verify (pull_request) Successful in 1m4s Details CI / infrastructure-smoke (pull_request) Successful in 36s Details CI / migration-smoke (pull_request) Successful in 1m46s Details CI / package-release (pull_request) Successful in 33s Details CI / image-build (pull_request) Successful in 22s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 48s Details CI / deploy-smoke (split) (pull_request) Successful in 1m27s Details CI / package-publication (pull_request) Successful in 43s Details ADR 0053 was accepted assuming a private package phase before launch. The project owner has decided otherwise: Ekklesia is not secret, its source is already public, and only publication must be restricted. ADR 0054 supersedes ADR 0053 only where it describes that phase as private or requires authenticated package reads. Packages may be read anonymously, which is neither a launch nor an API stability promise beyond pre-1.0 SemVer; publication stays authenticated and restricted; published versions stay immutable; the River_of_Glory_Church Gitea namespace is an acceptable host; a public launch remains a separate decision. Every other ADR 0053 decision is unchanged. ADR 0053 gets only a cross-reference line. The ADR index, the release and module-development guides, the README status, and the publish workflow's comment now point at ADR 0054. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 10:24:17 -05:00
ekklesiaandClaude Opus 5.5	1f30c86d4f	fix: hand the proven release train on from a directory the artifact actions upload CI / verify (pull_request) Successful in 1m4s Details CI / infrastructure-smoke (pull_request) Successful in 38s Details CI / migration-smoke (pull_request) Successful in 1m53s Details CI / package-release (pull_request) Successful in 32s Details CI / image-build (pull_request) Successful in 22s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 49s Details CI / deploy-smoke (split) (pull_request) Successful in 1m39s Details CI / package-publication (pull_request) Successful in 59s Details The CI package-release gate passed, but the upload found no files: the artifact actions leave hidden files out, and .package-release starts with a dot. Keep the release in package-train instead, in both workflows, and test that no artifact path is hidden. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 09:56:06 -05:00
ekklesiaandClaude Opus 5.5	d3c62e63bf	feat: publish the exact @ekklesia package train to the npm registry (ADR 0053) CI / verify (pull_request) Successful in 1m1s Details CI / infrastructure-smoke (pull_request) Successful in 35s Details CI / migration-smoke (pull_request) Successful in 1m53s Details CI / package-release (pull_request) Failing after 43s Details CI / package-publication (pull_request) Skipped Details CI / image-build (pull_request) Successful in 29s Details CI / deploy-smoke (split) (pull_request) Canceled after 0s Details CI / deploy-smoke (same-origin) (pull_request) Canceled after 38s Details Publishes one package release train to the Gitea npm registry under River_of_Glory_Church, whose packages are publicly readable on purpose: exactly the .tgz files the package-release gate proved, and nothing else. Nothing is published by this change. - scripts/publish-package-train.ts validates the whole local train before any request (gate manifest hash, version, revision, unmodified source, the nine packages, every artifact's size, SHA-256, integrity, SHA256SUMS line, and inner package.json), then publishes in dependency order with `npm publish <file.tgz>` under a staging tag. Each package is reconciled first (absent: publish; same bytes: accept; other bytes: hard stop, version burned), then read back: metadata (name, version, integrity, dependency maps, normalized bin, tarball on the registry) and the tarball itself, byte for byte, also anonymously. `latest` moves only after all nine verify; reruns converge and never delete anything. It writes a publication record. The token comes from EKKLESIA_PACKAGES_PUBLISH_TOKEN only, through a temporary npm config that refers to the variable. - scripts/test-package-publication.sh proves it against a disposable Gitea 1.27.2 with public owners, a publisher team and an outsider: anonymous reads, refused unauthorized publishing, byte-identical round trips, the registry's own 409, partial-train recovery, the burned version hard stop, and dist-tag retry convergence. - CI: package-release keeps its proven release and hands it on as an artifact with its manifest hash; the new package-publication job publishes exactly that artifact to the disposable Gitea. Artifact actions v3 (node20): v4 refuses any server other than github.com. - .github/workflows/publish-packages.yml publishes to the real registry only by manual dispatch on main, after its own gate run, with the secret in the publish step alone. - docs: the public-read model, the workflow, the record, credentials, immutability policy, provider moves, and the first-publication steps. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 09:49:27 -05:00
The_River	57df2e15f2	Merge pull request 'feat: the public @ekklesia package release train, built, reproduced, and proven (ADR 0053)' (#80 ) from feat/public-package-release-train into main CI / verify (push) Successful in 1m5s Details CI / infrastructure-smoke (push) Successful in 37s Details CI / migration-smoke (push) Successful in 1m54s Details CI / package-release (push) Successful in 32s Details CI / image-build (push) Successful in 10s Details CI / deploy-smoke (same-origin) (push) Successful in 49s Details CI / deploy-smoke (split) (push) Successful in 1m22s Details Reviewed-on: https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia/pulls/80 Reviewed-by: The_River <[email protected]>	2026-10-08 13:53:41 +00:00
ekklesiaandClaude Opus 5.5	4f1b1d68c7	fix: keep pnpm's package store out of the release builder's clean-source check CI / verify (pull_request) Successful in 1m4s Details CI / infrastructure-smoke (pull_request) Successful in 37s Details CI / migration-smoke (pull_request) Successful in 1m54s Details CI / package-release (pull_request) Successful in 32s Details CI / image-build (pull_request) Successful in 30s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 50s Details CI / deploy-smoke (split) (pull_request) Successful in 1m32s Details The package-release job failed its clean-tree assertion in CI. Reproduced as root in a container with a bind-mounted checkout, as the Gitea runner does: after checkout the tree is clean; `pnpm install --frozen-lockfile` then creates `.pnpm-store/` (17,272 untracked files) at the checkout's root, because pnpm keeps its store on the node_modules file system and the checkout is its own mount; `pnpm build` changes nothing. No tracked file is ever modified. - `.pnpm-store/` is ignored, like node_modules: a package cache, never source. The clean-commit requirement is unchanged for every tracked file and every untracked file Git does not ignore. - The clean-tree failure now lists `git status --short` and `git diff --stat`. - Nothing is built before the clean-source assertion: the gate no longer runs a global `pnpm build` first. The builder asserts a clean tree, builds, then fails if its build changed the tree, before packing. Core's verifier is built after both releases, for the consumer proof only. - Every secondary offline install (the second worktree, the consumer module) uses the workspace install's own store explicitly, since pnpm picks a store per file system and those directories are on another. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 08:43:19 -05:00
ekklesiaandClaude Opus 5.5	9debe4e891	feat: the public @ekklesia package release train, built, reproduced, and proven (ADR 0053) CI / verify (pull_request) Successful in 1m2s Details CI / infrastructure-smoke (pull_request) Successful in 35s Details CI / migration-smoke (pull_request) Successful in 1m52s Details CI / package-release (pull_request) Failing after 16s Details CI / image-build (pull_request) Successful in 29s Details CI / deploy-smoke (same-origin) (pull_request) Successful in 44s Details CI / deploy-smoke (split) (pull_request) Successful in 1m29s Details Produces the exact public package tarballs of a platform release, validates them, and proves a standalone module consumes those artifacts end to end. Nothing is published and no credential is configured. - scripts/package-release.ts (pnpm packages:release) is the canonical release builder: from a clean commit it rebuilds the nine public packages from clean output, packs each, inspects every tarball, checks the release set and coordinated versions, and only then writes ekklesia-packages-<version>/ with the tarballs, SHA256SUMS, and a provider-neutral manifest (ekklesia-package-train.json: version, revision, and each package's file, size, SHA-256, npm integrity). - Packing uses a pack-only pnpm beforePacking hook (passed with --config.pnpmfile, never the workspace's install settings). pnpm inserts rewritten workspace: dependencies in async completion order, so two checkouts of one commit packed module-pack's package.json with keys in a different order; the hook restores the source key order (and the inspection enforces it). It also drops devDependencies, which named private packages outside the train. - scripts/test-package-release.sh (pnpm test:package-release, the CI package-release gate) builds the train twice, the second time from a separate worktree, requires byte-identical release directories, then runs the standalone consumer proof on the release: manifest checked, offline install from the tarballs only, lockfile integrity equal to the manifest's, frozen-lockfile reinstall, no Drizzle, one React, contracts only transitive, every @ekklesia package and module-pack at the release version, skipLibCheck: false, UI build, pack, and Core verification. - docs/development/releases.md documents the release order, the train, the artifacts, and the reproducibility findings; registry publication remains unimplemented. - ADR 0053 is Accepted: everything it decides that does not need a registry is now proven, and registry provisioning is on its own Deferred list. Co-Authored-By: Claude Opus 5.5 <[email protected]>	2026-10-08 08:02:41 -05:00