@kelpie/server 0.12.0 → 0.14.0

package/src/runtime/jobs.ts

@@ -0,0 +1,358 @@
+import { sql } from 'drizzle-orm'
+import { PgBoss, fromDrizzle } from 'pg-boss'
+import type { Job } from 'pg-boss'
+
+import { describeThrown } from '../lib/errors.ts'
+import type { Logger } from '../lib/logger.ts'
+import type {
+  EnqueueOptions,
+  JobContext,
+  JobDefinition,
+  JobHandle,
+  JobRegistry,
+} from '../lib/jobs.ts'
+import { deadLetterQueueName } from '../lib/jobs.ts'
+import type { Transaction } from './transaction.ts'
+
+/**
+ * The pg-boss provider that binds the job port defined in `lib/jobs.ts` to a
+ * real Postgres-backed queue.
+ *
+ * Two phases:
+ *
+ * 1. Registration, at boot. Modules call `context.jobs.define(...)` during
+ *    `register`. The registry records the definition (fails boot on a
+ *    duplicate name) and returns the handle. Nothing touches the database
+ *    yet.
+ * 2. `start()`, from the entry point. Opens the pg-boss instance, primes the
+ *    queue cache, and calls `createQueue` for every registered handle plus
+ *    its dead-letter queue. Idempotent (`create_queue` upserts).
+ *
+ * The API and the worker both call `start()`: the API needs a boss instance
+ * to insert jobs on request-scoped transactions; the worker adds a
+ * `startWorking()` step that runs `work()` per handle.
+ *
+ * @see modules.md for how jobs sit next to the event bus.
+ */
+
+/**
+ * The pg-boss schema name. Fixed here rather than configurable per assembly:
+ * self-hosters run one Postgres per Kelpie install and would gain nothing
+ * from renaming the schema.
+ */
+const PGBOSS_SCHEMA = 'pgboss'
+
+const DEFAULT_LOCAL_CONCURRENCY = 5
+
+interface RegisteredJob<Data> {
+  readonly definition: JobDefinition<Data>
+  readonly handle: JobHandle<Data>
+}
+
+export interface JobsRuntimeOptions {
+  readonly connectionString: string
+  readonly logger: Logger
+  /**
+   * Polling floor. LISTEN/NOTIFY wakes a worker immediately when a job is
+   * inserted via `send()`, but pg-boss's own retry re-insert (inside
+   * `fail()`) never notifies, so a retried job is only ever picked up by
+   * this poll — as is a fresh job if the listener never opened. Also used
+   * as pg-boss's `notifyPollingIntervalSeconds`, so NOTIFY-active queues
+   * poll no slower than this either. Default 2s in production; tests pass
+   * a shorter value so a retry runs within the test's own budget.
+   */
+  readonly pollingIntervalSeconds?: number
+  /**
+   * How many workers the runtime spins up per handle when a definition does
+   * not override `defaults.localConcurrency`. Matches pg-boss's default.
+   */
+  readonly defaultLocalConcurrency?: number
+}
+
+export interface JobsRuntime {
+  /** The port modules bind to at register time. */
+  readonly registry: JobRegistry
+  /** True once `register` has been called with this name. Used by tests. */
+  hasHandle(name: string): boolean
+  /**
+   * Applies pg-boss's own schema migration. Idempotent: safe to run on every
+   * boot. Uses a throwaway `PgBoss` in `migrate: true, createSchema: true`
+   * mode, matching the release-command flow the cloud runs.
+   */
+  migrate(): Promise<void>
+  /**
+   * Opens the persistent pg-boss instance and declares every registered
+   * queue plus its dead-letter counterpart. Must run before `enqueueOnTx`
+   * or `startWorking`. `migrate: false` here: `migrate()` above owns that
+   * step, so instances never race the migration.
+   */
+  start(): Promise<void>
+  /**
+   * Starts the `work()` loop for every registered handle. The worker entry
+   * point calls this; the API calls it too unless `--no-worker` is set.
+   * Handler errors are logged and rethrown so pg-boss retries or
+   * dead-letters the job.
+   */
+  startWorking(): Promise<void>
+  /**
+   * Enqueues a job on the caller's transaction via `fromDrizzle(tx, sql)`.
+   * The insert commits with the surrounding write; a rollback discards it.
+   * Rejects when no `handle` was registered for `name` (this would be a
+   * boot-time bug, not a runtime one).
+   */
+  enqueueOnTx<Data>(
+    tx: Transaction,
+    handle: JobHandle<Data>,
+    data: Data,
+    options?: EnqueueOptions,
+  ): Promise<string | null>
+  /**
+   * Drains in-flight work and closes the pg-boss instance. `offWork({wait:
+   * true})` awaits every handler mid-flight; `boss.stop` then tears down
+   * the connection pool.
+   */
+  stop(): Promise<void>
+}
+
+export function createJobsRuntime(options: JobsRuntimeOptions): JobsRuntime {
+  const registered = new Map<string, RegisteredJob<unknown>>()
+  // Tracks which handles have had `createQueue` run and which have had
+  // `work()` called, so a runtime that registers a fresh handle after
+  // `start()` (a test that adds one mid-suite) still gets its queue built
+  // and its worker started without redoing the ones already up.
+  const queuesCreated = new Set<string>()
+  const workersStarted = new Set<string>()
+  let boss: PgBoss | undefined
+
+  function requireBoss(): PgBoss {
+    if (boss === undefined) {
+      throw new Error('jobs runtime used before start(): call jobs.start() at boot')
+    }
+    return boss
+  }
+
+  const registry: JobRegistry = {
+    define<Data>(definition: JobDefinition<Data>): JobHandle<Data> {
+      if (registered.has(definition.name)) {
+        throw new Error(`job "${definition.name}" is defined twice`)
+      }
+
+      const handle: JobHandle<Data> = { name: definition.name }
+      registered.set(definition.name, {
+        definition: definition as JobDefinition<unknown>,
+        handle: handle as JobHandle<unknown>,
+      })
+
+      return handle
+    },
+  }
+
+  async function migrate(): Promise<void> {
+    // A throwaway instance in migrate/createSchema mode. Cheaper than
+    // vendoring the SQL: pg-boss owns its schema, and `getConstructionPlans`
+    // / `getMigrationPlans` produce statements we would just execute in the
+    // same order the library does itself. `supervise: false, schedule: false`
+    // keeps the instance from spawning any background work while it lives.
+    const migrator = new PgBoss({
+      connectionString: options.connectionString,
+      schema: PGBOSS_SCHEMA,
+      migrate: true,
+      createSchema: true,
+      supervise: false,
+      schedule: false,
+    })
+
+    try {
+      await migrator.start()
+    } finally {
+      await migrator.stop({ graceful: false, close: true, timeout: 5_000 })
+    }
+  }
+
+  async function ensureQueuesFor(instance: PgBoss): Promise<void> {
+    for (const { definition } of registered.values()) {
+      if (queuesCreated.has(definition.name)) {
+        continue
+      }
+
+      const deadLetter = deadLetterQueueName(definition.name)
+
+      // Dead letter queue must exist before the main queue references it.
+      await instance.createQueue(deadLetter, {
+        policy: 'standard',
+        notify: false,
+      })
+
+      await instance.createQueue(definition.name, {
+        policy: 'standard',
+        deadLetter,
+        notify: true,
+        ...(definition.defaults?.retryLimit === undefined
+          ? {}
+          : { retryLimit: definition.defaults.retryLimit }),
+        ...(definition.defaults?.retryDelay === undefined
+          ? {}
+          : { retryDelay: definition.defaults.retryDelay }),
+        ...(definition.defaults?.retryBackoff === undefined
+          ? {}
+          : { retryBackoff: definition.defaults.retryBackoff }),
+        ...(definition.defaults?.retryDelayMax === undefined
+          ? {}
+          : { retryDelayMax: definition.defaults.retryDelayMax }),
+        ...(definition.defaults?.expireInSeconds === undefined
+          ? {}
+          : { expireInSeconds: definition.defaults.expireInSeconds }),
+      })
+
+      queuesCreated.add(definition.name)
+    }
+  }
+
+  async function start(): Promise<void> {
+    if (boss === undefined) {
+      const instance = new PgBoss({
+        connectionString: options.connectionString,
+        schema: PGBOSS_SCHEMA,
+        migrate: false,
+        createSchema: false,
+        supervise: false,
+        schedule: false,
+        useListenNotify: true,
+      })
+
+      instance.on('error', (error: unknown) => {
+        options.logger.error('pg-boss error', { error: describeThrown(error) })
+      })
+
+      await instance.start()
+      boss = instance
+    }
+
+    await ensureQueuesFor(boss)
+  }
+
+  async function startWorking(): Promise<void> {
+    const instance = requireBoss()
+    const pollingIntervalSeconds = options.pollingIntervalSeconds ?? 2
+    const defaultLocalConcurrency = options.defaultLocalConcurrency ?? DEFAULT_LOCAL_CONCURRENCY
+
+    for (const { definition } of registered.values()) {
+      if (workersStarted.has(definition.name)) {
+        continue
+      }
+
+      const localConcurrency = definition.defaults?.localConcurrency ?? defaultLocalConcurrency
+
+      await instance.work(
+        definition.name,
+        {
+          batchSize: 1,
+          localConcurrency,
+          pollingIntervalSeconds,
+          notifyPollingIntervalSeconds: pollingIntervalSeconds,
+        },
+        async (batch: Job<unknown>[]) => {
+          const job = batch[0]
+          if (job === undefined) {
+            return
+          }
+
+          const parsed = definition.schema.safeParse(job.data)
+
+          if (!parsed.success) {
+            options.logger.error('job payload rejected by schema', {
+              job: definition.name,
+              id: job.id,
+              issues: parsed.error.issues,
+            })
+            throw new Error(
+              `job "${definition.name}" payload does not match its schema: ${parsed.error.issues
+                .map((issue) => issue.message)
+                .join('; ')}`,
+            )
+          }
+
+          const jobLogger = options.logger.child({ job: definition.name, jobId: job.id })
+          const context: JobContext<unknown> = {
+            id: job.id,
+            data: parsed.data,
+            log: jobLogger,
+            signal: job.signal,
+          }
+
+          try {
+            await definition.handler(context)
+          } catch (error: unknown) {
+            jobLogger.error('job handler failed', { error: describeThrown(error) })
+            throw error
+          }
+        },
+      )
+
+      workersStarted.add(definition.name)
+    }
+  }
+
+  async function enqueueOnTx<Data>(
+    tx: Transaction,
+    handle: JobHandle<Data>,
+    data: Data,
+    enqueueOptions: EnqueueOptions = {},
+  ): Promise<string | null> {
+    const instance = requireBoss()
+    const entry = registered.get(handle.name)
+
+    if (entry === undefined) {
+      throw new Error(`enqueue for unregistered job "${handle.name}"`)
+    }
+
+    return instance.send(
+      handle.name,
+      data as object,
+      {
+        db: fromDrizzle(tx, sql),
+        ...(enqueueOptions.retryLimit === undefined ? {} : { retryLimit: enqueueOptions.retryLimit }),
+        ...(enqueueOptions.retryBackoff === undefined
+          ? {}
+          : { retryBackoff: enqueueOptions.retryBackoff }),
+        ...(enqueueOptions.singletonKey === undefined
+          ? {}
+          : { singletonKey: enqueueOptions.singletonKey }),
+        ...(enqueueOptions.startAfter === undefined ? {} : { startAfter: enqueueOptions.startAfter }),
+      },
+    )
+  }
+
+  async function stop(): Promise<void> {
+    const instance = boss
+    if (instance === undefined) {
+      return
+    }
+
+    for (const name of workersStarted) {
+      try {
+        await instance.offWork(name, { wait: true })
+      } catch (error: unknown) {
+        options.logger.error('offWork failed', {
+          job: name,
+          error: describeThrown(error),
+        })
+      }
+    }
+    workersStarted.clear()
+
+    await instance.stop({ graceful: true, close: true, timeout: 30_000 })
+    boss = undefined
+    queuesCreated.clear()
+  }
+
+  return {
+    registry,
+    hasHandle: (name) => registered.has(name),
+    migrate,
+    start,
+    startWorking,
+    enqueueOnTx,
+    stop,
+  }
+}

