@fullstackhouse/open-mercato-durable-work 0.1.0

package/src/modules/durable_work/api/jobs/[id]/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from 'next/server'
+
+import { routeContext, toDto } from '../../../lib/route-helpers'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['durable_work.view'] },
+  DELETE: { requireAuth: true, requireFeatures: ['durable_work.operate'] },
+}
+
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+  const ctx = await routeContext(req)
+  if (ctx instanceof NextResponse) return ctx
+  const job = await ctx.service.get(params.id, ctx.scope)
+  if (!job) return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  return NextResponse.json(toDto(job))
+}
+
+/** Asks the job to stop. Answers with what actually happened — a running job is `cancelling`
+ *  until its driver observes the request, and saying `cancelled` before that would be a lie
+ *  an operator might act on. */
+export async function DELETE(req: Request, { params }: { params: { id: string } }) {
+  const ctx = await routeContext(req)
+  if (ctx instanceof NextResponse) return ctx
+  const job = await ctx.service.cancel(params.id, ctx.scope, ctx.userId)
+  if (!job) return NextResponse.json({ error: 'Not found or already finished' }, { status: 404 })
+  return NextResponse.json({ ...toDto(job), state: job.status === 'cancelled' ? 'cancelled' : 'cancelling' })
+}

package/src/modules/durable_work/api/jobs/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server'
+
+import { routeContext, toDto } from '../../lib/route-helpers'
+import type { DurableJobStatus } from '../../../../core/types'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['durable_work.view'] },
+}
+
+const STATUSES = new Set<DurableJobStatus>(['pending', 'running', 'completed', 'failed', 'cancelled'])
+
+export async function GET(req: Request) {
+  const ctx = await routeContext(req)
+  if (ctx instanceof NextResponse) return ctx
+
+  const url = new URL(req.url)
+  const status = url.searchParams.get('status')
+  const { items, total } = await ctx.service.list(ctx.scope, {
+    kind: url.searchParams.get('kind') ?? undefined,
+    status: status && STATUSES.has(status as DurableJobStatus) ? (status as DurableJobStatus) : undefined,
+    page: Number(url.searchParams.get('page') ?? '1'),
+    pageSize: Number(url.searchParams.get('pageSize') ?? '20'),
+  })
+
+  return NextResponse.json({ items: items.map(toDto), total })
+}

package/src/modules/durable_work/cli.ts

