feat: standalone module-build readiness for the public @ekklesia packages (ADR 0053)

Makes the public module-development package set usable from a module
repository outside the monorepo. Nothing is published.

- Curated @ekklesia/module-sdk: an explicit author API, no contracts
  barrel, no identity/authorization internals, no Drizzle and no legacy
  ModuleDatabase type. defineModuleRuntime returns the SDK's own named
  interfaces so a module's emitted declarations never reach into
  @ekklesia/contracts. defineModuleSchema is gone; createModuleTable and
  defineModuleSchemaMetadata live in @ekklesia/module-database.
- Drizzle: no longer a dependency of module-sdk or contracts. Core keeps
  the legacy Drizzle schema validator (moved to core/src/modules) and
  its legacy runtime support; drizzle-orm is an optional peer only.
- React is a peer (plus devDependency) of @ekklesia/ui; the boundary
  checker allows exactly that consumer-selected peer.
- @ekklesia/typescript-config is publishable; module-ui-host is private.
  Every public package carries "ekklesia.distribution":
  "module-development" and no monorepo-root prepack.
- module-pack reads the Node.js range from the module's own engines.node
  and recognizes Ekklesia packages by name plus that marker, so
  registry-installed packages are incorporated, SDK-compatibility
  checked, and never credited as third-party.
- scripts/pack-public-packages.ts (pnpm packages:pack) rebuilds, packs
  and inspects the nine public tarballs; scripts/test-standalone-module.sh
  (pnpm test:standalone-module, new CI job) installs them into a fixture
  module outside the repository and proves it typechecks, builds,
  packages, and verifies.
- Public-package boundary tests and module-development docs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

tests/boundaries.test.ts

@@ -119,7 +119,7 @@ describe("repository dependency boundaries", () => {
     expect(result.violations).toEqual([]);
   });
 
-  it("accepts only the module database adapter's consumer-selected Drizzle runtime peer", async () => {
+  it("accepts only the consumer-selected runtime peers: the database adapter's Drizzle and the shared UI's React", async () => {
     const result = await checkBoundaries(path.join(fixtures, "legal-consumer-runtime-peer"));
 
     expect(result.violations).toEqual([]);

tests/fixtures/boundaries/legal-consumer-runtime-peer/packages/ui/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@ekklesia/ui",
+  "version": "0.0.0",
+  "type": "module",
+  "peerDependencies": { "react": "^19.2.0" },
+  "devDependencies": { "react": "19.2.8" },
+  "exports": {
+    ".": "./src/index.tsx"
+  },
+  "ekklesia": {
+    "layer": "ui"
+  }
+}

tests/fixtures/boundaries/legal-consumer-runtime-peer/packages/ui/src/index.tsx

@@ -0,0 +1,6 @@
+import { useId } from "react";
+
+export function Badge(props: { readonly label: string }) {
+  const id = useId();
+  return <span id={id}>{props.label}</span>;
+}

tests/fixtures/boundaries/runtime-jsx-implies-react/packages/ui/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@ekklesia/ui",
+  "name": "@ekklesia/widgets",
   "version": "0.0.0",
   "type": "module",
   "peerDependencies": { "react": "19.2.8" },

tests/fixtures/standalone-module/drizzle/0000_initial.sql

@@ -0,0 +1 @@
+CREATE TABLE "standalone_proof_notes" ("id" uuid PRIMARY KEY NOT NULL, "body" text NOT NULL);

tests/fixtures/standalone-module/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,6 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "id": "20000000-0000-4000-8000-000000000001",
+  "prevId": "00000000-0000-0000-0000-000000000000"
+}

tests/fixtures/standalone-module/drizzle/meta/_ekklesia.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "moduleId": "standalone-proof",
+  "entries": [{ "tag": "0000_initial", "destructive": { "mode": "none" } }]
+}

tests/fixtures/standalone-module/drizzle/meta/_journal.json

@@ -0,0 +1,7 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    { "idx": 0, "version": "7", "when": 1700000000000, "tag": "0000_initial", "breakpoints": true }
+  ]
+}

tests/fixtures/standalone-module/ekklesia.module.json

@@ -0,0 +1,28 @@
+{
+  "manifestVersion": 8,
+  "id": "standalone-proof",
+  "name": "Standalone Proof",
+  "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"
+  },
+  "database": {
+    "abi": 1
+  },
+  "capabilities": [],
+  "permissions": [
+    {
+      "id": "standalone-proof.notes.read",
+      "baseline": "restricted",
+      "description": "Read notes."
+    }
+  ],
+  "entrypoints": {
+    "server": "./dist/server/index.js",
+    "schema": "./dist/schema/index.js",
+    "migrations": "./drizzle",
+    "ui": "./dist/ui/index.js"
+  }
+}

