pipework 0.251.0 → 0.252.1

package/src/core/surface/http.ts

@@ -0,0 +1,133 @@
+import type { Manifold } from '../pipework.js'
+import type { HttpSurfaceBuilder, SurfaceHandle, HttpSurfaceConfig, SurfaceContext, SurfaceStartOptions, TestClient } from './types.js'
+import type { ServerConfig } from '../../request/http/types.js'
+import { DEFAULT_DB } from '../../request/di/types.js'
+import { createServer } from '../../request/http/server.js'
+import { resourceToHandlers } from '../../request/fixture/to-handlers.js'
+import { generateOpenAPI } from '../../request/openapi/generate.js'
+import type { RouteRegistration } from '../../request/http/types.js'
+import { ConfigError } from '../config/errors.js'
+
+export function createHttpSurface(config: HttpSurfaceConfig): HttpSurfaceBuilder {
+  const databases = collectHttpDatabases(config)
+  const deps: Record<string, string> = {}
+
+  const surface: HttpSurfaceBuilder = {
+    kind: 'http',
+    port: config.port,
+    manifest: { databases, jobTypes: [], dependencies: deps },
+
+    openapi() {
+      if (config.openapi === undefined) {
+        throw new ConfigError(
+          'This http surface declares no `openapi` info, so there is no OpenAPI document to build.',
+          'Add `openapi: { title, version }` to the surface config, e.g. surface.http({ openapi: { title: \'My API\', version: \'1.0.0\' }, ... }).',
+        )
+      }
+      return generateOpenAPI(config.openapi, surfaceRoutes(config), { rateLimited: config.rateLimit !== false || config.rateLimits !== undefined })
+    },
+
+    dependencies(d: Record<string, string>) {
+      Object.assign(deps, d)
+      return surface
+    },
+
+    async start(context: SurfaceContext, options?: SurfaceStartOptions): Promise<SurfaceHandle> {
+      const serverConfig = buildServerConfig(config)
+      if (config.port === undefined && options?.port !== undefined) (serverConfig as { port: number }).port = options.port
+      const server = createServer(context as unknown as Manifold, serverConfig)
+
+      registerSurfaceHandlers(server, config)
+
+      const address = await server.listen()
+
+      return {
+        kind: 'http',
+        address,
+        async stop(force) {
+          await server.stop(force)
+        },
+      }
+    },
+
+    async test(context: SurfaceContext): Promise<TestClient> {
+      const serverConfig = buildServerConfig(config)
+      serverConfig.managed = false
+      if (serverConfig.logger === undefined) {
+        serverConfig.logger = false
+      }
+
+      const server = createServer(context as unknown as Manifold, serverConfig)
+
+      registerSurfaceHandlers(server, config)
+
+      await server.ready()
+
+      return {
+        inject: (opts) => server.inject(opts),
+        close: () => server.close(),
+      }
+    },
+  }
+
+  return surface
+}
+
+/** The routes a server registers for this surface, in registration order: handlers, then each resource's handlers. */
+export function surfaceRoutes(config: HttpSurfaceConfig): RouteRegistration[] {
+  const routes: RouteRegistration[] = []
+  const add = (handlers: readonly RouteRegistration['handler'][]): void => {
+    for (const handler of handlers) {
+      if (handler.meta.route) {
+        routes.push({ method: handler.meta.route.method, path: handler.meta.route.path, handler })
+      }
+    }
+  }
+  add(config.handlers ?? [])
+  for (const resource of config.resources ?? []) add(resourceToHandlers(resource))
+  return routes
+}
+
+function registerSurfaceHandlers(server: ReturnType<typeof createServer>, config: HttpSurfaceConfig): void {
+  const handlers = surfaceRoutes(config).map((r) => r.handler)
+  if (handlers.length > 0) server.registerHandlers(handlers)
+}
+
+function buildServerConfig(config: HttpSurfaceConfig): ServerConfig {
+  const sc: ServerConfig = { managed: true }
+
+  if (config.port !== undefined) (sc as { port: number }).port = config.port
+  if (config.host !== undefined) (sc as { host: string }).host = config.host
+  if (config.gracefulShutdownMs !== undefined) (sc as { gracefulShutdownMs: number }).gracefulShutdownMs = config.gracefulShutdownMs
+  if (config.auth !== undefined) (sc as { auth: ServerConfig['auth'] }).auth = config.auth
+  if (config.tenant !== undefined) (sc as { tenant: ServerConfig['tenant'] }).tenant = config.tenant
+  if (config.cors !== undefined) (sc as { cors: ServerConfig['cors'] }).cors = config.cors
+  if (config.security !== undefined) (sc as { security: ServerConfig['security'] }).security = config.security
+  if (config.rateLimit !== undefined) (sc as { rateLimit: ServerConfig['rateLimit'] }).rateLimit = config.rateLimit
+  if (config.rateLimits !== undefined) (sc as { rateLimits: ServerConfig['rateLimits'] }).rateLimits = config.rateLimits
+  if (config.openapi !== undefined) (sc as { openapi: ServerConfig['openapi'] }).openapi = config.openapi
+  if (config.rbac !== undefined) (sc as { rbac: ServerConfig['rbac'] }).rbac = config.rbac
+  if (config.transactionPerRequest !== undefined) (sc as { transactionPerRequest: ServerConfig['transactionPerRequest'] }).transactionPerRequest = config.transactionPerRequest
+  if (config.transactionTimeoutMs !== undefined) (sc as { transactionTimeoutMs: ServerConfig['transactionTimeoutMs'] }).transactionTimeoutMs = config.transactionTimeoutMs
+  if (config.healthChecks !== undefined) (sc as { healthChecks: ServerConfig['healthChecks'] }).healthChecks = config.healthChecks
+  if (config.logging !== undefined) (sc as { logging: ServerConfig['logging'] }).logging = config.logging
+  if (config.logger !== undefined) (sc as { logger: ServerConfig['logger'] }).logger = config.logger
+  if (config.trustProxy !== undefined) (sc as { trustProxy: ServerConfig['trustProxy'] }).trustProxy = config.trustProxy
+  if (config.bodyLimit !== undefined) (sc as { bodyLimit: ServerConfig['bodyLimit'] }).bodyLimit = config.bodyLimit
+  if (config.onInternalError !== undefined) (sc as { onInternalError: ServerConfig['onInternalError'] }).onInternalError = config.onInternalError
+
+  return sc
+}
+
+function collectHttpDatabases(config: HttpSurfaceConfig): string[] {
+  const dbs = new Set<string>()
+  for (const h of config.handlers ?? []) {
+    for (const db of h.meta.databases) {
+      dbs.add(db === DEFAULT_DB ? DEFAULT_DB : db)
+    }
+  }
+  for (const r of config.resources ?? []) {
+    dbs.add(r.meta.database)
+  }
+  return [...dbs]
+}