@@ -0,0 +1,91 @@
+// The worker process, and the operator's command line.
+//
+// `mercato durable_work worker` is how the mechanism runs in production. It is deliberately its
+// own process: a slice can run for minutes, and hosting that inside the web process means a
+// deploy either kills work mid-batch or holds the deploy open for the length of a slice.
+
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+
+import type { DurableWorkService } from '../../core/service'
+import { registry } from '../../core/registry'
+import { startWorker } from '../../core/worker'
+import { readConfig } from '../../om/config'
+import type { SqlTransactor } from '../../core/types'
+import type { TransportAdapter } from '../../transport/types'
+
+const flag = (argv: string[], name: string): string | undefined => {
+  const index = argv.indexOf(`--${name}`)
+  return index >= 0 ? argv[index + 1] : undefined
+}
+
+const emit = (event: string, fields: Record<string, unknown> = {}) => console.log(JSON.stringify({ event, ...fields }))
+
+const workerCommand: ModuleCli = {
+  command: 'worker',
+  async run(argv: string[]) {
+    const config = readConfig()
+    const container = await createRequestContainer()
+    const sql = container.resolve('durableWorkSql') as SqlTransactor
+    const transport = container.resolve('durableWorkTransport') as TransportAdapter
+
+    const worker = await startWorker({
+      sql,
+      transport,
+      registry,
+      kinds: flag(argv, 'kinds')?.split(','),
+      concurrency: flag(argv, 'concurrency') ? Number(flag(argv, 'concurrency')) : undefined,
+      tickMs: config.tickMs,
+      reconcilerGraceMs: config.reconcilerGraceMs,
+      drainTimeoutMs: config.drainTimeoutMs,
+      log: (event, fields) => emit(event, fields),
+    })
+
+    emit('durable_work.worker_started', {
+      owner: worker.owner,
+      transport: transport.name,
+      kinds: registry.list().map((kind) => kind.kind),
+    })
+
+    // SIGTERM is what a deploy sends. Draining rather than exiting is the difference between a
+    // slice handing its remaining work back and a slice being killed between two writes.
+    let stopping = false
+    const stop = async (signal: string) => {
+      if (stopping) return
+      stopping = true
+      emit('durable_work.worker_draining', { signal, timeoutMs: config.drainTimeoutMs })
+      await worker.stop()
+      emit('durable_work.worker_stopped')
+      process.exit(0)
+    }
+    process.on('SIGTERM', () => void stop('SIGTERM'))
+    process.on('SIGINT', () => void stop('SIGINT'))
+
+    await new Promise(() => undefined) // run until signalled
+  },
+}
+
+const reconcileCommand: ModuleCli = {
+  command: 'reconcile',
+  async run() {
+    const container = await createRequestContainer()
+    const service = container.resolve('durableWorkService') as DurableWorkService
+    console.log(JSON.stringify(await service.reconcile(), null, 2))
+  },
+}
+
+const helpCommand: ModuleCli = {
+  command: 'help',
+  async run() {
+    console.log(
+      [
+        'mercato durable_work worker [--kinds a,b] [--concurrency n]',
+        '    Bind every registered kind, own the reconciler tick, drain on SIGTERM.',
+        'mercato durable_work reconcile',
+        '    Run one reconciler pass and print what it repaired.',
+      ].join('\n'),
+    )
+  },
+}
+
+export default [workerCommand, reconcileCommand, helpCommand]

package/src/modules/durable_work/data/entities.ts

