better-supabase 0.7.1 → 0.9.0

package/dist/blocks/jobs/index.js

@@ -1,16 +1,23 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-B11Duf73.js";
-import { s as nowInstant } from "../../temporal-BJGitm-h.js";
-import { t as temporal } from "../../temporal-required-BVvW7SYJ.js";
-import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { s as nowInstant } from "../../temporal-CB5Fpo5d.js";
+import { t as temporal } from "../../temporal-required-DqRzr7i0.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-BlgnMB0H.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
 import { n as allTenantsContext } from "../../plugin-tfXW1-qO.js";
-import { n as validate } from "../../standard-BK0cqJ7y.js";
-import { a as problemResponse } from "../../problem-BreOl8b8.js";
+import { n as validate } from "../../standard-B5fe2gnW.js";
+import { o as problemResponse } from "../../problem-pIiL3WbE.js";
 import { o as tenantFrom, s as tenantPathsFor } from "../../claims-PqzCxaTD.js";
-import { n as nextCronRun, t as assertCron } from "../../cron-DVPUg5k3.js";
-import { A as workerId, C as run, E as sleep, c as errorText, d as isRecord, g as pageOf, i as blockCall, k as toInstant, n as applyTemporal, v as readBodyCapped, w as seconds } from "../../block-helpers-DWHxHsEQ.js";
-import { d as verifyWebhook, l as verifySharedSecret } from "../../verify-DL41hbvY.js";
-import { n as withContext, t as unwrap } from "../../envelope-DqnYGRw7.js";
+import { t as cronRoute } from "../../cron-route-CoL-By8Z.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { M as seconds, P as sleep, R as toInstant, f as errorText, g as leaseHeartbeat, j as run, n as applyTemporal, o as blockCall, s as budget, w as pageOf } from "../../block-helpers-CfG_MvDR.js";
+import { n as periodSeconds } from "../../ratelimit-headers-Bsxx0Tj2.js";
+import { n as nextCronRun, t as assertCron } from "../../cron-CUaKTjWC.js";
+import { r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { a as purgeWebhookInbox, i as createWebhookInbox, r as rateLimited, t as createRateLimit } from "../../rate-limit--QSiFA6D.js";
+import { r as wrapPayload, t as unwrap } from "../../envelope-CHYk5MXU.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as rateLimitSqlOptions, r as webhookInboxSqlOptions, t as jobsSqlOptions } from "../../options-OJ5zmgr8.js";
 //#region src/blocks/jobs/dev.ts
 function devDrainSecret(env, name = "CRON_SECRET") {
 	const current = env[name];
@@ -55,364 +62,6 @@ function devDrain(options) {
 	};
 }
 //#endregion
-//#region src/blocks/jobs/jobs.ts
-async function sha256(text) {
-	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-const AUTH_COOKIE = /^sb-.+-auth-token(?:\.\d+)?$/;
-/** A hash of the credentials the request carries, or `''` without any. */
-async function callerScope(request) {
-	const authorization = request.headers.get("authorization");
-	const cookies = (request.headers.get("cookie") ?? "").split(";").map((pair) => pair.trim()).filter((pair) => AUTH_COOKIE.test(pair.split("=", 1)[0] ?? "")).sort();
-	const credential = authorization ?? cookies.join(";");
-	return credential === "" ? "" : `caller:${await sha256(credential)}`;
-}
-/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL module. */
-function createIdempotency(sql, options = {}) {
-	applyTemporal(options);
-	const headerName = options.header ?? "idempotency-key";
-	const format = options.problem;
-	const ttl = seconds(options.ttl ?? "24 hours");
-	const lock = seconds(options.lock ?? "1 minute");
-	const begin = (key, fingerprint, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
-			scope,
-			key,
-			fingerprint,
-			ttl,
-			lock
-		]);
-		return {
-			state: row.state,
-			status: row.status_code,
-			body: row.response,
-			holder: row.holder ?? void 0
-		};
-	});
-	const complete = (key, holder, status, body, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4, $5) as done", [
-			scope,
-			key,
-			holder,
-			status,
-			JSON.stringify(body)
-		]);
-		return row?.done === true;
-	});
-	const release = (key, holder, scope = "") => run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.release_idempotent($1, $2, $3) as done", [
-			scope,
-			key,
-			holder
-		]);
-		return row?.done === true;
-	});
-	return {
-		begin,
-		complete,
-		release,
-		async handle(request, handler) {
-			const key = request.headers.get(headerName);
-			const instance = new URL(request.url).pathname;
-			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), {
-				instance,
-				format
-			}) : handler(request);
-			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), {
-				instance,
-				format
-			});
-			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? await callerScope(request);
-			const body = await request.clone().text();
-			const fingerprint = await sha256(`${request.method} ${instance}\n${body}`);
-			const started = await begin(key, fingerprint, scope);
-			if (!started.ok) return problemResponse(started.error, {
-				instance,
-				format
-			});
-			const { state, holder = "" } = started.data;
-			switch (state) {
-				case "replay": {
-					const stored = started.data.body;
-					return new Response(stored.body, {
-						status: started.data.status ?? 200,
-						headers: {
-							...stored.contentType ? { "content-type": stored.contentType } : {},
-							"idempotency-replayed": "true"
-						}
-					});
-				}
-				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
-					instance,
-					format,
-					headers: { "retry-after": "1" }
-				});
-				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
-					code: "IDEMPOTENCY_KEY_REUSED",
-					issues: [{
-						message: "Use a new key for a new request",
-						path: [headerName]
-					}]
-				}), {
-					instance,
-					format
-				});
-				case "started": break;
-				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
-			}
-			let response;
-			try {
-				response = await handler(request);
-			} catch (cause) {
-				await release(key, holder, scope);
-				throw cause;
-			}
-			if (response.status >= 500) {
-				await release(key, holder, scope);
-				return response;
-			}
-			const stored = {
-				body: await response.clone().text(),
-				contentType: response.headers.get("content-type")
-			};
-			await complete(key, holder, response.status, stored, scope);
-			return response;
-		}
-	};
-}
-/**
-* Runs `fn` while holding the lease on `key`, one holder at a time, and
-* releases it afterwards, also when `fn` throws. `{ acquired: false }` while
-* another holder has it. A lease that expires mid-run is taken by the next
-* caller; call `lease.extend()` for long work.
-*/
-function withLease(sql, key, fn, options = {}) {
-	const scope = options.scope ?? "";
-	const ttl = options.seconds ?? 60;
-	return run(async () => {
-		const [row] = await sql.queryRaw("select better_supabase.acquire_lease($1, $2, $3) as holder", [
-			key,
-			ttl,
-			scope
-		]);
-		const holder = row?.holder;
-		if (!holder) return { acquired: false };
-		const lease = {
-			holder,
-			extend: (next = ttl) => run(async () => {
-				const [extended] = await sql.queryRaw("select better_supabase.extend_lease($1, $2, $3, $4) as done", [
-					key,
-					holder,
-					next,
-					scope
-				]);
-				return extended?.done === true;
-			})
-		};
-		try {
-			return {
-				acquired: true,
-				value: await fn(lease)
-			};
-		} finally {
-			await sql.queryRaw("select better_supabase.release_lease($1, $2, $3)", [
-				key,
-				holder,
-				scope
-			]);
-		}
-	});
-}
-function defaultType(payload) {
-	if (typeof payload !== "object" || payload === null) return null;
-	const type = payload.type;
-	return typeof type === "string" ? type : null;
-}
-/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
-function createWebhookInbox(sql, options) {
-	applyTemporal(options);
-	const worker = options.worker ?? workerId();
-	const format = options.problem;
-	const maxAttempts = options.maxAttempts ?? 8;
-	if (!Number.isInteger(maxAttempts) || maxAttempts < 1) throw new TypeError(`createWebhookInbox maxAttempts must be a positive integer, not ${String(maxAttempts)}`);
-	const maxBodyBytes = options.maxBodyBytes ?? 1048576;
-	if (!Number.isInteger(maxBodyBytes) || maxBodyBytes < 1) throw new TypeError(`createWebhookInbox maxBodyBytes must be a positive integer, not ${String(maxBodyBytes)}`);
-	const verified = async (request, body) => {
-		if (options.verify) return options.verify(request, body);
-		const result = await verifyWebhook({
-			headers: request.headers,
-			body
-		}, options.secrets ?? []);
-		return result.ok ? ok({
-			id: result.data.id,
-			payload: result.data.payload
-		}) : result;
-	};
-	const save = (event) => run(async () => {
-		const [row] = await sql.queryRaw("select * from better_supabase.receive_webhook($1, $2, $3, $4, $5, $6, $7)", [
-			options.source,
-			event.id,
-			event.type === void 0 ? (options.typeOf ?? defaultType)(event.payload) : event.type,
-			JSON.stringify(event.payload),
-			JSON.stringify(event.headers ?? {}),
-			(event.tenant === void 0 ? options.tenantOf?.(event.payload) : event.tenant) ?? null,
-			maxAttempts
-		]);
-		return {
-			id: Number(row.id),
-			duplicate: row.duplicate
-		};
-	});
-	return {
-		store: save,
-		list: (listOptions) => run(async () => {
-			return (await sql.queryRaw("select * from better_supabase.list_webhooks($1, $2, $3, $4)", [
-				listOptions.tenant,
-				options.source,
-				listOptions.status ?? null,
-				listOptions.limit ?? 100
-			])).map((row) => ({
-				id: Number(row.id),
-				messageId: row.message_id,
-				type: row.event_type,
-				status: row.status ?? "pending",
-				attempts: row.attempts,
-				maxAttempts: row.max_attempts ?? maxAttempts,
-				lastError: row.last_error ?? null,
-				tenant: row.tenant ?? null,
-				receivedAt: toInstant(row.received_at),
-				processedAt: row.processed_at === null || row.processed_at === void 0 ? null : toInstant(row.processed_at)
-			}));
-		}),
-		purge: (purgeOptions = {}) => run(async () => {
-			const [row] = await sql.queryRaw("select better_supabase.purge_webhooks($1::interval, $2, $3, $4) as purged", [
-				seconds(purgeOptions.olderThan ?? "30 days"),
-				purgeOptions.includeDead ?? false,
-				purgeOptions.batch ?? 1e4,
-				purgeOptions.tenant ?? null
-			]);
-			return row?.purged ?? 0;
-		}),
-		async receive(request) {
-			const instance = new URL(request.url).pathname;
-			if (request.method !== "POST") return new Response(null, {
-				status: 405,
-				headers: { allow: "POST" }
-			});
-			if (!options.verify && !options.secrets) throw new TypeError(`The inbox for "${options.source}" has no \`secrets\` or \`verify\`, so it only stores events through \`store\``);
-			const body = await readBodyCapped(request.clone(), maxBodyBytes);
-			if (body === void 0) return problemResponse({
-				...dbError("invalid_input", "The body is too large", { code: "WEBHOOK_TOO_LARGE" }),
-				status: 413
-			}, {
-				instance,
-				format
-			});
-			const message = await verified(request, body);
-			if (!message.ok) return problemResponse(message.error, {
-				instance,
-				format
-			});
-			const headers = Object.fromEntries((options.keepHeaders ?? []).flatMap((name) => {
-				const value = request.headers.get(name);
-				return value === null ? [] : [[name.toLowerCase(), value]];
-			}));
-			const stored = await save({
-				id: message.data.id,
-				payload: message.data.payload,
-				headers,
-				...message.data.tenant === void 0 ? {} : { tenant: message.data.tenant }
-			});
-			if (!stored.ok) return problemResponse(stored.error, {
-				instance,
-				format
-			});
-			return Response.json(stored.data, { status: stored.data.duplicate ? 200 : 202 });
-		},
-		async process(handler, processOptions = {}) {
-			let succeeded = 0;
-			let failed = 0;
-			const lease = seconds(processOptions.lease ?? 300);
-			const deadline = processOptions.budgetMs === void 0 ? void 0 : Date.now() + processOptions.budgetMs;
-			for (;;) {
-				if (deadline !== void 0 && Date.now() >= deadline) return {
-					succeeded,
-					failed
-				};
-				const rows = await sql.queryRaw("select * from better_supabase.claim_webhooks($1, $2, $3, $4::interval)", [
-					options.source,
-					worker,
-					processOptions.batch ?? 10,
-					lease
-				]);
-				if (rows.length === 0) return {
-					succeeded,
-					failed
-				};
-				for (const row of rows) {
-					const id = Number(row.id);
-					const attempt = row.attempts;
-					const extend = async () => {
-						const [held] = await sql.queryRaw("select better_supabase.extend_webhook($1, $2, $3, $4::interval) as lease", [
-							id,
-							worker,
-							attempt,
-							lease
-						]);
-						return held?.lease ?? void 0;
-					};
-					const leaseSeconds = await extend();
-					if (leaseSeconds === void 0) continue;
-					const message = {
-						id,
-						source: row.source,
-						messageId: row.message_id,
-						type: row.event_type,
-						payload: row.payload,
-						headers: row.headers,
-						attempts: row.attempts,
-						maxAttempts: row.max_attempts ?? maxAttempts,
-						receivedAt: toInstant(row.received_at),
-						tenant: row.tenant ?? null,
-						progress: row.checkpoint ?? {},
-						async checkpoint(fields) {
-							const [saved] = await sql.queryRaw("select better_supabase.checkpoint_webhook($1, $2, $3, $4) as saved", [
-								id,
-								worker,
-								JSON.stringify(fields),
-								attempt
-							]);
-							return saved?.saved ?? false;
-						}
-					};
-					const heartbeat = setInterval(() => void extend().catch(() => void 0), Math.max(1e3, leaseSeconds * 500));
-					try {
-						const outcome = await handler(message);
-						if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false) throw new Error(errorText(outcome.error ?? "The handler failed"));
-						const [done] = await sql.queryRaw("select better_supabase.complete_webhook($1, $2, $3) as done", [
-							message.id,
-							worker,
-							attempt
-						]);
-						if (done?.done !== false) succeeded += 1;
-					} catch (cause) {
-						await sql.queryRaw("select better_supabase.fail_webhook($1, $2, $3, null, $4)", [
-							message.id,
-							worker,
-							errorText(cause),
-							attempt
-						]);
-						failed += 1;
-					} finally {
-						clearInterval(heartbeat);
-					}
-				}
-			}
-		}
-	};
-}
-//#endregion
 //#region src/blocks/jobs/backends.ts
 const instantOrNull = (value) => value === null ? null : toInstant(value);
 /** Schedule times are stored to the millisecond, the precision `Date` reads back. */