package/src/runtime/module.ts

@@ -5,6 +5,7 @@ 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 { JobRegistry } from '../lib/jobs.ts'
 import type { Logger } from '../lib/logger.ts'
 import type { SecretEncryptionConfig } from '../lib/secrets.ts'
 import type { EntitlementRegistry } from './entitlements.ts'
@@ -133,6 +134,14 @@ export interface ModuleServices {
    * `secretEncryption`. Same fallback pattern as `appBaseUrl`.
    */
   readonly secretEncryption?: SecretEncryptionConfig | undefined
+  /**
+   * Whether the instance accepts a brand-new account, from `kelpie.config.ts`'s
+   * `signups` (or `SIGNUPS`). Undefined defaults to `true` (open), the same
+   * default `loadConfig` and `resolveKelpieConfig` use, so a caller that has
+   * not thought about it — a test, an older assembly — sees no change in
+   * behaviour.
+   */
+  readonly signupsEnabled?: boolean
 }
 
 export interface ModuleContext extends ModuleServices {
@@ -232,6 +241,17 @@ export interface ModuleContext extends ModuleServices {
    * commits, and must be idempotent.
    */
   readonly events: EventBus
+  /**
+   * Declares a background job. Modules call `context.jobs.define(...)` at
+   * register time and receive a typed handle to enqueue against. The insert
+   * lives inside the caller's transaction (`services.transaction`) so a
+   * rollback discards the job.
+   *
+   * A second `define` with the same name fails boot. Handlers run out of
+   * process on the worker entry point, or inline when the API runs its own
+   * worker.
+   */
+  readonly jobs: JobRegistry
   /**
    * Declare capabilities and check grants. Every check is granted and unlimited
    * until a module registers a provider.

package/src/runtime/registry.ts

@@ -7,6 +7,7 @@ import type { Environment } from '../lib/config.ts'
 import { createLogEmailSender } from '../lib/email.ts'
 import type { EmailMessage, EmailSender } from '../lib/email.ts'
 import { AppError, describeThrown, describeValidationIssue, toErrorDetails } from '../lib/errors.ts'
+import type { JobRegistry } from '../lib/jobs.ts'
 import type { Logger } from '../lib/logger.ts'
 import { createEntitlementRegistry, requireCapability } from './entitlements.ts'
 import type { EntitlementRegistry } from './entitlements.ts'
@@ -87,6 +88,117 @@ function assertMountablePath(moduleId: string, kind: string, path: string): void
   }
 }
 
+/** Verb methods a module can call on the router — full Hono set. */
+const ROUTER_VERB_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'all'] as const
+type RouterVerbMethod = (typeof ROUTER_VERB_METHODS)[number]
+
+function isRouterVerbMethod(name: string): name is RouterVerbMethod {
+  return (ROUTER_VERB_METHODS as readonly string[]).includes(name)
+}
+
+/**
+ * Wraps a Hono router so every route the module registers runs `gate` first,
+ * and only that module's own routes. The straightforward alternative —
+ * `router.use('*', gate)` — attaches at `/v1/*` on the app once the router is
+ * mounted (Hono flattens sub-routers onto the parent prefix), so the gate
+ * fires for every module's routes, not just this module's. Prepending the gate
+ * to each declared route keeps the check local.
+ *
+ * The full router surface is covered so a future contributor cannot silently
+ * reintroduce the leak by reaching for a method that was not wrapped:
+ *
+ * - HTTP verbs and `on`: prepend `gate`, then the module's handlers.
+ * - `use(pattern, ...)` at a specific path: prepend `gate`, then the mw.
+ * - `route(subPath, subApp)`: recursively wrap `subApp` before mounting, so
+ *   every route it contributes still runs the gate first.
+ *
+ * And the calls that cannot be made module-local through wrapping fail at
+ * boot with a message naming the module, rather than shipping a subtle leak:
+ *
+ * - `use()` with no path, `use('*')`, `use('/*')`, `use('/')`: any of these
+ *   register a middleware at `/v1/*` on the parent app once the router is
+ *   mounted — the exact bug this wrapper prevents. A module that wants to
+ *   share middleware across many of its routes must name a specific path
+ *   (`/things/*`) or attach the middleware per route.
+ * - `notFound` / `onError`: fire for every unmatched or failing `/v1`
+ *   request once the router is flattened, so a module's handler would run
+ *   for other modules' traffic. Handle failures inside the module's own
+ *   route handlers instead.
+ */
+function gateRouter(router: Hono, moduleId: string, gate: MiddlewareHandler): Hono {
+  const proxy: Hono = new Proxy(router, {
+    get(target, property, receiver) {
+      if (typeof property !== 'string') {
+        return Reflect.get(target, property, receiver)
+      }
+
+      if (isRouterVerbMethod(property)) {
+        return (path: string, ...handlers: Handler[]): Hono => {
+          const method = target[property] as (path: string, ...handlers: Handler[]) => Hono
+          method.call(target, path, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'on') {
+        return (
+          method: string | string[],
+          path: string | string[],
+          ...handlers: Handler[]
+        ): Hono => {
+          target.on(method as never, path as never, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'use') {
+        return (...args: unknown[]): Hono => {
+          const first = args[0]
+          const isAppWide =
+            typeof first !== 'string' || first === '*' || first === '/*' || first === '/'
+
+          if (isAppWide) {
+            throw new ModuleBootError([
+              `module "${moduleId}" called router.use() with an app-wide pattern (${
+                typeof first === 'string' ? `"${first}"` : 'no path'
+              }). Hono flattens the module router onto "/v1", so this would fire for every module's routes. Name a specific path ("/things/*") or attach middleware per route.`,
+            ])
+          }
+
+          const [pattern, ...handlers] = args as [string, ...MiddlewareHandler[]]
+          target.use(pattern, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'route') {
+        return (path: string, subApp: Hono): Hono => {
+          // The sub-app's routes were registered on it before this call, so a
+          // proxy over `subApp` cannot retroactively prepend the gate to them.
+          // Instead attach the gate as middleware scoped to the sub-router's
+          // mount prefix on this router — once flattened onto `/v1`, the
+          // middleware covers exactly `/v1${path}/*`, which is the module's
+          // own routes. `use` must land before `route` so composition order
+          // runs the gate first.
+          target.use(`${path.replace(/\/+$/, '')}/*`, gate)
+          target.route(path, subApp)
+          return proxy
+        }
+      }
+
+      if (property === 'notFound' || property === 'onError') {
+        throw new ModuleBootError([
+          `module "${moduleId}" called router.${property}(). A module router's ${property} fires for every unmatched or failing "/v1" request once the router is mounted; handle failures inside the module's own route handlers instead.`,
+        ])
+      }
+
+      return Reflect.get(target, property, receiver)
+    },
+  }) as Hono
+
+  return proxy
+}
+
 /**
  * What `registerModules` needs.
  *
@@ -130,6 +242,13 @@ export interface ModuleRuntimeOptions {
    * two modules had registered it.
    */
   readonly additionalEmailProviders?: ReadonlyMap<string, EmailSender> | undefined
+  /**
+   * The job registry modules bind to at register time. Bound to the pg-boss
+   * runtime in production (`runtime/jobs.ts`) and to a stub in unit tests
+   * that never define a job. A module that calls `context.jobs.define` when
+   * this is absent gets a boot-time error naming the module.
+   */
+  readonly jobs?: JobRegistry | undefined
   /**
    * The deploy-time module override (`lib/moduleConfig.ts`), parsed. A locked
    * module id wins over whatever a workspace's own settings say.
@@ -238,6 +357,21 @@ interface RegisteredProvider {
   readonly registeredBy: string
 }
 
+/**
+ * Refuses `define` for a module that reached `context.jobs` when the runtime
+ * booted without a jobs registry. Named so a boot log points at the module
+ * whose declaration cannot be honoured, rather than a bare stack trace.
+ */
+function createMissingJobsRegistry(moduleId: string): JobRegistry {
+  return {
+    define() {
+      throw new ModuleBootError([
+        `module "${moduleId}" defines a job but the assembly booted without a jobs runtime`,
+      ])
+    },
+  }
+}
+
 function createModuleContext(
   module: KelpieModule,
   accumulator: Accumulator,
@@ -252,6 +386,7 @@ function createModuleContext(
   return {
     ...options.services,
     email: emailProxy,
+    jobs: options.jobs ?? createMissingJobsRegistry(module.id),
 
     provideExternalSignIn(handler) {
       externalSignIn.install(module.id, handler)
@@ -282,22 +417,25 @@ function createModuleContext(
     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.
+      // Gate must run before anything `mount` adds. A `router.use('*', gate)`
+      // here would attach at `/v1/*` on the app after mounting (Hono flattens
+      // the sub-router onto the parent prefix), which would fire the gate for
+      // every module's routes, not just this one's. So the gate is prepended
+      // to each individual route through `gateRouter` instead.
       if (module.structural !== true && options.resolveActor !== undefined) {
         const { resolveActor } = options
-
-        router.use('*', async (context, next) => {
+        const gate: MiddlewareHandler = async (context, next) => {
           const actor = await resolveActor(context)
 
           await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id))
           await next()
-        })
+        }
+
+        mount(gateRouter(router, module.id, gate))
+      } else {
+        mount(router)
       }
 
-      mount(router)
       accumulator.routers.push({ moduleId: module.id, router })
     },
 

package/src/runtime/transaction.ts

@@ -2,6 +2,11 @@ import type { EventActor, EventTarget, KelpieEvent } from '@kelpie/schemas'
 
 import type { Database } from '../lib/database.ts'
 import type { IdFactory } from '../lib/ids.ts'
+import type {
+  EnqueueOptions,
+  JobHandle,
+  TransactionJobs,
+} from '../lib/jobs.ts'
 import type { Logger } from '../lib/logger.ts'
 import { checkEventCycle, currentEventChain } from './events.ts'
 import type { EventBus, EventName, KelpieEventMap } from './events.ts'
@@ -43,6 +48,13 @@ export interface BufferedEvents {
 export interface TransactionContext {
   readonly tx: Transaction
   readonly events: BufferedEvents
+  /**
+   * Enqueues background work on the caller's transaction. The insert runs
+   * inside `tx` via pg-boss's Drizzle adapter, so a rolled-back scope
+   * discards the job with the write. Unlike `events`, this is not buffered:
+   * the return value carries the pg-boss job id, awaited inside the scope.
+   */
+  readonly jobs: TransactionJobs
 }
 
 export interface TransactionOptions {
@@ -69,6 +81,17 @@ interface BufferedEvent {
 
 const SYSTEM_ACTOR: EventActor = { kind: 'system' }
 
+/**
+ * Inserts a background job on `tx`. Bound to the pg-boss provider in
+ * production (`runtime/jobs.ts`) and to a stub in tests that never enqueue.
+ */
+export type EnqueueOnTransaction = <Data>(
+  tx: Transaction,
+  handle: JobHandle<Data>,
+  data: Data,
+  options?: EnqueueOptions,
+) => Promise<string | null>
+
 export interface TransactionScopeDependencies {
   readonly db: Database
   readonly bus: EventBus
@@ -78,12 +101,27 @@ export interface TransactionScopeDependencies {
   readonly now?: () => Date
   /** Chain-depth cap. Reads `KELPIE_EVENT_MAX_DEPTH`; otherwise 8. */
   readonly maxDepth?: number
+  /**
+   * How `tx.jobs.enqueue(...)` reaches pg-boss. Optional so unit tests that
+   * never enqueue can build the scope without a runtime; a call from a
+   * scope built without one rejects with a boot-time bug message.
+   */
+  readonly enqueueOnTx?: EnqueueOnTransaction
 }
 
 export function createTransactionScope(dependencies: TransactionScopeDependencies): TransactionScope {
   const now = dependencies.now ?? ((): Date => new Date())
   const maxDepth = dependencies.maxDepth ?? readMaxDepthFromEnv() ?? 8
 
+  const enqueueOnTx: EnqueueOnTransaction =
+    dependencies.enqueueOnTx ??
+    (() =>
+      Promise.reject(
+        new Error(
+          'jobs.enqueue used but no jobs runtime was wired into the transaction scope',
+        ),
+      ))
+
   return async function runInTransaction(work, options) {
     const actor = options?.actor ?? SYSTEM_ACTOR
     const workspaceId = options?.workspaceId
@@ -92,6 +130,11 @@ export function createTransactionScope(dependencies: TransactionScopeDependencie
     const result = await dependencies.db.transaction((tx) =>
       work({
         tx,
+        jobs: {
+          enqueue(handle, data, enqueueOptions) {
+            return enqueueOnTx(tx, handle, data, enqueueOptions)
+          },
+        },
         events: {
           emit(name, target, data) {
             if (workspaceId === undefined || workspaceId.length === 0) {

package/src/schema/index.ts

@@ -20,6 +20,7 @@ export * from '../modules/opportunities/schema.ts'
 export * from '../modules/partnerships/schema.ts'
 export * from '../modules/raises/schema.ts'
 export * from '../modules/hiring/schema.ts'
+export * from '../modules/events/schema.ts'
 export * from '../modules/plans/schema.ts'
 export * from '../modules/decisions/schema.ts'
 export * from '../modules/notes/schema.ts'