@@ -0,0 +1,158 @@
+// The MikroORM view of the job table.
+//
+// The mechanism itself never goes through this entity — every statement in `core/store.ts` is
+// hand-written SQL, because each is a compare-and-set whose predicate is the guarantee. The
+// entity exists so the table is discoverable to the host: migrations, the entity registry,
+// query tooling and anything an app wants to join against.
+//
+// It must therefore stay in step with `core/schema.ts`, which is the definition. A test
+// asserts they agree column for column.
+
+import { OptionalProps } from '@mikro-orm/core'
+import { Entity, Index, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
+
+export type DurableWorkJobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+@Entity({ tableName: 'durable_work_jobs' })
+@Index({ name: 'durable_work_jobs_running_idx', properties: ['tenantId'] })
+@Index({ name: 'durable_work_jobs_subject_idx', properties: ['subjectType', 'subjectId'] })
+export class DurableWorkJob {
+  [OptionalProps]?:
+    | 'status'
+    | 'leaseEpoch'
+    | 'continuationSeq'
+    | 'redrives'
+    | 'redrivesSinceCommit'
+    | 'consecutiveFailures'
+    | 'interruptions'
+    | 'mirrorAttempts'
+    | 'processedCount'
+    | 'createdAt'
+    | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'kind', type: 'text' })
+  kind!: string
+
+  @Property({ name: 'status', type: 'text' })
+  status: DurableWorkJobStatus = 'pending'
+
+  @Property({ name: 'created_by', type: 'uuid', nullable: true })
+  createdBy?: string | null
+
+  @Property({ name: 'created_at', type: 'timestamptz' })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: 'timestamptz', onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'input', type: 'jsonb', nullable: true })
+  input?: unknown
+
+  @Property({ name: 'checkpoint', type: 'jsonb', nullable: true })
+  checkpoint?: unknown
+
+  @Property({ name: 'meta', type: 'jsonb', nullable: true })
+  meta?: Record<string, unknown> | null
+
+  @Property({ name: 'idempotency_key', type: 'text', nullable: true })
+  idempotencyKey?: string | null
+
+  @Property({ name: 'lock_key', type: 'text', nullable: true })
+  lockKey?: string | null
+
+  @Property({ name: 'subject_type', type: 'text', nullable: true })
+  subjectType?: string | null
+
+  @Property({ name: 'subject_id', type: 'text', nullable: true })
+  subjectId?: string | null
+
+  @Property({ name: 'progress_job_id', type: 'uuid', nullable: true })
+  progressJobId?: string | null
+
+  @Property({ name: 'lease_owner', type: 'text', nullable: true })
+  leaseOwner?: string | null
+
+  @Property({ name: 'lease_epoch', type: 'bigint' })
+  leaseEpoch: number = 0
+
+  @Property({ name: 'lease_expires_at', type: 'timestamptz', nullable: true })
+  leaseExpiresAt?: Date | null
+
+  @Property({ name: 'heartbeat_at', type: 'timestamptz', nullable: true })
+  heartbeatAt?: Date | null
+
+  @Property({ name: 'queue_name', type: 'text', nullable: true })
+  queueName?: string | null
+
+  @Property({ name: 'queue_job_id', type: 'text', nullable: true })
+  queueJobId?: string | null
+
+  @Property({ name: 'continuation_seq', type: 'int' })
+  continuationSeq: number = 0
+
+  @Property({ name: 'redrives', type: 'int' })
+  redrives: number = 0
+
+  @Property({ name: 'next_run_at', type: 'timestamptz', nullable: true })
+  nextRunAt?: Date | null
+
+  @Property({ name: 'pending_since', type: 'timestamptz', nullable: true })
+  pendingSince?: Date | null
+
+  @Property({ name: 'redrives_since_commit', type: 'int' })
+  redrivesSinceCommit: number = 0
+
+  @Property({ name: 'consecutive_failures', type: 'int' })
+  consecutiveFailures: number = 0
+
+  @Property({ name: 'interruptions', type: 'int' })
+  interruptions: number = 0
+
+  @Property({ name: 'mirror_attempts', type: 'int' })
+  mirrorAttempts: number = 0
+
+  @Property({ name: 'last_committed_at', type: 'timestamptz', nullable: true })
+  lastCommittedAt?: Date | null
+
+  @Property({ name: 'started_at', type: 'timestamptz', nullable: true })
+  startedAt?: Date | null
+
+  @Property({ name: 'finished_at', type: 'timestamptz', nullable: true })
+  finishedAt?: Date | null
+
+  @Property({ name: 'parked_at', type: 'timestamptz', nullable: true })
+  parkedAt?: Date | null
+
+  @Property({ name: 'cancel_requested_at', type: 'timestamptz', nullable: true })
+  cancelRequestedAt?: Date | null
+
+  @Property({ name: 'cancelled_by', type: 'uuid', nullable: true })
+  cancelledBy?: string | null
+
+  @Property({ name: 'error_class', type: 'text', nullable: true })
+  errorClass?: string | null
+
+  @Property({ name: 'error_code', type: 'text', nullable: true })
+  errorCode?: string | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'domain_mirrored_at', type: 'timestamptz', nullable: true })
+  domainMirroredAt?: Date | null
+
+  @Property({ name: 'processed_count', type: 'int' })
+  processedCount: number = 0
+
+  @Property({ name: 'total_count', type: 'int', nullable: true })
+  totalCount?: number | null
+}

package/src/modules/durable_work/di.ts

