@fabrika/platform-node 0.0.1

package/migrations/0001_jobs.sql

@@ -0,0 +1,33 @@
+-- Job queue — the table behind `PostgresJobQueue` (src/job-queue-postgres.ts).
+--
+-- On Workers a queue exists because there is no process to poll with. A long-running process has one,
+-- so the whole primitive collapses to a table of due work plus `SELECT … FOR UPDATE SKIP LOCKED`.
+--
+-- Delivery is VISIBILITY-based, like SQS and Cloudflare Queues: a claim pushes `visible_at` into the
+-- future and bumps `attempts`; a completed job deletes its row; a consumer that dies simply lets the
+-- timeout lapse and the job becomes claimable again. There is no separate lock column because a lock
+-- that outlives its holder is the bug the visibility timeout exists to prevent.
+--
+-- DIALECT. This DDL is in the SQLite ∩ Postgres common subset — no AUTOINCREMENT, no SERIAL, no
+-- `unixepoch()`/`now()` default (ids and timestamps are stamped caller-side, per the repo convention),
+-- no partial index. It applies unchanged to both. The Postgres-specific part of this feature is the
+-- CLAIM STATEMENT, not the schema: `FOR UPDATE SKIP LOCKED` has no SQLite equivalent, which is fine —
+-- SQLite has no concurrent writers to skip.
+--
+-- TYPE NOTE (this bites on Postgres only). Bun's Postgres client decodes `BIGINT` as a STRING, never a
+-- number. The millisecond columns below are therefore BIGINT and are never read back into JS — every
+-- comparison against them happens inside SQL. `attempts`/`max_attempts` are INTEGER (int4) precisely
+-- so they DO come back as numbers.
+CREATE TABLE IF NOT EXISTS jobs (
+	id           TEXT PRIMARY KEY,   -- UUIDv7, minted caller-side (time-ordered)
+	queue        TEXT NOT NULL,      -- queue name, so several queues share one table
+	payload      TEXT NOT NULL,      -- the JSON-serialized message
+	visible_at   BIGINT NOT NULL,    -- unix MILLIS: claimable once now >= this (delay + visibility timeout)
+	attempts     INTEGER NOT NULL,   -- claims consumed so far
+	max_attempts INTEGER NOT NULL,   -- claims allowed before the job is abandoned
+	created_at   BIGINT NOT NULL     -- unix MILLIS, enqueued
+);
+
+-- The claim's access path: due rows of one queue, oldest first. `id` tie-breaks so the order is total
+-- and two consumers scan in the same sequence (which is what makes SKIP LOCKED skip cheaply).
+CREATE INDEX IF NOT EXISTS idx_jobs_due ON jobs(queue, visible_at, id);

package/migrations/0002_deploy_locks.sql

@@ -0,0 +1,24 @@
+-- Deploy locks — the table behind `SqlDeployLocks` (src/deploy-locks-sql.ts).
+--
+-- One row per lease. The row IS the lock: acquire is a single conditional upsert whose `changes` count
+-- is the answer, so there is no read-then-write window for two consumers to slip through. A MISSING
+-- row means free; a present row whose `expires_at` is in the past means expired-and-takeable; a
+-- release deletes the row, but only when the caller is still the named holder.
+--
+-- `SqlDeployLocks` is parameterised by table name, so a service that wants a second, independent lease
+-- namespace applies this DDL under a different name rather than getting a second implementation.
+--
+-- DIALECT. Common subset — no defaults, no generated columns, no partial index; applies unchanged to
+-- SQLite and Postgres.
+--
+-- TYPE NOTE (this bites on Postgres only). `expires_at` is a `Date.now()`-based DEADLINE in unix
+-- MILLISECONDS, not a creation timestamp, so it does NOT follow the unix-seconds convention the `*_at`
+-- columns elsewhere in this codebase use. It must be BIGINT: Postgres `INTEGER` is int4, which tops
+-- out at 2147483647 and cannot hold a millisecond epoch at all (SQLite's INTEGER is 64-bit, so the
+-- same DDL survives there and the overflow only appears after the port). Nothing reads the column into
+-- JS — Bun would decode a BIGINT as a string — every comparison stays inside SQL.
+CREATE TABLE IF NOT EXISTS deploy_locks (
+	lock_key   TEXT PRIMARY KEY,  -- the lease target, e.g. `<app_id>:<env>`
+	holder     TEXT NOT NULL,     -- the run id holding the lease; release is checked against it
+	expires_at BIGINT NOT NULL    -- unix MILLIS after which the lease is stale and takeable
+);

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@fabrika/platform-node",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/platform-node"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"migrations",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./postgres-migrations": {
+			"bun": "./src/postgres-migrations.ts",
+			"types": "./src/postgres-migrations.ts",
+			"default": "./src/postgres-migrations.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/platform": "^0.0.1"
+	}
+}