@@ -421,19 +70,75 @@ const millis = (instant) => instant.round({
 	roundingMode: "floor"
 });
 /** The first run of a schedule written without one, or undefined for a cron the drain can't read. */
-function firstRun(row) {
+function firstRun(row, now) {
 	try {
-		return millis(nextCronRun(row.schedule, row.timezone, row.first_after ? toInstant(row.first_after) : nowInstant()));
+		return millis(nextCronRun(row.schedule, row.timezone, row.first_after ? toInstant(row.first_after) : now()));
 	} catch {
 		return;
 	}
 }
 /**
+* The due schedules among claimed rows. A row written in SQL without a next
+* run gets its first run here; one not due yet is moved to it with `advance`.
+*/
+async function dueOf(rows, now, advance) {
+	const due = [];
+	for (const row of rows) {
+		const schedule = {
+			name: row.job_name,
+			cron: row.schedule,
+			timeZone: row.timezone,
+			queue: row.queue,
+			payload: row.payload
+		};
+		if (row.next_run !== null) {
+			due.push({
+				...schedule,
+				nextRun: toInstant(row.next_run)
+			});
+			continue;
+		}
+		const first = firstRun(row, now);
+		if (first === void 0) continue;
+		if (temporal().Instant.compare(first, now()) <= 0) due.push({
+			...schedule,
+			nextRun: first
+		});
+		else await advance(row.job_name, first);
+	}
+	return due;
+}
+const scheduleInfo = (row) => ({
+	name: row.job_name,
+	cron: row.schedule,
+	timeZone: row.timezone,
+	queue: row.queue,
+	tenant: row.tenant,
+	nextRun: instantOrNull(row.next_run),
+	lastRun: instantOrNull(row.last_run),
+	leasedUntil: instantOrNull(row.locked_until),
+	createdAt: instantOrNull(row.created_at)
+});
+const statsOf = (row) => ({
+	ready: Number(row?.ready ?? 0),
+	inFlight: Number(row?.in_flight ?? 0),
+	delayed: Number(row?.delayed ?? 0),
+	dead: Number(row?.dead ?? 0),
+	oldestAgeSeconds: row?.oldest_age_seconds === null || row?.oldest_age_seconds === void 0 ? null : Number(row.oldest_age_seconds)
+});
+const onceOf = (row) => {
+	if (!row) throw new TypeError("enqueue_job_once returned no row");
+	return {
+		id: Number(row.id),
+		duplicate: row.duplicate
+	};
+};
+/**
 * The `jobs` SQL module over a service SQL connection. The same
-* functions back both `sql.modules.jobs.options.backend` values (pgmq and table)
-* and both schedulers.
+* functions back both `blocks.jobs.options.backend` values (pgmq and table)
+* and both schedulers. `now` dates a schedule's first run.
 */
-function sqlQueueBackend(sql) {
+function sqlQueueBackend(sql, now = nowInstant) {
 	return {
 		apiVersion: 1,
 		name: "sql",
@@ -449,6 +154,16 @@ function sqlQueueBackend(sql) {
 			]);
 			return Number(row.id);
 		},
+		async sendOnce(queue, payload, delay, maxAttempts, dedupeKey) {
+			const [row] = await sql.queryRaw("select * from better_supabase.enqueue_job_once($1, $2, $3, $4, $5)", [
+				queue,
+				JSON.stringify(payload ?? {}),
+				dedupeKey,
+				delay,
+				maxAttempts
+			]);
+			return onceOf(row);
+		},
 		read: (queue, lease, batch) => sql.queryRaw("select * from better_supabase.claim_jobs($1, $2, $3)", [
 			queue,
 			lease,
@@ -487,13 +202,7 @@ function sqlQueueBackend(sql) {
 		},
 		async stats(queue) {
 			const [row] = await sql.queryRaw("select * from better_supabase.job_queue_stats($1)", [queue]);
-			return {
-				ready: Number(row?.ready ?? 0),
-				inFlight: Number(row?.in_flight ?? 0),
-				delayed: Number(row?.delayed ?? 0),
-				dead: Number(row?.dead ?? 0),
-				oldestAgeSeconds: row?.oldest_age_seconds === null || row?.oldest_age_seconds === void 0 ? null : Number(row.oldest_age_seconds)
-			};
+			return statsOf(row);
 		},
 		listDead: (queue, limit, before) => sql.queryRaw("select * from better_supabase.list_dead_jobs($1, $2, $3)", [
 			queue,
@@ -508,6 +217,15 @@ function sqlQueueBackend(sql) {
 			]);
 			return row?.retried ?? 0;
 		},
+		async purge(queue, args) {
+			const named = Object.entries({
+				older_than: args.olderThan,
+				batch: args.batch,
+				dead_older_than: args.deadOlderThan
+			}).filter(([, value]) => value !== void 0);
+			const [row] = await sql.queryRaw(`select better_supabase.purge_job_archive(${["queue => $1", ...named.map(([name], index) => `${name} => $${String(index + 2)}`)].join(", ")}) as purged`, [queue, ...named.map(([, value]) => value)]);
+			return row?.purged ?? 0;
+		},
 		async schedule(name, cron, queue, payload, timeZone, nextRun, tenant) {
 			await sql.queryRaw("select better_supabase.schedule_job($1, $2, $3, $4, $5, $6, $7)", [
 				name,
@@ -520,17 +238,7 @@ function sqlQueueBackend(sql) {
 			]);
 		},
 		async listSchedules(filter) {
-			return (await sql.queryRaw("select * from better_supabase.list_schedules($1, $2)", [filter.prefix ?? null, filter.tenant ?? null])).map((row) => ({
-				name: row.job_name,
-				cron: row.schedule,
-				timeZone: row.timezone,
-				queue: row.queue,
-				tenant: row.tenant,
-				nextRun: instantOrNull(row.next_run),
-				lastRun: instantOrNull(row.last_run),
-				leasedUntil: instantOrNull(row.locked_until),
-				createdAt: instantOrNull(row.created_at)
-			}));
+			return (await sql.queryRaw("select * from better_supabase.list_schedules($1, $2)", [filter.prefix ?? null, filter.tenant ?? null])).map(scheduleInfo);
 		},
 		async unscheduleTenant(tenant) {
 			const [row] = await sql.queryRaw("select better_supabase.unschedule_tenant($1) as removed", [tenant]);
@@ -541,32 +249,9 @@ function sqlQueueBackend(sql) {
 			return row?.done ?? false;
 		},
 		async dueSchedules(lease, batch) {
-			const rows = await sql.queryRaw("select * from better_supabase.claim_due_schedules($1, $2)", [lease, batch]);
-			const due = [];
-			for (const row of rows) {
-				const schedule = {
-					name: row.job_name,
-					cron: row.schedule,
-					timeZone: row.timezone,
-					queue: row.queue,
-					payload: row.payload
-				};
-				if (row.next_run !== null) {
-					due.push({
-						...schedule,
-						nextRun: toInstant(row.next_run)
-					});
-					continue;
-				}
-				const first = firstRun(row);
-				if (first === void 0) continue;
-				if (temporal().Instant.compare(first, nowInstant()) <= 0) due.push({
-					...schedule,
-					nextRun: first
-				});
-				else await sql.queryRaw("select better_supabase.advance_schedule($1, null, $2)", [row.job_name, first.toString()]);
-			}
-			return due;
+			return dueOf(await sql.queryRaw("select * from better_supabase.claim_due_schedules($1, $2)", [lease, batch]), now, async (name, first) => {
+				await sql.queryRaw("select better_supabase.advance_schedule($1, null, $2)", [name, first.toString()]);
+			});
 		},
 		async advanceSchedule(name, ran, next) {
 			const [row] = await sql.queryRaw("select better_supabase.advance_schedule($1, $2, $3) as advanced", [
@@ -578,6 +263,142 @@ function sqlQueueBackend(sql) {
 		}
 	};
 }
+/** The named arguments of each `jobs` function, in call order. */
+const PARAMS = {
+	enqueue_job: [
+		"queue",
+		"payload",
+		"delay",
+		"max_attempts",
+		"dedupe_key",
+		"dedupe_running"
+	],
+	enqueue_job_once: [
+		"queue",
+		"payload",
+		"dedupe_key",
+		"delay",
+		"max_attempts"
+	],
+	claim_jobs: [
+		"queue",
+		"lease",
+		"batch"
+	],
+	complete_job: [
+		"queue",
+		"job_id",
+		"attempt"
+	],
+	fail_job: [
+		"queue",
+		"job_id",
+		"attempt",
+		"error",
+		"retry_in"
+	],
+	extend_job_lease: [
+		"queue",
+		"job_id",
+		"attempt",
+		"lease"
+	],
+	replay_dead_job: ["queue", "job_id"],
+	job_queue_stats: ["queue"],
+	list_dead_jobs: [
+		"queue",
+		"max_rows",
+		"before_id"
+	],
+	retry_dead_jobs: [
+		"queue",
+		"ids",
+		"batch"
+	],
+	schedule_job: [
+		"job_name",
+		"schedule",
+		"queue",
+		"payload",
+		"timezone",
+		"next_run",
+		"tenant"
+	],
+	unschedule_job: ["job_name"],
+	list_schedules: ["name_prefix", "for_tenant"],
+	unschedule_tenant: ["tenant"],
+	claim_due_schedules: ["lease", "batch"],
+	advance_schedule: [
+		"job_name",
+		"ran",
+		"next_run"
+	],
+	purge_job_archive: [
+		"queue",
+		"older_than",
+		"batch",
+		"dead_older_than"
+	]
+};
+/**
+* The rows a set-returning function answered with. PostgREST and `dbTransport`
+* return an array; a single object is one row.
+*/
+function transportRows(fn, value) {
+	if (value === null || value === void 0) return [];
+	if (Array.isArray(value)) return value;
+	if (isRecord(value)) return [value];
+	throw new TypeError(`${fn} returned ${typeof value}, not rows: pass a SqlClient instead of sqlTransport for set-returning functions`);
+}
+/**
+* The `jobs` SQL module over a `BlockTransport`, with named arguments: a
+* service-role `rpcTransport(supabase, { schema: "api" })` reaches the
+* wrappers `blocks.jobs.api` writes, so stats, dead letters, replays
+* and schedules work without a direct Postgres connection. Over Postgres,
+* pass the `SqlClient` to `createJobs` instead.
+*/
+function transportQueueBackend(transport, options = {}) {
+	const schema = options.schema ?? "better_supabase";
+	const now = options.now ?? nowInstant;
+	const call = (fn, ...args) => transport.call(schema, fn, Object.fromEntries(PARAMS[fn].flatMap((name, index) => index < args.length ? [[name, args[index]]] : [])));
+	const rows = async (fn, ...args) => transportRows(fn, await call(fn, ...args));
+	const bool = async (fn, ...args) => await call(fn, ...args) === true;
+	const count = async (fn, ...args) => Number(await call(fn, ...args) ?? 0);
+	const id = (value) => value === null || value === void 0 ? null : Number(value);
+	return {
+		apiVersion: 1,
+		name: "transport",
+		leases: true,
+		async send(queue, payload, delay, maxAttempts, dedupeKey, dedupe) {
+			const sent = id(await call("enqueue_job", queue, payload ?? {}, delay, maxAttempts, dedupeKey ?? null, dedupe !== "waiting"));
+			if (sent === null) throw new TypeError("enqueue_job returned no id");
+			return sent;
+		},
+		sendOnce: async (queue, payload, delay, maxAttempts, dedupeKey) => onceOf((await rows("enqueue_job_once", queue, payload ?? {}, dedupeKey, delay, maxAttempts))[0]),
+		read: (queue, lease, batch) => rows("claim_jobs", queue, lease, batch),
+		complete: (job) => bool("complete_job", job.queue, job.id, job.attempts),
+		async fail(job, error, retryIn) {
+			const status = await call("fail_job", job.queue, job.id, job.attempts, error, retryIn ?? null);
+			return status === "queued" || status === "dead" ? status : null;
+		},
+		extend: (job, lease) => bool("extend_job_lease", job.queue, job.id, job.attempts, lease),
+		replay: async (queue, jobId) => id(await call("replay_dead_job", queue, jobId)),
+		stats: async (queue) => statsOf((await rows("job_queue_stats", queue))[0]),
+		listDead: (queue, limit, before) => rows("list_dead_jobs", queue, limit, before ?? null),
+		retryDead: (queue, ids, limit) => count("retry_dead_jobs", queue, ids === void 0 ? null : [...ids], limit),
+		purge: (queue, args) => count("purge_job_archive", queue, args.olderThan, args.batch, args.deadOlderThan),
+		async schedule(name, cron, queue, payload, timeZone, nextRun, tenant) {
+			await call("schedule_job", name, cron, queue, payload ?? {}, timeZone, nextRun.toString(), tenant ?? null);
+		},
+		unschedule: (name) => bool("unschedule_job", name),
+		listSchedules: async (filter) => (await rows("list_schedules", filter.prefix ?? null, filter.tenant ?? null)).map(scheduleInfo),
+		unscheduleTenant: (tenant) => count("unschedule_tenant", tenant),
+		dueSchedules: async (lease, batch) => dueOf(await rows("claim_due_schedules", lease, batch), now, async (name, first) => {
+			await call("advance_schedule", name, null, first.toString());
+		}),
+		advanceSchedule: (name, ran, next) => bool("advance_schedule", name, ran.toString(), next.toString())
+	};
+}
 /** Throws for a feature the transport doesn't support. */
 function sqlOnly(feature) {
 	throw new DbException(dbError("invalid_request", `${feature} needs a SQL connection; pgmq_public (PostgREST) does not support it`));
@@ -623,12 +444,12 @@ function pgmqPublicBackend(client) {
 				sleep_seconds: lease,
 				n: batch
 			});
-			const live = [];
-			for (const row of rows) if (row.read_ct > (row.message?.max_attempts ?? 5)) await call("archive", {
+			const dead = (row) => row.read_ct > (row.message?.max_attempts ?? 5);
+			const live = rows.filter((row) => !dead(row));
+			await Promise.all(rows.filter(dead).map((row) => call("archive", {
 				queue_name: queue,
 				message_id: row.msg_id
-			});
-			else live.push(row);
+			})));
 			return live.map((row) => ({
 				id: row.msg_id,
 				attempts: row.read_ct,
@@ -649,9 +470,300 @@ function pgmqPublicBackend(client) {
 	};
 }
 //#endregion
+//#region src/blocks/jobs/idempotency.ts
+async function sha256(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+const AUTH_COOKIE = /^sb-.+-auth-token(?:\.\d+)?$/;
+/** A hash of the credentials the request carries, or `''` without any. */
+async function callerScope(request) {
+	const authorization = request.headers.get("authorization");
+	const cookies = (request.headers.get("cookie") ?? "").split(";").map((pair) => pair.trim()).filter((pair) => AUTH_COOKIE.test(pair.split("=", 1)[0] ?? "")).sort();
+	const credential = authorization ?? cookies.join(";");
+	return credential === "" ? "" : `caller:${await sha256(credential)}`;
+}
+function sqlCalls$1(sql) {
+	return {
+		begin: (scope, key, fingerprint, ttl, lock) => run(async () => {
+			const [row] = await sql.queryRaw("select * from better_supabase.begin_idempotent($1, $2, $3, $4::interval, $5::interval)", [
+				scope,
+				key,
+				fingerprint,
+				ttl,
+				lock
+			]);
+			return row;
+		}),
+		complete: (scope, key, holder, status, body) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.complete_idempotent($1, $2, $3, $4, $5) as done", [
+				scope,
+				key,
+				holder,
+				status,
+				JSON.stringify(body)
+			]);
+			return row?.done === true;
+		}),
+		extend: (scope, key, holder, lock) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.extend_idempotent($1, $2, $3, $4::interval) as done", [
+				scope,
+				key,
+				holder,
+				lock
+			]);
+			return row?.done === true;
+		}),
+		release: (scope, key, holder) => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.release_idempotent($1, $2, $3) as done", [
+				scope,
+				key,
+				holder
+			]);
+			return row?.done === true;
+		}),
+		purge: () => run(async () => {
+			const [row] = await sql.queryRaw("select better_supabase.purge_idempotency_keys() as purged");
+			return row?.purged ?? 0;
+		})
+	};
+}
+function transportCalls$1(transport, schema, mappers) {
+	const call = blockCall(transport, schema, mappers);
+	return {
+		begin: (scope, key, fingerprint, ttl, lock) => call("begin_idempotent", {
+			scope,
+			key,
+			request_hash: fingerprint,
+			ttl,
+			lock
+		}, (value) => transportRows("begin_idempotent", value)[0]),
+		complete: (scope, key, holder, status, body) => call("complete_idempotent", {
+			scope,
+			key,
+			holder,
+			status_code: status,
+			response: body
+		}, (value) => value === true),
+		extend: (scope, key, holder, lock) => call("extend_idempotent", {
+			scope,
+			key,
+			holder,
+			lock
+		}, (value) => value === true),
+		release: (scope, key, holder) => call("release_idempotent", {
+			scope,
+			key,
+			holder
+		}, (value) => value === true),
+		purge: () => call("purge_idempotency_keys", {}, (value) => Number(value ?? 0))
+	};
+}
+/**
+* HTTP idempotency keys (IETF `Idempotency-Key` header) over the
+* `idempotency` SQL module: a service SQL connection, or a service-role
+* `rpcTransport` over the wrappers `blocks.idempotency.api` writes.
+*/
+function createIdempotency(options) {
+	applyTemporal(options);
+	const headerName = options.header ?? "idempotency-key";
+	const format = options.problem;
+	const ttl = seconds(options.ttl ?? "24 hours");
+	const lock = seconds(options.lock ?? "1 minute");
+	const lockSeconds = periodSeconds(options.lock ?? 60) ?? 2;
+	const calls = options.transport === void 0 ? sqlCalls$1(options.sql) : transportCalls$1(options.transport, options.schema, options.mappers);
+	const hooked = withBlockHooks({
+		purge: () => calls.purge(),
+		purgeJob: () => async () => hooked.purge().orThrow(),
+		begin: (key, fingerprint, scope = "") => calls.begin(scope, key, fingerprint, ttl, lock).andThen((row) => row ? AsyncResult.ok({
+			state: row.state,
+			status: row.status_code,
+			body: row.response,
+			holder: row.holder ?? void 0
+		}) : AsyncResult.err(dbError("unexpected", "begin_idempotent returned no row"))),
+		extend: (key, holder, scope = "") => calls.extend(scope, key, holder, lock),
+		complete: (key, holder, status, body, scope = "") => calls.complete(scope, key, holder, status, body),
+		release: (key, holder, scope = "") => calls.release(scope, key, holder),
+		async handle(request, handler) {
+			const key = request.headers.get(headerName);
+			const url = new URL(request.url);
+			const instance = url.pathname;
+			if (!key) return options.required ? problemResponse(dbError("invalid_request", `The ${headerName} header is required`, { code: "IDEMPOTENCY_KEY_MISSING" }), {
+				instance,
+				format
+			}) : handler(request);
+			if (key.length > 255) return problemResponse(dbError("invalid_request", `The ${headerName} header is too long`, { code: "IDEMPOTENCY_KEY_INVALID" }), {
+				instance,
+				format
+			});
+			const scope = typeof options.scope === "function" ? options.scope(request) : options.scope ?? await callerScope(request);
+			const body = await request.clone().text();
+			const fingerprint = await sha256(`${request.method} ${instance}${url.search}\n${body}`);
+			const started = await hooked.begin(key, fingerprint, scope);
+			if (!started.ok) return problemResponse(started.error, {
+				instance,
+				format
+			});
+			const { state, holder = "" } = started.data;
+			switch (state) {
+				case "replay": {
+					const stored = started.data.body;
+					return new Response(stored.body, {
+						status: started.data.status ?? 200,
+						headers: {
+							...stored.contentType ? { "content-type": stored.contentType } : {},
+							"idempotency-replayed": "true"
+						}
+					});
+				}
+				case "running": return problemResponse(dbError("conflict", "A request with this idempotency key is still running", { code: "IDEMPOTENCY_KEY_IN_USE" }), {
+					instance,
+					format,
+					headers: { "retry-after": "1" }
+				});
+				case "mismatch": return problemResponse(dbError("validation", "This idempotency key was used for a different request", {
+					code: "IDEMPOTENCY_KEY_REUSED",
+					issues: [{
+						message: "Use a new key for a new request",
+						path: [headerName]
+					}]
+				}), {
+					instance,
+					format
+				});
+				case "started": break;
+				default: throw new TypeError(`Unknown idempotency state ${String(state)}`);
+			}
+			let renewing = true;
+			const stopHeartbeat = leaseHeartbeat(lockSeconds, () => {
+				if (!renewing) return;
+				hooked.extend(key, holder, scope).then((extended) => {
+					if (extended.ok && !extended.data) renewing = false;
+				});
+			});
+			try {
+				let response;
+				try {
+					response = await handler(request);
+				} catch (cause) {
+					await hooked.release(key, holder, scope);
+					throw cause;
+				}
+				if (response.status >= 500) {
+					await hooked.release(key, holder, scope);
+					return response;
+				}
+				const stored = {
+					body: await response.clone().text(),
+					contentType: response.headers.get("content-type")
+				};
+				const completed = await hooked.complete(key, holder, response.status, stored, scope);
+				if (!completed.ok || !completed.data) return problemResponse(completed.ok ? dbError("conflict", "The idempotency key's lock expired before the response was saved", { code: "IDEMPOTENCY_KEY_LOST" }) : completed.error, {
+					instance,
+					format,
+					headers: { "retry-after": "1" }
+				});
+				return response;
+			} finally {
+				stopHeartbeat();
+			}
+		}
+	}, options.hooks, {
+		block: "idempotency",
+		...options.logger ? { logger: options.logger } : {}
+	});
+	return hooked;
+}
+//#endregion
+//#region src/blocks/jobs/lease.ts
+function sqlCalls(sql) {
+	return {
+		async acquire(key, ttl, scope) {
+			const [row] = await sql.queryRaw("select better_supabase.acquire_lease($1, $2, $3) as holder", [
+				key,
+				ttl,
+				scope
+			]);
+			return row?.holder ?? null;
+		},
+		async extend(key, holder, ttl, scope) {
+			const [row] = await sql.queryRaw("select better_supabase.extend_lease($1, $2, $3, $4) as done", [
+				key,
+				holder,
+				ttl,
+				scope
+			]);
+			return row?.done === true;
+		},
+		async release(key, holder, scope) {
+			await sql.queryRaw("select better_supabase.release_lease($1, $2, $3)", [
+				key,
+				holder,
+				scope
+			]);
+		}
+	};
+}
+function transportCalls(transport, schema) {
+	return {
+		async acquire(key, ttl, scope) {
+			const holder = await transport.call(schema, "acquire_lease", {
+				key,
+				seconds: ttl,
+				scope
+			});
+			return typeof holder === "string" ? holder : null;
+		},
+		extend: async (key, holder, ttl, scope) => await transport.call(schema, "extend_lease", {
+			key,
+			holder,
+			seconds: ttl,
+			scope
+		}) === true,
+		async release(key, holder, scope) {
+			await transport.call(schema, "release_lease", {
+				key,
+				holder,
+				scope
+			});
+		}
+	};
+}
+/**
+* Runs `fn` while holding the lease on `key`, one holder at a time, and
+* releases it afterwards, also when `fn` throws. `{ acquired: false }` while
+* another holder has it. A lease that expires mid-run is taken by the next
+* caller; call `lease.extend()` for long work. Takes a service SQL
+* connection, or a service-role `rpcTransport` over the wrappers
+* `blocks.idempotency.api` writes.
+*/
+function withLease(source, key, fn, options = {}) {
+	const scope = options.scope ?? "";
+	const ttl = options.seconds ?? 60;
+	const calls = "call" in source ? transportCalls(source, options.schema ?? "better_supabase") : sqlCalls(source);
+	return run(async () => {
+		const holder = await calls.acquire(key, ttl, scope);
+		if (!holder) return { acquired: false };
+		const lease = {
+			holder,
+			extend: (next = ttl) => run(() => calls.extend(key, holder, next, scope))
+		};
+		try {
+			return {
+				acquired: true,
+				value: await fn(lease)
+			};
+		} finally {
+			await calls.release(key, holder, scope);
+		}
+	});
+}
+//#endregion
 //#region src/blocks/jobs/queue.ts
 /** Transient claim errors in a row a lane retries, with backoff, before the loop throws. */
 const CLAIM_RETRIES = 3;