@@ -0,0 +1,41 @@
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+import { DurableWorkService } from '../../core/service'
+import { registry } from '../../core/registry'
+import { createTransport, readConfig } from '../../om/config'
+import { mikroExecutor } from '../../om/sql-executor-mikro'
+import type { TransportAdapter } from '../../transport/types'
+
+// One transport per process, not per request.
+//
+// A container is built per request, and a transport owns broker connections and bound workers.
+// Building one per request would open a Redis connection per HTTP call — the kind of leak that
+// looks like a memory problem for a week before anyone finds it.
+let transport: TransportAdapter | null = null
+function sharedTransport(): TransportAdapter {
+  if (!transport) transport = createTransport(readConfig())
+  return transport
+}
+
+export function register(container: AppContainer) {
+  container.register({
+    durableWorkService: {
+      resolve: (c) => {
+        const em = c.resolve<EntityManager>('em')
+        const config = readConfig()
+        return new DurableWorkService({
+          sql: mikroExecutor(em),
+          transport: sharedTransport(),
+          registry,
+          graceMs: config.reconcilerGraceMs,
+        })
+      },
+    },
+    // The raw executor, for the worker command: it drives the mechanism directly rather than
+    // through the service, and needs to open its own transactions.
+    durableWorkSql: { resolve: (c) => mikroExecutor(c.resolve<EntityManager>('em')) },
+    durableWorkRegistry: { resolve: () => registry },
+    durableWorkTransport: { resolve: () => sharedTransport() },
+  })
+}

package/src/modules/durable_work/events.ts

@@ -0,0 +1,30 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+// The lifecycle a host can subscribe to.
+//
+// Every one is emitted after its transaction commits, and never inside it: a subscriber that
+// throws must not be able to roll back the fact the event describes, and a slow subscriber
+// must not hold a row lock for the length of its work.
+export const events = [
+  { id: 'durable_work.job.created', label: 'Job created', entity: 'job', category: 'crud', clientBroadcast: true },
+  { id: 'durable_work.job.started', label: 'Job started', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.yielded', label: 'Slice handed back', entity: 'job', category: 'lifecycle', clientBroadcast: false },
+  { id: 'durable_work.job.completed', label: 'Job completed', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.failed', label: 'Job failed', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.parked', label: 'Job parked for an operator', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.cancelled', label: 'Job cancelled', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.redriven', label: 'Job re-driven', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+  { id: 'durable_work.job.lease_lost', label: 'Lease lost', entity: 'job', category: 'lifecycle', clientBroadcast: false },
+  { id: 'durable_work.job.mirror_stuck', label: 'Domain mirror stuck', entity: 'job', category: 'lifecycle', clientBroadcast: true },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'durable_work',
+  events,
+})
+
+export const emitDurableWorkEvent = eventsConfig.emit
+
+export type DurableWorkEventId = (typeof events)[number]['id']
+
+export default eventsConfig

package/src/modules/durable_work/index.ts

@@ -0,0 +1,16 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'durable_work',
+  title: 'Durable Work',
+  version: '0.0.1',
+  description:
+    'Durable at-least-once background work: a leased job record with epoch fencing, bounded resumable slices, a server-side reconciler, fenced cancel and an operator API. Other modules register job kinds; this module runs them.',
+  author: 'Full Stack House',
+  license: 'MIT',
+  ejectable: true,
+}
+
+export { features } from './acl'
+
+export default metadata

package/src/modules/durable_work/lib/route-helpers.ts