package/src/asset-server-fs.ts

@@ -0,0 +1,113 @@
+// `AssetServer` over a built SPA directory — the replacement for Cloudflare's `ASSETS` binding.
+//
+// Three things it has to get right, and they are the three things a hand-rolled static handler
+// usually gets wrong:
+//   * PATH SAFETY. The request path is attacker-controlled. It is percent-decoded, resolved against
+//     the root, and then the RESOLVED path is checked to still be inside the root — so `..`, encoded
+//     `%2e%2e` and absolute paths all land outside the root and are refused.
+//   * CONTENT TYPES. Taken from `Bun.file(...).type`, which maps the extension (and appends a charset
+//     for text types). A wrong `content-type` on `.js` or `.css` breaks a SPA outright in a browser.
+//   * SPA FALLBACK. A client-routed path like `/apps/foo` has no file behind it and must serve
+//     `index.html` with 200, not 404 — but a MISSING ASSET must still 404, or a typo'd bundle URL
+//     silently returns HTML and the browser reports a syntax error instead of a missing file. The
+//     discriminator is "does this look like a document request": an explicit `text/html` in `Accept`
+//     (every browser navigation) or an extension-less path (curl, deep links). A request for
+//     `/assets/main-abc123.js` has an extension and does not accept HTML, so it 404s.
+
+import type { AssetServer } from '@fabrika/platform'
+import { join, resolve, sep } from 'node:path'
+
+export interface FileSystemAssetServerOptions {
+	/** File served for a directory and for the SPA fallback. */
+	indexFile?: string
+	/** Serve `indexFile` (200) for an unmatched document request. Off = everything unmatched 404s. */
+	spaFallback?: boolean
+}
+
+const DEFAULT_INDEX = 'index.html'
+/** A trailing `.ext` on the last path segment — the "this is an asset, not a route" signal. */
+const HAS_EXTENSION = /\.[^./]+$/
+
+export class FileSystemAssetServer implements AssetServer {
+	private readonly root: string
+	private readonly indexFile: string
+	private readonly spaFallback: boolean
+
+	constructor(root: string, options: FileSystemAssetServerOptions = {}) {
+		this.root = resolve(root)
+		this.indexFile = options.indexFile ?? DEFAULT_INDEX
+		this.spaFallback = options.spaFallback ?? true
+	}
+
+	async fetch(request: Request): Promise<Response> {
+		if (request.method !== 'GET' && request.method !== 'HEAD') {
+			return new Response('method not allowed', { status: 405, headers: { allow: 'GET, HEAD' } })
+		}
+
+		const pathname = decodePathname(new URL(request.url).pathname)
+		if (pathname === null) {
+			return new Response('bad request', { status: 400 })
+		}
+
+		const file = await this.locate(pathname)
+		if (file !== null) {
+			return serve(file, request.method)
+		}
+
+		// Unmatched. A navigation gets the SPA shell; a missing asset gets an honest 404.
+		if (this.spaFallback && looksLikeDocument(request, pathname)) {
+			const fallback = await this.locate(`/${this.indexFile}`)
+			if (fallback !== null) {
+				return serve(fallback, request.method)
+			}
+		}
+		return new Response('not found', { status: 404 })
+	}
+
+	/** The file backing `pathname`, or null when there is none inside the root. */
+	private async locate(pathname: string): Promise<Bun.BunFile | null> {
+		const candidate = resolve(this.root, `.${pathname}`)
+		if (candidate !== this.root && !candidate.startsWith(this.root + sep)) {
+			return null
+		}
+		const direct = Bun.file(candidate)
+		if (await direct.exists()) {
+			return direct
+		}
+		// A directory is not a `BunFile` that exists, so this also covers `/` and `/sub/`.
+		const index = Bun.file(join(candidate, this.indexFile))
+		return await index.exists() ? index : null
+	}
+}
+
+function serve(file: Bun.BunFile, method: string): Response {
+	const headers = new Headers({
+		'content-type': file.type === '' ? 'application/octet-stream' : file.type,
+		'content-length': String(file.size),
+	})
+	// HEAD must carry the same headers as the GET it stands for, but no body. A `BunFile` body streams.
+	return method === 'HEAD' ? new Response(null, { status: 200, headers }) : new Response(file, { status: 200, headers })
+}
+
+/** Percent-decode a request path. Null when it is malformed or smuggles a NUL. */
+function decodePathname(pathname: string): string | null {
+	let decoded: string
+	try {
+		decoded = decodeURIComponent(pathname)
+	} catch {
+		return null
+	}
+	if (decoded.includes('\0')) {
+		return null
+	}
+	return decoded.startsWith('/') ? decoded : `/${decoded}`
+}
+
+/** Whether this reads as a request for a page rather than for a build artifact. */
+function looksLikeDocument(request: Request, pathname: string): boolean {
+	if (request.headers.get('accept')?.includes('text/html') === true) {
+		return true
+	}
+	const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1)
+	return !HAS_EXTENSION.test(lastSegment)
+}