+/** The abort reason of a job whose lease couldn't be extended. */
+const LEASE_LOST = Symbol("lease lost");
 const TRANSIENT = /* @__PURE__ */ new Set([
 	"network",
 	"timeout",
@@ -674,30 +786,48 @@ function toJob(queue, row) {
 	};
 }
 const QUEUE_NAME = /^[a-z_][a-z0-9_]{0,46}$/;
-function isBackend(source) {
-	return "apiVersion" in source;
-}
-function isSqlClient(source) {
-	return typeof source.queryRaw === "function";
+/**
+* `transport` with every call made through `blockCall`, so a rejection is
+* mapped to a `DbError` (with the app's `mappers` first), as in every block.
+*/
+function mappedTransport(transport, mappers) {
+	return { async call(schema, fn, args) {
+		const result = await blockCall(transport, schema, mappers)(fn, args, (value) => value);
+		if (!result.ok) throw new DbException(result.error);
+		return result.data;
+	} };
 }
-function backendOf(source) {
-	if (isBackend(source)) return source;
-	return isSqlClient(source) ? sqlQueueBackend(source) : pgmqPublicBackend(source);
+function backendOf(options, now) {
+	if (options.backend) return options.backend;
+	if (options.sql) return sqlQueueBackend(options.sql, now);
+	if (options.client && options.schema) return transportQueueBackend(mappedTransport(rpcTransport(options.client, { schema: options.schema }), options.mappers), {
+		now,
+		schema: options.schema
+	});
+	if (options.client) return pgmqPublicBackend(options.client);
+	if (options.transport) return transportQueueBackend(mappedTransport(options.transport, options.mappers), {
+		now,
+		...options.schema ? { schema: options.schema } : {}
+	});
+	throw new TypeError("createJobs needs a backend, sql, client or transport to store jobs");
 }
 const later = (a, b) => temporal().Instant.compare(a, b) >= 0 ? a : b;
 /**
 * Typed jobs on Supabase Queues (pgmq), over the `jobs` SQL module.
 *
 * Pass a service SQL connection (`postgres.admin`, `ctx.sql`) for the full
-* feature set, a service-role Supabase client to go through the
-* `pgmq_public` RPCs where no direct connection exists (edge functions), or
-* any `QueueBackend`. Queue names are lowercase letters, digits and
-* underscores.
+* feature set, a service-role `rpcTransport` over the wrappers
+* `blocks.jobs.api` writes for the same features over the Data API (or a
+* service-role Supabase client with `schema` set to that schema), a
+* service-role Supabase client to go through the `pgmq_public` RPCs, or any
+* `QueueBackend`. Queue names are lowercase letters, digits and underscores.
 */
-function createJobs(source, queues, options = {}) {
+function createJobs(options) {
 	applyTemporal(options);
+	const queues = options.queues ?? {};
+	const now = options.now ?? nowInstant;
 	for (const name of Object.keys(queues)) if (!QUEUE_NAME.test(name)) throw new TypeError(`Queue "${name}": pgmq queue names are lowercase letters, digits and underscores (at most 47)`);
-	const transport = backendOf(source);
+	const transport = backendOf(options, now);
 	const schemaOf = (queue) => {
 		const schema = queues[queue];
 		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
@@ -712,12 +842,20 @@ function createJobs(source, queues, options = {}) {
 	/**
 	* Extends the lease of every job in `held` at half the lease, so jobs
 	* waiting their turn in a claimed batch don't expire before they run.
+	* A job whose lease can't be extended is aborted: another worker may
+	* already hold it.
 	*/
-	const heartbeat = (held, lease) => transport.leases ? setInterval(() => {
-		for (const job of held) run(() => transport.extend(job, lease));
-	}, Math.max(1e3, lease * 1e3 / 2)) : void 0;
-	const handle = async (job, handler, workOptions) => {
-		const controller = new AbortController();
+	const heartbeat = (held, lease) => transport.leases ? leaseHeartbeat(lease, () => {
+		for (const [job, controller] of held) run(() => transport.extend(job, lease)).then((extended) => {
+			if (!extended.ok || !extended.data) controller.abort(LEASE_LOST);
+		});
+	}) : void 0;
+	const leaseLost = (job, workOptions) => {
+		workOptions.onError?.(dbError("conflict", `The lease on job ${String(job.id)} in "${job.queue}" was lost, so another worker may run it`, { code: "JOB_LEASE_LOST" }), job);
+		return false;
+	};
+	const handle = async (job, handler, workOptions, controller = new AbortController()) => {
+		if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
 		try {
 			const payload = await validate(schemaOf(job.queue), job.payload, "payload");
 			if (!payload.ok) {
@@ -732,16 +870,22 @@ function createJobs(source, queues, options = {}) {
 				context
 			}, controller.signal);
 			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
-			await complete(job);
-			return true;
+			if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
+			const completed = await complete(job);
+			if (!completed.ok) {
+				workOptions.onError?.(completed.error, job);
+				return false;
+			}
+			return completed.data || leaseLost(job, workOptions);
 		} catch (cause) {
+			if (controller.signal.reason === LEASE_LOST) return leaseLost(job, workOptions);
 			controller.abort();
 			await fail(job, cause);
 			workOptions.onError?.(typeof cause === "object" && cause !== null && "kind" in cause ? cause : toDbError(cause), job);
 			return false;
 		}
 	};
-	const loop = async (queue, handler, workOptions, forever, deadline) => {
+	const loop = async (queue, handler, workOptions, forever, spent = budget(void 0)) => {
 		const concurrency = Math.max(1, workOptions.concurrency ?? 1);
 		const lease = workOptions.lease ?? 300;
 		const firstWait = workOptions.pollInterval ?? 1e3;
@@ -754,7 +898,7 @@ function createJobs(source, queues, options = {}) {
 			let wait = firstWait;
 			let misses = 0;
 			while (!signal.aborted) {
-				if (deadline !== void 0 && Date.now() >= deadline) return;
+				if (spent.expired()) return;
 				const claimed = await claim(queue, {
 					...workOptions,
 					batch: workOptions.batch ?? 1
@@ -765,8 +909,7 @@ function createJobs(source, queues, options = {}) {
 						stop.abort();
 						throw new TypeError(claimed.error.message, { cause: claimed.error });
 					}
-					const left = deadline === void 0 ? Infinity : deadline - Date.now();
-					await sleep(Math.min(firstWait * 2 ** (misses - 1), left), signal);
+					await sleep(Math.min(firstWait * 2 ** (misses - 1), spent.remaining()), signal);
 					continue;
 				}
 				misses = 0;
@@ -777,16 +920,16 @@ function createJobs(source, queues, options = {}) {
 					continue;
 				}
 				wait = firstWait;
-				const held = new Set(claimed.data);
-				const timer = heartbeat(held, lease);
+				const held = new Map(claimed.data.map((job) => [job, new AbortController()]));
+				const stopHeartbeat = heartbeat(held, lease);
 				try {
 					for (const job of claimed.data) {
-						if (await handle(job, handler, workOptions)) succeeded += 1;
+						if (await handle(job, handler, workOptions, held.get(job))) succeeded += 1;
 						else failed += 1;
 						held.delete(job);
 					}
 				} finally {
-					clearInterval(timer);
+					stopHeartbeat?.();
 				}
 			}
 		});
@@ -803,7 +946,7 @@ function createJobs(source, queues, options = {}) {
 		let ran = 0;
 		for (const schedule of due) {
 			await transport.send(schedule.queue, schedule.payload, 0, 5, `schedule:${schedule.name}:${schedule.nextRun.toString()}`);
-			const next = millis(nextCronRun(schedule.cron, schedule.timeZone, later(nowInstant(), schedule.nextRun)));
+			const next = millis(nextCronRun(schedule.cron, schedule.timeZone, later(now(), schedule.nextRun)));
 			if (await transport.advanceSchedule(schedule.name, schedule.nextRun, next)) ran += 1;
 		}
 		return ran;
@@ -813,30 +956,77 @@ function createJobs(source, queues, options = {}) {
 		if (!valid.ok) return valid;
 		const timeZone = scheduleOptions.timeZone ?? "UTC";
 		try {
-			nextCronRun(cron, timeZone, nowInstant());
+			nextCronRun(cron, timeZone, now());
 		} catch (cause) {
 			return err(dbError("validation", errorText(cause), { issues: [{
 				message: errorText(cause),
 				path: [name, "cron"]
 			}] }));
 		}
+		const wrapped = wrapPayload(valid.data, scheduleOptions.context);
+		if (!wrapped.ok) return wrapped;
 		return ok({
 			name,
 			cron,
 			queue,
-			payload: withContext(valid.data, scheduleOptions.context),
+			payload: wrapped.data,
 			timeZone,
 			tenant: scheduleOptions.tenant ?? (scheduleOptions.context ? tenantFrom(scheduleOptions.context, tenantPathsFor(void 0)) : void 0) ?? tenantDefault
 		});
 	};
-	const write = (prepared) => transport.schedule(prepared.name, prepared.cron, prepared.queue, prepared.payload, prepared.timeZone, millis(nextCronRun(prepared.cron, prepared.timeZone, nowInstant())), prepared.tenant);
-	return {
+	const write = (prepared) => transport.schedule(prepared.name, prepared.cron, prepared.queue, prepared.payload, prepared.timeZone, millis(nextCronRun(prepared.cron, prepared.timeZone, now())), prepared.tenant);
+	const purge = (purgeOptions = {}) => run(async () => {
+		if (!transport.purge) sqlOnly("purge");
+		const backendPurge = transport.purge.bind(transport);
+		const interval = (value) => value === void 0 ? void 0 : seconds(value);
+		return (await Promise.all((purgeOptions.queues ?? Object.keys(queues)).map((queue) => {
+			schemaOf(queue);
+			return backendPurge(queue, {
+				olderThan: interval(purgeOptions.olderThan),
+				deadOlderThan: interval(purgeOptions.deadOlderThan),
+				batch: purgeOptions.batch
+			});
+		}))).reduce((sum, count) => sum + count, 0);
+	});
+	const delayOf = (enqueueOptions) => {
+		const delay = enqueueOptions.delay;
+		if (delay !== void 0 && (!Number.isInteger(delay) || delay < 0)) return err(dbError("validation", "delay is a whole number of seconds", { issues: [{
+			message: "Expected a non-negative integer",
+			path: ["delay"]
+		}] }));
+		return ok(delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - now().epochMilliseconds) / 1e3)) : 0));
+	};
+	/** The validated payload in its envelope, and the delay, for `enqueue` and `enqueueOnce`. */
+	const prepareSend = async (queue, payload, enqueueOptions) => {
+		const valid = await validate(schemaOf(queue), payload, "payload");
+		if (!valid.ok) return valid;
+		const delay = delayOf(enqueueOptions);
+		if (!delay.ok) return delay;
+		const message = wrapPayload(valid.data, enqueueOptions.context, { ...enqueueOptions.ticket === void 0 ? {} : { ticket: enqueueOptions.ticket } });
+		if (!message.ok) return message;
+		return ok({
+			message: message.data,
+			delay: delay.data
+		});
+	};
+	return withBlockHooks({
 		enqueue(queue, payload, enqueueOptions = {}) {
 			return AsyncResult.from(async () => {
-				const valid = await validate(schemaOf(queue), payload, "payload");
-				if (!valid.ok) return valid;
-				const delay = enqueueOptions.delay ?? (enqueueOptions.runAt ? Math.max(0, Math.ceil((enqueueOptions.runAt.epochMilliseconds - nowInstant().epochMilliseconds) / 1e3)) : 0);
-				return run(() => transport.send(queue, withContext(valid.data, enqueueOptions.context), delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey, enqueueOptions.dedupe));
+				const prepared = await prepareSend(queue, payload, enqueueOptions);
+				if (!prepared.ok) return prepared;
+				const { message, delay } = prepared.data;
+				return run(() => transport.send(queue, message, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey, enqueueOptions.dedupe));
+			});
+		},
+		enqueueOnce(queue, payload, enqueueOptions) {
+			return AsyncResult.from(async () => {
+				const prepared = await prepareSend(queue, payload, enqueueOptions);
+				if (!prepared.ok) return prepared;
+				const { message, delay } = prepared.data;
+				return run(() => {
+					if (!transport.sendOnce) sqlOnly("enqueueOnce");
+					return transport.sendOnce(queue, message, delay, enqueueOptions.maxAttempts ?? 5, enqueueOptions.dedupeKey);
+				});
 			});
 		},
 		claim,
@@ -876,6 +1066,8 @@ function createJobs(source, queues, options = {}) {
 			schemaOf(queue);
 			return transport.retryDead(queue, retryOptions.ids, retryOptions.limit ?? 1e3);
 		}),
+		purge,
+		purgeJob: (purgeOptions) => async () => purge(purgeOptions).orThrow(),
 		replay: (queue, id) => run(() => {
 			if (!transport.replay) sqlOnly("replay");
 			return transport.replay(queue, id);
@@ -929,23 +1121,16 @@ function createJobs(source, queues, options = {}) {
 			return transport.unscheduleTenant(filter.tenant);
 		}),
 		runSchedules: (scheduleOptions = {}) => run(() => runSchedules(scheduleOptions)),
-		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false, drainOptions.budgetMs === void 0 ? void 0 : Date.now() + drainOptions.budgetMs),
+		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false, budget(drainOptions.budgetMs)),
 		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true),
 		drainRoute(routeOptions) {
-			const secret = routeOptions.secret;
-			if (!secret) throw new TypeError("drainRoute needs a secret, such as process.env.CRON_SECRET");
 			for (const queue of Object.keys(routeOptions.handlers)) schemaOf(queue);
-			return async (request) => {
-				const instance = new URL(request.url).pathname;
-				if (request.method !== "GET" && request.method !== "POST") return new Response(null, {
-					status: 405,
-					headers: { allow: "GET, POST" }
-				});
-				if (!verifySharedSecret(request, secret)) return problemResponse(dbError("unauthorized", "The drain route needs its bearer secret"), {
-					instance,
-					format: routeOptions.problem
-				});
-				const deadline = Date.now() + (routeOptions.budgetMs ?? 5e4);
+			return cronRoute({
+				name: "drain",
+				secret: routeOptions.secret,
+				problem: routeOptions.problem
+			}, async (request) => {
+				const spent = budget(routeOptions.budgetMs ?? 5e4);
 				const monitor = routeOptions.monitor;
 				let errors = 0;
 				const report = (cause) => {
@@ -973,9 +1158,9 @@ function createJobs(source, queues, options = {}) {
 				const results = {};
 				for (const [queue, handler] of Object.entries(routeOptions.handlers)) {
 					if (handler === void 0) continue;
-					if (Date.now() >= deadline) break;
+					if (spent.expired()) break;
 					try {
-						results[queue] = await loop(queue, handler, routeOptions, false, deadline);
+						results[queue] = await loop(queue, handler, routeOptions, false, spent);
 					} catch (cause) {
 						report(cause);
 						results[queue] = {
@@ -987,65 +1172,51 @@ function createJobs(source, queues, options = {}) {
 				const result = {
 					schedules: scheduled,
 					queues: results,
-					budgetExhausted: Date.now() >= deadline,
+					budgetExhausted: spent.expired(),
 					errors
 				};
 				if (monitor?.onFinish) await watch(() => monitor.onFinish?.(result, started));
 				return Response.json(result);
-			};
+			});
 		}
-	};
+	}, options.hooks, {
+		block: "jobs",
+		...options.logger ? { logger: options.logger } : {}
+	});
 }
 //#endregion
-//#region src/blocks/jobs/rate-limit.ts
-const isTransport = (source) => "call" in source;
-/**
-* Fixed-window limits for keys that aren't claims, over the `rate-limit`
-* module's counters. Pass a service SQL connection (`ctx.postgresAdmin`,
-* `postgres.admin`), or a service-role `BlockTransport` such as
-* `rpcTransport(adminClient)`.
-*/
-function createRateLimit(source, options = {}) {
-	applyTemporal(options);
-	const hit = isTransport(source) ? overTransport(blockCall(source, void 0, options.mappers)) : overSql(source);
-	return { check: (scope, key, rule) => {
-		if (rule !== void 0 && (!Number.isInteger(rule.max) || rule.max < 1)) return AsyncResult.err(dbError("invalid_input", "A rate limit's max must be a positive integer"));
-		return hit(scope, key, rule?.max ?? null, rule === void 0 ? null : seconds(rule.period));
-	} };
-}
-const overTransport = (call) => (scope, key, max, period) => call("check_rate_limit", {
-	scope,
-	key,
-	max_requests: max ?? void 0,
-	period: period ?? void 0
-}, (value) => {
-	const row = isRecord(value) ? value : {};
-	return {
-		allowed: row["allowed"] === true,
-		remaining: Number(row["remaining"] ?? 0),
-		retryAfter: Number(row["retry_after"] ?? 0)
-	};
+//#region src/blocks/jobs/manifest.ts
+/** The `jobs` block's manifest (ADR 0029). */
+const jobsBlock = defineBlock({
+	name: "jobs",
+	sql: ["jobs"],
+	options: { jobs: jobsSqlOptions },
+	create: createJobs,
+	category: "automation",
+	recipes: ["job-runs-table"]
 });
-const overSql = (sql) => (scope, key, max, period) => run(async () => {
-	const [row] = await sql.queryRaw("select * from better_supabase.hit_rate_limit($1, $2, $3, $4::interval)", [
-		scope,
-		key,
-		max,
-		period
-	]);
-	return {
-		allowed: row?.allowed ?? false,
-		remaining: row?.remaining ?? 0,
-		retryAfter: row?.retry_after ?? 0
-	};
+/** The `idempotency` block's manifest (ADR 0029). */
+const idempotencyBlock = defineBlock({
+	name: "idempotency",
+	sql: ["idempotency"],
+	create: createIdempotency,
+	category: "developer"
+});
+/** The `rate-limit` block's manifest (ADR 0029). */
+const rateLimitBlock = defineBlock({
+	name: "rate-limit",
+	sql: ["rate-limit"],
+	options: { "rate-limit": rateLimitSqlOptions },
+	create: createRateLimit,
+	category: "developer"
+});
+/** The `webhook-inbox` block's manifest (ADR 0029). */
+const webhookInboxBlock = defineBlock({
+	name: "webhook-inbox",
+	sql: ["webhook-inbox"],
+	options: { "webhook-inbox": webhookInboxSqlOptions },
+	create: createWebhookInbox,
+	category: "developer"
 });
-/** A `problem+json` 429 with `Retry-After`, for a refused `check`. */
-function rateLimited(decision, options = {}) {
-	const retryAfter = Math.max(1, Math.ceil(decision.retryAfter));
-	return problemResponse(dbError("rate_limited", options.detail ?? `Too many requests. Retry after ${retryAfter} seconds.`, { retryAfter }), {
-		...options.instance === void 0 ? {} : { instance: options.instance },
-		format: options.problem
-	});
-}
 //#endregion
-export { assertCron, createIdempotency, createJobs, createRateLimit, createWebhookInbox, devDrain, devDrainSecret, nextCronRun, pgmqPublicBackend, rateLimited, sqlQueueBackend, withLease };
+export { assertCron, createIdempotency, createJobs, createRateLimit, createWebhookInbox, dbTransport, devDrain, devDrainSecret, idempotencyBlock, jobsBlock, nextCronRun, pgmqPublicBackend, purgeWebhookInbox, rateLimitBlock, rateLimited, rpcTransport, sqlQueueBackend, sqlTransport, transportQueueBackend, webhookInboxBlock, withLease };