@@ -0,0 +1,83 @@
+// Shared plumbing for the operator routes.
+
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+
+import type { DurableWorkService } from '../../../core/service'
+import type { DurableJob, Scope } from '../../../core/types'
+
+export type RouteContext = { service: DurableWorkService; scope: Scope; userId: string | null }
+
+/**
+ * Resolves the caller's scope and the service, or the response to return instead.
+ *
+ * The scope comes from the session, never from the request body or the path. An operator API
+ * that let a caller name a tenant would be a way to re-drive somebody else's work.
+ */
+export async function routeContext(req: Request): Promise<RouteContext | NextResponse> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  const container = await createRequestContainer()
+  return {
+    service: container.resolve('durableWorkService') as DurableWorkService,
+    scope: { tenantId: auth.tenantId, organizationId: auth.orgId ?? null },
+    userId: auth.sub ?? null,
+  }
+}
+
+/** The wire shape. Timestamps as ISO strings, plus two things only the server can decide. */
+export function toDto(job: DurableJob) {
+  return {
+    id: job.id,
+    kind: job.kind,
+    status: job.status,
+    input: job.input,
+    checkpoint: job.checkpoint,
+    subject: job.subjectType ? { type: job.subjectType, id: job.subjectId } : null,
+    lockKey: job.lockKey,
+    idempotencyKey: job.idempotencyKey,
+    processedCount: job.processedCount,
+    totalCount: job.totalCount,
+    redrives: job.redrives,
+    interruptions: job.interruptions,
+    consecutiveFailures: job.consecutiveFailures,
+    mirrorAttempts: job.mirrorAttempts,
+    leaseOwner: job.leaseOwner,
+    leaseEpoch: job.leaseEpoch,
+    leaseExpiresAt: iso(job.leaseExpiresAt),
+    heartbeatAt: iso(job.heartbeatAt),
+    nextRunAt: iso(job.nextRunAt),
+    startedAt: iso(job.startedAt),
+    finishedAt: iso(job.finishedAt),
+    parkedAt: iso(job.parkedAt),
+    cancelRequestedAt: iso(job.cancelRequestedAt),
+    errorClass: job.errorClass,
+    errorCode: job.errorCode,
+    errorMessage: job.errorMessage,
+    createdAt: iso(job.createdAt),
+    updatedAt: iso(job.updatedAt),
+    // Derived on the server because the client cannot see the kind's grace, its pending TTL
+    // or its mirror budget — and a UI that guessed would offer buttons that then 409.
+    redrivable: isRedrivable(job),
+    stuck: isStuck(job),
+  }
+}
+
+const iso = (value: Date | null): string | null => (value ? value.toISOString() : null)
+
+/** `completed` and `cancelled` are done on purpose: the first succeeded, the second was asked
+ *  for. Everything else that has stopped can be re-driven. */
+function isRedrivable(job: DurableJob): boolean {
+  if (job.status === 'completed' || job.status === 'cancelled') return false
+  if (job.status === 'failed') return true
+  return job.status === 'running' && job.leaseExpiresAt != null && job.leaseExpiresAt.getTime() < Date.now()
+}
+
+/** "Nobody is driving this and nothing is scheduled" — the state an operator needs to see. */
+function isStuck(job: DurableJob): boolean {
+  if (job.status !== 'running') return false
+  const expired = job.leaseExpiresAt != null && job.leaseExpiresAt.getTime() < Date.now() - 20_000
+  const nothingScheduled = job.nextRunAt == null || job.nextRunAt.getTime() < Date.now() - 900_000
+  return expired && nothingScheduled
+}

package/src/modules/durable_work/migrations/Migration20260908120000.ts

@@ -0,0 +1,24 @@
+import { Migration } from '@mikro-orm/migrations'
+
+import { CREATE_INDEXES, CREATE_TABLE, DROP_INDEXES, DROP_TABLE, SET_FILLFACTOR } from '../../../core/schema'
+
+/**
+ * Creates `durable_work_jobs`.
+ *
+ * The statements come from `core/schema.ts` rather than being written out again here, so what
+ * a host migrates and what the failure harness exercises are the same DDL. Two copies of a
+ * schema drift, and the way that drift surfaces is a predicate silently not being enforced in
+ * production while every test still passes.
+ */
+export class Migration20260908120000 extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(CREATE_TABLE)
+    this.addSql(SET_FILLFACTOR)
+    for (const statement of CREATE_INDEXES) this.addSql(statement)
+  }
+
+  override async down(): Promise<void> {
+    for (const statement of DROP_INDEXES) this.addSql(statement)
+    this.addSql(DROP_TABLE)
+  }
+}

package/src/modules/durable_work/setup.ts