package/src/blob-s3.ts

@@ -0,0 +1,79 @@
+// `BlobStore` over S3-compatible object storage, using Bun's built-in S3 client (`Bun.S3Client`).
+//
+// ONE implementation covers both targets the platform has: Cloudflare R2 and Zerops object storage
+// (MinIO) are both S3-compatible, so the only difference is the endpoint and the credentials. That is
+// also why this does not depend on `@aws-sdk/client-s3` — the built-in client speaks the same
+// protocol, ships with the runtime, and keeps credentials in one object instead of a middleware stack.
+//
+// Divergence from the R2 binding worth knowing: R2's `get()` returns null for a missing key in the
+// same round trip, whereas S3 needs a HEAD first. `get()` therefore costs one extra request on a hit.
+// Nothing here logs the credentials, the endpoint, or an error object that might quote a signed URL.
+
+import type { BlobStore } from '@fabrika/platform'
+
+/** Connection details for an S3-compatible bucket. `endpoint` is what makes it R2, MinIO, or AWS. */
+export interface S3BlobStoreOptions {
+	bucket: string
+	accessKeyId: string
+	secretAccessKey: string
+	/** e.g. `https://<account>.r2.cloudflarestorage.com` (R2) or `http://storage:9000` (Zerops/MinIO). */
+	endpoint?: string
+	/** Required by AWS; R2 wants `auto`; MinIO ignores it. */
+	region?: string
+	/** Temporary-credential session token, when the deployment uses one. */
+	sessionToken?: string
+	/** `https://<bucket>.<host>` addressing. MinIO normally wants this OFF (path-style). */
+	virtualHostedStyle?: boolean
+}
+
+/** The blob body handed back by `get()` — a stream, opened lazily and only once, plus a text shortcut. */
+interface BlobBody {
+	body: ReadableStream
+	text(): Promise<string>
+}
+
+export class S3BlobStore implements BlobStore {
+	constructor(private readonly client: Bun.S3Client) {}
+
+	/** Build a store from plain connection options. Never logs them. */
+	static connect(options: S3BlobStoreOptions): S3BlobStore {
+		return new S3BlobStore(
+			new Bun.S3Client({
+				bucket: options.bucket,
+				accessKeyId: options.accessKeyId,
+				secretAccessKey: options.secretAccessKey,
+				...(options.endpoint !== undefined ? { endpoint: options.endpoint } : {}),
+				...(options.region !== undefined ? { region: options.region } : {}),
+				...(options.sessionToken !== undefined ? { sessionToken: options.sessionToken } : {}),
+				...(options.virtualHostedStyle !== undefined ? { virtualHostedStyle: options.virtualHostedStyle } : {}),
+			}),
+		)
+	}
+
+	async put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void> {
+		// The S3 client takes bytes or a Response, not a bare stream — wrapping a stream in a Response
+		// is what lets it be uploaded without buffering the whole body first.
+		const payload = value instanceof ReadableStream ? new Response(value) : value
+		await this.client.write(key, payload)
+	}
+
+	async get(key: string): Promise<BlobBody | null> {
+		const file = this.client.file(key)
+		if (!(await file.exists())) {
+			return null
+		}
+		let stream: ReadableStream | undefined
+		return {
+			// Lazy + memoised, matching R2: the body is one stream, consumable once.
+			get body(): ReadableStream {
+				stream ??= file.stream()
+				return stream
+			},
+			text: () => file.text(),
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.client.delete(key)
+	}
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+// @fabrika/platform-node — every `@fabrika/platform` port implemented for a LONG-RUNNING BUN PROCESS.
+//
+// This is the second implementation set behind the ports (the first being the Cloudflare bindings that
+// live with the workers using them), and the one ADR-0003 needs: on Zerops the control plane executes
+// the deploy itself, in a process, so it needs Postgres instead of D1, S3 instead of R2, a job table
+// instead of Cloudflare Queues, a lock row instead of a Durable Object, and a directory instead of an
+// `ASSETS` binding.
+//
+//   SqlDatabase  → PostgresDatabase       (Bun.SQL; `?` → `$n` via a real tokeniser)
+//   BlobStore    → S3BlobStore            (Bun.S3Client; one impl for R2 and MinIO alike)
+//   JobQueue     → PostgresJobQueue       (+ PostgresJobConsumer, the poller the port omits by design)
+//   DeployLocks  → (none — @fabrika/platform's `SqlDeployLocks` needs nothing but the SqlDatabase
+//                   port, so it is runtime-neutral and lives there; import it from @fabrika/platform)
+//   AssetServer  → FileSystemAssetServer  (built SPA directory + SPA fallback)
+//   WaitUntil    → createBackgroundTasks  (supervised promises; rejections logged, never fatal)
+//
+// Dependencies: none beyond `@fabrika/platform` itself. Everything else is a Bun built-in.
+// Migrations for what this package owns (the jobs table, the Postgres lock table) live in
+// `migrations/` — DDL is per-dialect even when the statement over it is portable.
+
+export { FileSystemAssetServer, type FileSystemAssetServerOptions } from './asset-server-fs'
+export { S3BlobStore, type S3BlobStoreOptions } from './blob-s3'
+export { type Job, PostgresJobConsumer, type PostgresJobConsumerOptions, PostgresJobQueue, type PostgresJobQueueOptions } from './job-queue-postgres'
+export { rewritePlaceholders, type RewrittenSql } from './placeholders'
+export {
+	applyPostgresMigrations,
+	definePostgresMigrationPlan,
+	platformNodePostgresMigrationBundle,
+	type PostgresLegacyMigrationEffect,
+	type PostgresLegacyMigrationLedger,
+	type PostgresMigration,
+	type PostgresMigrationBundle,
+	postgresMigrationFilenames,
+	postgresMigrationIdentity,
+	type PostgresMigrationPlan,
+	readPostgresMigrationBundle,
+	type ReadPostgresMigrationBundleOptions,
+} from './postgres-migrations'
+export {
+	definePostgresServiceMigrations,
+	postgresMigrationResultMessage,
+	type PostgresServiceMigrations,
+	type PostgresServiceMigrationsConfig,
+} from './service-postgres-migrations'
+export { PostgresDatabase, PostgresStatement, type SqlBindValue } from './sql-postgres'
+export { uuidv7 } from './uuid'
+export { type BackgroundTasks, type BackgroundTasksOptions, createBackgroundTasks } from './wait-until'

package/src/job-queue-postgres.ts

@@ -0,0 +1,275 @@
+// `JobQueue` as a Postgres table plus `SELECT … FOR UPDATE SKIP LOCKED`, and the in-process consumer
+// the port deliberately does not model.
+//
+// WHY THE CONSUMER IS NOT IN THE PORT. On Workers the consumer side is not an API at all — it is an
+// inversion of control: the platform delivers a batch to an exported `queue()` handler, with the
+// platform owning retries, batching, concurrency and the ack protocol. There is nothing for fabrika to
+// call and nothing for it to start or stop. In a long-running process fabrika owns the loop, the
+// visibility timeout and the retry policy. Those two shapes have no honest common supertype: putting
+// a `poll()`/`start()` on the port would force the Cloudflare implementation to expose a loop it can
+// never run, and putting a `queue(batch)` on it would force this side to fake a delivery it never
+// receives. `send()` — the only operation both sides genuinely share — is the whole port, and the
+// consumer is a concrete class here (see ../../../docs/reference/portability-surface.md: "the reason
+// Workers need a queue does not apply" once there is a process to poll with).
+//
+// The claim is a SINGLE statement — an `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED)
+// RETURNING …` — so it runs through the `SqlDatabase` port with no explicit transaction: Postgres
+// evaluates the sub-select's row locks and the update atomically. `SKIP LOCKED` is what lets N
+// consumers drain one queue without blocking each other or handing the same job to two of them.
+//
+// Visibility, not locking, is the delivery model (same as SQS and Cloudflare Queues): claiming a job
+// pushes `visible_at` into the future and bumps `attempts`. Finish it → `ack()` deletes the row.
+// Crash → the timeout lapses and the job is claimable again. That is the ONLY reason a consumer that
+// dies mid-job does not strand it, so `visibilityTimeoutMs` must exceed the slowest handler.
+//
+// `FOR UPDATE SKIP LOCKED` is the one Postgres-specific statement in this package; the DDL itself
+// (migrations/0001_jobs.sql) is in the SQLite ∩ Postgres common subset.
+
+import type { JobQueue, SqlDatabase } from '@fabrika/platform'
+import { uuidv7 } from './uuid'
+
+/** A claimed job, as handed to a handler. `payload` has been through the caller's `decode`. */
+export interface Job<T> {
+	id: string
+	payload: T
+	/** How many times this job has been claimed, including now. First delivery is 1. */
+	attempts: number
+	/** Claims allowed before the job is abandoned. */
+	maxAttempts: number
+}
+
+export interface PostgresJobQueueOptions {
+	/** Table holding the jobs. Must already exist; see migrations/0001_jobs.sql. */
+	table?: string
+	/** Queue name, so several queues can share one table. */
+	queue?: string
+	/** Claims allowed per job before it is abandoned. */
+	maxAttempts?: number
+	/** Injectable clock (unix millis) so delays and timeouts are testable without sleeping. */
+	now?: () => number
+}
+
+const DEFAULT_TABLE = 'jobs'
+const DEFAULT_QUEUE = 'default'
+const DEFAULT_MAX_ATTEMPTS = 5
+/** A table name is interpolated into SQL, so it is restricted to a bare unqualified identifier. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** The claim statement's projection. snake_case, mirroring the migration. */
+interface ClaimedRow {
+	id: string
+	payload: string
+	attempts: number
+	max_attempts: number
+}
+
+/**
+ * Producer + claim/ack primitives over one jobs table. Implements the `JobQueue` port (`send`); the
+ * rest is the consumer-side surface `PostgresJobConsumer` is built from and tests drive directly.
+ */
+export class PostgresJobQueue<T> implements JobQueue<T> {
+	private readonly queue: string
+	private readonly maxAttempts: number
+	private readonly now: () => number
+	private readonly sendSql: string
+	private readonly claimSql: string
+	private readonly ackSql: string
+	private readonly deferSql: string
+
+	constructor(private readonly db: SqlDatabase, options: PostgresJobQueueOptions = {}) {
+		const table = options.table ?? DEFAULT_TABLE
+		if (!IDENTIFIER.test(table)) {
+			throw new Error(`invalid jobs table name: ${table}`)
+		}
+		this.queue = options.queue ?? DEFAULT_QUEUE
+		this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+		this.now = options.now ?? Date.now
+
+		this.sendSql = `INSERT INTO ${table} (id, queue, payload, visible_at, attempts, max_attempts, created_at)
+			VALUES (?, ?, ?, ?, 0, ?, ?)`
+		// One statement: the sub-select takes row locks (skipping rows another consumer already holds)
+		// and the UPDATE hides + counts them, so a claim can never be split across two consumers.
+		this.claimSql = `UPDATE ${table} SET visible_at = ?, attempts = attempts + 1
+			WHERE id IN (
+				SELECT id FROM ${table}
+				WHERE queue = ? AND visible_at <= ?
+				ORDER BY visible_at, id
+				LIMIT ?
+				FOR UPDATE SKIP LOCKED
+			)
+			RETURNING id, payload, attempts, max_attempts`
+		this.ackSql = `DELETE FROM ${table} WHERE id = ?`
+		this.deferSql = `UPDATE ${table} SET visible_at = ? WHERE id = ?`
+	}
+
+	/** Enqueue a message. `delaySeconds` becomes a visible-after deadline, exactly as on Cloudflare Queues. */
+	async send(message: T, options: { delaySeconds?: number } = {}): Promise<void> {
+		const now = this.now()
+		const visibleAt = now + Math.max(0, options.delaySeconds ?? 0) * 1000
+		await this.db
+			.prepare(this.sendSql)
+			// The id is minted on the queue's own clock, so id order and enqueue order agree — which is
+			// what `claim()` sorts a batch by. The generator is monotonic (RFC 9562 §6.2 counter), so
+			// two sends inside one millisecond still order by which was sent first.
+			.bind(uuidv7(now), this.queue, JSON.stringify(message), visibleAt, this.maxAttempts, now)
+			.run()
+	}
+
+	/**
+	 * Take up to `limit` due jobs and hide them for `visibilityTimeoutMs`. `decode` narrows the stored
+	 * JSON at the deserialization boundary — a row this consumer cannot understand throws here rather
+	 * than reaching a handler that assumes a shape.
+	 */
+	async claim(options: { limit: number; visibilityTimeoutMs: number; decode: (payload: unknown) => T }): Promise<Job<T>[]> {
+		const now = this.now()
+		const { results } = await this.db
+			.prepare(this.claimSql)
+			.bind(now + options.visibilityTimeoutMs, this.queue, now, options.limit)
+			.all<ClaimedRow>()
+		// Postgres does NOT promise that `RETURNING` follows the sub-select's `ORDER BY` — that clause
+		// only decides WHICH rows the LIMIT takes, not the order they come back in. Sorting by id here
+		// restores enqueue order, because ids are monotonic UUIDv7 and therefore strictly time-ordered.
+		return results
+			.sort((left, right) => (left.id < right.id ? -1 : 1))
+			.map((row) => {
+				const parsed: unknown = JSON.parse(row.payload)
+				return { id: row.id, payload: options.decode(parsed), attempts: row.attempts, maxAttempts: row.max_attempts }
+			})
+	}
+
+	/** The job is done (or permanently abandoned) — drop the row. Idempotent. */
+	async ack(id: string): Promise<void> {
+		await this.db.prepare(this.ackSql).bind(id).run()
+	}
+
+	/** Make the job claimable again after `delayMs`. Used for retries and for a deferred (locked-out) run. */
+	async defer(id: string, delayMs: number): Promise<void> {
+		await this.db.prepare(this.deferSql).bind(this.now() + delayMs, id).run()
+	}
+}
+
+export interface PostgresJobConsumerOptions<T> {
+	/** Narrow the stored JSON to the message type. Throwing here abandons the job as undecodable. */
+	decode: (payload: unknown) => T
+	/** Handle one job. A throw schedules a retry until `maxAttempts` is spent. */
+	handler: (job: Job<T>) => Promise<void>
+	/** Jobs claimed per pass. Handlers still run one at a time. */
+	batchSize?: number
+	/** Sleep between passes that found nothing. A pass that found work polls again immediately. */
+	pollIntervalMs?: number
+	/** How long a claimed job stays hidden. MUST exceed the slowest handler, or the job is redelivered mid-flight. */
+	visibilityTimeoutMs?: number
+	/** Backoff before the next attempt, from the attempt count just consumed. */
+	retryDelayMs?: (attempts: number) => number
+	/** A handler threw and the job will be retried. Never log the error object (it may carry a token). */
+	onError?: (error: unknown, job: Job<T>) => void
+	/** A job spent its last attempt and was dropped. */
+	onAbandoned?: (job: Job<T>) => void
+}
+
+const DEFAULT_BATCH_SIZE = 1
+const DEFAULT_POLL_INTERVAL_MS = 1_000
+const DEFAULT_VISIBILITY_TIMEOUT_MS = 15 * 60 * 1_000
+
+/**
+ * The in-process poller. One pass = claim a batch, run the handlers in order, ack or reschedule each.
+ * Handlers run SEQUENTIALLY: a deploy consumer is one run per message and ordering per queue is the
+ * cheapest correct default; raise `batchSize` only for genuinely independent work.
+ *
+ * `start()` is fire-and-forget and never throws; `stop()` waits for the pass in flight, so a shutdown
+ * does not orphan a job it has already made invisible.
+ */
+export class PostgresJobConsumer<T> {
+	private readonly options: Required<Omit<PostgresJobConsumerOptions<T>, 'onError' | 'onAbandoned'>>
+	private readonly onError: (error: unknown, job: Job<T>) => void
+	private readonly onAbandoned: (job: Job<T>) => void
+	private running = false
+	private timer: ReturnType<typeof setTimeout> | null = null
+	private pass: Promise<void> = Promise.resolve()
+
+	constructor(private readonly queue: PostgresJobQueue<T>, options: PostgresJobConsumerOptions<T>) {
+		this.options = {
+			decode: options.decode,
+			handler: options.handler,
+			batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+			pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+			visibilityTimeoutMs: options.visibilityTimeoutMs ?? DEFAULT_VISIBILITY_TIMEOUT_MS,
+			retryDelayMs: options.retryDelayMs ?? ((attempts) => Math.min(60_000, 1_000 * 2 ** attempts)),
+		}
+		this.onError = options.onError ?? ((error) => {
+			console.error('job handler failed:', error instanceof Error ? error.message : 'unknown error')
+		})
+		this.onAbandoned = options.onAbandoned ?? ((job) => {
+			console.warn(`job ${job.id} abandoned after ${job.attempts} attempt(s)`)
+		})
+	}
+
+	/** Run one pass. Returns how many jobs were handled — 0 means the queue was empty. Exposed for tests. */
+	async poll(): Promise<number> {
+		const jobs = await this.queue.claim({
+			limit: this.options.batchSize,
+			visibilityTimeoutMs: this.options.visibilityTimeoutMs,
+			decode: this.options.decode,
+		})
+		for (const job of jobs) {
+			await this.handle(job)
+		}
+		return jobs.length
+	}
+
+	/** Start polling in the background. Idempotent. */
+	start(): void {
+		if (this.running) {
+			return
+		}
+		this.running = true
+		this.schedule(0)
+	}
+
+	/** Stop polling and wait for the pass in flight. Idempotent. */
+	async stop(): Promise<void> {
+		this.running = false
+		if (this.timer !== null) {
+			clearTimeout(this.timer)
+			this.timer = null
+		}
+		await this.pass
+	}
+
+	private schedule(delayMs: number): void {
+		this.timer = setTimeout(() => {
+			this.timer = null
+			// One pass at a time: the next is scheduled only once this one has settled, so a slow handler
+			// can never have two passes claiming against the same visibility window.
+			this.pass = this.runPass()
+		}, delayMs)
+	}
+
+	private async runPass(): Promise<void> {
+		let handled = 0
+		try {
+			handled = await this.poll()
+		} catch (error) {
+			// A claim failure is usually the database being unreachable — log short and back off.
+			console.error('job poll failed:', error instanceof Error ? error.message : 'unknown error')
+		}
+		if (this.running) {
+			this.schedule(handled > 0 ? 0 : this.options.pollIntervalMs)
+		}
+	}
+
+	private async handle(job: Job<T>): Promise<void> {
+		try {
+			await this.options.handler(job)
+			await this.queue.ack(job.id)
+		} catch (error) {
+			this.onError(error, job)
+			if (job.attempts >= job.maxAttempts) {
+				await this.queue.ack(job.id)
+				this.onAbandoned(job)
+				return
+			}
+			await this.queue.defer(job.id, this.options.retryDelayMs(job.attempts))
+		}
+	}
+}