@kelpie/server 0.5.2 → 0.6.0

package/src/modules/workspace/service.ts

@@ -9,7 +9,9 @@ import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
 import { limitFor } from '../../runtime/entitlements.ts'
 import { moduleCapabilityName } from '../../runtime/moduleConfig.ts'
 import type { TransactionScope } from '../../runtime/transaction.ts'
+import { toEventActor } from '../../lib/actor.ts'
 import type { Actor, SessionActor } from '../auth/actor.ts'
+import './events.ts'
 import * as authRepository from '../auth/repository.ts'
 import { SEATS_LIMIT } from './capabilities.ts'
 import * as repository from './repository.ts'
@@ -460,11 +462,19 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
         // The session that created the workspace should land in it.
         await authRepository.setActiveWorkspace(tx, actor.sessionId, workspaceId)
 
-        events.emit('workspace.created', { workspaceId, slug: workspace.slug })
-        events.emit('member.joined', { workspaceId, memberId, userId: actor.userId })
+        events.emit(
+          'workspace.workspace.created',
+          { type: 'workspace', id: workspaceId },
+          { slug: workspace.slug },
+        )
+        events.emit(
+          'workspace.member.joined',
+          { type: 'member', id: memberId },
+          { userId: actor.userId },
+        )
 
         return toWorkspaceView(workspace)
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async get(actor, workspaceId) {
@@ -526,8 +536,12 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       await dependencies.transaction(async ({ tx, events }) => {
         await repository.deleteWorkspace(tx, workspaceId)
 
-        events.emit('workspace.deleted', { workspaceId, slug: workspace.slug })
-      })
+        events.emit(
+          'workspace.workspace.deleted',
+          { type: 'workspace', id: workspaceId },
+          { slug: workspace.slug },
+        )
+      }, { workspaceId, actor: toEventActor(actor) })
     },
 
     async listMembers(actor, workspaceId) {
@@ -602,8 +616,12 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
         await dependencies.transaction(async ({ tx, events }) => {
           await repository.deleteMember(tx, target.id)
 
-          events.emit('member.removed', { workspaceId, memberId: target.id, userId: target.userId })
-        })
+          events.emit(
+            'workspace.member.removed',
+            { type: 'member', id: target.id },
+            { userId: target.userId },
+          )
+        }, { workspaceId, actor: toEventActor(actor) })
       } catch (error: unknown) {
         // A record assigned to them between the count and this delete. The
         // constraint answers the same question the count did, so the caller gets
@@ -658,10 +676,14 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
           expiresAt: new Date(now.getTime() + INVITE_LIFETIME_MS),
         })
 
-        events.emit('member.invited', { workspaceId, inviteId: created.id, email: created.email })
+        events.emit(
+          'workspace.member.invited',
+          { type: 'invite', id: created.id },
+          { inviteId: created.id, email: created.email },
+        )
 
         return created
-      })
+      }, { workspaceId, actor: toEventActor(actor) })
 
       // Sent after commit, so a rolled-back invite never reaches an inbox.
       await sendInviteEmail(invite.email, token)
@@ -790,14 +812,14 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
           throw AppError.notFound('Workspace not found')
         }
 
-        events.emit('member.joined', {
-          workspaceId: invite.workspaceId,
-          memberId,
-          userId: actor.userId,
-        })
+        events.emit(
+          'workspace.member.joined',
+          { type: 'member', id: memberId },
+          { userId: actor.userId },
+        )
 
         return toWorkspaceView(workspace)
