better-supabase 0.13.0 → 0.15.0

package/dist/blocks/queue/index.js

@@ -0,0 +1,1407 @@
+import { t as DbException } from "../../db-exception-Lngc1W49.js";
+import { n as dbError } from "../../errors-BVFgt8BZ.js";
+import { n as isRecord$1 } from "../../guards-6F2bCtQR.js";
+import { s as nowInstant } from "../../temporal-DLZlWbOi.js";
+import { t as temporal } from "../../temporal-required-Dy0GGD8E.js";
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "../../result-ntFBW2p2.js";
+import { n as allTenantsContext } from "../../plugin-AKwwe2gF.js";
+import { n as validate } from "../../standard-BA3mLh6w.js";
+import { o as problemResponse } from "../../problem-Bf0cJ7tk.js";
+import { o as tenantFrom, s as tenantPathsFor } from "../../claims-Bp9My7XP.js";
+import { n as rateLimitSqlOptions, r as webhookInboxSqlOptions, t as queueSqlOptions } from "../../options-HLwOuF2H.js";
+import { B as dbTransport, H as rpcTransport, M as seconds, P as sleep, R as toInstant, U as sqlTransport, f as errorText, g as leaseHeartbeat, j as run, n as applyTemporal, o as blockCall, s as budget, w as pageOf } from "../../block-helpers-CtBdjgO4.js";
+import { r as withBlockHooks } from "../../block-hooks-BfxX3682.js";
+import { t as cronRoute } from "../../cron-route-UU9i5i9J.js";
+import { n as periodSeconds } from "../../ratelimit-headers-kEcXyO3H.js";
+import { n as nextCronRun, t as assertCron } from "../../cron-CgHTKwYG.js";
+import { a as purgeWebhookInbox, i as createWebhookInbox, r as rateLimited, t as createRateLimit } from "../../rate-limit-o44SYkVY.js";
+import { r as wrapPayload, t as unwrap } from "../../envelope-Bzu0JnY2.js";
+import { n as defineBlock } from "../../define-block-BGqOO8B3.js";
+import { n as DATABASE_URL_ENV, t as CRON_SECRET_ENV } from "../../wiring-CDNuQoJJ.js";
+//#region src/blocks/queue/block-schedules.ts
+/** The queue every block timer enqueues on. */
+const BLOCK_TICKS_QUEUE = "block_ticks";
+/** The schedule name prefix of the block timers, for `ensureSchedules`. */
+const BLOCK_SCHEDULE_PREFIX = "block:";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `block_ticks` queue's payload schema, for `createQueue({ queues })`. */
+const blockTickSchema = { "~standard": {
+	version: 1,
+	vendor: "better-supabase",
+	validate: (value) => isRecord(value) && typeof value["block"] === "string" && typeof value["name"] === "string" ? { value: {
+		block: value["block"],
+		name: value["name"]
+	} } : { issues: [{ message: "A block tick is { block: string, name: string }" }] }
+} };
+/**
+* The timers the installed blocks declare, as queue schedules named
+* `block:<block>.<name>`: pass them to
+* `jobs.ensureSchedules(blockSchedules(blocks), { prefix: BLOCK_SCHEDULE_PREFIX
+* })` on deploy, so SLA deadlines, sequence waits, AI schedules and workflow
+* schedules all run from the one scheduler.
+*/
+function blockSchedules(blocks) {
+	return blocks.flatMap((block) => (block.schedules ?? []).map((schedule) => ({
+		name: `${BLOCK_SCHEDULE_PREFIX}${block.name}.${schedule.name}`,
+		cron: schedule.cron,
+		queue: BLOCK_TICKS_QUEUE,
+		payload: {
+			block: block.name,
+			name: schedule.name
+		}
+	})));
+}
+/**
+* The `block_ticks` queue handler: runs the handler named `<block>.<name>`,
+* such as `"sla.check": () => sla.check()`. A tick without a handler, or a
+* failed run, throws so the queue retries it and the dead letter shows it.
+*/
+function blockTickHandler(handlers) {
+	return async (payload) => {
+		const key = `${payload.block}.${payload.name}`;
+		const run = handlers[key];
+		if (run === void 0) throw new Error(`No handler for the block timer ${key}. Handlers: ${Object.keys(handlers).join(", ") || "none"}`);
+		const outcome = await run();
+		if (!outcome.ok) throw new Error(`${key}: ${outcome.error.message}`);
+	};
+}
+//#endregion
+//#region src/blocks/queue/dev.ts
+function devDrainSecret(env, name = "CRON_SECRET") {
+	const current = env[name];
+	if (current) return current;
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32));
+	const secret = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	env[name] = secret;
+	return secret;
+}
+function devDrain(options) {
+	if (!options.secret) throw new TypeError("devDrain needs the drain route's secret, such as devDrainSecret(process.env)");
+	const every = options.every ?? 6e4;
+	if (!Number.isFinite(every) || every <= 0) throw new TypeError("devDrain: every must be a positive number of ms");
+	const doFetch = options.fetch ?? fetch;
+	const report = options.onError ?? ((message) => {
+		console.warn(message);
+	});
+	let running = false;
+	const tick = async () => {
+		if (running || options.signal?.aborted) return;
+		running = true;
+		try {
+			const response = await doFetch(options.url, { headers: { authorization: `Bearer ${options.secret}` } });
+			await response.body?.cancel();
+			if (!response.ok) report(`[jobs] dev drain answered ${String(response.status)}`);
+		} catch (cause) {
+			report(`[jobs] dev drain failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+		} finally {
+			running = false;
+		}
+	};
+	const timer = setInterval(() => {
+		tick();
+	}, every);
+	const stop = () => {
+		clearInterval(timer);
+	};
+	options.signal?.addEventListener("abort", stop, { once: true });
+	return {
+		tick,
+		stop
+	};
+}
+//#endregion
+//#region src/blocks/queue/backends.ts
+const instantOrNull = (value) => value === null ? null : toInstant(value);
+/**
+* Schedule times are stored to the millisecond, the precision `Date` reads
+* back.
+*/
+const millis = (instant) => instant.round({
+	smallestUnit: "millisecond",
+	roundingMode: "floor"
+});
+/**
+* The first run of a schedule written without one, or undefined for a cron the
+* drain can't read.
+*/
+function firstRun(row, now) {
+	try {
+		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 `blocks.queue.options.backend` values (pgmq and table) and both
+* schedulers. `now` dates a schedule's first run.
+*/
+function sqlQueueProvider(sql, now = nowInstant) {
+	return {
+		apiVersion: 1,
+		name: "sql",
+		leases: true,
+		async send(queue, payload, delay, maxAttempts, dedupeKey, dedupe) {
+			const [row] = await sql.queryRaw("select better_supabase.enqueue_job($1, $2, $3, $4, $5, $6) as id", [
+				queue,
+				JSON.stringify(payload ?? {}),
+				delay,
+				maxAttempts,
+				dedupeKey ?? null,
+				dedupe !== "waiting"
+			]);
+			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,
+			batch
+		]),
+		async complete(job) {
+			const [row] = await sql.queryRaw("select better_supabase.complete_job($1, $2, $3) as done", [
+				job.queue,
+				job.id,
+				job.attempts
+			]);
+			return row?.done ?? false;
+		},
+		async fail(job, error, retryIn) {
+			const [row] = await sql.queryRaw("select better_supabase.fail_job($1, $2, $3, $4, $5) as status", [
+				job.queue,
+				job.id,
+				job.attempts,
+				error,
+				retryIn ?? null
+			]);
+			return row?.status ?? null;
+		},
+		async extend(job, lease) {
+			const [row] = await sql.queryRaw("select better_supabase.extend_job_lease($1, $2, $3, $4) as extended", [
+				job.queue,
+				job.id,
+				job.attempts,
+				lease
+			]);
+			return row?.extended ?? false;
+		},
+		async replay(queue, id) {
+			const [row] = await sql.queryRaw("select better_supabase.replay_dead_job($1, $2) as id", [queue, id]);
+			return row?.id === null || row?.id === void 0 ? null : Number(row.id);
+		},
+		async stats(queue) {
+			const [row] = await sql.queryRaw("select * from better_supabase.job_queue_stats($1)", [queue]);
+			return statsOf(row);
+		},
+		listDead: (queue, limit, before) => sql.queryRaw("select * from better_supabase.list_dead_jobs($1, $2, $3)", [
+			queue,
+			limit,
+			before ?? null
+		]),
+		async retryDead(queue, ids, limit) {
+			const [row] = await sql.queryRaw("select better_supabase.retry_dead_jobs($1, $2, $3) as retried", [
+				queue,
+				ids === void 0 ? null : [...ids],
+				limit
+			]);
+			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,
+				cron,
+				queue,
+				JSON.stringify(payload ?? {}),
+				timeZone,
+				nextRun.toString(),
+				tenant ?? null
+			]);
+		},
+		async listSchedules(filter) {
+			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]);
+			return row?.removed ?? 0;
+		},
+		async unschedule(name) {
+			const [row] = await sql.queryRaw("select better_supabase.unschedule_job($1) as done", [name]);
+			return row?.done ?? false;
+		},
+		async dueSchedules(lease, batch) {
+			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", [
+				name,
+				ran.toString(),
+				next.toString()
+			]);
+			return row?.advanced ?? false;
+		}
+	};
+}
+/** 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$1(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.queue.api` writes, so stats, dead letters, replays and schedules work
+* without a direct Postgres connection. Over Postgres, pass the `SqlClient` to
+* `createQueue` instead.
+*/
+function transportQueueProvider(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`));
+}
+/**
+* Supabase's `pgmq_public` RPCs (Integrations, Queues, "Expose Queues via
+* PostgREST"). No lease check on complete, no retry delay, no deduplication and
+* no schedules: a failed job reappears when its lease ends.
+*/
+function pgmqPublicBackend(client) {
+	const untyped = client;
+	const call = async (fn, args) => {
+		const { data, error } = await untyped.schema("pgmq_public").rpc(fn, args);
+		if (error) {
+			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
+			throw new Error(`pgmq_public.${fn}: ${message}`, { cause: error });
+		}
+		return data;
+	};
+	const archive = (job) => call("archive", {
+		queue_name: job.queue,
+		message_id: job.id
+	});
+	return {
+		apiVersion: 1,
+		name: "pgmq_public",
+		leases: false,
+		async send(queue, payload, delay, maxAttempts, dedupeKey) {
+			if (dedupeKey !== void 0) sqlOnly("dedupeKey");
+			const ids = await call("send", {
+				queue_name: queue,
+				message: {
+					payload: payload ?? {},
+					max_attempts: maxAttempts
+				},
+				sleep_seconds: delay
+			});
+			return Number(ids[0]);
+		},
+		async read(queue, lease, batch) {
+			const rows = await call("read", {
+				queue_name: queue,
+				sleep_seconds: lease,
+				n: batch
+			});
+			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
+			})));
+			return live.map((row) => ({
+				id: row.msg_id,
+				attempts: row.read_ct,
+				enqueued_at: row.enqueued_at,
+				visible_until: row.vt,
+				message: row.message
+			}));
+		},
+		complete: archive,
+		async fail(job) {
+			if (job.attempts < job.maxAttempts) return "queued";
+			await archive(job);
+			return "dead";
+		},
+		extend: () => Promise.resolve(false),
+		schedule: () => sqlOnly("schedule"),
+		unschedule: () => sqlOnly("unschedule")
+	};
+}
+//#endregion
+//#region src/blocks/queue/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] ?? "")).toSorted();
+	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/queue/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/queue/vercel-queue.ts
+const TOPIC = /^[A-Za-z0-9_-]+$/;
+/**
+* Stores jobs on Vercel Queues through a `PollingQueueClient`. Queue names are
+* topic names. `read` holds each message open inside the client's `receive`
+* handler (the client keeps the visibility timeout alive), `complete`
+* acknowledges it and `fail` throws so the topic redelivers it after the retry
+* delay. Vercel Queues has no dead letters, schedules or ids that fit a number,
+* so ids are local handles, a message past `maxAttempts` is acknowledged and
+* dropped, and schedules need the SQL backend.
+*/
+function vercelQueueProvider(client, options = {}) {
+	const group = options.consumerGroup ?? "better-supabase";
+	const retryAfter = options.retryAfter ?? 30;
+	const settle = options.settle ?? 25;
+	const held = /* @__PURE__ */ new Map();
+	const delays = /* @__PURE__ */ new Map();
+	const handles = /* @__PURE__ */ new Map();
+	let next = 0;
+	const handleOf = (messageId) => {
+		const known = messageId === null ? void 0 : handles.get(messageId);
+		if (known !== void 0) return known;
+		next += 1;
+		if (messageId !== null) handles.set(messageId, next);
+		return next;
+	};
+	const topicOf = (queue) => {
+		if (!TOPIC.test(queue)) throw new TypeError(`Vercel Queues topic names match ${TOPIC.source}, got "${queue}"`);
+		return queue;
+	};
+	const key = (job) => `${job.queue}:${job.id}`;
+	return {
+		apiVersion: 1,
+		name: "vercel-queues",
+		leases: false,
+		async send(queue, payload, delay, maxAttempts, dedupeKey) {
+			const sent = await client.send(topicOf(queue), {
+				payload: payload ?? {},
+				max_attempts: maxAttempts
+			}, {
+				delaySeconds: delay,
+				...dedupeKey === void 0 ? {} : { idempotencyKey: dedupeKey }
+			});
+			return handleOf(sent.messageId);
+		},
+		read(queue, lease, batch) {
+			const rows = [];
+			return new Promise((resolve, reject) => {
+				let timer;
+				const finish = () => {
+					resolve([...rows]);
+				};
+				const handler = (message, metadata) => {
+					const id = handleOf(metadata.messageId);
+					rows.push({
+						id,
+						attempts: metadata.deliveryCount,
+						enqueued_at: metadata.createdAt,
+						visible_until: new Date(Date.now() + lease * 1e3),
+						message
+					});
+					return new Promise((done, failed) => {
+						held.set(`${queue}:${id}`, {
+							metadata,
+							done: () => {
+								done();
+							},
+							fail: (error) => {
+								failed(error);
+							}
+						});
+						timer ??= setTimeout(finish, settle);
+					});
+				};
+				client.receive(topicOf(queue), group, handler, {
+					limit: Math.min(Math.max(batch, 1), 10),
+					visibilityTimeoutSeconds: Math.min(Math.max(lease, 30), 3600),
+					retry: (_error, metadata) => {
+						const afterSeconds = delays.get(metadata.messageId) ?? retryAfter;
+						delays.delete(metadata.messageId);
+						return { afterSeconds };
+					}
+				}).then(() => {
+					if (timer !== void 0) clearTimeout(timer);
+					finish();
+				}, reject);
+			});
+		},
+		complete(job) {
+			const entry = held.get(key(job));
+			if (!entry) return Promise.resolve(false);
+			held.delete(key(job));
+			entry.done();
+			return Promise.resolve(true);
+		},
+		fail(job, error, retryIn) {
+			const entry = held.get(key(job));
+			if (!entry) return Promise.resolve(null);
+			held.delete(key(job));
+			if (job.attempts >= job.maxAttempts) {
+				entry.done();
+				return Promise.resolve("dead");
+			}
+			if (retryIn !== void 0) delays.set(entry.metadata.messageId, retryIn);
+			entry.fail(new Error(error));
+			return Promise.resolve("queued");
+		},
+		extend: () => Promise.resolve(false),
+		schedule: () => sqlOnly("schedule"),
+		unschedule: () => sqlOnly("unschedule")
+	};
+}
+//#endregion
+//#region src/blocks/queue/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",
+	"serialization",
+	"rate_limited"
+]);
+function toJob(queue, row) {
+	const message = row.message ?? {};
+	const { payload, context } = unwrap(message.payload);
+	return {
+		id: Number(row.id),
+		queue,
+		payload,
+		context,
+		attempts: row.attempts,
+		maxAttempts: message.max_attempts ?? 5,
+		enqueuedAt: toInstant(row.enqueued_at),
+		visibleUntil: toInstant(row.visible_until),
+		lastError: message.last_error ?? null
+	};
+}
+const QUEUE_NAME = /^[a-z_][a-z0-9_]{0,46}$/;
+/**
+* `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(options, now) {
+	if (options.backend) return options.backend;
+	if (options.sql) return sqlQueueProvider(options.sql, now);
+	if (options.client && options.schema) return transportQueueProvider(mappedTransport(rpcTransport(options.client, { schema: options.schema }), options.mappers), {
+		now,
+		schema: options.schema
+	});
+	if (options.client) return pgmqPublicBackend(options.client);
+	if (options.transport) return transportQueueProvider(mappedTransport(options.transport, options.mappers), {
+		now,
+		...options.schema ? { schema: options.schema } : {}
+	});
+	throw new TypeError("createQueue 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 `rpcTransport` over the wrappers
+* `blocks.queue.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
+* `QueueProvider`. Queue names are lowercase letters, digits and underscores.
+*/
+function createQueue(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(options, now);
+	const schemaOf = (queue) => {
+		const schema = queues[queue];
+		if (!schema) throw new TypeError(`Unknown queue "${queue}". Queues: ${Object.keys(queues).join(", ")}`);
+		return schema;
+	};
+	const complete = (job) => run(() => transport.complete(job));
+	const fail = (job, error, failOptions = {}) => run(() => transport.fail(job, errorText(error), failOptions.retryIn));
+	const claim = (queue, claimOptions = {}) => run(async () => {
+		schemaOf(queue);
+		return (await transport.read(queue, claimOptions.lease ?? 300, claimOptions.batch ?? 1)).map((row) => toJob(queue, row));
+	});
+	/**
+	* 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 ? 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) {
+				await fail(job, payload.error.message);
+				workOptions.onError?.(payload.error, job);
+				return false;
+			}
+			const context = workOptions.allTenants && job.context.tenant === void 0 ? allTenantsContext(job.context) : job.context;
+			const outcome = await handler(payload.data, {
+				...job,
+				payload: payload.data,
+				context
+			}, controller.signal);
+			if (typeof outcome === "object" && outcome !== null && "ok" in outcome && outcome.ok === false && "error" in outcome) throw outcome.error;
+			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, spent = budget(void 0)) => {
+		const concurrency = Math.max(1, workOptions.concurrency ?? 1);
+		const lease = workOptions.lease ?? 300;
+		const firstWait = workOptions.pollInterval ?? 1e3;
+		const maxWait = Math.max(firstWait, workOptions.maxPollInterval ?? 3e4);
+		let succeeded = 0;
+		let failed = 0;
+		const stop = new AbortController();
+		const signal = workOptions.signal ? AbortSignal.any([workOptions.signal, stop.signal]) : stop.signal;
+		const lanes = Array.from({ length: concurrency }, async () => {
+			let wait = firstWait;
+			let misses = 0;
+			while (!signal.aborted) {
+				if (spent.expired()) return;
+				const claimed = await claim(queue, {
+					...workOptions,
+					batch: workOptions.batch ?? 1
+				});
+				if (!claimed.ok) {
+					misses += 1;
+					if (misses > CLAIM_RETRIES || !TRANSIENT.has(claimed.error.kind)) {
+						stop.abort();
+						throw new TypeError(claimed.error.message, { cause: claimed.error });
+					}
+					await sleep(Math.min(firstWait * 2 ** (misses - 1), spent.remaining()), signal);
+					continue;
+				}
+				misses = 0;
+				if (claimed.data.length === 0) {
+					if (!forever) return;
+					await sleep(wait, signal);
+					wait = Math.min(maxWait, wait * 2);
+					continue;
+				}
+				wait = firstWait;
+				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, held.get(job))) succeeded += 1;
+						else failed += 1;
+						held.delete(job);
+					}
+				} finally {
+					stopHeartbeat?.();
+				}
+			}
+		});
+		const settled = await Promise.allSettled(lanes);
+		for (const lane of settled) if (lane.status === "rejected") throw lane.reason;
+		return {
+			succeeded,
+			failed
+		};
+	};
+	const runSchedules = async (scheduleOptions) => {
+		if (!transport.dueSchedules || !transport.advanceSchedule) return 0;
+		const due = await transport.dueSchedules(scheduleOptions.lease ?? 60, scheduleOptions.batch ?? 100);
+		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(now(), schedule.nextRun)));
+			if (await transport.advanceSchedule(schedule.name, schedule.nextRun, next)) ran += 1;
+		}
+		return ran;
+	};
+	const prepare = async (name, cron, queue, payload, scheduleOptions, tenantDefault) => {
+		const valid = await validate(schemaOf(queue), payload, "payload");
+		if (!valid.ok) return valid;
+		const timeZone = scheduleOptions.timeZone ?? "UTC";
+		try {
+			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: 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, 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 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,
+		complete,
+		fail,
+		extend: (job, lease) => run(() => transport.extend(job, lease)),
+		stats: (names) => run(async () => {
+			const stats = (queue) => transport.stats?.(queue) ?? sqlOnly("stats");
+			const list = names ?? Object.keys(queues);
+			const entries = await Promise.all(list.map(async (queue) => {
+				schemaOf(queue);
+				return [queue, await stats(queue)];
+			}));
+			return Object.fromEntries(entries);
+		}),
+		listDead: (queue, listOptions = {}) => run(async () => {
+			if (!transport.listDead) sqlOnly("listDead");
+			schemaOf(queue);
+			return (await transport.listDead(queue, listOptions.limit ?? 100, pageOf(listOptions).cursor)).map((row) => {
+				const message = row.message ?? {};
+				const { payload, context } = unwrap(message.payload);
+				return {
+					id: Number(row.id),
+					queue,
+					payload,
+					context,
+					attempts: row.attempts,
+					maxAttempts: message.max_attempts ?? 5,
+					lastError: message.last_error ?? null,
+					enqueuedAt: toInstant(row.enqueued_at),
+					diedAt: row.died_at === null ? null : toInstant(row.died_at)
+				};
+			});
+		}),
+		retryDead: (queue, retryOptions = {}) => run(async () => {
+			if (!transport.retryDead) sqlOnly("retryDead");
+			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);
+		}),
+		schedule(name, cron, queue, payload, scheduleOptions = {}) {
+			return AsyncResult.from(async () => {
+				const prepared = await prepare(name, cron, queue, payload, scheduleOptions);
+				if (!prepared.ok) return prepared;
+				return run(() => write(prepared.data));
+			});
+		},
+		unschedule: (name) => run(() => transport.unschedule(name)),
+		ensureSchedules(definitions, ensureOptions) {
+			return AsyncResult.from(async () => {
+				const { prefix, tenant } = ensureOptions;
+				if (prefix.length === 0) return err(dbError("invalid_request", "ensureSchedules needs a non-empty prefix"));
+				const names = /* @__PURE__ */ new Set();
+				const prepared = [];
+				for (const definition of definitions) {
+					if (!definition.name.startsWith(prefix) || names.has(definition.name)) return err(dbError("invalid_request", names.has(definition.name) ? `Schedule "${definition.name}" is defined twice` : `Schedule "${definition.name}" does not start with "${prefix}"`));
+					names.add(definition.name);
+					const ready = await prepare(definition.name, definition.cron, definition.queue, definition.payload, definition, tenant);
+					if (!ready.ok) return ready;
+					prepared.push(ready.data);
+				}
+				return run(async () => {
+					if (!transport.listSchedules) sqlOnly("ensureSchedules");
+					const existing = await transport.listSchedules({
+						prefix,
+						...tenant === void 0 ? {} : { tenant }
+					});
+					for (const schedule of prepared) await write(schedule);
+					const removed = [];
+					for (const schedule of existing) {
+						if (names.has(schedule.name)) continue;
+						if (await transport.unschedule(schedule.name)) removed.push(schedule.name);
+					}
+					return {
+						scheduled: [...names],
+						removed
+					};
+				});
+			});
+		},
+		listSchedules: (filter = {}) => run(async () => {
+			if (!transport.listSchedules) sqlOnly("listSchedules");
+			return [...await transport.listSchedules(filter)];
+		}),
+		unscheduleAll: (filter) => run(() => {
+			if (!transport.unscheduleTenant) sqlOnly("unscheduleAll");
+			return transport.unscheduleTenant(filter.tenant);
+		}),
+		runSchedules: (scheduleOptions = {}) => run(() => runSchedules(scheduleOptions)),
+		drain: (queue, handler, drainOptions = {}) => loop(queue, handler, drainOptions, false, budget(drainOptions.budgetMs)),
+		work: (queue, handler, workOptions = {}) => loop(queue, handler, workOptions, true),
+		drainRoute(routeOptions) {
+			for (const queue of Object.keys(routeOptions.handlers)) schemaOf(queue);
+			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) => {
+					errors += 1;
+					routeOptions.onError?.(toDbError(cause));
+				};
+				const watch = async (fn) => {
+					try {
+						return await fn();
+					} catch (cause) {
+						routeOptions.onError?.(toDbError(cause));
+						return;
+					}
+				};
+				const started = monitor?.onStart ? await watch(() => monitor.onStart?.(request)) : void 0;
+				let scheduled = 0;
+				if (routeOptions.schedules ?? true) {
+					const ran = await run(() => runSchedules({}));
+					if (ran.ok) scheduled = ran.data;
+					else {
+						errors += 1;
+						routeOptions.onError?.(ran.error);
+					}
+				}
+				const results = {};
+				for (const [queue, handler] of Object.entries(routeOptions.handlers)) {
+					if (handler === void 0) continue;
+					if (spent.expired()) break;
+					try {
+						results[queue] = await loop(queue, handler, routeOptions, false, spent);
+					} catch (cause) {
+						report(cause);
+						results[queue] = {
+							succeeded: 0,
+							failed: 0
+						};
+					}
+				}
+				const result = {
+					schedules: scheduled,
+					queues: results,
+					budgetExhausted: spent.expired(),
+					errors
+				};
+				if (monitor?.onFinish) await watch(() => monitor.onFinish?.(result, started));
+				return Response.json(result);
+			});
+		}
+	}, options.hooks, {
+		block: "queue",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/queue/manifest.ts
+/** The `jobs` block's manifest (ADR 0029). */
+const queueBlock = defineBlock({
+	name: "queue",
+	sql: ["queue"],
+	options: { queue: queueSqlOptions },
+	create: createQueue,
+	category: "automation",
+	env: [CRON_SECRET_ENV, {
+		...DATABASE_URL_ENV,
+		required: false
+	}],
+	routes: ["jobs-drain"],
+	workers: [{
+		name: "queue-drain",
+		description: "Enqueues due schedules and block timers, then runs the queued jobs.",
+		path: "/api/jobs/drain",
+		schedule: "* * * * *"
+	}],
+	recipes: ["job-runs-table"]
+});
+/** 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"
+});
+//#endregion
+export { BLOCK_SCHEDULE_PREFIX, BLOCK_TICKS_QUEUE, assertCron, blockSchedules, blockTickHandler, blockTickSchema, createIdempotency, createQueue, createRateLimit, createWebhookInbox, dbTransport, devDrain, devDrainSecret, idempotencyBlock, nextCronRun, pgmqPublicBackend, purgeWebhookInbox, queueBlock, rateLimitBlock, rateLimited, rpcTransport, sqlQueueProvider, sqlTransport, transportQueueProvider, vercelQueueProvider, webhookInboxBlock, withLease };