@@ -0,0 +1,10 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: ['durable_work.view', 'durable_work.operate'],
+    admin: ['durable_work.view', 'durable_work.operate'],
+  },
+}
+
+export default setup

package/src/om/__tests__/sql-executor-mikro.test.ts

@@ -0,0 +1,83 @@
+import { toPositional } from '../sql-executor-mikro'
+
+// The statements are written in Postgres's own `$n` form so the SQL the failure harness
+// exercises is character-for-character the SQL a host runs. MikroORM binds `?` positionally,
+// and this is the whole of the translation between them — so it is the whole of what can go
+// silently wrong between a tested statement and a deployed one.
+describe('toPositional', () => {
+  it('rewrites placeholders in order', () => {
+    expect(toPositional('select $1, $2', ['a', 'b'])).toEqual({ text: 'select ?, ?', params: ['a', 'b'] })
+  })
+
+  it('duplicates a parameter that the statement reads twice', () => {
+    // The scope predicate does exactly this: compares the organization and tests it for null.
+    const sql = 'where organization_id = $2 or ($2::uuid is null and organization_id is null)'
+    expect(toPositional(sql, ['tenant', null])).toEqual({
+      text: 'where organization_id = ? or (?::uuid is null and organization_id is null)',
+      params: [null, null],
+    })
+  })
+
+  it('handles placeholders that are not in ascending order', () => {
+    expect(toPositional('select $3, $1', ['a', 'b', 'c'])).toEqual({ text: 'select ?, ?', params: ['c', 'a'] })
+  })
+
+  it('refuses a statement that references a parameter nobody supplied', () => {
+    // Silently binding undefined would turn a fenced predicate into one that matches nothing,
+    // which reads exactly like "the lease was lost" and would be debugged as such.
+    expect(() => toPositional('select $2', ['only-one'])).toThrow(/references \$2 but 1 parameter/)
+  })
+})
+
+// The two bugs that made the OM adapter differ from the harness — where every statement runs
+// through node-postgres, which reports affected rows and honours transactions for free.
+describe('mikroExecutor', () => {
+  const stub = (result: unknown) => {
+    const calls: Array<{ sql: string; method?: string; ctx?: unknown }> = []
+    const connection = {
+      execute: async (sql: string, _params?: unknown[], method?: string, ctx?: unknown) => {
+        calls.push({ sql, method, ctx })
+        return result
+      },
+    }
+    const em = {
+      getConnection: () => connection,
+      getTransactionContext: () => 'the-transaction',
+      fork: () => em,
+      transactional: async (fn: (trx: unknown) => Promise<unknown>) => fn(em),
+    }
+    return { em, calls }
+  }
+
+  it('counts rows a statement affected, not rows it returned', async () => {
+    // An UPDATE with no RETURNING returns nothing. Reporting that as zero affected rows makes
+    // every domain mirror look like it matched nothing — which is treated exactly like a throw,
+    // so the mirror is retried forever over a write that already landed.
+    const { em, calls } = stub({ affectedRows: 1 })
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { mikroExecutor } = await import('../sql-executor-mikro')
+    const sql = mikroExecutor(em as any)
+    expect(await sql.query('update sync_runs set status = $1 where id = $2', ['completed', 'x'])).toEqual({ rows: [], rowCount: 1 })
+    expect(calls[0]!.method).toBe('run')
+  })
+
+  it('reads rows from a statement that returns them', async () => {
+    const { em, calls } = stub([{ id: 'a' }])
+    const { mikroExecutor } = await import('../sql-executor-mikro')
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sql = mikroExecutor(em as any)
+    expect(await sql.query('update t set a = $1 returning id', [1])).toEqual({ rows: [{ id: 'a' }], rowCount: 1 })
+    expect(calls[0]!.method).toBe('all')
+  })
+
+  it('passes the transaction context to every statement', async () => {
+    // Without it the statements run on a pooled connection outside the transaction: nothing
+    // fails, it simply stops being atomic — so `fencedWrite` no longer rolls back a stale
+    // worker's writes and a terminal transition no longer moves both rows together.
+    const { em, calls } = stub([{ id: 'a' }])
+    const { mikroExecutor } = await import('../sql-executor-mikro')
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await mikroExecutor(em as any).transaction(async (tx) => tx.query('select 1'))
+    expect(calls[0]!.ctx).toBe('the-transaction')
+  })
+})

