pipework 0.252.0 → 0.253.0

package/src/infra/support/handle.ts

@@ -0,0 +1,869 @@
+import { sql } from '../../data/db/sql.js'
+import { pipe, pipeSystem } from '../../data/db/db.js'
+import type { DB } from '../../data/db/index.js'
+import { fitting } from '../../request/di/index.js'
+import { requireContext, getContext } from '../../request/context/store.js'
+import type { Flow } from '../../request/context/types.js'
+import { inTenant } from '../../auth/tenant/in-tenant.js'
+import { resolveActorId } from '../../data/write/audit/actor.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../alerts/faults.js'
+import { ConflictError, ForbiddenError, NotFoundError, ValidationError } from '../../core/errors/index.js'
+import { defineStateMachine } from '../../async/state-machine/define.js'
+import type { Queue } from '../../async/jobs/queue.js'
+import type { Handler } from '../../request/di/types.js'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import { recordBeat, beatsEnabled } from '../alerts/beat.js'
+import type { Mail } from '../email/mail.js'
+import type { ReceivedEmail } from '../email/inbound.js'
+import { createOutbox, type Sink, type SinkDelivery } from '../outbox/core.js'
+import { TICKET_STATES } from './schema.js'
+import { describeError } from '../../core/logging/error-chain.js'
+
+export type TicketState = typeof TICKET_STATES[number]
+export type SupportEventKind = 'ticket.created' | 'ticket.customer-replied' | 'draft.awaiting-approval'
+
+/** What a sink receives as `delivery.payload` for a support event. No message bodies. */
+export interface SupportEventPayload {
+  readonly kind: SupportEventKind
+  readonly ticketId: string
+  readonly tenantId: string
+  readonly subject: string
+  readonly state: TicketState
+  readonly category: string | null
+  readonly at: string
+}
+
+/** A place ticket events are sent: `send(delivery)` gets `delivery.payload` as a `SupportEventPayload`. `alerts.webhook()` and `alerts.memory()` fit where a `SupportSink` is expected. */
+export type SupportSink = Sink<SupportEventPayload>
+export type SupportDelivery = SinkDelivery<SupportEventPayload>
+
+/** What `screen` decides for a received email: `accept` it, `separate` it (open a new ticket, never add to an existing one), or `drop` it. */
+export type ScreenVerdict = 'accept' | 'separate' | 'drop'
+
+export interface SupportConfig {
+  /** The app's mail interface; the only caller of its `send` is `approve`. Its templates must include `support.templates`. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the app's own template map
+  readonly mail: Pick<Mail<any>, 'send'>
+  /**
+   * Where ticket events go: `alerts.webhook(...)`, `alerts.memory()` or your own `SupportSink`. A delivery's
+   * `kind` is the event kind, its `key` the ticket id and its `payload` a `SupportEventPayload`.
+   */
+  readonly sinks: readonly SupportSink[]
+  /** The queue the events job runs on; its worker surface must run `support.job`. */
+  readonly queue: Pick<Queue, 'enqueue'>
+  /**
+   * Whether `actorId` may approve replies for `tenantId`. Called by `approve` before anything is read or sent.
+   * With rbac: `({ actorId, tenantId }) => rbac.can(actorId, 'support:approve', { tenantId })`.
+   */
+  readonly canApprove: (who: { actorId: string; tenantId: string }) => Promise<boolean>
+  /** The author of a draft may not approve it. Default true. */
+  readonly distinctApprover?: boolean
+  /** Template name `approve` sends with; default `'pipework.support.reply'`. The app's mail templates must define it (spread `support.templates`). */
+  readonly replyTemplate?: string
+  /**
+   * Decides what `receiveEmail` does with a message. Default: virus verdict `FAIL` drops it; DMARC `FAIL`, or SPF and
+   * DKIM both `FAIL`, separates it (the From address is probably forged, so it must not add text to a ticket an agent
+   * is reading: it always opens a new ticket); anything else, including no verdicts (the folder stand-in), is accepted. A message it
+   * separates never names a user: `resolveContact` is not called for it.
+   */
+  readonly screen?: (email: ReceivedEmail) => ScreenVerdict
+  /**
+   * Finds the user a sender is: `address` is lowercased. Called inside the receive's tenant transaction (`tx` is bound
+   * to that tenant; a throw rolls the receive back) when a message has no user of its own: for a new ticket, and for a
+   * message joining a ticket whose `user_id` is null, which it fills. A ticket's non-null `user_id` is never changed.
+   * `receive` with `contact.userId` does not call it. Null: no known user.
+   *
+   * `email` is the received message when it came through `receiveEmail` (its `verdicts` say whether the From can be
+   * believed) and `null` for `receive` (chat/api). A message `screen` separates (default: DMARC `FAIL`, or SPF and DKIM
+   * both `FAIL`) never reaches this hook: its ticket's `user_id` stays null. To also require a pass:
+   * `resolveContact: async ({ address, email }, tx) => email !== null && email.verdicts?.dmarc !== 'PASS' ? null : lookUp(address, tx)`.
+   */
+  readonly resolveContact?: (
+    contact: { address: string; name: string | null; tenantId: string; email: ReceivedEmail | null },
+    tx: DB,
+  ) => Promise<{ userId: string } | null>
+  /**
+   * Who may join a ticket by thread. `'contact'` (default): only the ticket's contact; a message from anyone else in the
+   * thread opens its own ticket, and `receive` with a `ticketId` refuses a sender who is not the contact. `'conversation'`:
+   * a message threaded into the ticket's conversation, or sent to it with `ticketId`, joins it and reopens it whoever sent
+   * it; the message keeps its own sender, and the ticket's contact and user do not change. Risk: with `'conversation'`,
+   * anyone who holds a reply's Message-ID can add to the ticket, so pair it with a strict `screen` (for example, require
+   * a DMARC pass). A message `screen` separates still never joins.
+   */
+  readonly joinThread?: 'contact' | 'conversation'
+  /** Job type of `support.job`; default `'pipework.support.events'`. */
+  readonly jobType?: string
+  /** Delivery attempts before an event is given up on; default 10. */
+  readonly maxAttempts?: number
+  /** First retry delay, doubling per attempt up to one hour; default 5000. */
+  readonly backoffMs?: number
+}
+
+export interface Ticket {
+  readonly id: string
+  readonly tenantId: string
+  readonly state: TicketState
+  readonly category: string | null
+  readonly subject: string
+  readonly contactEmail: string
+  readonly contactName: string | null
+  readonly userId: string | null
+  /** The email conversation this ticket answers into, or `null` (chat, API, or a second sender in a conversation another ticket holds). */
+  readonly conversationId: string | null
+  readonly createdAt: Date
+  readonly updatedAt: Date
+  readonly lastCustomerMessageAt: Date
+}
+
+export interface TicketMessage {
+  readonly id: string
+  readonly ticketId: string
+  readonly kind: 'inbound' | 'note' | 'draft' | 'outbound'
+  readonly channel: 'email' | 'chat' | 'api'
+  readonly subject: string | null
+  readonly text: string
+  readonly html: string | null
+  readonly fromAddress: string | null
+  readonly inboundEmailId: string | null
+  /** Stored file ids and names of an inbound email's attachments. */
+  readonly attachments: readonly { id: string; filename: string | null; mediaType: string; size: number }[] | null
+  readonly draftStatus: 'draft' | 'approved' | 'discarded' | null
+  /** Starts at 1; `editDraft` adds one. `approve` must be given the version the approver read. */
+  readonly version: number
+  readonly approvedBy: string | null
+  readonly approvedAt: Date | null
+  /** The `pipework_email_messages` row an approved draft (and its outbound message) was sent as. */
+  readonly emailMessageId: string | null
+  readonly createdBy: string | null
+  readonly createdAt: Date
+}
+
+export interface TicketLink {
+  readonly id: string
+  readonly ticketId: string
+  readonly kind: string
+  readonly ref: string
+  readonly label: string | null
+  readonly createdAt: Date
+}
+
+export interface TicketDetail {
+  readonly ticket: Ticket
+  /** Oldest first. */
+  readonly messages: readonly TicketMessage[]
+  readonly links: readonly TicketLink[]
+}
+
+export interface ListOptions {
+  readonly state?: TicketState
+  readonly category?: string
+  readonly limit?: number
+  /** The `next` of a previous page. */
+  readonly cursor?: string
+}
+
+export interface ListPage {
+  /** Newest first. */
+  readonly tickets: readonly Ticket[]
+  readonly next: string | null
+}
+
+export interface DraftInput {
+  readonly text: string
+  readonly html?: string
+  /** Default `Re: <ticket subject>`. */
+  readonly subject?: string
+}
+
+export type ReceiveResult =
+  | { readonly status: 'received' | 'duplicate'; readonly ticketId: string; readonly created: boolean }
+  | { readonly status: 'dropped' | 'no-tenant' }
+
+export interface ReceiveInput {
+  readonly channel: 'chat' | 'api'
+  readonly contact: { readonly email: string; readonly name?: string; readonly userId?: string }
+  readonly text: string
+  readonly html?: string
+  /** Subject of a new ticket; default the first line of `text`. */
+  readonly subject?: string
+  /** Adds to this ticket (the contact must be the ticket's) instead of opening one. */
+  readonly ticketId?: string
+}
+
+/** A draft could not be approved, edited or discarded: it is already approved, discarded, or changed since `expectedVersion`. */
+export class DraftStateError extends ConflictError {
+  constructor(readonly reason: 'approved' | 'discarded' | 'changed' | 'not-awaiting-approval', message: string) {
+    super(message, { reason })
+  }
+}
+
+/** The calls on one tenant's tickets. Each also exists as `<name>For(tenantId, ...)` for callers with no tenant in the Flow. */
+export interface TicketApi {
+  get(ticketId: string): Promise<TicketDetail>
+  list(options?: ListOptions): Promise<ListPage>
+  /** `null` clears it. */
+  setCategory(ticketId: string, category: string | null): Promise<Ticket>
+  /** Moves the ticket along the state machine; an illegal move throws `InvalidTransitionError`. `awaiting_approval` and `answered` are reached only by drafting and approving. */
+  transition(ticketId: string, to: TicketState): Promise<Ticket>
+  /** An internal note: stored, audited, never sent. */
+  addNote(ticketId: string, text: string): Promise<TicketMessage>
+  link(ticketId: string, link: { kind: string; ref: string; label?: string }): Promise<TicketLink>
+  /**
+   * Stores a draft reply and moves the ticket to `awaiting_approval` (from `open` through `triaged`).
+   * A ticket has one live draft: a new draft discards the previous. Nothing is sent.
+   */
+  draftReply(ticketId: string, draft: DraftInput): Promise<{ draftId: string; version: number }>
+  /** Changes the live draft's content and adds one to its version; the editor becomes its author for `distinctApprover`. */
+  editDraft(draftId: string, draft: Partial<DraftInput>): Promise<{ draftId: string; version: number }>
+  /** Discards the live draft; the ticket goes back to `triaged`. */
+  discardDraft(draftId: string): Promise<void>
+  /**
+   * Approves and sends a draft. The actor is the Flow's `auth.userId`. Refused (`ForbiddenError`) when `canApprove`
+   * says no or, with `distinctApprover`, when the actor wrote the draft. Refused with `DraftStateError` when the draft
+   * is approved, discarded or at another version than `expectedVersion`. In one transaction the draft is marked
+   * approved (approver and time recorded), exactly its text and html are handed to `mail.send` as a reply in the
+   * ticket's conversation, an outbound message is stored and the ticket becomes `answered`.
+   */
+  approve(draftId: string, options: { expectedVersion: number }): Promise<{ messageId: string; emailMessageId: string }>
+}
+
+type WithFor<T> = T & {
+  [K in keyof T & string as `${K}For`]: T[K] extends (...args: infer A) => infer R ? (tenantId: string, ...args: A) => R : never
+}
+
+export interface Support extends WithFor<TicketApi> {
+  /**
+   * Hands a received email to the ticket system; call it from `mail.inbound`'s `onMessage`. It uses `email.tenantId`
+   * (none: logged, `{ status: 'no-tenant' }`) and is idempotent on `email.id`. A message `screen` drops (default: virus
+   * verdict `FAIL`) opens nothing and is audited; one it separates (default: DMARC `FAIL`, or SPF and DKIM both `FAIL`)
+   * always opens a new ticket and never adds to an existing one, because a forged From address must not add text to a
+   * ticket the agent is reading. A new conversation opens a ticket; a message in a conversation that
+   * has a ticket joins it only when its sender is the ticket's contact (threading is not authentication), and
+   * otherwise opens a new ticket, tied to the conversation if no ticket holds it yet. A customer message moves the
+   * ticket to `open` and discards a live draft.
+   */
+  receiveEmail(email: ReceivedEmail): Promise<ReceiveResult>
+  /** A customer message from another channel; same rules as `receiveEmail`. */
+  receive(tenantId: string, input: ReceiveInput): Promise<ReceiveResult>
+  /**
+   * Tickets of every tenant (or of `tenantId`), newest first, in the shape and cursor of `list`. Needs a Flow but no tenant.
+   * It reads on the system channel, which a database with `rls.platformRole` refuses over these tenant-scoped tables.
+   */
+  listAll(options?: ListOptions & { tenantId?: string }): Promise<ListPage>
+  /** The job to add to a worker surface's `jobs`: delivers ticket events to the sinks. */
+  readonly job: Handler<Record<string, unknown>, unknown>
+  /** What one run of `job` does; callable from a test. Needs a Flow. */
+  tick(): Promise<{ delivered: number; retried: number; failed: number }>
+  /**
+   * Puts the event deliveries that were given up (and never delivered) back on the queue, for every tenant, optionally
+   * only those of `sink` and/or that failed at or after `failedSince`; the next `tick` sends them. Delivery ids stay the
+   * same, so a receiver that dedupes on `delivery.id` takes each once. Writes a `requeue` audit row per delivery naming `by`
+   * (who asked: an operator or key name, required). Needs a Flow but no tenant.
+   */
+  requeueFailed(options: { by: string; sink?: string; failedSince?: Date }): Promise<{ requeued: number }>
+  /** Event deliveries, oldest first, for a ticket or all. */
+  deliveries(options?: { ticketId?: string }): Promise<readonly { id: string; ticketId: string; kind: SupportEventKind; sink: string; attempts: number; deliveredAt: Date | null; failedAt: Date | null; lastError: string | null }[]>
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const DEFAULT_LIST_LIMIT = 50
+const MAX_LIST_LIMIT = 200
+const ENTITY = 'SupportTicket'
+
+function toDate(value: unknown): Date {
+  if (value instanceof Date) return value
+  const text = String(value)
+  return new Date(/(Z|[+-]\d\d(:?\d\d)?)$/.test(text) ? text : `${text.replace(' ', 'T')}Z`)
+}
+
+function toTicket(r: Record<string, unknown>): Ticket {
+  return {
+    id: r['id'] as string, tenantId: r['tenant_id'] as string, state: r['state'] as TicketState,
+    category: (r['category'] ?? null) as string | null, subject: r['subject'] as string,
+    contactEmail: r['contact_email'] as string, contactName: (r['contact_name'] ?? null) as string | null,
+    userId: (r['user_id'] ?? null) as string | null, conversationId: (r['conversation_id'] ?? null) as string | null,
+    createdAt: toDate(r['created_at']), updatedAt: toDate(r['updated_at']), lastCustomerMessageAt: toDate(r['last_customer_message_at']),
+  }
+}
+
+function toMessage(r: Record<string, unknown>): TicketMessage {
+  return {
+    id: r['id'] as string, ticketId: r['ticket_id'] as string, kind: r['kind'] as TicketMessage['kind'],
+    channel: r['channel'] as TicketMessage['channel'], subject: (r['subject'] ?? null) as string | null,
+    text: r['text'] as string, html: (r['html'] ?? null) as string | null, fromAddress: (r['from_address'] ?? null) as string | null,
+    inboundEmailId: (r['inbound_email_id'] ?? null) as string | null,
+    attachments: (r['attachments'] ?? null) as TicketMessage['attachments'],
+    draftStatus: (r['draft_status'] ?? null) as TicketMessage['draftStatus'], version: Number(r['version']),
+    approvedBy: (r['approved_by'] ?? null) as string | null,
+    approvedAt: r['approved_at'] === null || r['approved_at'] === undefined ? null : toDate(r['approved_at']),
+    emailMessageId: (r['email_message_id'] ?? null) as string | null, createdBy: (r['created_by'] ?? null) as string | null,
+    createdAt: toDate(r['created_at']),
+  }
+}
+
+function toLink(r: Record<string, unknown>): TicketLink {
+  return {
+    id: r['id'] as string, ticketId: r['ticket_id'] as string, kind: r['kind'] as string, ref: r['ref'] as string,
+    label: (r['label'] ?? null) as string | null, createdAt: toDate(r['created_at']),
+  }
+}
+
+function nonEmpty(field: string, value: unknown): string {
+  if (typeof value !== 'string' || value.trim() === '') throw new ValidationError({ [field]: ['must be a non-empty string'] }, `Support ${field} must be a non-empty string.`)
+  return value
+}
+
+function requireUuid(field: string, value: unknown): string {
+  if (typeof value !== 'string' || !UUID_RE.test(value)) throw new ValidationError({ [field]: ['must be a UUID'] }, `Support ${field} must be a UUID.`)
+  return value
+}
+
+/** Mail templates for `mail.create({ templates: { ...support.templates, ... } })`: the reply is rendered verbatim from the approved draft, nothing added. */
+export const supportTemplates = {
+  'pipework.support.reply': ({ subject, text, html }: { subject: string; text: string; html?: string | null }): { subject: string; text: string; html?: string } =>
+    ({ subject, text, ...(html !== undefined && html !== null ? { html } : {}) }),
+} as const
+
+/**
+ * Creates the support handle: tickets for a tenant's customers, opened from received email, with replies
+ * sent only after an approval.
+ *
+ * Needs blueprint `support: {}` (tables `support_ticket`, `support_message`, `support_link` with forced
+ * row-level security, and the event outbox `support_event_delivery`) and, for email, `email: {}`.
+ * The app's mail templates must include `support.templates`, which render an approved draft verbatim.
+ *
+ * The only code path that sends a reply is `approve`: it needs an actor that `canApprove` accepts (and, by
+ * default, who is not the draft's author), and hands `mail.send` exactly the approved text and html in the
+ * ticket's conversation. Events (`ticket.created`, `ticket.customer-replied`, `draft.awaiting-approval`)
+ * go to the sinks through an outbox with retries, delivered by `job` or `tick()`. Every change is a
+ * `SupportTicket:<verb>` audit record under the Flow's open trace step.
+ */
+export function createSupport(config: SupportConfig): Support {
+  if (config.sinks.length === 0) throw new Error('[pipework] support.create needs at least one sink.')
+  const sinks = new Map<string, SupportSink>()
+  for (const s of config.sinks) {
+    if (sinks.has(s.name)) throw new Error(`[pipework] support.create: two sinks are named "${s.name}"; give each its own name.`)
+    sinks.set(s.name, s)
+  }
+  const sinkNames = JSON.stringify([...sinks.keys()])
+  const joinThread = config.joinThread ?? 'contact'
+  if ((joinThread as string) !== 'contact' && (joinThread as string) !== 'conversation') {
+    throw new Error(`[pipework] support.create: joinThread must be 'contact' or 'conversation', got ${JSON.stringify(joinThread)}.`)
+  }
+  const jobType = config.jobType ?? 'pipework.support.events'
+  const replyTemplate = config.replyTemplate ?? 'pipework.support.reply'
+  const distinctApprover = config.distinctApprover ?? true
+  const screen = config.screen ?? ((email: ReceivedEmail): ScreenVerdict => {
+    const v = email.verdicts
+    if (v === null) return 'accept'
+    if (v.virus === 'FAIL') return 'drop'
+    return v.dmarc === 'FAIL' || (v.spf === 'FAIL' && v.dkim === 'FAIL') ? 'separate' : 'accept'
+  })
+  const log = getBaseLogger()
+
+  // Edges into `awaiting_approval`, out of it, and to `answered` are taken only by draft, discard, approve and a
+  // customer message (metadata.internal); `transition` cannot take them.
+  const internal = (ctx: { metadata?: Record<string, unknown> }): boolean => ctx.metadata?.['internal'] === true
+  const machine = defineStateMachine({
+    states: TICKET_STATES,
+    initial: 'open',
+    transitions: [
+      { from: 'open', to: 'triaged' },
+      { from: 'triaged', to: 'awaiting_approval', guard: internal },
+      { from: 'awaiting_approval', to: ['triaged', 'answered'], guard: internal },
+      { from: 'open', to: 'closed' },
+      { from: 'triaged', to: 'closed' },
+      { from: 'answered', to: 'closed' },
+      { from: 'triaged', to: 'open', guard: internal },
+      { from: 'awaiting_approval', to: 'open', guard: internal },
+      { from: 'answered', to: 'open', guard: internal },
+      { from: 'closed', to: 'open', guard: internal },
+    ],
+  })
+
+  function tenantOf(explicit: string | null, flow: Flow): string {
+    if (explicit !== null) return requireUuid('tenantId', explicit)
+    if (flow.tenant === null) {
+      throw new Error(
+        '[pipework] This support method needs a tenant in the Flow.\n\n' +
+        '  Call it from an authenticated tenant route, or use the ...For(tenantId, ...) form\n' +
+        '  (getFor, draftReplyFor, approveFor, ...) from a webhook or a job with no tenant.\n',
+      )
+    }
+    return flow.tenant
+  }
+
+  async function run<T>(explicit: string | null, fn: (tx: DB, tenantId: string, flow: Flow) => Promise<T>): Promise<T> {
+    const flow = requireContext()
+    const tenantId = tenantOf(explicit, flow)
+    if (explicit !== null) return inTenant(flow, tenantId, tx => fn(tx, tenantId, flow))
+    return pipe.transaction((tx: DB) => fn(tx, tenantId, flow))
+  }
+
+  // An audit record under the Flow's open trace step (none: nothing). In a transaction it is a savepoint, so a
+  // failed write cannot abort the change it describes.
+  async function audit(flow: Flow, tx: DB | null, tenantId: string, verb: string, entityId: string, details: Record<string, unknown>): Promise<void> {
+    const trace = flow.trace
+    const stepId = trace?.buffer.openStepId ?? null
+    if (trace === null || stepId === null) return
+    const write = async (db: DB): Promise<void> => {
+      await db.execute(sql`
+        INSERT INTO audit_record
+          (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
+        VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${tenantId}, ${resolveActorId(flow)},
+          ${ENTITY}, ${verb}, ${entityId}, ${JSON.stringify(details)}::jsonb, now())`)
+    }
+    try {
+      if (tx === null) await write(pipeSystem())
+      else await tx.transaction(write)
+    } catch (err) {
+      log.error({ err, traceId: trace.id }, `Failed to write the support ${verb} audit record`)
+      void recordFault('audit-write', faultMessage(err), { entity: ENTITY, verb })
+    }
+  }
+
+  async function emit(tx: DB, kind: SupportEventKind, ticket: Ticket): Promise<void> {
+    const payload: SupportEventPayload = {
+      kind, ticketId: ticket.id, tenantId: ticket.tenantId, subject: ticket.subject, state: ticket.state,
+      category: ticket.category, at: new Date().toISOString(),
+    }
+    await tx.execute(sql`
+      INSERT INTO support_event_delivery (ticket_id, kind, sink, payload, created_at, next_attempt_at)
+      SELECT ${ticket.id}::uuid, ${kind}, s.sink, ${JSON.stringify(payload)}::jsonb, clock_timestamp(), clock_timestamp()
+      FROM jsonb_array_elements_text(${sinkNames}::jsonb) AS s(sink)`)
+    await config.queue.enqueue(tx, { type: jobType, payload: {}, continueFlow: true })
+  }
+
+  async function loadTicket(tx: DB, tenantId: string, ticketId: string, lock: boolean): Promise<Ticket> {
+    requireUuid('ticketId', ticketId)
+    const rows = lock
+      ? await tx.execute(sql`SELECT * FROM support_ticket WHERE id = ${ticketId}::uuid AND tenant_id = ${tenantId}::uuid FOR UPDATE`)
+      : await tx.execute(sql`SELECT * FROM support_ticket WHERE id = ${ticketId}::uuid AND tenant_id = ${tenantId}::uuid`)
+    if (rows[0] === undefined) throw new NotFoundError('Support ticket', { ticketId })
+    return toTicket(rows[0])
+  }
+
+  async function loadDraftRow(tx: DB, tenantId: string, draftId: string): Promise<Record<string, unknown>> {
+    requireUuid('draftId', draftId)
+    const rows = await tx.execute(sql`SELECT * FROM support_message WHERE id = ${draftId}::uuid AND tenant_id = ${tenantId}::uuid AND kind = 'draft'`)
+    if (rows[0] === undefined) throw new NotFoundError('Support draft', { draftId })
+    return rows[0]
+  }
+
+  async function moveTo(flow: Flow, tx: DB, ticket: Ticket, to: TicketState, internalMove: boolean): Promise<Ticket> {
+    await machine.transition({ entityId: ticket.id, entityType: 'SupportTicket', from: ticket.state, to, metadata: { internal: internalMove } })
+    const rows = await tx.execute(sql`UPDATE support_ticket SET state = ${to}, updated_at = clock_timestamp() WHERE id = ${ticket.id}::uuid RETURNING *`)
+    await audit(flow, tx, ticket.tenantId, 'transition', ticket.id, { from: ticket.state, to })
+    return toTicket(rows[0]!)
+  }
+
+  async function discardLive(flow: Flow, tx: DB, ticket: Ticket, reason: string): Promise<boolean> {
+    const rows = await tx.execute(sql`
+      UPDATE support_message SET draft_status = 'discarded'
+      WHERE ticket_id = ${ticket.id}::uuid AND kind = 'draft' AND draft_status = 'draft' RETURNING id`)
+    for (const r of rows) await audit(flow, tx, ticket.tenantId, 'discard', ticket.id, { draftId: r['id'], reason })
+    return rows.length > 0
+  }
+
+  async function lockConversation(tx: DB, tenantId: string, key: string): Promise<void> {
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${`pipework.support:${tenantId}:${key}`}, 0))`)
+  }
+
+  interface Incoming {
+    readonly channel: 'email' | 'chat' | 'api'
+    readonly contactEmail: string
+    readonly contactName: string | null
+    readonly userId: string | null
+    readonly subject: string
+    readonly text: string
+    readonly html: string | null
+    readonly fromAddress: string | null
+    readonly inboundEmailId: string | null
+    readonly conversationId: string | null
+    readonly attachments: unknown
+    readonly ticketId: string | null
+    /** Never add to an existing ticket, never name a user. */
+    readonly separate?: boolean
+    /** The received message; null for chat/api. */
+    readonly email?: ReceivedEmail | null
+  }
+
+  async function ingest(flow: Flow, tx: DB, tenantId: string, m: Incoming): Promise<ReceiveResult> {
+    await lockConversation(tx, tenantId, m.conversationId ?? m.inboundEmailId ?? m.ticketId ?? m.contactEmail)
+    if (m.inboundEmailId !== null) {
+      const seen = await tx.execute(sql`SELECT ticket_id FROM support_message WHERE tenant_id = ${tenantId}::uuid AND inbound_email_id = ${m.inboundEmailId}::uuid`)
+      if (seen[0] !== undefined) return { status: 'duplicate', ticketId: seen[0]['ticket_id'] as string, created: false }
+    }
+
+    let ticket: Ticket | null = null
+    if (m.ticketId !== null) {
+      ticket = await loadTicket(tx, tenantId, m.ticketId, true)
+      if (joinThread === 'contact' && ticket.contactEmail !== m.contactEmail) {
+        throw new ForbiddenError('The sender is not the ticket\'s contact.', { ticketId: m.ticketId })
+      }
+    } else if (m.conversationId !== null && m.separate !== true) {
+      const contactOnly = joinThread === 'contact' ? sql`AND t.contact_email = ${m.contactEmail}` : sql``
+      const found = await tx.execute(sql`
+        SELECT t.id FROM support_ticket t
+        WHERE t.tenant_id = ${tenantId}::uuid ${contactOnly}
+          AND (t.conversation_id = ${m.conversationId}::uuid OR EXISTS (
+            SELECT 1 FROM support_message sm JOIN pipework_email_inbound i ON i.id = sm.inbound_email_id
+            WHERE sm.ticket_id = t.id AND i.conversation_id = ${m.conversationId}::uuid))
+        ORDER BY (t.conversation_id = ${m.conversationId}::uuid) DESC NULLS LAST, t.created_at DESC, t.id LIMIT 1`)
+      if (found[0] !== undefined) ticket = await loadTicket(tx, tenantId, found[0]['id'] as string, true)
+    }
+
+    const resolve = async (): Promise<string | null> => {
+      if (m.userId !== null) return m.userId
+      if (m.separate === true) return null
+      const found = await config.resolveContact?.({ address: m.contactEmail, name: m.contactName, tenantId, email: m.email ?? null }, tx)
+      return found?.userId ?? null
+    }
+
+    const joinedBy = ticket !== null && ticket.contactEmail !== m.contactEmail ? 'conversation' : null
+    let created = false
+    let userIdSet: string | null = null
+    if (ticket === null) {
+      const userId = await resolve()
+      let conversationId = m.conversationId
+      if (m.separate === true) conversationId = null
+      if (conversationId !== null) {
+        const held = await tx.execute(sql`SELECT 1 FROM support_ticket WHERE tenant_id = ${tenantId}::uuid AND conversation_id = ${conversationId}::uuid`)
+        if (held.length > 0) conversationId = null
+      }
+      const rows = await tx.execute(sql`
+        INSERT INTO support_ticket (tenant_id, state, subject, contact_email, contact_name, user_id, conversation_id)
+        VALUES (${tenantId}::uuid, 'open', ${m.subject}, ${m.contactEmail}, ${m.contactName}, ${userId}, ${conversationId}::uuid)
+        RETURNING *`)
+      ticket = toTicket(rows[0]!)
+      created = true
+      await audit(flow, tx, tenantId, 'create', ticket.id, { subject: ticket.subject, contact: ticket.contactEmail, channel: m.channel, userId: ticket.userId })
+    } else {
+      await discardLive(flow, tx, ticket, 'customer-replied')
+      if (ticket.state !== 'open') ticket = await moveTo(flow, tx, ticket, 'open', true)
+      const viaConversation = ticket.contactEmail !== m.contactEmail
+      const userId = ticket.userId === null && !viaConversation ? await resolve() : null
+      userIdSet = userId
+      const rows = await tx.execute(sql`UPDATE support_ticket SET last_customer_message_at = clock_timestamp(), updated_at = clock_timestamp(), user_id = COALESCE(user_id, ${userId}) WHERE id = ${ticket.id}::uuid RETURNING *`)
+      ticket = toTicket(rows[0]!)
+    }
+
+    await tx.execute(sql`
+      INSERT INTO support_message (tenant_id, ticket_id, kind, channel, text, html, from_address, inbound_email_id, attachments)
+      VALUES (${tenantId}::uuid, ${ticket.id}::uuid, 'inbound', ${m.channel}, ${m.text}, ${m.html}, ${m.fromAddress},
+        ${m.inboundEmailId}::uuid, ${m.attachments === null ? null : JSON.stringify(m.attachments)}::jsonb)`)
+    await audit(flow, tx, tenantId, 'receive', ticket.id, { channel: m.channel, emailId: m.inboundEmailId, created, separated: m.separate === true, ...(joinedBy === null ? {} : { joinedBy }), ...(userIdSet === null ? {} : { userIdSet }) })
+    await emit(tx, created ? 'ticket.created' : 'ticket.customer-replied', ticket)
+    return { status: 'received', ticketId: ticket.id, created }
+  }
+
+  async function receiveEmail(email: ReceivedEmail): Promise<ReceiveResult> {
+    const flow = requireContext()
+    if (email.tenantId === null) {
+      log.warn({ emailId: email.id }, 'support: received email has no tenant; dropped')
+      void recordFault('support-inbound-untenanted', `received email ${email.id} has no tenant; dropped`, { emailId: email.id })
+      return { status: 'no-tenant' }
+    }
+    const tenantId = email.tenantId
+    const contactEmail = email.from.address.trim().toLowerCase()
+    const verdict = contactEmail === '' ? 'drop' : screen(email)
+    if (verdict === 'drop') {
+      await audit(flow, null, tenantId, 'drop', email.id, {
+        reason: contactEmail === '' ? 'no-sender' : 'screened', virus: email.verdicts?.virus ?? null,
+      })
+      return { status: 'dropped' }
+    }
+    const attachments = email.attachments.flatMap(a => a.file === null
+      ? []
+      : [{ id: a.file.id, filename: a.filename, mediaType: a.mediaType, size: a.size }])
+    return inTenant(flow, tenantId, tx => ingest(flow, tx, tenantId, {
+      channel: 'email', contactEmail, contactName: email.from.name === '' ? null : email.from.name, userId: null,
+      subject: email.subject.trim() === '' ? '(no subject)' : email.subject, text: email.text ?? '', html: email.html,
+      fromAddress: contactEmail, inboundEmailId: email.id, conversationId: email.conversationId,
+      attachments: attachments.length === 0 ? null : attachments, ticketId: null, separate: verdict === 'separate', email,
+    }))
+  }
+
+  async function receive(tenantId: string, input: ReceiveInput): Promise<ReceiveResult> {
+    const flow = requireContext()
+    requireUuid('tenantId', tenantId)
+    nonEmpty('text', input.text)
+    const contactEmail = nonEmpty('contact.email', input.contact.email).trim().toLowerCase()
+    if ((input.channel as string) !== 'chat' && (input.channel as string) !== 'api') throw new ValidationError({ channel: ['must be chat or api'] }, 'support.receive: channel must be "chat" or "api".')
+    const firstLine = input.text.trim().split('\n')[0]!.slice(0, 200)
+    return inTenant(flow, tenantId, tx => ingest(flow, tx, tenantId, {
+      channel: input.channel, contactEmail, contactName: input.contact.name ?? null, userId: input.contact.userId ?? null,
+      subject: input.subject ?? firstLine, text: input.text, html: input.html ?? null, fromAddress: contactEmail,
+      inboundEmailId: null, conversationId: null, attachments: null, ticketId: input.ticketId ?? null,
+    }))
+  }
+
+  async function getDetail(tx: DB, tenantId: string, ticketId: string): Promise<TicketDetail> {
+    const ticket = await loadTicket(tx, tenantId, ticketId, false)
+    const messages = await tx.execute(sql`SELECT * FROM support_message WHERE ticket_id = ${ticketId}::uuid ORDER BY created_at, id`)
+    const links = await tx.execute(sql`SELECT * FROM support_link WHERE ticket_id = ${ticketId}::uuid ORDER BY created_at, id`)
+    return { ticket, messages: messages.map(toMessage), links: links.map(toLink) }
+  }
+
+  async function listTickets(tx: DB, tenantId: string | null, options: ListOptions = {}): Promise<ListPage> {
+    const limit = Math.min(options.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT)
+    if (!Number.isInteger(limit) || limit < 1) throw new ValidationError({ limit: ['must be a positive integer'] }, 'support.list: limit must be a positive integer.')
+    let cursorAt: string | null = null
+    let cursorId: string | null = null
+    if (options.cursor !== undefined) {
+      const [at, id] = Buffer.from(options.cursor, 'base64url').toString('utf-8').split('|')
+      if (at === undefined || id === undefined || !UUID_RE.test(id) || Number.isNaN(Date.parse(at))) {
+        throw new ValidationError({ cursor: ['is not a cursor from a previous page'] }, 'support.list: bad cursor.')
+      }
+      cursorAt = at
+      cursorId = id
+    }
+    const rows = await tx.execute(sql`
+      SELECT t.*, t.created_at::text AS created_at_raw FROM support_ticket t
+      WHERE (${tenantId}::uuid IS NULL OR t.tenant_id = ${tenantId}::uuid)
+        AND (${options.state ?? null}::text IS NULL OR t.state = ${options.state ?? null})
+        AND (${options.category ?? null}::text IS NULL OR t.category = ${options.category ?? null})
+        AND (${cursorAt}::timestamptz IS NULL OR (t.created_at, t.id) < (${cursorAt}::timestamptz, ${cursorId}::uuid))
+      ORDER BY t.created_at DESC, t.id DESC LIMIT ${limit + 1}`)
+    const page = rows.slice(0, limit)
+    const last = page[page.length - 1]
+    const next = rows.length > limit && last !== undefined
+      ? Buffer.from(`${String(last['created_at_raw'])}|${String(last['id'])}`).toString('base64url')
+      : null
+    return { tickets: page.map(toTicket), next }
+  }
+
+  async function setCategory(flow: Flow, tx: DB, tenantId: string, ticketId: string, category: string | null): Promise<Ticket> {
+    if (category !== null) nonEmpty('category', category)
+    const before = await loadTicket(tx, tenantId, ticketId, true)
+    const rows = await tx.execute(sql`UPDATE support_ticket SET category = ${category}, updated_at = clock_timestamp() WHERE id = ${ticketId}::uuid RETURNING *`)
+    await audit(flow, tx, tenantId, 'categorise', ticketId, { from: before.category, to: category })
+    return toTicket(rows[0]!)
+  }
+
+  async function transition(flow: Flow, tx: DB, tenantId: string, ticketId: string, to: TicketState): Promise<Ticket> {
+    if (!(TICKET_STATES as readonly string[]).includes(to)) throw new ValidationError({ to: [`must be one of ${TICKET_STATES.join(', ')}`] }, `support.transition: unknown state "${String(to)}".`)
+    const ticket = await loadTicket(tx, tenantId, ticketId, true)
+    return moveTo(flow, tx, ticket, to, false)
+  }
+
+  async function addNote(flow: Flow, tx: DB, tenantId: string, ticketId: string, text: string): Promise<TicketMessage> {
+    nonEmpty('text', text)
+    await loadTicket(tx, tenantId, ticketId, true)
+    const rows = await tx.execute(sql`
+      INSERT INTO support_message (tenant_id, ticket_id, kind, channel, text, created_by)
+      VALUES (${tenantId}::uuid, ${ticketId}::uuid, 'note', 'api', ${text}, ${resolveActorId(flow)}) RETURNING *`)
+    await tx.execute(sql`UPDATE support_ticket SET updated_at = clock_timestamp() WHERE id = ${ticketId}::uuid`)
+    await audit(flow, tx, tenantId, 'note', ticketId, { messageId: rows[0]!['id'] })
+    return toMessage(rows[0]!)
+  }
+
+  async function link(flow: Flow, tx: DB, tenantId: string, ticketId: string, l: { kind: string; ref: string; label?: string }): Promise<TicketLink> {
+    nonEmpty('kind', l.kind)
+    nonEmpty('ref', l.ref)
+    await loadTicket(tx, tenantId, ticketId, true)
+    await tx.execute(sql`
+      INSERT INTO support_link (tenant_id, ticket_id, kind, ref, label)
+      VALUES (${tenantId}::uuid, ${ticketId}::uuid, ${l.kind}, ${l.ref}, ${l.label ?? null})
+      ON CONFLICT (ticket_id, kind, ref) DO UPDATE SET label = COALESCE(EXCLUDED.label, support_link.label)`)
+    const rows = await tx.execute(sql`SELECT * FROM support_link WHERE ticket_id = ${ticketId}::uuid AND kind = ${l.kind} AND ref = ${l.ref}`)
+    await audit(flow, tx, tenantId, 'link', ticketId, { kind: l.kind, ref: l.ref })
+    return toLink(rows[0]!)
+  }
+
+  async function draftReply(flow: Flow, tx: DB, tenantId: string, ticketId: string, draft: DraftInput): Promise<{ draftId: string; version: number }> {
+    nonEmpty('text', draft.text)
+    if (draft.subject !== undefined) nonEmpty('subject', draft.subject)
+    let ticket = await loadTicket(tx, tenantId, ticketId, true)
+    if (ticket.state === 'awaiting_approval') {
+      await discardLive(flow, tx, ticket, 'replaced')
+    } else {
+      // From open the draft passes through triaged: both moves are taken and audited.
+      if (ticket.state === 'open') ticket = await moveTo(flow, tx, ticket, 'triaged', true)
+      ticket = await moveTo(flow, tx, ticket, 'awaiting_approval', true)
+    }
+    const rows = await tx.execute(sql`
+      INSERT INTO support_message (tenant_id, ticket_id, kind, channel, subject, text, html, draft_status, created_by)
+      VALUES (${tenantId}::uuid, ${ticketId}::uuid, 'draft', 'email', ${draft.subject ?? null}, ${draft.text}, ${draft.html ?? null}, 'draft', ${resolveActorId(flow)})
+      RETURNING id, version`)
+    const draftId = rows[0]!['id'] as string
+    await audit(flow, tx, tenantId, 'draft', ticketId, { draftId, version: 1 })
+    await emit(tx, 'draft.awaiting-approval', ticket)
+    return { draftId, version: Number(rows[0]!['version']) }
+  }
+
+  async function editDraft(flow: Flow, tx: DB, tenantId: string, draftId: string, patch: Partial<DraftInput>): Promise<{ draftId: string; version: number }> {
+    if (patch.text !== undefined) nonEmpty('text', patch.text)
+    if (patch.subject !== undefined) nonEmpty('subject', patch.subject)
+    const row = await loadDraftRow(tx, tenantId, draftId)
+    await loadTicket(tx, tenantId, row['ticket_id'] as string, true)
+    const rows = await tx.execute(sql`
+      UPDATE support_message SET
+        text = COALESCE(${patch.text ?? null}, text), html = COALESCE(${patch.html ?? null}, html),
+        subject = COALESCE(${patch.subject ?? null}, subject), version = version + 1, created_by = ${resolveActorId(flow)}
+      WHERE id = ${draftId}::uuid AND draft_status = 'draft' RETURNING version`)
+    if (rows[0] === undefined) throw staleDraft(String(row['draft_status']))
+    const version = Number(rows[0]['version'])
+    await audit(flow, tx, tenantId, 'draft', row['ticket_id'] as string, { draftId, version, edited: true })
+    return { draftId, version }
+  }
+
+  function staleDraft(status: string, version?: { expected: number; actual: number }): DraftStateError {
+    if (status === 'approved') return new DraftStateError('approved', 'This draft is already approved.')
+    if (status === 'discarded') return new DraftStateError('discarded', 'This draft was discarded.')
+    return new DraftStateError('changed', `This draft changed since it was read (version ${String(version?.actual)}, expected ${String(version?.expected)}).`)
+  }
+
+  async function discardDraft(flow: Flow, tx: DB, tenantId: string, draftId: string): Promise<void> {
+    const row = await loadDraftRow(tx, tenantId, draftId)
+    const ticket = await loadTicket(tx, tenantId, row['ticket_id'] as string, true)
+    const rows = await tx.execute(sql`UPDATE support_message SET draft_status = 'discarded' WHERE id = ${draftId}::uuid AND draft_status = 'draft' RETURNING id`)
+    if (rows[0] === undefined) throw staleDraft(String(row['draft_status']))
+    await audit(flow, tx, tenantId, 'discard', ticket.id, { draftId, reason: 'discarded' })
+    await moveTo(flow, tx, ticket, 'triaged', true)
+  }
+
+  async function approve(explicit: string | null, draftId: string, options: { expectedVersion: number }): Promise<{ messageId: string; emailMessageId: string }> {
+    const flow = requireContext()
+    const tenantId = tenantOf(explicit, flow)
+    const actorId = resolveActorId(flow)
+    if (actorId === null) throw new ForbiddenError('Approving a reply needs an authenticated actor.')
+    if (!Number.isInteger(options.expectedVersion)) throw new ValidationError({ expectedVersion: ['must be an integer'] }, 'support.approve needs the expectedVersion the approver read.')
+    if (!(await config.canApprove({ actorId, tenantId }))) {
+      throw new ForbiddenError('This actor may not approve replies.', { actorId, tenantId })
+    }
+    return run(explicit, async (tx) => {
+      // The ticket row is locked first, so a customer message, a discard and a second approve wait for this one.
+      const row = await loadDraftRow(tx, tenantId, draftId)
+      const ticket = await loadTicket(tx, tenantId, row['ticket_id'] as string, true)
+      const draft = toMessage(await loadDraftRow(tx, tenantId, draftId))
+      if (distinctApprover && draft.createdBy === actorId) {
+        throw new ForbiddenError('A draft cannot be approved by its author.', { actorId })
+      }
+      const claimed = await tx.execute(sql`
+        UPDATE support_message SET draft_status = 'approved', approved_by = ${actorId}, approved_at = clock_timestamp()
+        WHERE id = ${draftId}::uuid AND draft_status = 'draft' AND version = ${options.expectedVersion}
+        RETURNING *`)
+      if (claimed[0] === undefined) throw staleDraft(draft.draftStatus ?? 'changed', { expected: options.expectedVersion, actual: draft.version })
+      // What is sent is what the update matched, not the earlier read.
+      const approved = toMessage(claimed[0])
+      if (ticket.state !== 'awaiting_approval') {
+        throw new DraftStateError('not-awaiting-approval', `The ticket is ${ticket.state}, not awaiting approval.`)
+      }
+      const parent = await tx.execute(sql`
+        SELECT inbound_email_id FROM support_message
+        WHERE ticket_id = ${ticket.id}::uuid AND kind = 'inbound' AND inbound_email_id IS NOT NULL
+        ORDER BY created_at DESC, id DESC LIMIT 1`)
+      const inReplyTo = (parent[0]?.['inbound_email_id'] ?? null) as string | null
+      const subject = approved.subject ?? (/^re:/i.test(ticket.subject) ? ticket.subject : `Re: ${ticket.subject}`)
+      const sent = await config.mail.send(tx, {
+        to: ticket.contactEmail, template: replyTemplate,
+        data: { subject, text: approved.text, ...(approved.html !== null ? { html: approved.html } : {}) },
+        key: `support-reply:${draftId}`,
+        ...(ticket.conversationId !== null ? { conversationId: ticket.conversationId } : {}),
+        ...(inReplyTo !== null ? { inReplyTo } : {}),
+      })
+      await tx.execute(sql`UPDATE support_message SET email_message_id = ${sent.messageId}::uuid WHERE id = ${draftId}::uuid`)
+      const outbound = await tx.execute(sql`
+        INSERT INTO support_message (tenant_id, ticket_id, kind, channel, subject, text, html, approved_by, approved_at, email_message_id, created_by)
+        VALUES (${tenantId}::uuid, ${ticket.id}::uuid, 'outbound', 'email', ${subject}, ${approved.text}, ${approved.html}, ${actorId},
+          clock_timestamp(), ${sent.messageId}::uuid, ${approved.createdBy})
+        RETURNING id`)
+      await moveTo(flow, tx, ticket, 'answered', true)
+      await audit(flow, tx, tenantId, 'approve', ticket.id, { draftId, version: draft.version, approvedBy: actorId, emailMessageId: sent.messageId, author: draft.createdBy })
+      return { messageId: outbound[0]!['id'] as string, emailMessageId: sent.messageId }
+    })
+  }
+
+  const outbox = createOutbox<SupportDelivery>({
+    table: 'support_event_delivery', groupColumn: 'ticket_id', database: undefined, sinks,
+    maxAttempts: config.maxAttempts ?? 10, backoffMs: config.backoffMs ?? 5000, label: 'support event delivery given up',
+    toDelivery: (row, attempt) => ({
+      id: row['id'] as string, kind: row['kind'] as SupportEventKind, key: row['ticket_id'] as string, sink: row['sink'] as string,
+      payload: row['payload'] as SupportEventPayload, attempt,
+    }),
+    onDelivered: (row, attempt) => auditDelivery('deliver', row, { attempt }),
+    onGivenUp: (row, attempt, error) => auditDelivery('deliver-failed', row, { attempt, error }),
+  })
+
+  async function auditDelivery(verb: string, row: Record<string, unknown>, extra: Record<string, unknown>): Promise<void> {
+    const flow = requireContext()
+    const payload = row['payload'] as SupportEventPayload
+    await audit(flow, null, payload.tenantId, verb, row['ticket_id'] as string, { sink: row['sink'], kind: row['kind'], ...extra })
+  }
+
+  const drainStep = __flowStep({ ref: 'pipework/support:tick' }, () => outbox.drain())
+  // A beat for `alerts.source.loopStalled`, written only where the blueprint has `alerts`.
+  const beat = async (outcome: { ok: boolean; error?: string }): Promise<void> => {
+    const ctx = getContext()
+    if (ctx === undefined || !beatsEnabled(ctx.instance.config)) return
+    await recordBeat(() => pipeSystem(), 'support.events', { ...outcome, everyMs: 60_000 })
+  }
+  const tickStep = async () => {
+    try {
+      const result = await drainStep()
+      await beat({ ok: true })
+      return result
+    } catch (err) {
+      await beat({ ok: false, error: describeError(err).message })
+      throw err
+    }
+  }
+  const job = fitting.use().job(jobType).fit(async () => tickStep())
+
+  // Each call exists twice: for the Flow's tenant, and as `<name>For(tenantId, ...)`.
+  const ops: Record<Exclude<keyof TicketApi, 'approve'>, (flow: Flow, tx: DB, tenantId: string, ...args: never[]) => Promise<unknown>> = {
+    get: (_f, tx, t, id: string) => getDetail(tx, t, id),
+    list: (_f, tx, t, o?: ListOptions) => listTickets(tx, t, o),
+    setCategory: (f, tx, t, id: string, c: string | null) => setCategory(f, tx, t, id, c),
+    transition: (f, tx, t, id: string, to: TicketState) => transition(f, tx, t, id, to),
+    addNote: (f, tx, t, id: string, text: string) => addNote(f, tx, t, id, text),
+    link: (f, tx, t, id: string, l: { kind: string; ref: string; label?: string }) => link(f, tx, t, id, l),
+    draftReply: (f, tx, t, id: string, d: DraftInput) => draftReply(f, tx, t, id, d),
+    editDraft: (f, tx, t, id: string, d: Partial<DraftInput>) => editDraft(f, tx, t, id, d),
+    discardDraft: (f, tx, t, id: string) => discardDraft(f, tx, t, id),
+  }
+  const api: Record<string, unknown> = {
+    approve: (draftId: string, options: { expectedVersion: number }) => approve(null, draftId, options),
+    approveFor: (tenantId: string, draftId: string, options: { expectedVersion: number }) => approve(tenantId, draftId, options),
+  }
+  for (const [name, fn] of Object.entries(ops)) {
+    const call = fn as (flow: Flow, tx: DB, tenantId: string, ...args: unknown[]) => Promise<unknown>
+    api[name] = (...args: unknown[]) => run(null, (tx, t, f) => call(f, tx, t, ...args))
+    api[`${name}For`] = (tenantId: string, ...args: unknown[]) => run(tenantId, (tx, t, f) => call(f, tx, t, ...args))
+  }
+
+  return {
+    ...(api as unknown as WithFor<TicketApi>),
+    receiveEmail,
+    receive,
+    async listAll(options = {}) {
+      requireContext()
+      const { tenantId, ...rest } = options
+      if (tenantId !== undefined) requireUuid('tenantId', tenantId)
+      return listTickets(pipeSystem(), tenantId ?? null, rest)
+    },
+    job: job as unknown as Handler<Record<string, unknown>, unknown>,
+    tick: () => tickStep(),
+    async requeueFailed(options) {
+      requireContext()
+      nonEmpty('by', options.by)
+      const requeued = await outbox.requeue({ ...(options.sink !== undefined ? { sink: options.sink } : {}), ...(options.failedSince !== undefined ? { failedSince: options.failedSince } : {}) })
+      for (const row of requeued) {
+        await auditDelivery('requeue', row, { by: options.by.trim(), attempts: Number(row['prev_attempts']), error: row['last_error'] ?? null })
+      }
+      return { requeued: requeued.length }
+    },
+    async deliveries(options = {}) {
+      const rows = options.ticketId === undefined
+        ? await pipeSystem().execute(sql`SELECT * FROM support_event_delivery ORDER BY created_at, id`)
+        : await pipeSystem().execute(sql`SELECT * FROM support_event_delivery WHERE ticket_id = ${options.ticketId}::uuid ORDER BY created_at, id`)
+      return rows.map(r => ({
+        id: r['id'] as string, ticketId: r['ticket_id'] as string, kind: r['kind'] as SupportEventKind, sink: r['sink'] as string,
+        attempts: Number(r['attempts']), deliveredAt: r['delivered_at'] === null ? null : toDate(r['delivered_at']),
+        failedAt: r['failed_at'] === null ? null : toDate(r['failed_at']), lastError: (r['last_error'] ?? null) as string | null,
+      }))
+    },
+  }
+}