tests/fixtures/standalone-module/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ekklesia-fixtures/standalone-proof",
+  "version": "0.1.0",
+  "description": "A module built outside the Ekklesia repository from packed @ekklesia/* tarballs. Not a workspace package: scripts/test-standalone-module.sh copies it elsewhere and installs it.",
+  "license": "AGPL-3.0-or-later",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24.11.0 <25"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui",
+    "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",
+    "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",
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "typescript": "7.0.2"
+  }
+}

tests/fixtures/standalone-module/src/schema/index.ts

@@ -0,0 +1,6 @@
+import { defineModuleSchemaMetadata } from "@ekklesia/module-database";
+
+export default defineModuleSchemaMetadata({
+  moduleId: "standalone-proof",
+  tables: [{ name: "standalone_proof_notes", foreignKeys: [] }],
+});

tests/fixtures/standalone-module/src/server/index.ts

@@ -0,0 +1,23 @@
+import { sql } from "@ekklesia/module-database";
+import { defineModuleRuntime } from "@ekklesia/module-sdk";
+
+/** A Module Database ABI v1 module with no ORM: SQL through the executor Core provides. */
+export default defineModuleRuntime({
+  database: { abi: 1 },
+  id: "standalone-proof",
+  version: "0.1.0",
+  register({ http }) {
+    http.route({
+      method: "GET",
+      path: "/notes",
+      permission: "standalone-proof.notes.read",
+      maxBodyBytes: 0,
+      async handler(_request, { services }) {
+        const result = await services.database.query(
+          sql`SELECT id, body FROM standalone_proof_notes ORDER BY id LIMIT ${50}`,
+        );
+        return Response.json(result.rows);
+      },
+    });
+  },
+});

tests/fixtures/standalone-module/src/ui/index.tsx

@@ -0,0 +1,23 @@
+import { designTokenVariableName } from "@ekklesia/design-tokens";
+import { defineModuleUi } from "@ekklesia/module-ui-sdk";
+import { EKKLESIA_UI_STYLESHEET, EmptyState, Panel } from "@ekklesia/ui";
+import { createRoot } from "react-dom/client";
+
+const accent = `var(${designTokenVariableName("color.accent")})`;
+
+export default defineModuleUi({
+  id: "standalone-proof",
+  version: "0.1.0",
+  styles: EKKLESIA_UI_STYLESHEET,
+  mount(container) {
+    const root = createRoot(container);
+    root.render(
+      <Panel title="Notes">
+        <div style={{ borderColor: accent }}>
+          <EmptyState title="No notes yet" />
+        </div>
+      </Panel>,
+    );
+    return () => root.unmount();
+  },
+});

tests/fixtures/standalone-module/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}

tests/fixtures/standalone-module/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@ekklesia/typescript-config/node.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/server/**/*.ts", "src/schema/**/*.ts"]
+}

tests/fixtures/standalone-module/tsconfig.ui.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@ekklesia/typescript-config/browser-react.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src/ui/**/*.tsx"]
+}

tests/public-packages.test.ts