package/src/core/surface/index.ts

@@ -0,0 +1,11 @@
+export { createHttpSurface } from './http.js'
+export { createWorkerSurface } from './worker.js'
+export { createScriptSurface } from './script.js'
+export { validateSurfaces, validateNoJobTypeDuplicates } from './validate.js'
+export { startSurfaces, type StartResult } from './start.js'
+export type {
+  SurfaceKind, SurfaceManifest, SurfaceHandle, Surface, SurfaceBuilder, SurfaceContext,
+  HttpSurfaceConfig, HttpSurfaceBuilder, TestClient,
+  WorkerSurfaceConfig, JobEvent, JobEventJob, ScriptSurfaceConfig, ScriptContext,
+  RetryConfig, SurfaceMap,
+} from './types.js'

package/src/core/surface/job-timeout.ts

@@ -0,0 +1,40 @@
+/**
+ * Runs the job under a deadline that CANCELS it rather than merely giving up on
+ * it: the signal reaches `executeJob`, which cancels the in-flight query and
+ * rolls back, so a timed-out job stops holding its transaction and its backend.
+ * The abort reason is the timeout error, so that is what the job fails with.
+ *
+ * The deadline still holds for a handler that ignores its signal: the wait ends
+ * on abort either way, so the worker slot is freed on time and the job is
+ * recorded as failed — the signal is what additionally frees the backend.
+ */
+export async function executeWithTimeout<T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  timeoutMs: number | undefined,
+  jobType: string,
+  jobId: string,
+): Promise<T> {
+  if (timeoutMs === undefined) return fn()
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => {
+    controller.abort(new Error(
+      `[pipework] Job "${jobType}" (${jobId}) timed out after ${timeoutMs}ms.\n\n` +
+      '  The job handler did not complete within the configured timeout.\n' +
+      '  Increase the timeout with .timeout(ms) or optimize the handler.\n'
+    ))
+  }, timeoutMs)
+  timer.unref()
+
+  const expired = new Promise<never>((_, reject) => {
+    controller.signal.addEventListener('abort', () => { reject(controller.signal.reason as Error) }, { once: true })
+  })
+
+  try {
+    const work = fn(controller.signal)
+    work.catch(() => {})
+    return await Promise.race([work, expired])
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/src/core/surface/namespace.ts

@@ -0,0 +1,13 @@
+import { createHttpSurface } from './http.js'
+import { createWorkerSurface } from './worker.js'
+import { createScriptSurface } from './script.js'
+
+/** Surface namespace — declarative entry points that define how the app runs (HTTP server, background worker, one-shot script). */
+export const surface = {
+  /** Creates an HTTP surface — a Fastify server with routes, middleware, and production validation. Returns an HttpSurfaceBuilder with a .test() method for inject()-based integration tests. */
+  http: createHttpSurface,
+  /** Creates a worker surface — a long-running process that claims and executes jobs from queues. */
+  worker: createWorkerSurface,
+  /** Creates a script surface — a one-shot process that runs and exits (migrations, seeds, CLI tools). The run is traced as a job-kind trace that names the surface. */
+  script: createScriptSurface,
+}

package/src/core/surface/script.ts

@@ -0,0 +1,33 @@
+import type { SurfaceBuilder, SurfaceHandle, ScriptSurfaceConfig, SurfaceContext, SurfaceStartOptions } from './types.js'
+import type { Manifold } from '../pipework.js'
+import { runScript } from '../../async/jobs/run-script.js'
+
+export function createScriptSurface(config: ScriptSurfaceConfig): SurfaceBuilder {
+  const deps: Record<string, string> = {}
+
+  const surface: SurfaceBuilder = {
+    kind: 'script',
+    manifest: { databases: config.databases ?? [], jobTypes: [], dependencies: deps },
+
+    dependencies(d: Record<string, string>) {
+      Object.assign(deps, d)
+      return surface
+    },
+
+    async start(context: SurfaceContext, options?: SurfaceStartOptions): Promise<SurfaceHandle> {
+      const instance = context as unknown as Manifold
+      await runScript(instance, () => config.run({
+        config: context.config,
+        env: context.env,
+        pool: context.pool,
+      }), { jobType: 'script', process: { phase: 'script', surfaces: [options?.name ?? 'script'] } })
+
+      return {
+        kind: 'script',
+        async stop() {},
+      }
+    },
+  }
+
+  return surface
+}

package/src/core/surface/start.ts

@@ -0,0 +1,142 @@
+import type { SurfaceContext, SurfaceKind, SurfaceHandle, SurfaceMap, SurfaceStartOptions } from './types.js'
+import { validateSurfaces, validateNoJobTypeDuplicates } from './validate.js'
+import type { ResolvedConfig } from '../config/load.js'
+import { ConfigError } from '../config/errors.js'
+import { getBaseLogger } from '../logging/index.js'
+
+export interface StartResult {
+  readonly handles: ReadonlyMap<string, SurfaceHandle>
+  /** Tells every surface to stop at once, concurrently, with one shared `force` signal. */
+  stop(force?: AbortSignal): Promise<void>
+  /** Names of surfaces whose stop has not returned. */
+  pending(): readonly string[]
+}
+
+export async function startSurfaces(
+  context: SurfaceContext,
+  config: ResolvedConfig,
+  surfaces: SurfaceMap,
+  options: SurfaceStartOptions = {},
+): Promise<StartResult> {
+  const logger = getBaseLogger()
+
+  validateSurfaces(config, surfaces)
+  validateNoJobTypeDuplicates(surfaces)
+
+  const selected = selectSurfaces(surfaces, options.kinds, logger)
+  checkStartPort(selected, options.port, logger)
+
+  const handles = new Map<string, SurfaceHandle>()
+  const startOrder: string[] = []
+
+  const entries = Object.entries(selected)
+  const scripts = entries.filter(([, s]) => s.kind === 'script')
+  const workers = entries.filter(([, s]) => s.kind === 'worker')
+  const httpSurfaces = entries.filter(([, s]) => s.kind === 'http')
+
+  const ordered = [...scripts, ...workers, ...httpSurfaces]
+
+  for (const [name, surface] of ordered) {
+    logger.info({ surface: name, kind: surface.kind }, `Starting surface "${name}"`)
+
+    try {
+      const handle = await surface.start(context, { ...(options.port === undefined ? {} : { port: options.port }), name })
+      handles.set(name, handle)
+      startOrder.push(name)
+
+      if (handle.address !== undefined) {
+        logger.info({ surface: name, address: handle.address }, `Surface "${name}" listening`)
+      }
+    } catch (err) {
+      logger.error({ surface: name, err }, `Failed to start surface "${name}"`)
+
+      const abandoned = AbortSignal.abort()
+      for (const started of startOrder.reverse()) {
+        try {
+          await handles.get(started)!.stop(abandoned)
+        } catch (stopErr) {
+          logger.error({ surface: started, err: stopErr }, `Failed to stop surface "${started}" during rollback`)
+        }
+      }
+
+      throw new Error(
+        `[pipework] Failed to start surface "${name}".\n\n` +
+        `  ${err instanceof Error ? err.message : String(err)}\n\n` +
+        `  Surfaces that were started have been stopped.\n`,
+      )
+    }
+  }
+
+  const stopping = new Set<string>()
+
+  return {
+    handles,
+    pending: () => [...stopping],
+    async stop(force = new AbortController().signal) {
+      const stopOrder = [...startOrder].reverse()
+      const errors: Array<{ name: string; error: unknown }> = []
+
+      await Promise.all(stopOrder.map(async (name) => {
+        const handle = handles.get(name)
+        if (handle === undefined) return
+
+        logger.info({ surface: name }, `Stopping surface "${name}"`)
+        stopping.add(name)
+        try {
+          await handle.stop(force)
+        } catch (err) {
+          logger.error({ surface: name, err }, `Error stopping surface "${name}"`)
+          errors.push({ name, error: err })
+        } finally {
+          stopping.delete(name)
+        }
+      }))
+
+      if (errors.length > 0) {
+        const details = errors.map(e => `  - ${e.name}: ${e.error instanceof Error ? e.error.message : String(e.error)}`).join('\n')
+        throw new Error(
+          `[pipework] Errors occurred while stopping surfaces:\n\n${details}\n`,
+        )
+      }
+    },
+  }
+}
+
+function selectSurfaces(surfaces: SurfaceMap, kinds: readonly SurfaceKind[] | undefined, logger: ReturnType<typeof getBaseLogger>): SurfaceMap {
+  if (kinds === undefined) return surfaces
+  const entries = Object.entries(surfaces)
+  const chosen = entries.filter(([, s]) => kinds.includes(s.kind))
+  if (chosen.length === 0) {
+    const declared = entries.map(([n, s]) => `${n} (${s.kind})`).join(', ')
+    throw new ConfigError(
+      `kinds [${kinds.join(', ')}] matched no surface; declared: ${declared === '' ? 'none' : declared}.`,
+      'Declare a surface of one of those kinds, or start without a kinds filter.',
+    )
+  }
+  const skipped = entries.filter(([, s]) => !kinds.includes(s.kind))
+  if (skipped.length > 0) {
+    logger.info(
+      { skipped: skipped.map(([n]) => n), kinds },
+      `Skipping surfaces not of kind [${kinds.join(', ')}]: ${skipped.map(([n, s]) => `"${n}" (${s.kind})`).join(', ')}`,
+    )
+  }
+  return Object.fromEntries(chosen)
+}
+
+function checkStartPort(surfaces: SurfaceMap, port: number | undefined, logger: ReturnType<typeof getBaseLogger>): void {
+  if (port === undefined) return
+  const http = Object.entries(surfaces).filter(([, s]) => s.kind === 'http')
+  const bare = http.filter(([, s]) => s.port === undefined).map(([n]) => n)
+  if (bare.length > 1) {
+    throw new ConfigError(
+      `Start port ${port} would be bound by ${bare.length} http surfaces that declare no port: ${bare.map(n => `"${n}"`).join(', ')}.`,
+      'Give each http surface its own `port`, or start without --port / PORT.',
+    )
+  }
+  for (const [name, s] of http) {
+    const own = s.port
+    if (own !== undefined && own !== port) {
+      logger.warn({ surface: name, port: own, startPort: port }, `Surface "${name}" declares port ${own}; the start port ${port} does not apply to it`)
+    }
+  }
+}

package/src/core/surface/types.ts

@@ -0,0 +1,225 @@
+import type { Handler } from '../../request/di/types.js'
+import type { Resource } from '../../request/fixture/types.js'
+import type { ServerConfig } from '../../request/http/types.js'
+import type { OpenAPIDocument } from '../../request/openapi/index.js'
+import type { QueueConfig, BackoffConfig } from '../../async/jobs/queue.js'
+import type { GraphSelection, StepGraph } from '../../async/steps/types.js'
+
+export type SurfaceKind = 'http' | 'worker' | 'script'
+
+export interface SurfaceManifest {
+  readonly databases: readonly string[]
+  readonly jobTypes: readonly string[]
+  readonly dependencies: Readonly<Record<string, string>>
+}
+
+export interface SurfaceHandle {
+  readonly kind: SurfaceKind
+  readonly address?: string
+  /**
+   * Stops accepting new work at once, then drains what is in flight. When `force` aborts, abandons the
+   * drain (aborting in-flight work) and returns promptly. Without `force` the drain is not bounded.
+   */
+  stop(force?: AbortSignal): Promise<void>
+  /** Worker surface only: enqueues the declared schedule for `job` now, without waiting for the clock and without moving its next run. Resolves with the job id. */
+  fireSchedule?(job: string): Promise<string>
+}
+
+export interface Surface {
+  readonly kind: SurfaceKind
+  readonly manifest: SurfaceManifest
+  /** Http surface only: the port it declares, if any. */
+  readonly port?: number | undefined
+  /** `options.port` is the start port; only the http surface reads it. */
+  start(context: SurfaceContext, options?: SurfaceStartOptions): Promise<SurfaceHandle>
+}
+
+export interface SurfaceStartOptions {
+  readonly port?: number
+  /**
+   * Start only the surfaces of these kinds; the rest are skipped. Unset starts every surface.
+   * Read by `startSurfaces`; a surface ignores it.
+   */
+  readonly kinds?: readonly SurfaceKind[]
+  /** The name this surface is registered under. */
+  readonly name?: string
+}
+
+export interface SurfaceBuilder extends Surface {
+  dependencies(d: Record<string, string>): SurfaceBuilder
+}
+
+export interface HttpSurfaceBuilder extends SurfaceBuilder {
+  /** The OpenAPI document the running surface serves, built from its declarations alone. Throws ConfigError without `openapi` info. */
+  openapi(): OpenAPIDocument
+  test(context: SurfaceContext): Promise<TestClient>
+}
+
+export interface TestClient {
+  inject(opts: import('../../request/http/types.js').InjectOptions): Promise<import('../../request/http/types.js').InjectResponse>
+  close(): Promise<void>
+}
+
+export interface SurfaceContext {
+  readonly config: {
+    readonly environment: string
+    database(name?: string): { readonly name: string; readonly url: string }
+    databases(): ReadonlyMap<string, { readonly name: string }>
+    databaseNames(): readonly string[]
+    defaultDatabaseName(): string
+    readonly observability: {
+      readonly slowQueryMs: number
+      readonly inFlightQueryMs?: number | undefined
+      readonly logAllQueries: boolean
+      readonly poolMetricsInterval: number
+      readonly onStatement: import('../config/statement-observer.js').StatementObserver | undefined
+    }
+    readonly raw: unknown
+  }
+  readonly env: Readonly<Record<string, unknown>>
+  readonly pool: {
+    getOrCreate(config: { readonly name: string; readonly url: string }): { readonly drizzle: import('../../data/db/index.js').DB; close(): Promise<void> }
+    get(name: string): { readonly drizzle: import('../../data/db/index.js').DB; close(): Promise<void> } | undefined
+    closeAll(): Promise<void>
+    count(): number
+  }
+  readonly isolation: {
+    markBegin(): void
+    markEnd(): void
+    assertClean(): void
+  }
+  readonly connections: {
+    track(id: string, name: string, context: string): void
+    release(id: string): void
+    activeCount(): number
+  }
+}
+
+export interface HttpSurfaceConfig {
+  readonly handlers?: readonly Handler<Record<string, unknown>, unknown>[]
+  readonly resources?: readonly Resource<unknown>[]
+  readonly port?: number
+  readonly host?: string
+  readonly auth?: ServerConfig['auth']
+  readonly tenant?: ServerConfig['tenant']
+  /** Default CORS grant for routes without `.cors()`. Unset or `false` grants nothing; `{}` allows all origins. */
+  readonly cors?: ServerConfig['cors']
+  readonly security?: ServerConfig['security']
+  readonly rateLimit?: ServerConfig['rateLimit']
+  readonly rateLimits?: ServerConfig['rateLimits']
+  readonly openapi?: ServerConfig['openapi']
+  readonly rbac?: ServerConfig['rbac']
+  readonly transactionPerRequest?: ServerConfig['transactionPerRequest']
+  readonly transactionTimeoutMs?: ServerConfig['transactionTimeoutMs']
+  readonly healthChecks?: ServerConfig['healthChecks']
+  readonly logging?: ServerConfig['logging']
+  readonly logger?: ServerConfig['logger']
+  readonly trustProxy?: ServerConfig['trustProxy']
+  readonly gracefulShutdownMs?: number
+  readonly bodyLimit?: ServerConfig['bodyLimit']
+  /** Called before each internal 5xx is sent, as `ServerConfig.onInternalError`; `alerts.requestFaults(handle)` is such a hook. */
+  readonly onInternalError?: ServerConfig['onInternalError']
+}
+
+export interface RetryConfig {
+  readonly attempts: number
+  readonly backoff?: BackoffConfig
+}
+
+/** The job an event is about. `attempt` is the 1-based attempt that was running when it ended. */
+export interface JobEventJob {
+  readonly id: string
+  readonly type: string
+  readonly attempt: number
+  readonly maxAttempts: number
+  readonly tenant: string | null
+}
+
+/**
+ * A job ended without its handler finishing it: its worker was lost and the
+ * reaper took it (`outcome`: tried again, or dead-lettered), the worker is
+ * stopping and handed it back to the queue, this worker lost its claim, or this
+ * worker's attempt failed and the job was dead-lettered (`error` as stored in the job's `error_payload`).
+ */
+export type JobEvent =
+  | { readonly kind: 'reaped'; readonly outcome: 'retry' | 'dead_letter' | 'superseded'; readonly job: JobEventJob }
+  | {
+    readonly kind: 'dead-lettered'
+    readonly cause: 'failed' | 'timeout' | 'permanent' | 'no-handler'
+    readonly error: unknown
+    readonly job: JobEventJob
+  }
+  | { readonly kind: 'handed-back'; readonly job: JobEventJob }
+  | { readonly kind: 'claim-lost'; readonly job: JobEventJob }
+
+export interface WorkerSurfaceConfig {
+  readonly jobs: readonly Handler<Record<string, unknown>, unknown>[]
+  /**
+   * Step graphs whose jobs this worker runs: a graph takes every worker class, `graph.workers('model')` only the named
+   * classes. Each taken class's step jobs (type `pipework.step.<name>[:<class>]`) are handled here, and a step job that dead-letters through this worker's queue fails its run. The worker's `queue` must use the
+   * table of the graph's queue.
+   */
+  readonly graphs?: readonly (StepGraph | GraphSelection)[]
+  readonly database?: string
+  readonly concurrency?: number
+  readonly pollIntervalMs?: number
+  readonly queue?: QueueConfig
+  readonly listen?: boolean
+  /** Reclaims jobs whose claim went stale. Default off, except on when the worker declares `schedules` (a stale claim would otherwise block its schedule); `false` turns it off. */
+  readonly reaper?: ReaperConfig | boolean
+  /** How long `stop()` waits for in-flight jobs; those still running then are aborted and handed back to the queue. Default 30000. */
+  readonly shutdownDeadlineMs?: number
+  /** How often a running job's claim is renewed, and noticed lost. Default 30000; keep it well under the queue's `staleTimeoutMs`. */
+  readonly heartbeatIntervalMs?: number
+  /**
+   * Called for each job the reaper took, each job handed back at stop, and each
+   * job whose claim this worker lost, and each job this worker's failed attempt dead-lettered (`error` as stored
+   * in the job's `error_payload`, called after the dead-lettering transaction commits). Runs in the job's tenant Flow (`pipe()` works as
+   * that tenant, in its own transaction), traced as a child of the job's trace. A throw is
+   * logged and never reaches the reaper, the stop or the claim loop.
+   */
+  readonly onJobEvent?: (event: JobEvent) => void | Promise<void>
+  /** Consecutive failing claims that end the worker surface (fatal log, non-zero exit code). Default 10. */
+  readonly maxConsecutiveClaimFailures?: number
+  readonly timeouts?: Readonly<Record<number, number>>
+  /**
+   * Cron schedules this worker runs. Each `job` must be a job type in `jobs`.
+   * At start the worker upserts these (an unchanged schedule keeps its next
+   * run), removes schedules for its job types that are no longer declared (`[]`
+   * removes them all; omitting the key leaves the table alone), and fires each
+   * due schedule once across every worker process on the database. Each run is
+   * a root trace with `entryKind: 'cron'` and no tenant. Needs the
+   * `pipework_schedules` table: run `pipework generate`.
+   */
+  readonly schedules?: readonly WorkerSchedule[]
+  /** How often the worker looks for due schedules. Default 15000. */
+  readonly schedulerIntervalMs?: number
+}
+
+export interface WorkerSchedule {
+  /** The job type to enqueue; also the schedule's name. */
+  readonly job: string
+  /** Five-field cron expression. */
+  readonly cron: string
+  /** IANA time zone. Default `UTC`. */
+  readonly timezone?: string
+  /** Payload of each scheduled job. Default `{}`. */
+  readonly payload?: unknown
+}
+
+export interface ReaperConfig {
+  readonly intervalMs?: number
+}
+
+export interface ScriptSurfaceConfig {
+  readonly databases?: readonly string[]
+  readonly run: (context: ScriptContext) => Promise<void>
+}
+
+export interface ScriptContext {
+  readonly config: SurfaceContext['config']
+  readonly env: SurfaceContext['env']
+  readonly pool: SurfaceContext['pool']
+}
+
+export type SurfaceMap = Record<string, Surface>