-      })
+      }, { workspaceId: invite.workspaceId, actor: toEventActor(actor) })
     },
 
     async listModuleSettings(actor, workspaceId) {

package/src/runtime/events.ts

@@ -1,3 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+import type { EventTarget, KelpieEvent } from '@kelpie/schemas'
+import Emittery from 'emittery'
+import type { ZodType } from 'zod'
+
 import { describeThrown } from '../lib/errors.ts'
 import type { Logger } from '../lib/logger.ts'
 
@@ -7,15 +13,16 @@ import type { Logger } from '../lib/logger.ts'
  * Delivery is at-least-once within the process, with no durable queue. A crash
  * between commit and dispatch loses the event. A durable outbox is a known
  * follow-up; do not build it before a consumer cannot tolerate the loss.
+ *
+ * Every event carries the envelope defined in `@kelpie/schemas`
+ * (`KelpieEvent<Name, Data>`). Names and payload schemas live in per-module
+ * catalogs the bus registers at boot; two modules cannot declare the same name.
  */
 
 /**
- * CRM object types that `record.*` events carry. Every object the API writes,
- * including the link and content records.
- *
- * Wider than `EXTENSIBLE_RECORD_TYPES` in `@kelpie/schemas`, which is the
- * shorter list of detail pages a UI module can contribute to. A Position, a
- * Form, and a Handbook page each publish events but have no page to extend.
+ * CRM object types the webhooks bridge treats as deliverable records. Kept
+ * here (rather than folded into a module) because import and webhooks both
+ * read it, and neither owns the list.
  */
 export const RECORD_OBJECT_TYPES = [
   'person',
@@ -33,87 +40,134 @@ export const RECORD_OBJECT_TYPES = [
 
 export type RecordObjectType = (typeof RECORD_OBJECT_TYPES)[number]
 
-/** Objects whose stage or status moves through a pipeline. */
-export type StagedObjectType = 'deal' | 'opportunity' | 'raise' | 'partnership'
-
 /**
- * The event catalog. Every payload carries `workspaceId`: a consumer must never
- * have to look up which tenant an event belongs to.
+ * The compile-time event catalog.
  *
- * Adding an event means adding a key here. The name is the key, so a typo is a
- * compile error rather than a subscription that never fires.
+ * Modules extend this interface via TypeScript declaration merging, one
+ * declaration per module. The runtime catalog (see `registerCatalog`) is the
+ * authority; this interface is what gives autocomplete and payload typing at
+ * every `publish` and `subscribe` call site.
  */
-export interface DomainEvents {
-  'workspace.created': { workspaceId: string; slug: string }
-  /** Fires after the cascade, so nothing the workspace owned still exists. */
-  'workspace.deleted': { workspaceId: string; slug: string }
-  'member.invited': { workspaceId: string; inviteId: string; email: string }
-  'member.joined': { workspaceId: string; memberId: string; userId: string }
-  /** Pairs with `member.joined`, which is what a seat count subscribes to. */
-  'member.removed': { workspaceId: string; memberId: string; userId: string }
-  'record.created': { workspaceId: string; objectType: RecordObjectType; recordId: string }
-  'record.updated': {
-    workspaceId: string
-    objectType: RecordObjectType
-    recordId: string
-    changedFields: readonly string[]
-  }
-  'record.deleted': { workspaceId: string; objectType: RecordObjectType; recordId: string }
-  'stage.changed': {
-    workspaceId: string
-    objectType: StagedObjectType
-    recordId: string
-    fromStageId: string | null
-    toStageId: string
-  }
-  'note.added': { workspaceId: string; noteId: string; targetType: string; targetId: string }
-  'decision.added': { workspaceId: string; decisionId: string; targetType: string; targetId: string }
-  'plan.completed': { workspaceId: string; planItemId: string; targetType: string; targetId: string }
-  'form.submitted': { workspaceId: string; formId: string; submissionId: string }
-  'import.completed': { workspaceId: string; importJobId: string; object: string }
-  'agent_run.finished': { workspaceId: string; agentRunId: string; status: 'succeeded' | 'failed' }
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface KelpieEventMap {}
+
+/**
+ * When `KelpieEventMap` is empty (no module has declared an event yet) `keyof`
+ * is `never`, which would make every `EventHandler` signature unusable. The
+ * fallback keeps types working during boot and in tests that build the bus
+ * without any modules registered.
+ */
+type EventMapWithFallback = keyof KelpieEventMap extends never
+  ? Readonly<Record<string, unknown>>
+  : KelpieEventMap
+
+export type EventName = string & keyof EventMapWithFallback
+
+/** Handlers are async and must be idempotent: the same event may arrive twice. */
+export type EventHandler<Name extends EventName> = (
+  event: KelpieEvent<Name, EventMapWithFallback[Name]>,
+) => Promise<void> | void
+
+/** Prefix subscribers see events they cannot name statically. */
+export type AnyEventHandler = (event: KelpieEvent<string, unknown>) => Promise<void> | void
+
+/**
+ * What a module hands the runtime at registration: the module's id and the Zod
+ * schema for every event name the module publishes.
+ */
+export interface EventCatalog {
+  readonly moduleId: string
+  readonly events: Readonly<Record<string, ZodType>>
 }
 
-export type DomainEventName = keyof DomainEvents
+/** One frame in the causation chain that produced an event. */
+export interface EventChainEntry {
+  readonly id: string
+  readonly name: string
+  readonly targetType: string
+  readonly targetId: string
+}
 
 /**
- * The catalog as data. Webhooks needs the deliverable event names at runtime, and
- * `satisfies` keeps this list from drifting from the interface above.
+ * The chain of ancestor events currently being handled, keyed against the async
+ * context that started them. `undefined` outside any handler.
  *
- * An event added to `DomainEvents` but forgotten here is caught by
- * `createHandlerRegistry`, which must produce an entry for every name.
+ * The bus wraps every `publish` in `run(child, ...)`, so a handler that opens a
+ * transaction and calls `emit(...)` inherits the chain. The transaction scope
+ * reads this to stamp `causedBy` and to run the cycle guard.
  */
-export const DOMAIN_EVENT_NAMES = [
-  'workspace.created',
-  'workspace.deleted',
-  'member.invited',
-  'member.joined',
-  'member.removed',
-  'record.created',
-  'record.updated',
-  'record.deleted',
-  'stage.changed',
-  'note.added',
-  'decision.added',
-  'plan.completed',
-  'form.submitted',
-  'import.completed',
-  'agent_run.finished',
-] as const satisfies readonly DomainEventName[]
+const chainStorage = new AsyncLocalStorage<readonly EventChainEntry[]>()
 
-/** Handlers are async and must be idempotent: the same event may arrive twice. */
-export type EventHandler<Name extends DomainEventName> = (payload: DomainEvents[Name]) => Promise<void>
+export function currentEventChain(): readonly EventChainEntry[] {
+  return chainStorage.getStore() ?? []
+}
+
+/**
+ * Runs the cycle guard against the current chain. Called from the transaction
+ * scope's `emit` before it buffers the event.
+ */
+export function checkEventCycle(
+  chain: readonly EventChainEntry[],
+  name: string,
+  target: EventTarget,
+  maxDepth: number,
+): CycleGuardOutcome {
+  if (chain.length >= maxDepth) {
+    return { kind: 'depth' }
+  }
+  for (const entry of chain) {
+    if (entry.name === name && entry.targetType === target.type && entry.targetId === target.id) {
+      return { kind: 'repeat' }
+    }
+  }
+  return { kind: 'ok' }
+}
+
+export type CycleGuardOutcome =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'depth' }
+  | { readonly kind: 'repeat' }
+
+export interface SubscribeOptions {
+  /** Shown in logs when the handler fails or times out. Defaults to the event name. */
+  readonly label?: string
+  /** Overrides the bus-wide default. */
+  readonly timeoutMs?: number
+}
 
 export interface EventBus {
-  /** Registers a handler. Handlers for one event run concurrently, not in order. */
-  subscribe<Name extends DomainEventName>(name: Name, handler: EventHandler<Name>): void
+  /**
+   * Registers a module's event catalog. Called by `registerModules` at boot,
+   * once per module that declares events. Two modules cannot declare the same
+   * event name; the second call throws.
+   */
+  registerCatalog(catalog: EventCatalog): void
+  /** True if any module has declared this event name. */
+  hasEvent(name: string): boolean
+  /** The payload schema registered for this event, or `undefined` if unknown. */
+  getSchema(name: string): ZodType | undefined
+  /**
+   * Subscribe to an event by exact name. Handlers for one event run
+   * concurrently, each in its own error and timeout boundary.
+   */
+  subscribe<Name extends EventName>(
+    name: Name,
+    handler: EventHandler<Name>,
+    options?: SubscribeOptions,
+  ): void
+  /**
+   * Subscribe to every event whose name starts with `prefix`. Runs concurrently
+   * with exact-name subscribers. Match is a plain `startsWith`; there is no
+   * pattern language.
+   */
+  subscribePrefix(prefix: string, handler: AnyEventHandler, options?: SubscribeOptions): void
   /**
    * Dispatches immediately. Services should not call this directly: they emit
    * through the transaction scope so nothing fires before the commit.
-   *
-   * @returns A promise that settles when every handler for this event has settled.
    */
-  publish<Name extends DomainEventName>(name: Name, payload: DomainEvents[Name]): Promise<void>
+  publish<Name extends EventName>(
+    event: KelpieEvent<Name, EventMapWithFallback[Name]>,
+  ): Promise<void>
   /**
    * Settles once every in-flight publication has finished, including any a
    * handler started. Used by tests, and by shutdown to flush before exit.
@@ -121,57 +175,164 @@ export interface EventBus {
   drain(): Promise<void>
 }
 
-/**
- * A handler that throws must not break the emitting request, and must not stop
- * its siblings. Failures are logged and dropped.
- */
-/** One handler list per event, keyed so each list stays tied to its payload type. */
-type HandlerRegistry = { [Name in DomainEventName]: EventHandler<Name>[] }
+export interface EventBusOptions {
+  /** Default per-handler timeout in ms. Defaults to 5000. */
+  readonly defaultHandlerTimeoutMs?: number
+}
+
+const DEFAULT_HANDLER_TIMEOUT_MS = 5000
+
+interface PrefixHandler {
+  readonly prefix: string
+  readonly label: string
+  readonly run: (event: KelpieEvent<string, unknown>) => Promise<void>
+}
 
 /**
- * Every name gets a list up front. TypeScript cannot check a write through a
- * generic key, so pre-seeding turns `subscribe` into a read plus a push, which it
- * can check. The one assertion is building a complete record from its own key list.
+ * Emittery v2 passes each listener an `{ name, data }` object rather than the
+ * raw payload. This shape stays internal so nothing outside this file sees the
+ * extra envelope on top of ours.
  */
-function createHandlerRegistry(): HandlerRegistry {
-  const registry: Partial<HandlerRegistry> = {}
-
-  for (const name of DOMAIN_EVENT_NAMES) {
-    registry[name] = []
-  }
+interface EmitteryListenerEvent {
+  readonly name: string
+  readonly data: unknown
+}
 
-  return registry as HandlerRegistry
+interface EmitterySignature {
+  readonly on: (
+    name: string,
+    listener: (event: EmitteryListenerEvent) => Promise<void> | void,
+  ) => () => void
+  readonly emit: (name: string, data: unknown) => Promise<void>
 }
 
-export function createEventBus(logger: Logger): EventBus {
-  const handlers = createHandlerRegistry()
-  const inFlight = new Set<Promise<void>>()
+export function createEventBus(logger: Logger, options: EventBusOptions = {}): EventBus {
+  const emittery = new Emittery() as unknown as EmitterySignature
+  const schemas = new Map<string, ZodType>()
+  const owners = new Map<string, string>()
+  const prefixHandlers: PrefixHandler[] = []
+  const inFlight = new Set<Promise<unknown>>()
+  const defaultTimeoutMs = options.defaultHandlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS
+
+  function wrap<Value>(
+    label: string,
+    timeoutMs: number,
+    handler: (event: Value) => Promise<void> | void,
+    context: (event: Value) => Readonly<Record<string, unknown>>,
+  ): (event: Value) => Promise<void> {
+    return async (event) => {
+      let timerHandle: NodeJS.Timeout | undefined
+      const timedOut = Symbol('timeout')
+      const timer = new Promise<typeof timedOut>((resolve) => {
+        timerHandle = setTimeout(() => resolve(timedOut), timeoutMs)
+        timerHandle.unref?.()
+      })
+
+      try {
+        const outcome = await Promise.race([
+          Promise.resolve().then(() => handler(event)),
+          timer,
+        ])
+        if (outcome === timedOut) {
+          logger.error('event handler timed out', { label, timeoutMs, ...context(event) })
+        }
+      } catch (error: unknown) {
+        logger.error('event handler failed', {
+          label,
+          error: describeThrown(error),
+          ...context(event),
+        })
+      } finally {
+        if (timerHandle !== undefined) {
+          clearTimeout(timerHandle)
+        }
+      }
+    }
+  }
 
   return {
-    subscribe(name, handler) {
-      handlers[name].push(handler)
+    registerCatalog(catalog) {
+      for (const [name, schema] of Object.entries(catalog.events)) {
+        const existing = owners.get(name)
+        if (existing !== undefined) {
+          throw new Error(
+            `event "${name}" is declared by both module "${existing}" and module "${catalog.moduleId}"`,
+          )
+        }
+        owners.set(name, catalog.moduleId)
+        schemas.set(name, schema)
+      }
+    },
+
+    hasEvent(name) {
+      return schemas.has(name)
     },
 
-    publish(name, payload) {
-      const registered = handlers[name]
-
-      const settled = Promise.allSettled(registered.map((handler) => handler(payload))).then(
-        (outcomes) => {
-          for (const outcome of outcomes) {
-            if (outcome.status === 'rejected') {
-              logger.error('event handler failed', {
-                event: name,
-                error: describeThrown(outcome.reason),
-              })
-            }
-          }
+    getSchema(name) {
+      return schemas.get(name)
+    },
+
+    subscribe(name, handler, subscribeOptions) {
+      const label = subscribeOptions?.label ?? name
+      const timeoutMs = subscribeOptions?.timeoutMs ?? defaultTimeoutMs
+      const wrapped = wrap<EmitteryListenerEvent>(
+        label,
+        timeoutMs,
+        (event) => {
+          const envelope = event.data as KelpieEvent<string, unknown>
+          return handler(envelope as never)
         },
+        (event) => {
+          const envelope = event.data as KelpieEvent<string, unknown>
+          return { event: envelope.name, eventId: envelope.id }
+        },
+      )
+      emittery.on(name, wrapped)
+    },
+
+    subscribePrefix(prefix, handler, subscribeOptions) {
+      const label = subscribeOptions?.label ?? `${prefix}*`
+      const timeoutMs = subscribeOptions?.timeoutMs ?? defaultTimeoutMs
+      prefixHandlers.push({
+        prefix,
+        label,
+        run: wrap<KelpieEvent<string, unknown>>(
+          label,
+          timeoutMs,
+          handler,
+          (event) => ({ event: event.name, eventId: event.id }),
+        ),
+      })
+    },
+
+    publish(event) {
+      const parent = chainStorage.getStore() ?? []
+      const child: EventChainEntry[] = [
+        ...parent,
+        {
+          id: event.id,
+          name: event.name,
+          targetType: event.target.type,
+          targetId: event.target.id,
+        },
+      ]
+
+      const matching = prefixHandlers.filter((entry) => event.name.startsWith(entry.prefix))
+      const typedEvent = event as KelpieEvent<string, unknown>
+
+      const settled = chainStorage.run(child, () =>
+        Promise.allSettled([
+          emittery.emit(event.name, typedEvent),
+          ...matching.map((entry) => entry.run(typedEvent)),
+        ]),
       )
 
       inFlight.add(settled)
-      void settled.finally(() => inFlight.delete(settled))
+      void settled.finally(() => {
+        inFlight.delete(settled)
+      })
 
-      return settled
+      return settled.then(() => undefined)
     },
 
     async drain() {

package/src/runtime/module.ts

@@ -6,6 +6,7 @@ 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 { SecretEncryptionConfig } from '../lib/secrets.ts'
 import type { EntitlementRegistry } from './entitlements.ts'
 import type { EventBus } from './events.ts'
 import type { TransactionScope } from './transaction.ts'
@@ -69,17 +70,55 @@ 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
+  /**
+   * The deployment's base URL, when the assembly declares `appBaseUrl` in
+   * `kelpie.config.ts`. Modules that need it prefer this over
+   * `context.config(appUrlConfigSchema)`, which they fall back to when this is
+   * undefined (older assemblies).
+   */
+  readonly appBaseUrl?: string | undefined
+  /**
+   * The keys that seal stored secrets, when the assembly declares
+   * `secretEncryption`. Same fallback pattern as `appBaseUrl`.
+   */
+  readonly secretEncryption?: SecretEncryptionConfig | undefined
 }
 
 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 a named transactional-mail provider. `name` is what the assembly
+   * puts in `kelpie.config.ts`'s `email.provider`; the runtime resolves that
+   * field against the registry after every module has registered.
+   *
+   * `build` is a factory the runtime calls exactly once, and only for the
+   * provider `email.provider` picked. A provider that is registered but never
+   * picked never has its factory called, so a module can register itself
+   * without demanding its own env up front: a self-hoster who leaves the
+   * built-in `smtp-email` core module in `coreModules` while running on
+   * `EMAIL_PROVIDER=log` will not be asked for SMTP credentials at boot.
+   * The factory may throw; the runtime wraps the error with the module id.
+   *
+   * Any number of modules may register different names side by side. Two
+   * modules registering the same name fails boot. `'log'` is registered by
+   * the runtime itself, so a module that tries to shadow it fails boot too.
+   *
+   * `context.email` is a proxy: every module receives the same object, and
+   * its `send` delegates to whichever provider `email.provider` picked.
+   * Consumer modules capture the proxy at register time; registration order
+   * does not matter.
+   */
+  provideEmailSender(name: string, build: () => EmailSender): void
+  /**
+   * Transactional mail. Every module receives the same proxy; `.send()`
+   * delegates to the provider `email.provider` picked.
+   */
+  readonly email: EmailSender
   /**
    * Registers routes that mount under `/v1/public`, take no credentials, and
    * answer cross-origin requests from any site.
@@ -153,6 +192,15 @@ export interface ModuleCatalogEntry {
   readonly structural: boolean
 }
 
+/**
+ * A module's event catalog: the Zod schema for every event name the module
+ * publishes. Registered with the bus at boot; two modules cannot claim the same
+ * name.
+ */
+export interface ModuleEventCatalog {
+  readonly [eventName: string]: ZodType
+}
+
 export interface KelpieModule {
   readonly id: string
   /** Ids of modules that must register first. Missing ones fail boot. */
@@ -167,5 +215,10 @@ export interface KelpieModule {
    * without its author having to opt in.
    */
   readonly structural?: boolean
+  /**
+   * The events this module publishes, as a runtime catalog. Optional: a module
+   * that only consumes events, or contributes none, may omit it.
+   */
+  readonly events?: ModuleEventCatalog
   register(context: ModuleContext): Promise<void>
 }