@kelpie/server 0.1.0

package/dist/runtime/module.d.ts

@@ -0,0 +1,138 @@
+import type { Hono } from 'hono';
+import type { ZodType } from 'zod';
+import type { Actor } from '../lib/actor.ts';
+import type { Database } from '../lib/database.ts';
+import type { EmailSender } from '../lib/email.ts';
+import type { IdFactory } from '../lib/ids.ts';
+import type { Logger } from '../lib/logger.ts';
+import type { EntitlementRegistry } from './entitlements.ts';
+import type { EventBus } from './events.ts';
+import type { TransactionScope } from './transaction.ts';
+/**
+ * The module contract from `modules.md`. Core features register through this
+ * same runtime, so anything core can do, a module can do.
+ *
+ * Composition is build-time: an assembly lists its modules in `kelpie.config.ts`
+ * and the runtime registers them. There is no runtime plugin loading.
+ */
+/** A module's Drizzle tables plus the directory holding its migrations. */
+export interface SchemaContribution {
+    readonly moduleId: string;
+    /** The module's schema namespace: table, relation, and enum exports. */
+    readonly tables: Readonly<Record<string, unknown>>;
+    readonly migrationsDir: string;
+}
+/**
+ * A tool as a module declares it. The input schema is the same one the matching
+ * REST route validates with, so the two surfaces cannot drift.
+ *
+ * `invoke` receives the caller for the same reason a route handler resolves one:
+ * every service call is authorized against an actor and scoped to its workspace.
+ * The MCP endpoint resolves it once per request from the bearer key and hands it
+ * down, so a tool never reads identity from anywhere but its own arguments.
+ */
+export interface McpToolDefinition<Input> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodType<Input>;
+    readonly invoke: (input: Input, actor: Actor) => Promise<unknown>;
+}
+/**
+ * A tool as the registry holds it. Registration erases the input type behind a
+ * parse, so every call is validated before the tool body sees it.
+ */
+export interface McpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodType;
+    readonly invoke: (rawInput: unknown, actor: Actor) => Promise<unknown>;
+}
+export interface McpToolRegistry {
+    tool<Input>(definition: McpToolDefinition<Input>): void;
+}
+/**
+ * What a module gets to build with, beyond its own contributions.
+ *
+ * `modules.md` does not list these. A module that contributes tables has no way
+ * to query them without a handle, and every write needs the transaction scope so
+ * its events publish after commit rather than during. Recorded here as the
+ * builder decision the spec left open.
+ */
+export interface ModuleServices {
+    readonly db: Database;
+    /** Runs work in one transaction and publishes its events after commit. */
+    readonly transaction: TransactionScope;
+    /** Transactional mail only: invites and password resets. */
+    readonly email: EmailSender;
+    /** Generates `<prefix>_<ulid>` ids. Injected so tests can pin them. */
+    readonly createId: IdFactory;
+    /** The current time, injected so expiry logic is testable. */
+    readonly now: () => Date;
+}
+export interface ModuleContext extends ModuleServices {
+    /** Registers routes. They mount under `/v1` and are public API like any other. */
+    routes(mount: (router: Hono) => void): void;
+    /**
+     * Registers routes that mount under `/v1/public`, take no credentials, and
+     * answer cross-origin requests from any site.
+     *
+     * A second method rather than an argument to `routes`, because the auth
+     * boundary is then visible at the call site: a reader of a module's `register`
+     * can see which of its endpoints anyone on the internet may call.
+     *
+     * A handler here has no `Actor` and therefore no workspace. It must resolve one
+     * from something in the request that identifies it — a form's `publicKey` — and
+     * scope every query to that. There is no other way in.
+     */
+    publicRoutes(mount: (router: Hono) => void): void;
+    schema(tables: Readonly<Record<string, unknown>>, migrationsDir: string): void;
+    readonly mcp: McpToolRegistry;
+    /**
+     * Subscribe to domain events. Handlers run after the emitting transaction
+     * commits, and must be idempotent.
+     */
+    readonly events: EventBus;
+    /**
+     * Declare capabilities and check grants. Every check is granted and unlimited
+     * until a module registers a provider.
+     */
+    readonly entitlements: EntitlementRegistry;
+    /** Validates this module's slice of the environment. Fails boot when invalid. */
+    config<T>(schema: ZodType<T>): T;
+    readonly log: Logger;
+    /**
+     * Every module in the assembly, id and `structural` flag only. The workspace
+     * module's settings screen is the one reader today: it needs the toggleable
+     * id list and cannot import `modules/core.ts` itself without a cycle, since
+     * that file is what constructs the workspace module in the first place.
+     */
+    readonly moduleCatalog: readonly ModuleCatalogEntry[];
+    /**
+     * The deploy-time module override (`lib/moduleConfig.ts`), unparsed into
+     * grants. The workspace module reads this to answer whether a module's value
+     * is locked, which `EntitlementRegistry.check`'s single merged answer cannot
+     * tell a caller on its own.
+     */
+    readonly moduleConfig: Readonly<Record<string, boolean>> | undefined;
+}
+export interface ModuleCatalogEntry {
+    readonly id: string;
+    readonly structural: boolean;
+}
+export interface KelpieModule {
+    readonly id: string;
+    /** Ids of modules that must register first. Missing ones fail boot. */
+    readonly requires?: readonly string[];
+    /**
+     * Marks a module as always enabled: no `module.<id>` capability is declared for
+     * it, its routes and MCP tools are never gated, and a deploy-time module config
+     * file or a workspace's own settings may not name it. True for the modules the
+     * rest of the app cannot function without.
+     *
+     * Absent (or false) means toggleable, which is the default a new module gets
+     * without its author having to opt in.
+     */
+    readonly structural?: boolean;
+    register(context: ModuleContext): Promise<void>;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/runtime/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/runtime/module.ts"],"names":[],"mappings":"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"}

package/dist/runtime/module.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=module.js.map

package/dist/runtime/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/runtime/module.ts"],"names":[],"mappings":""}

package/dist/runtime/moduleConfig.d.ts

@@ -0,0 +1,21 @@
+import type { GrantProvider } from './entitlements.ts';
+import type { KelpieModule } from './module.ts';
+export declare function moduleCapabilityName(moduleId: string): string;
+/** The inverse of `moduleCapabilityName`, for a provider deciding whether a capability is its concern. */
+export declare function parseModuleCapability(capabilityName: string): string | undefined;
+/**
+ * Validates a deploy-time module override (`lib/moduleConfig.ts`) against the
+ * assembled module list, the same way an unmet `requires` fails boot.
+ *
+ * @throws ModuleBootError listing every id that does not exist or names a
+ *   structural module, which cannot be locked because it cannot be disabled.
+ */
+export declare function validateModuleConfig(overrides: Readonly<Record<string, boolean>>, modules: readonly KelpieModule[]): void;
+/**
+ * Answers every `module.<id>` capability the deploy-time file has an opinion
+ * on. Registered ahead of any module's own provider (`registry.ts`), so a
+ * locked value wins over a workspace's own setting: `EntitlementRegistry.check`
+ * asks providers in registration order and stops at the first answer.
+ */
+export declare function createModuleConfigProvider(overrides: Readonly<Record<string, boolean>>): GrantProvider;
+//# sourceMappingURL=moduleConfig.d.ts.map

package/dist/runtime/moduleConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleConfig.d.ts","sourceRoot":"","sources":["../../src/runtime/moduleConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAU/C,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIhF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5C,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,IAAI,CAoBN;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,CAOtG"}

package/dist/runtime/moduleConfig.js

@@ -0,0 +1,54 @@
+import { ModuleBootError } from './order.js';
+/**
+ * The capability namespace `registry.ts` declares one flag under per
+ * non-structural module: `module.<id>`. Kept here, alongside the two things
+ * that read and write it, so the prefix has one owner.
+ */
+const MODULE_CAPABILITY_PREFIX = 'module.';
+export function moduleCapabilityName(moduleId) {
+    return `${MODULE_CAPABILITY_PREFIX}${moduleId}`;
+}
+/** The inverse of `moduleCapabilityName`, for a provider deciding whether a capability is its concern. */
+export function parseModuleCapability(capabilityName) {
+    return capabilityName.startsWith(MODULE_CAPABILITY_PREFIX)
+        ? capabilityName.slice(MODULE_CAPABILITY_PREFIX.length)
+        : undefined;
+}
+/**
+ * Validates a deploy-time module override (`lib/moduleConfig.ts`) against the
+ * assembled module list, the same way an unmet `requires` fails boot.
+ *
+ * @throws ModuleBootError listing every id that does not exist or names a
+ *   structural module, which cannot be locked because it cannot be disabled.
+ */
+export function validateModuleConfig(overrides, modules) {
+    const byId = new Map(modules.map((module) => [module.id, module]));
+    const problems = [];
+    for (const moduleId of Object.keys(overrides)) {
+        const module = byId.get(moduleId);
+        if (module === undefined) {
+            problems.push(`module config names "${moduleId}", which is not in the module list`);
+            continue;
+        }
+        if (module.structural === true) {
+            problems.push(`module config names "${moduleId}", which is structural and cannot be disabled`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new ModuleBootError(problems);
+    }
+}
+/**
+ * Answers every `module.<id>` capability the deploy-time file has an opinion
+ * on. Registered ahead of any module's own provider (`registry.ts`), so a
+ * locked value wins over a workspace's own setting: `EntitlementRegistry.check`
+ * asks providers in registration order and stops at the first answer.
+ */
+export function createModuleConfigProvider(overrides) {
+    return (_workspaceId, capability) => {
+        const moduleId = parseModuleCapability(capability.name);
+        const enabled = moduleId === undefined ? undefined : overrides[moduleId];
+        return Promise.resolve(enabled === undefined ? undefined : { kind: 'flag', granted: enabled });
+    };
+}
+//# sourceMappingURL=moduleConfig.js.map

package/dist/runtime/moduleConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleConfig.js","sourceRoot":"","sources":["../../src/runtime/moduleConfig.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;GAIG;AACH,MAAM,wBAAwB,GAAG,SAAS,CAAA;AAE1C,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,GAAG,wBAAwB,GAAG,QAAQ,EAAE,CAAA;AACjD,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,qBAAqB,CAAC,cAAsB;IAC1D,OAAO,cAAc,CAAC,UAAU,CAAC,wBAAwB,CAAC;QACxD,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC;QACvD,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA4C,EAC5C,OAAgC;IAEhC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAClE,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAEjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CAAC,wBAAwB,QAAQ,oCAAoC,CAAC,CAAA;YACnF,SAAQ;QACV,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,wBAAwB,QAAQ,+CAA+C,CAAC,CAAA;QAChG,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAA;IACrC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,SAA4C;IACrF,OAAO,CAAC,YAAY,EAAE,UAAU,EAAE,EAAE;QAClC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QACvD,MAAM,OAAO,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QAExE,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;IAChG,CAAC,CAAA;AACH,CAAC"}

package/dist/runtime/order.d.ts

@@ -0,0 +1,21 @@
+import type { KelpieModule } from './module.ts';
+/**
+ * Boot failed while validating or registering modules. Carries every problem
+ * found, so a misconfigured assembly reports all of them at once rather than
+ * one per run.
+ */
+export declare class ModuleBootError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[], options?: ErrorOptions);
+}
+/**
+ * Sorts modules so each one registers after everything it `requires`.
+ *
+ * Independent modules keep their declared order, which is how `architecture.md`
+ * pins the core module sequence. Nothing else about runtime behaviour may depend
+ * on ordering.
+ *
+ * @throws ModuleBootError on duplicate ids, unmet `requires`, or a dependency cycle.
+ */
+export declare function orderModules(modules: readonly KelpieModule[]): readonly KelpieModule[];
+//# sourceMappingURL=order.d.ts.map

package/dist/runtime/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../src/runtime/order.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAEpC,YAAY,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,EAI9D;CACF;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,YAAY,EAAE,CAyCtF"}

package/dist/runtime/order.js

@@ -0,0 +1,72 @@
+/**
+ * Boot failed while validating or registering modules. Carries every problem
+ * found, so a misconfigured assembly reports all of them at once rather than
+ * one per run.
+ */
+export class ModuleBootError extends Error {
+    problems;
+    constructor(problems, options) {
+        super(`Module boot failed:\n${problems.map((problem) => `  - ${problem}`).join('\n')}`, options);
+        this.name = 'ModuleBootError';
+        this.problems = problems;
+    }
+}
+function findStructuralProblems(modules, byId) {
+    const problems = [];
+    const seen = new Set();
+    for (const module of modules) {
+        if (seen.has(module.id)) {
+            problems.push(`duplicate module id "${module.id}"`);
+        }
+        seen.add(module.id);
+    }
+    for (const module of modules) {
+        for (const required of module.requires ?? []) {
+            if (!byId.has(required)) {
+                problems.push(`module "${module.id}" requires "${required}", which is not in the module list`);
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Sorts modules so each one registers after everything it `requires`.
+ *
+ * Independent modules keep their declared order, which is how `architecture.md`
+ * pins the core module sequence. Nothing else about runtime behaviour may depend
+ * on ordering.
+ *
+ * @throws ModuleBootError on duplicate ids, unmet `requires`, or a dependency cycle.
+ */
+export function orderModules(modules) {
+    const byId = new Map(modules.map((module) => [module.id, module]));
+    const problems = findStructuralProblems(modules, byId);
+    if (problems.length > 0) {
+        throw new ModuleBootError(problems);
+    }
+    const ordered = [];
+    const progress = new Map();
+    function visit(module, trail) {
+        const state = progress.get(module.id);
+        if (state === 'done') {
+            return;
+        }
+        if (state === 'visiting') {
+            throw new ModuleBootError([`module dependency cycle: ${[...trail, module.id].join(' -> ')}`]);
+        }
+        progress.set(module.id, 'visiting');
+        for (const required of module.requires ?? []) {
+            const dependency = byId.get(required);
+            if (dependency !== undefined) {
+                visit(dependency, [...trail, module.id]);
+            }
+        }
+        progress.set(module.id, 'done');
+        ordered.push(module);
+    }
+    for (const module of modules) {
+        visit(module, []);
+    }
+    return ordered;
+}
+//# sourceMappingURL=order.js.map

package/dist/runtime/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../src/runtime/order.ts"],"names":[],"mappings":"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"}

package/dist/runtime/registry.d.ts

@@ -0,0 +1,66 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import type { Actor } from '../lib/actor.ts';
+import type { Environment } from '../lib/config.ts';
+import type { Logger } from '../lib/logger.ts';
+import type { EntitlementRegistry } from './entitlements.ts';
+import type { EventBus } from './events.ts';
+import type { KelpieModule, McpTool, ModuleServices, SchemaContribution } from './module.ts';
+/**
+ * Everything the modules contributed during the registration pass. The app mounts
+ * the routers; the migration pipeline and the MCP endpoint consume the rest as
+ * those land.
+ */
+export interface ModuleContributions {
+    readonly routers: readonly ModuleRouter[];
+    /** Routers for `/v1/public`: no credentials, CORS open. `architecture.md` boot step 5. */
+    readonly publicRouters: readonly ModuleRouter[];
+    readonly schemas: readonly SchemaContribution[];
+    readonly mcpTools: readonly McpTool[];
+    /** The bus every module subscribed to. Services publish through it after commit. */
+    readonly events: EventBus;
+    /** Everything the modules declared, and any provider they registered. */
+    readonly entitlements: EntitlementRegistry;
+}
+export interface ModuleRouter {
+    readonly moduleId: string;
+    readonly router: Hono;
+}
+export interface ModuleRuntimeOptions {
+    readonly modules: readonly KelpieModule[];
+    /** Raw variables. Each module validates the slice it needs via `context.config`. */
+    readonly environment: Environment;
+    readonly logger: Logger;
+    /** Injected so a test can watch what core modules subscribe to. Defaults to a fresh bus. */
+    readonly events?: EventBus;
+    /** Injected so a test can grant or deny before core modules register. */
+    readonly entitlements?: EntitlementRegistry;
+    /** The database, transaction scope, and collaborators every module builds on. */
+    readonly services: ModuleServices;
+    /**
+     * The deploy-time module override (`lib/moduleConfig.ts`), parsed. A locked
+     * module id wins over whatever a workspace's own settings say.
+     */
+    readonly moduleConfig?: Readonly<Record<string, boolean>>;
+    /**
+     * Resolves the caller of a REST request, the same way every route already
+     * does (`modules/auth/credentials.ts`), so a non-structural module's router
+     * can be gated by `module.<id>` before any of its own routes run.
+     *
+     * Optional, and not part of `ModuleServices`: `runtime/` must not import a
+     * feature module, so this arrives as a function rather than a dependency on
+     * auth directly. Omitted, REST gating is skipped entirely, which is what
+     * every test that does not exercise module toggling wants without having to
+     * say so.
+     */
+    readonly resolveActor?: (context: Context) => Promise<Actor>;
+}
+/**
+ * Runs the registration pass: validate the module list, then call each module's
+ * `register` once, in dependency order.
+ *
+ * @returns The accumulated contributions.
+ * @throws ModuleBootError when the list is invalid or a module fails to register.
+ */
+export declare function registerModules(options: ModuleRuntimeOptions): Promise<ModuleContributions>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/runtime/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EAGP,cAAc,EACd,kBAAkB,EACnB,MAAM,aAAa,CAAA;AAIpB;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC/C,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAA;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IACzC,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACzD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;CAC7D;AA+GD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuEjG"}

package/dist/runtime/registry.js

@@ -0,0 +1,148 @@
+import { Hono } from 'hono';
+import { requireWorkspaceId } from '../lib/actor.js';
+import { AppError, describeThrown, describeValidationIssue, toErrorDetails } from '../lib/errors.js';
+import { createEntitlementRegistry, requireCapability } from './entitlements.js';
+import { createEventBus } from './events.js';
+import { createModuleConfigProvider, moduleCapabilityName, validateModuleConfig } from './moduleConfig.js';
+import { ModuleBootError, orderModules } from './order.js';
+function createModuleContext(module, accumulator, options, events, entitlements, moduleCatalog) {
+    return {
+        ...options.services,
+        routes(mount) {
+            const router = new Hono();
+            // Gate first, so it runs before anything `mount` adds: Hono composes a
+            // path's handlers in the order they were registered on this router,
+            // middleware included, and registering after the routes it should guard
+            // would run it too late to block them.
+            if (module.structural !== true && options.resolveActor !== undefined) {
+                const { resolveActor } = options;
+                router.use('*', async (context, next) => {
+                    const actor = await resolveActor(context);
+                    await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id));
+                    await next();
+                });
+            }
+            mount(router);
+            accumulator.routers.push({ moduleId: module.id, router });
+        },
+        publicRoutes(mount) {
+            const router = new Hono();
+            mount(router);
+            accumulator.publicRouters.push({ moduleId: module.id, router });
+        },
+        schema(tables, migrationsDir) {
+            accumulator.schemas.push({ moduleId: module.id, tables, migrationsDir });
+        },
+        mcp: {
+            tool(definition) {
+                if (accumulator.mcpTools.some((existing) => existing.name === definition.name)) {
+                    throw new ModuleBootError([`module "${module.id}" declares MCP tool "${definition.name}" twice`]);
+                }
+                accumulator.mcpTools.push({
+                    name: definition.name,
+                    description: definition.description,
+                    inputSchema: definition.inputSchema,
+                    // Parsing here is what keeps MCP and REST from drifting: both surfaces
+                    // validate with the module's schema and fail with the same api.md error.
+                    invoke: async (rawInput, actor) => {
+                        const parsed = definition.inputSchema.safeParse(rawInput);
+                        if (!parsed.success) {
+                            throw AppError.validationFailed(`Invalid arguments for tool "${definition.name}"`, toErrorDetails(parsed.error.issues));
+                        }
+                        // The MCP endpoint already resolved `actor` once, from the bearer
+                        // key, before dispatch reached here (`modules/mcp/router.ts`), so
+                        // gating needs no resolution step of its own the way the REST
+                        // gate above does.
+                        if (module.structural !== true) {
+                            await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id));
+                        }
+                        return definition.invoke(parsed.data, actor);
+                    },
+                });
+            },
+        },
+        config(schema) {
+            const result = schema.safeParse(options.environment);
+            if (!result.success) {
+                throw new ModuleBootError(result.error.issues.map((issue) => `module "${module.id}" config ${describeValidationIssue(issue)}`));
+            }
+            return result.data;
+        },
+        events,
+        entitlements,
+        log: options.logger.child({ module: module.id }),
+        moduleCatalog,
+        moduleConfig: options.moduleConfig,
+    };
+}
+/**
+ * Runs the registration pass: validate the module list, then call each module's
+ * `register` once, in dependency order.
+ *
+ * @returns The accumulated contributions.
+ * @throws ModuleBootError when the list is invalid or a module fails to register.
+ */
+export async function registerModules(options) {
+    const ordered = orderModules(options.modules);
+    if (options.moduleConfig !== undefined) {
+        validateModuleConfig(options.moduleConfig, options.modules);
+    }
+    const events = options.events ?? createEventBus(options.logger);
+    const entitlements = options.entitlements ?? createEntitlementRegistry();
+    const accumulator = {
+        routers: [],
+        publicRouters: [],
+        schemas: [],
+        mcpTools: [],
+    };
+    const moduleCatalog = ordered.map((module) => ({
+        id: module.id,
+        structural: module.structural === true,
+    }));
+    // Declared once, centrally, rather than by each module's own `register`: a
+    // module author does nothing to become toggleable, which is the point of
+    // `structural` defaulting to false.
+    for (const module of ordered) {
+        if (module.structural !== true) {
+            entitlements.declare({
+                name: moduleCapabilityName(module.id),
+                kind: 'flag',
+                description: `Whether the "${module.id}" module is enabled for a workspace.`,
+            });
+        }
+    }
+    // Ahead of the registration loop, so it precedes any provider a module adds
+    // during its own `register` and therefore wins `EntitlementRegistry.check`'s
+    // first-answer-wins walk over providers.
+    if (options.moduleConfig !== undefined) {
+        entitlements.provide(createModuleConfigProvider(options.moduleConfig));
+    }
+    for (const module of ordered) {
+        const context = createModuleContext(module, accumulator, options, events, entitlements, moduleCatalog);
+        try {
+            await module.register(context);
+        }
+        catch (error) {
+            if (error instanceof ModuleBootError) {
+                throw error;
+            }
+            throw new ModuleBootError([`module "${module.id}" failed to register: ${describeThrown(error)}`], {
+                cause: error,
+            });
+        }
+        context.log.debug('module registered');
+    }
+    options.logger.info('modules registered', {
+        count: ordered.length,
+        ids: ordered.map((module) => module.id),
+    });
+    return {
+        routers: accumulator.routers,
+        publicRouters: accumulator.publicRouters,
+        schemas: accumulator.schemas,
+        mcpTools: accumulator.mcpTools,
+        events,
+        entitlements,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/runtime/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"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"}

package/dist/runtime/transaction.d.ts

@@ -0,0 +1,34 @@
+import type { Database } from '../lib/database.ts';
+import type { Logger } from '../lib/logger.ts';
+import type { DomainEventName, DomainEvents, EventBus } from './events.ts';
+/**
+ * One service call, one transaction, per `architecture.md`.
+ *
+ * Events emitted inside the work are buffered and published only after the
+ * transaction commits. A transaction that rolls back publishes nothing, so no
+ * consumer ever sees a record that does not exist.
+ */
+/** The transaction handle Drizzle passes to the work. Repositories join it. */
+export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0];
+/**
+ * What a repository function runs against: the pool for a single read, or an open
+ * transaction when a service is composing several writes.
+ */
+export type Queryable = Database | Transaction;
+/** Collects events during the transaction. Nothing leaves until commit. */
+export interface BufferedEvents {
+    emit<Name extends DomainEventName>(name: Name, payload: DomainEvents[Name]): void;
+}
+export interface TransactionContext {
+    readonly tx: Transaction;
+    readonly events: BufferedEvents;
+}
+/** Runs `work` in one transaction and publishes its events after commit. */
+export type TransactionScope = <Result>(work: (context: TransactionContext) => Promise<Result>) => Promise<Result>;
+export interface TransactionScopeDependencies {
+    readonly db: Database;
+    readonly bus: EventBus;
+    readonly logger: Logger;
+}
+export declare function createTransactionScope(dependencies: TransactionScopeDependencies): TransactionScope;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/runtime/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/runtime/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE1E;;;;;;GAMG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/E;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE9C,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAClF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAChC;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EACpC,IAAI,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,KACnD,OAAO,CAAC,MAAM,CAAC,CAAA;AAYpB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,4BAA4B,GAAG,gBAAgB,CA2BnG"}

package/dist/runtime/transaction.js

@@ -0,0 +1,24 @@
+export function createTransactionScope(dependencies) {
+    return async function runInTransaction(work) {
+        const buffered = [];
+        const result = await dependencies.db.transaction((tx) => work({
+            tx,
+            events: {
+                emit(name, payload) {
+                    buffered.push({ name, publish: () => dependencies.bus.publish(name, payload) });
+                },
+            },
+        }));
+        // Past this line the transaction has committed. Publishing is deliberately
+        // not awaited: the webhooks engine is a consumer, and an outbound HTTP
+        // delivery must not sit inside the request that triggered it. Tests and
+        // graceful shutdown wait via `bus.drain()`.
+        for (const event of buffered) {
+            void event.publish().catch((error) => {
+                dependencies.logger.error('event publication failed', { event: event.name, error });
+            });
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=transaction.js.map

package/dist/runtime/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/runtime/transaction.ts"],"names":[],"mappings":"AAoDA,MAAM,UAAU,sBAAsB,CAAC,YAA0C;IAC/E,OAAO,KAAK,UAAU,gBAAgB,CAAC,IAAI;QACzC,MAAM,QAAQ,GAAoB,EAAE,CAAA;QAEpC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CACtD,IAAI,CAAC;YACH,EAAE;YACF,MAAM,EAAE;gBACN,IAAI,CAAC,IAAI,EAAE,OAAO;oBAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;gBACjF,CAAC;aACF;SACF,CAAC,CACH,CAAA;QAED,2EAA2E;QAC3E,uEAAuE;QACvE,wEAAwE;QACxE,4CAA4C;QAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC5C,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;YACrF,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC"}