feat: add module runtime lifecycle

templates/module/README.md

@@ -1,8 +1,8 @@
 # Ekklesia module template
 
-This is the smallest supported backend-only Ekklesia module. It proves the manifest, package,
-Module SDK, discovery, capability, permission, and logical storage-bucket contracts without
-pretending that the later runtime, API, or Drizzle registration layers already exist.
+This is the smallest supported backend-only Ekklesia module. It proves the static manifest,
+compiled runtime entrypoint, capability registration, and logical storage-bucket declarations
+without pretending that API, Drizzle, or storage provisioning already exist.
 
 To create a module inside this repository:
 
@@ -10,7 +10,14 @@ To create a module inside this repository:
 2. Rename the package in `package.json` and remove `private` when it is ready for publication.
 3. Update the ID, name, version, namespaces, compatibility ranges, and bucket requests in
    `ekklesia.module.json`.
-4. Replace the example server entrypoint with backend behavior only.
-5. Run `pnpm install`, `pnpm modules:validate`, and `pnpm verify` from the repository root.
+4. Keep the manifest capability versions and dependency ranges aligned with the contracts the
+   module actually implements and consumes.
+5. Replace `src/server/index.ts` with backend behavior only. Its `defineModuleRuntime` ID and version
+   must match the manifest; do not duplicate the rest of the manifest in TypeScript.
+6. Run `pnpm install`, `pnpm build`, `pnpm modules:validate`, and `pnpm verify` from the repository
+   root. The declared production entrypoint is the compiled `dist/server/index.js`, not source
+   TypeScript.
 
 Do not add UI components, styles, renderers, navigation, or layouts. Those belong to surfaces.
+Keep imports side-effect-free, register capabilities in `register`, acquire resources in `start`,
+and release them in `stop`.

templates/module/ekklesia.module.json

@@ -1,5 +1,5 @@
 {
-  "manifestVersion": 1,
+  "manifestVersion": 2,
   "id": "example",
   "name": "Example Module",
   "description": "A minimal backend-only Ekklesia module template.",
@@ -8,7 +8,12 @@
     "platform": "^0.1.0",
     "moduleSdk": "^0.1.0"
   },
-  "capabilities": ["example.records"],
+  "capabilities": [
+    {
+      "id": "example.records",
+      "version": "1.0.0"
+    }
+  ],
   "permissions": ["example.records.read"],
   "storage": {
     "buckets": [
@@ -19,6 +24,6 @@
     ]
   },
   "entrypoints": {
-    "server": "./src/server/index.ts"
+    "server": "./dist/server/index.js"
   }
 }

templates/module/package.json

@@ -5,7 +5,6 @@
   "type": "module",
   "files": [
     "dist",
-    "src",
     "ekklesia.module.json"
   ],
   "exports": {

templates/module/src/server/index.ts

@@ -1,7 +1,13 @@
-export interface ExampleModuleServer {
-  readonly id: "example";
-}
+import { defineModuleRuntime } from "@ekklesia/module-sdk";
 
-export const exampleModuleServer: ExampleModuleServer = {
+export const recordsCapability = Object.freeze({
+  kind: "example-records",
+});
+
+export default defineModuleRuntime({
   id: "example",
-};
+  version: "0.1.0",
+  register({ capabilities }) {
+    capabilities.provide("example.records", recordsCapability);
+  },
+});

templates/module/tests/manifest.test.ts

@@ -1,14 +1,38 @@
 import { readFile } from "node:fs/promises";
-import { defineModule, type ModuleManifestInput } from "@ekklesia/module-sdk";
+import {
+  type CapabilityId,
+  parseModuleManifest,
+  type RegisteredCapability,
+} from "@ekklesia/module-sdk";
 import { describe, expect, it } from "vitest";
+import moduleRuntime, { recordsCapability } from "../src/server/index.js";
 
 describe("module template", () => {
   it("ships a valid backend-only manifest", async () => {
     const manifestUrl = new URL("../ekklesia.module.json", import.meta.url);
-    const manifestInput = JSON.parse(await readFile(manifestUrl, "utf8")) as ModuleManifestInput;
-    const manifest = defineModule(manifestInput);
+    const manifestInput = JSON.parse(await readFile(manifestUrl, "utf8")) as unknown;
+    const manifest = parseModuleManifest(manifestInput);
 
     expect(manifest.id).toBe("example");
+    expect(manifest.capabilities).toEqual([{ id: "example.records", version: "1.0.0" }]);
     expect(manifest.storage.buckets.map((bucket) => bucket.id)).toEqual(["records"]);
   });
+
+  it("exports the typed runtime definition used by the compiled server entrypoint", async () => {
+    const provided = new Map<CapabilityId, unknown>();
+    await moduleRuntime.register?.({
+      capabilities: {
+        provide(capabilityId, implementation) {
+          provided.set(capabilityId, implementation);
+        },
+        resolve(_capabilityId: CapabilityId): RegisteredCapability | undefined {
+          return undefined;
+        },
+      },
+      moduleId: "example",
+    });
+
+    expect(moduleRuntime).toMatchObject({ id: "example", version: "0.1.0" });
+    expect(provided.get("example.records")).toBe(recordsCapability);
+  });
 });