feat: define module HTTP routes

Phase 5B, pass 1: framework-neutral module HTTP route contracts and runtime
registration. Adds @ekklesia/contracts' module-http.ts (methods, canonical
path grammar, route definition/context/handler types, and validation)
and Core's module runtime staging/publication of a module's declared
routes alongside its capabilities, gated on the module's own manifest
permissions. Routes are collected into StartedModuleRuntime as an
immutable snapshot but are not yet mounted into apps/api; that is pass 2.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

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

@@ -1,5 +1,11 @@
 import { describe, expect, it, vi } from "vitest";
-import { defineModuleRuntime } from "../src/index.js";
+import {
+  defineModuleRuntime,
+  isModuleHttpMethod,
+  MODULE_HTTP_METHODS,
+  type ModuleHttpRouteRegistrar,
+  type ModuleRegistrationContext,
+} from "../src/index.js";
 
 describe("defineModuleRuntime", () => {
   it("defines a frozen server runtime without duplicating the static manifest", async () => {
@@ -22,4 +28,42 @@ describe("defineModuleRuntime", () => {
       }),
     ).toThrow("Invalid Ekklesia module runtime definition.");
   });
+
+  it("re-exports the module-http contract so a module's register hook can declare routes", async () => {
+    expect(MODULE_HTTP_METHODS).toContain("GET");
+    expect(isModuleHttpMethod("GET")).toBe(true);
+    expect(isModuleHttpMethod("get")).toBe(false);
+
+    const registeredRoutes: unknown[] = [];
+    const http: ModuleHttpRouteRegistrar = {
+      route: (definition) => {
+        registeredRoutes.push(definition);
+      },
+    };
+    const runtime = defineModuleRuntime({
+      id: "example",
+      version: "0.1.0",
+      register({ http: registrar }) {
+        registrar.route({
+          method: "GET",
+          path: "/records",
+          permission: "example.records.read",
+          handler: () => new Response(null, { status: 204 }),
+        });
+      },
+    });
+
+    const context: ModuleRegistrationContext = {
+      capabilities: {
+        provide: () => undefined,
+        resolve: () => undefined,
+      },
+      http,
+      moduleId: "example",
+    };
+    await runtime.register?.(context);
+
+    expect(registeredRoutes).toHaveLength(1);
+    expect(registeredRoutes[0]).toMatchObject({ method: "GET", path: "/records" });
+  });
 });