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]>

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

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

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

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