package/src/om/config.ts

@@ -0,0 +1,65 @@
+// How a host configures the mechanism: environment variables in, a transport out.
+
+import { BullMQTransport } from '../transport/bullmq'
+import { MemoryTransport } from '../transport/memory'
+import { PgBossTransport } from '../transport/pgboss'
+import type { TransportAdapter, TransportName } from '../transport/types'
+
+export type DurableWorkConfig = {
+  transport: TransportName
+  redisUrl: string | null
+  databaseUrl: string | null
+  pgBossSchema: string
+  tickMs: number
+  drainTimeoutMs: number
+  reconcilerGraceMs: number
+  /** Hosts the worker inside the app process. Dev and ephemeral tests only. */
+  inProcessWorker: boolean
+}
+
+const num = (value: string | undefined, fallback: number): number => {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+const bool = (value: string | undefined): boolean => value === '1' || value?.toLowerCase() === 'true'
+
+export function readConfig(env: NodeJS.ProcessEnv = process.env): DurableWorkConfig {
+  const raw = (env.DURABLE_WORK_TRANSPORT ?? 'pgboss').trim().toLowerCase()
+  if (raw !== 'memory' && raw !== 'bullmq' && raw !== 'pgboss') {
+    throw new Error(`DURABLE_WORK_TRANSPORT must be memory | bullmq | pgboss, got ${JSON.stringify(raw)}`)
+  }
+  return {
+    transport: raw,
+    // Falls back to the queue module's Redis, because an app that already runs one should not
+    // have to configure a second.
+    redisUrl: env.DURABLE_WORK_REDIS_URL ?? env.QUEUE_REDIS_URL ?? env.REDIS_URL ?? null,
+    databaseUrl: env.DATABASE_URL ?? null,
+    pgBossSchema: env.DURABLE_WORK_PGBOSS_SCHEMA ?? 'durable_work_boss',
+    tickMs: num(env.DURABLE_WORK_TICK_MS, 15_000),
+    drainTimeoutMs: num(env.DURABLE_WORK_DRAIN_TIMEOUT_MS, 30_000),
+    reconcilerGraceMs: num(env.DURABLE_WORK_GRACE_MS, 20_000),
+    inProcessWorker: bool(env.DURABLE_WORK_INPROCESS_WORKER),
+  }
+}
+
+export function createTransport(config: DurableWorkConfig, deps: { redisConnection?: unknown } = {}): TransportAdapter {
+  switch (config.transport) {
+    case 'memory':
+      // Nothing survives the process, so this is a development convenience and is refused in
+      // production rather than quietly losing every job on the next deploy.
+      if (process.env.NODE_ENV === 'production') {
+        throw new Error('DURABLE_WORK_TRANSPORT=memory keeps jobs in process memory and cannot be used in production.')
+      }
+      return new MemoryTransport()
+    case 'bullmq': {
+      const connection = deps.redisConnection ?? config.redisUrl
+      if (!connection) throw new Error('DURABLE_WORK_TRANSPORT=bullmq requires DURABLE_WORK_REDIS_URL (or QUEUE_REDIS_URL).')
+      return new BullMQTransport({ connection })
+    }
+    case 'pgboss': {
+      if (!config.databaseUrl) throw new Error('DURABLE_WORK_TRANSPORT=pgboss requires DATABASE_URL.')
+      return new PgBossTransport({ connectionString: config.databaseUrl, schema: config.pgBossSchema })
+    }
+  }
+}