@@ -0,0 +1,265 @@
+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 {
+  PUBLIC_PACKAGE_DISTRIBUTION,
+  PUBLIC_PACKAGES,
+  packedManifestProblems,
+  tarballFileProblems,
+} from "../scripts/pack-public-packages.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`.
+ */
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+type Manifest = Record<string, unknown> & {
+  name: string;
+  version: string;
+  private?: boolean;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  optionalDependencies?: Record<string, string>;
+  ekklesia?: Record<string, unknown>;
+  files?: string[];
+};
+
+async function readJson<T = Manifest>(file: string): Promise<T> {
+  return JSON.parse(await readFile(path.join(repositoryRoot, file), "utf8")) as T;
+}
+
+async function workspacePackages(): Promise<
+  Map<string, { directory: string; manifest: Manifest }>
+> {
+  const workspace = parse(await readFile(path.join(repositoryRoot, "pnpm-workspace.yaml"), "utf8"));
+  const packages = new Map<string, { directory: string; manifest: Manifest }>();
+  for (const pattern of workspace.packages as string[]) {
+    const directories = pattern.endsWith("/*")
+      ? (
+          await readdir(path.join(repositoryRoot, 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(`${directory}/package.json`).catch(() => undefined);
+      if (manifest) packages.set(manifest.name, { directory, manifest });
+    }
+  }
+  return packages;
+}
+
+describe("the public package set", () => {
+  it("is exactly the packages that carry the distribution marker, and nothing else is publishable", async () => {
+    const packages = await workspacePackages();
+    const publicNames = new Set(PUBLIC_PACKAGES.map((entry) => entry.name));
+    for (const entry of PUBLIC_PACKAGES) {
+      expect(packages.get(entry.name)?.directory, entry.name).toBe(entry.directory);
+    }
+    for (const [name, { manifest }] of packages) {
+      const marked = manifest.ekklesia?.distribution === PUBLIC_PACKAGE_DISTRIBUTION;
+      expect(marked, name).toBe(publicNames.has(name));
+      // Internal packages stay private, so no publish can ever take them by accident.
+      expect(manifest.private === true, name).toBe(!publicNames.has(name));
+    }
+    expect(packages.get("@ekklesia/core")?.manifest.private).toBe(true);
+    expect(packages.get("@ekklesia/module-ui-host")?.manifest.private).toBe(true);
+    expect(packages.get("@ekklesia/module-template")?.manifest.private).toBe(true);
+  });
+
+  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));
+    for (const entry of PUBLIC_PACKAGES) {
+      const manifest = await readJson(`${entry.directory}/package.json`);
+      expect(manifest.version, entry.name).toBe(platformVersion);
+      expect(manifest.license, entry.name).toBe("AGPL-3.0-or-later");
+      for (const field of ["dependencies", "peerDependencies", "optionalDependencies"] as const) {
+        for (const [name, range] of Object.entries(manifest[field] ?? {})) {
+          if (!name.startsWith("@ekklesia/")) continue;
+          expect(publicNames.has(name), `${entry.name} ${field} ${name}`).toBe(true);
+          // `pnpm pack` turns this into the exact coordinated version.
+          expect(range, `${entry.name} ${field} ${name}`).toBe("workspace:*");
+        }
+      }
+    }
+  });
+
+  it("runs no monorepo-root command, or any other script, when a consumer installs or packs it", async () => {
+    for (const entry of PUBLIC_PACKAGES) {
+      const manifest = await readJson(`${entry.directory}/package.json`);
+      for (const script of ["preinstall", "install", "postinstall", "prepare", "prepack"]) {
+        expect(manifest.scripts?.[script], `${entry.name} ${script}`).toBeUndefined();
+      }
+      expect(JSON.stringify(manifest.scripts ?? {}), entry.name).not.toContain("--workspace-root");
+    }
+  });
+
+  it("keeps module-pack's own LICENSE identical to the repository's", async () => {
+    // pnpm adds the workspace LICENSE to a tarball only when no packed path looks like a licence, and
+    // module-pack ships `licenses/` and `license-supplements/`, so it carries its own copy.
+    expect(await readFile(path.join(repositoryRoot, "packages/module-pack/LICENSE"))).toEqual(
+      await readFile(path.join(repositoryRoot, "LICENSE")),
+    );
+  });
+});
+
+describe("the curated Module SDK", () => {
+  async function sdkExports(): Promise<string[]> {
+    const source = await readFile(
+      path.join(repositoryRoot, "packages/module-sdk/src/index.ts"),
+      "utf8",
+    );
+    expect(source).not.toMatch(/export\s*\*/u);
+    const names: string[] = [];
+    for (const block of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/gu)) {
+      for (const item of (block[1] ?? "").split(",")) {
+        const name = item
+          .replace(/^\s*type\s+/u, "")
+          .split(/\s+as\s+/u)
+          .pop()
+          ?.trim();
+        if (name) names.push(name);
+      }
+    }
+    return names.sort();
+  }
+
+  it("exposes the author API only", async () => {
+    const names = await sdkExports();
+    expect(names).toContain("defineModuleRuntime");
+    expect(names).toContain("ModuleRouteHandlerContext");
+    expect(names).toContain("parseModuleManifest");
+    for (const name of names) {
+      // No identity or authorization internals, no Drizzle, and no legacy database facade.
+      expect(name).not.toMatch(
+        /Authoriz|Permission(?:Grant|Decision)|Identity|Session|Credential|Drizzle(?!MigrationJournal)|^ModuleDatabase$|^ModuleSchemaDefinition$|defineModuleSchema|createModuleTable|^parseEkklesia/u,
+      );
+    }
+  });
+
+  it("does not make Drizzle a dependency of a module that does not use it", async () => {
+    const sdk = await readJson("packages/module-sdk/package.json");
+    expect(Object.keys(sdk.dependencies ?? {})).toEqual(["@ekklesia/contracts"]);
+    expect(sdk.peerDependencies ?? {}).toEqual({});
+    // Everything the SDK installs: Drizzle is at most an optional peer, and no runtime path reaches it.
+    for (const name of ["contracts", "module-database"]) {
+      const manifest = await readJson(`packages/${name}/package.json`);
+      expect(manifest.dependencies?.["drizzle-orm"], name).toBeUndefined();
+      expect(manifest.optionalDependencies?.["drizzle-orm"], name).toBeUndefined();
+      if (manifest.peerDependencies?.["drizzle-orm"]) {
+        expect(manifest.peerDependenciesMeta?.["drizzle-orm"]?.optional, name).toBe(true);
+      }
+    }
+    const contractsSource = path.join(repositoryRoot, "packages/contracts/src");
+    for (const file of await readdir(contractsSource)) {
+      // Only types: Core alone validates the legacy Drizzle schema definition, with its own Drizzle.
+      const source = await readFile(path.join(contractsSource, file), "utf8");
+      for (const line of source.split("\n").filter((text) => /from\s+"drizzle-orm/u.test(text))) {
+        expect(line, file).toMatch(/^import type /u);
+      }
+    }
+    const contracts = await readJson("packages/contracts/package.json");
+    expect(Object.keys(contracts.exports as object)).toEqual([".", "./module-package"]);
+  });
+});
+
+describe("module authors' dependencies", () => {
+  it("never name @ekklesia/contracts directly", async () => {
+    const template = await readJson("templates/module/package.json");
+    const fixture = await readJson("tests/fixtures/standalone-module/package.json");
+    for (const manifest of [template, fixture]) {
+      expect(JSON.stringify(manifest), manifest.name).not.toContain("@ekklesia/contracts");
+    }
+    const guide = await readFile(
+      path.join(repositoryRoot, "docs/module-development/README.md"),
+      "utf8",
+    );
+    // Never shown as a dependency to add, and stated not to be one.
+    expect(guide).not.toMatch(/"@ekklesia\/contracts"\s*:/u);
+    expect(guide).toContain("`@ekklesia/contracts` is not a direct dependency.");
+  });
+
+  it("pin module-pack exactly 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);
+    expect((fixture.engines as Record<string, string>).node).toBeTruthy();
+  });
+});
+
+describe("@ekklesia/typescript-config", () => {
+  it("ships only its configurations, which extend each other by relative path", async () => {
+    const manifest = await readJson("packages/typescript-config/package.json");
+    expect(manifest.files?.every((file) => /^[a-z-]+\.json$/u.test(file))).toBe(true);
+    for (const file of manifest.files ?? []) {
+      const config = await readJson<{ extends?: string }>(`packages/typescript-config/${file}`);
+      if (config.extends !== undefined)
+        expect(config.extends, file).toMatch(/^\.\/[a-z-]+\.json$/u);
+    }
+  });
+});
+
+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",
+    name: "@ekklesia/module-sdk",
+    scripts: { build: "tsc" },
+    version: "0.1.2",
+  };
+  const expected = { name: "@ekklesia/module-sdk", version: "0.1.2" };
+
+  it("accepts a packed manifest that names only the coordinated train", () => {
+    expect(packedManifestProblems(good, expected)).toEqual([]);
+  });
+
+  it("refuses workspace ranges, privacy, missing markers, lifecycle scripts, and mixed trains", () => {
+    const cases: Record<string, unknown>[] = [
+      { ...good, dependencies: { "@ekklesia/contracts": "workspace:*" } },
+      { ...good, private: true },
+      { ...good, ekklesia: { layer: "module-sdk" } },
+      { ...good, scripts: { prepack: "pnpm --workspace-root exec turbo run build" } },
+      { ...good, scripts: { postinstall: "node setup.js" } },
+      { ...good, dependencies: { "@ekklesia/contracts": "0.1.1" } },
+      { ...good, peerDependencies: { "@ekklesia/core": "0.1.2" } },
+      { ...good, version: "0.1.3" },
+    ];
+    for (const manifest of cases) {
+      expect(packedManifestProblems(manifest, expected), JSON.stringify(manifest)).not.toEqual([]);
+    }
+  });
+
+  it("accepts only declared built files with sources, the manifest, and a LICENSE", () => {
+    const hasSource = (file: string) => ["index", "http"].includes(file);
+    expect(
+      tarballFileProblems(
+        ["LICENSE", "package.json", "dist/index.js", "dist/index.d.ts", "dist/http.js.map"],
+        good,
+        hasSource,
+      ),
+    ).toEqual([]);
+    for (const files of [
+      ["package.json", "dist/index.js"],
+      ["LICENSE", "package.json", "dist/removed.js"],
+      ["LICENSE", "package.json", "src/index.ts"],
+      ["LICENSE", "package.json", "tsconfig.json"],
+      ["LICENSE", "package.json", "dist/index.test.js"],
+    ]) {
+      expect(tarballFileProblems(files, good, hasSource), files.join(" ")).not.toEqual([]);
+    }
+  });
+});