@makerkit/workers-outbox 0.0.0-stage → 0.0.1

package/dist/create-outbox-BTMmdvLs.mjs

@@ -0,0 +1,1758 @@
+import { A as isUuid, C as readAttemptOutcome, D as rescheduleNow, E as replayJobs, O as setSettlementTimeouts, T as replayJob, _ as hasDueJobs, b as listDueJobIds, c as cancelJobs, d as countBacklog, k as settleJob, l as claimByIds, m as deleteTenantJobs, p as deleteFinishedJobs, r as evaluateBacklog, s as cancelJob, u as claimDue, v as insertJob, w as recordNudgeResult, x as listExpiredLeases, y as isLeaseHeld } from "./backlog-Bd62tjCT.mjs";
+import { v7 } from "uuid";
+// src/core/error-message.ts
+/** An error's message, or a non-error's string form. */
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+// src/core/outcome.ts
+/** `commit` runs in the settle transaction: its writes and `succeeded` land together, lease-fenced. */
+const ok = (options = {}) => options.commit ? {
+	type: "ok",
+	commit: options.commit
+} : { type: "ok" };
+/** `after` overrides the backoff (e.g. a provider's Retry-After). */
+const retry = (input) => {
+	const outcome = {
+		type: "retry",
+		code: input.code
+	};
+	if (input.after !== void 0) outcome.afterMs = input.after;
+	if (input.message !== void 0) outcome.message = input.message;
+	return outcome;
+};
+const fail = (input) => input.message === void 0 ? {
+	type: "fail",
+	code: input.code
+} : {
+	type: "fail",
+	code: input.code,
+	message: input.message
+};
+const cancel = (input) => ({
+	type: "cancel",
+	reason: input.reason
+});
+const TIMEOUT_CODE = "timeout";
+const LEASE_EXPIRED_CODE = "lease_expired";
+const HOOK_FAILED_CODE = "hook_failed";
+/** The claim's reply arrived too late to run the handler safely; it never started. */
+const CLAIM_LATE_CODE = "claim_late";
+/** Retried soon: lateness is the infrastructure's, not the job's. */
+const CLAIM_LATE_DELAY_MS = 5e3;
+// src/core/retry-policy.ts
+const DEFAULT_RETRY_POLICY = {
+	maxAttempts: 20,
+	backoff: {
+		baseMs: 3e4,
+		maxMs: 36e5,
+		factor: 2
+	},
+	perCode: {
+		timeout: 5,
+		invalid_payload: 3
+	},
+	maxCrashes: 5,
+	codes: {}
+};
+const RESERVED_CRASH_CODE = "lease_expired";
+/** Queues can't delay past a day. */
+const MAX_RETRY_AFTER_MS = 864e5;
+function resolveRetryPolicy(input = {}) {
+	const { perCode, codes } = splitPerCode(input.perCode ?? {});
+	const policy = {
+		maxAttempts: input.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+		backoff: {
+			baseMs: input.backoff?.baseMs ?? DEFAULT_RETRY_POLICY.backoff.baseMs,
+			maxMs: input.backoff?.maxMs ?? DEFAULT_RETRY_POLICY.backoff.maxMs,
+			factor: input.backoff?.factor ?? DEFAULT_RETRY_POLICY.backoff.factor
+		},
+		perCode: {
+			...DEFAULT_RETRY_POLICY.perCode,
+			...perCode
+		},
+		maxCrashes: input.maxCrashes ?? DEFAULT_RETRY_POLICY.maxCrashes,
+		codes
+	};
+	assertAttemptBudget("retry.maxAttempts", policy.maxAttempts);
+	assertPositiveInteger("retry.maxCrashes", policy.maxCrashes);
+	assertPositiveInteger("retry.backoff.baseMs", policy.backoff.baseMs);
+	assertPositiveInteger("retry.backoff.maxMs", policy.backoff.maxMs);
+	if (policy.backoff.maxMs < policy.backoff.baseMs) throw new Error("retry.backoff.maxMs must be >= retry.backoff.baseMs");
+	if (policy.backoff.maxMs > 864e5) throw new Error(`retry.backoff.maxMs must be <= ${MAX_RETRY_AFTER_MS} (24h)`);
+	if (!Number.isFinite(policy.backoff.factor) || policy.backoff.factor < 1) throw new Error("retry.backoff.factor must be a finite number >= 1");
+	for (const [code, cap] of Object.entries(policy.perCode)) assertPositiveInteger(`retry.perCode.${code}`, cap);
+	for (const [code, rule] of Object.entries(policy.codes)) {
+		if (rule.maxAttempts !== void 0) assertAttemptBudget(`retry.perCode.${code}.maxAttempts`, rule.maxAttempts);
+		if (rule.maxDelayMs !== void 0) assertPositiveInteger(`retry.perCode.${code}.maxDelayMs`, rule.maxDelayMs);
+		if (rule.sticky && rule.maxAttempts === void 0) throw new Error(`retry.perCode.${code}: sticky needs a maxAttempts to carry`);
+	}
+	return policy;
+}
+function splitPerCode(input) {
+	const perCode = {};
+	const codes = {};
+	for (const [code, entry] of Object.entries(input)) {
+		if (code === RESERVED_CRASH_CODE) throw new Error(`retry.perCode.${code}: crashes are budgeted by retry.maxCrashes`);
+		if (typeof entry === "number") {
+			perCode[code] = entry;
+			continue;
+		}
+		if (entry.streak !== void 0) perCode[code] = entry.streak;
+		codes[code] = {
+			...entry.maxAttempts === void 0 ? {} : { maxAttempts: entry.maxAttempts },
+			...entry.maxDelayMs === void 0 ? {} : { maxDelayMs: entry.maxDelayMs },
+			sticky: entry.sticky ?? false,
+			onExhaustion: entry.onExhaustion ?? "dead"
+		};
+	}
+	return {
+		perCode,
+		codes
+	};
+}
+function assertAttemptBudget(name, value) {
+	if (value !== Number.POSITIVE_INFINITY) assertPositiveInteger(name, value);
+}
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer, got ${value}`);
+}
+// src/core/define-job.ts
+const MAX_TIMEOUT_MS = 6e5;
+const HANDLER_GRACE_MS = 5e3;
+const LEASE_MARGIN_MS = 3e4;
+/** The longest lease any legal job can hold. */
+const MAX_LEASE_MS = 635e3;
+const KIND_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,199}$/;
+const LANE_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,49}$/;
+function defineJob(input) {
+	if (!KIND_PATTERN.test(input.kind)) throw new Error(`defineJob: kind ${JSON.stringify(input.kind)} must match ${KIND_PATTERN} (lowercase, ≤ 200 chars)`);
+	if (!Number.isInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > 6e5) throw new Error(`defineJob(${input.kind}): timeoutMs must be an integer in [1, ${MAX_TIMEOUT_MS}], got ${input.timeoutMs}`);
+	const lane = input.lane ?? "default";
+	if (!LANE_PATTERN.test(lane)) throw new Error(`defineJob(${input.kind}): lane ${JSON.stringify(lane)} must match ${LANE_PATTERN} (lowercase, ≤ 50 chars)`);
+	return {
+		kind: input.kind,
+		payload: input.payload,
+		timeoutMs: input.timeoutMs,
+		lane,
+		graceMs: HANDLER_GRACE_MS,
+		leaseMs: input.timeoutMs + HANDLER_GRACE_MS + LEASE_MARGIN_MS,
+		retry: resolveRetryPolicy(input.retry),
+		classify: withDefaultClassify(input.classify),
+		handle: input.handle
+	};
+}
+/**
+* `defineJob` with `ctx.deps` typed, without annotating every handler:
+*
+* ```ts
+* const defineAppJob = defineJobFor<AppDeps>();
+* export const welcome = defineAppJob({ kind: 'welcome', …, handle: async (p, ctx) => ctx.deps.mailer… });
+* ```
+*/
+function defineJobFor() {
+	return (input) => defineJob(input);
+}
+/** What a thrown error becomes when `classify` is omitted or returns `undefined`: retry with code `unexpected`. */
+function defaultClassify(error) {
+	return retry({
+		code: "unexpected",
+		message: errorMessage(error)
+	});
+}
+function withDefaultClassify(classify) {
+	if (!classify) return defaultClassify;
+	return (error) => classify(error) ?? defaultClassify(error);
+}
+// src/core/registry.ts
+function createJobRegistry(jobs) {
+	if (jobs.length === 0) throw new Error("createJobRegistry: at least one job is required");
+	const byKind = /* @__PURE__ */ new Map();
+	for (const job of jobs) {
+		if (byKind.has(job.kind)) throw new Error(`createJobRegistry: duplicate kind ${JSON.stringify(job.kind)}`);
+		byKind.set(job.kind, job);
+	}
+	return {
+		get: (kind) => byKind.get(kind),
+		laneOf: (kind) => byKind.get(kind)?.lane,
+		lanes: () => [...new Set([...byKind.values()].map((job) => job.lane))],
+		claimable: (budgetMs = Number.POSITIVE_INFINITY, options = {}) => [...byKind.values()].filter((job) => job.leaseMs <= budgetMs).filter((job) => options.lane === void 0 || job.lane === options.lane).map((job) => ({
+			kind: job.kind,
+			leaseMs: job.leaseMs
+		}))
+	};
+}
+// src/runtime/deadline.ts
+/** A bounded wait ran out: the work may still be running, and its outcome is unknown. */
+var DeadlineExceededError = class extends Error {
+	constructor(what) {
+		super(`${what} exceeded its deadline`);
+		this.name = "DeadlineExceededError";
+	}
+};
+const POLL_MS = 250;
+/**
+* Waits for `work` until `deadlineAt` on `clock` — or until the same span of real time passes,
+* whichever is first, so a stalled or frozen clock can't stretch it. Never rejects. A late result
+* is dropped: the caller must make abandoned work harmless (destroy its session, discard a late
+* connection).
+*/
+async function untilDeadline(clock, work, deadlineAt) {
+	let settled;
+	const watched = work.then((value) => {
+		settled = {
+			done: true,
+			value
+		};
+	}, (error) => {
+		settled = {
+			done: true,
+			error: error ?? /* @__PURE__ */ new Error("rejected")
+		};
+	});
+	let realDeadline = Infinity;
+	for (;;) {
+		if (settled) return settled;
+		realDeadline = Math.min(realDeadline, Date.now() + (deadlineAt - clock.nowMs()));
+		const remaining = realDeadline - Date.now();
+		if (remaining <= 0) return { done: false };
+		let timer;
+		await Promise.race([watched, new Promise((resolve) => {
+			timer = setTimeout(resolve, Math.min(remaining, POLL_MS));
+		})]);
+		clearTimeout(timer);
+	}
+}
+/** Resolves when `work` settles or `ms` of real time pass, whichever is first; never rejects. */
+async function settledWithin(work, ms) {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve({ done: false }), Math.max(0, ms));
+	});
+	try {
+		return await Promise.race([work.then((value) => ({
+			done: true,
+			value
+		}), (error) => ({
+			done: true,
+			error: error ?? /* @__PURE__ */ new Error("rejected")
+		})), timeout]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** The value of a bounded wait, or a throw: the work's own error, or `DeadlineExceededError`. */
+function unwrap(result, what) {
+	if (!result.done) throw new DeadlineExceededError(what);
+	if (result.error !== void 0) throw result.error;
+	return result.value;
+}
+// src/runtime/connection.ts
+const DESTROY_WAIT_MS = 5e3;
+const CLOSE_WAIT_MS = 2e3;
+/**
+* `connect()` bounded by `deadlineAt`: throws `DeadlineExceededError` past it, and destroys the
+* connection if it arrives later anyway.
+*/
+async function acquireConnection(connect, clock, deadlineAt) {
+	const connecting = connect();
+	const got = await untilDeadline(clock, connecting, deadlineAt);
+	if (!got.done) connecting.then(discardConnection, () => void 0);
+	return unwrap(got, "connection acquisition");
+}
+/** Destroys a session nobody will wait on. */
+function discardConnection(connection) {
+	connection.destroy().catch(() => void 0);
+}
+/** Destroys a session, waiting a bounded time for it. */
+const destroyConnection = (connection) => settledWithin(connection.destroy(), DESTROY_WAIT_MS);
+/** Returns a healthy session; one whose `close()` hangs is destroyed instead. */
+async function closeConnection(connection) {
+	if (!(await settledWithin(connection.close(), CLOSE_WAIT_MS)).done) discardConnection(connection);
+}
+// src/runtime/events.ts
+function createEmitter(sink) {
+	return (event) => {
+		if (!sink) return;
+		try {
+			sink(event);
+		} catch {}
+	};
+}
+// src/core/backoff.ts
+function computeBackoff(policy, jobId, attempt) {
+	const { baseMs, maxMs, factor } = policy.backoff;
+	const exponent = Math.max(0, attempt - 1);
+	const half = Math.min(maxMs, baseMs * factor ** exponent) / 2;
+	return Math.round(half + half * unitHash(`${jobId}:${attempt}`));
+}
+function unitHash(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0) / 4294967296;
+}
+// src/core/transition.ts
+function decideTransition(input) {
+	const { outcome, job, policy, timing } = input;
+	switch (outcome.type) {
+		case "ok": return {
+			to: "succeeded",
+			attemptOutcome: "succeeded"
+		};
+		case "cancel": return {
+			to: "cancelled",
+			reason: outcome.reason,
+			attemptOutcome: "cancelled"
+		};
+		case "fail": return {
+			to: "dead",
+			reason: "failed",
+			code: outcome.code,
+			message: outcome.message ?? null,
+			codeStreak: nextStreak(job, outcome.code),
+			attemptOutcome: "failed"
+		};
+		case "retry": return decideRetry({
+			job,
+			policy,
+			code: outcome.code,
+			message: outcome.message ?? null,
+			attemptOutcome: "retry",
+			afterMs: outcome.afterMs,
+			minDelayMs: 0
+		});
+		case "timeout": return decideRetry({
+			job,
+			policy,
+			code: TIMEOUT_CODE,
+			message: null,
+			attemptOutcome: "timeout",
+			afterMs: void 0,
+			minDelayMs: timing.graceMs
+		});
+		case "claim_late": return {
+			to: "retrying",
+			delayMs: CLAIM_LATE_DELAY_MS,
+			code: CLAIM_LATE_CODE,
+			message: null,
+			codeStreak: nextStreak(job, CLAIM_LATE_CODE),
+			...episode(job.stickyCode ?? null),
+			attemptOutcome: "lease_expired"
+		};
+		case "lease_expired": return decideRetry({
+			job,
+			policy,
+			code: LEASE_EXPIRED_CODE,
+			message: null,
+			attemptOutcome: "lease_expired",
+			afterMs: void 0,
+			minDelayMs: 0
+		});
+	}
+}
+function decideRetry(input) {
+	const { job, policy, code, message, attemptOutcome } = input;
+	const codeStreak = nextStreak(job, code);
+	if (attemptOutcome === "lease_expired" || code === "lease_expired") {
+		const kept = episode(job.stickyCode ?? null);
+		if (codeStreak >= policy.maxCrashes) return {
+			to: "dead",
+			reason: "crash_loop",
+			code,
+			message,
+			codeStreak,
+			...kept,
+			attemptOutcome
+		};
+		return {
+			to: "retrying",
+			delayMs: 0,
+			code,
+			message,
+			codeStreak,
+			...kept,
+			attemptOutcome
+		};
+	}
+	const rule = ownRule(policy, code);
+	const stickyCode = job.stickyCode ?? (rule?.sticky ? code : null);
+	const failure = {
+		code,
+		message,
+		codeStreak,
+		...episode(stickyCode),
+		attemptOutcome
+	};
+	const exhausted = () => rule?.onExhaustion === "cancel" ? {
+		to: "cancelled",
+		reason: "exhausted",
+		...failure
+	} : {
+		to: "dead",
+		reason: "exhausted",
+		...failure
+	};
+	const codeCap = Object.hasOwn(policy.perCode, code) ? policy.perCode[code] : void 0;
+	if (codeCap !== void 0 && codeStreak >= codeCap) return exhausted();
+	const attemptsUsed = job.spentAttempts + 1;
+	if (attemptsUsed >= attemptCeiling(policy, code, stickyCode)) return exhausted();
+	const requested = input.afterMs === void 0 || !Number.isFinite(input.afterMs) ? computeBackoff(policy, job.id, attemptsUsed) : Math.min(MAX_RETRY_AFTER_MS, Math.max(0, Math.round(input.afterMs)));
+	const capped = Math.min(requested, rule?.maxDelayMs ?? Number.POSITIVE_INFINITY);
+	return {
+		to: "retrying",
+		delayMs: Math.max(capped, input.minDelayMs),
+		...failure
+	};
+}
+const ownRule = (policy, code) => Object.hasOwn(policy.codes, code) ? policy.codes[code] : void 0;
+function attemptCeiling(policy, code, stickyCode) {
+	const own = ownRule(policy, code)?.maxAttempts ?? policy.maxAttempts;
+	const carried = stickyCode === null ? policy.maxAttempts : ownRule(policy, stickyCode)?.maxAttempts ?? 0;
+	return Math.max(policy.maxAttempts, own, carried);
+}
+function episode(stickyCode) {
+	return stickyCode === null ? {} : { stickyCode };
+}
+function nextStreak(job, code) {
+	return job.lastErrorCode === code ? job.codeStreak + 1 : 1;
+}
+// src/runtime/db-errors.ts
+const TRANSIENT_SQLSTATES = /* @__PURE__ */ new Set([
+	"40001",
+	"40003",
+	"40P01",
+	"55P03",
+	"57014"
+]);
+const CONNECTION_SQLSTATES = /* @__PURE__ */ new Set([
+	"57P01",
+	"57P02",
+	"57P03",
+	"25P03",
+	"25P04"
+]);
+const TIMEOUT_SQLSTATES = /* @__PURE__ */ new Set([
+	"57014",
+	"55P03",
+	"25P03",
+	"25P04"
+]);
+const SOCKET_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"EPIPE",
+	"ETIMEDOUT",
+	"EHOSTUNREACH",
+	"ENOTCONN",
+	"ENETUNREACH",
+	"ECONNABORTED",
+	"EAI_AGAIN",
+	"CONNECTION_CLOSED",
+	"CONNECTION_ENDED",
+	"CONNECTION_DESTROYED",
+	"CONNECT_TIMEOUT"
+]);
+const NODE_PG_TERMINATED = /^Connection terminated/;
+const NODE_PG_NOT_QUERYABLE = /^Client (?:has encountered a connection error|was closed) and is not queryable$/;
+const MAX_NODES = 16;
+/** Searches the `cause` chain and `AggregateError.errors`: Drizzle's wrapper has no `code`. */
+function findInChain(error, pick) {
+	const seen = /* @__PURE__ */ new Set();
+	const queue = [error];
+	while (queue.length > 0 && seen.size < MAX_NODES) {
+		const node = queue.shift();
+		if (!node || typeof node !== "object" || seen.has(node)) continue;
+		seen.add(node);
+		const picked = pick(node);
+		if (picked !== null) return picked;
+		queue.push(node.cause);
+		const nested = node.errors;
+		if (Array.isArray(nested)) queue.push(...nested);
+	}
+	return null;
+}
+function sqlstateOf(error) {
+	return findInChain(error, (node) => typeof node.code === "string" && /^[0-9A-Z]{5}$/.test(node.code) ? node.code : null);
+}
+/**
+* The connection dropped mid-statement: whether it committed is unknown, so a retry
+* must use a fresh connection and read back what landed.
+*/
+function isConnectionError(error) {
+	return findInChain(error, (node) => {
+		const code = typeof node.code === "string" ? node.code : "";
+		const message = typeof node.message === "string" ? node.message : "";
+		const terminated = NODE_PG_TERMINATED.test(message) || NODE_PG_NOT_QUERYABLE.test(message);
+		return code.startsWith("08") || CONNECTION_SQLSTATES.has(code) || SOCKET_CODES.has(code) || terminated ? true : null;
+	}) === true;
+}
+function isTimeoutError(error) {
+	const code = sqlstateOf(error);
+	return code !== null && TIMEOUT_SQLSTATES.has(code);
+}
+function isTransientDbError(error) {
+	const code = sqlstateOf(error);
+	return code !== null && (TRANSIENT_SQLSTATES.has(code) || code.startsWith("53")) || isConnectionError(error);
+}
+// src/runtime/execute-handler.ts
+async function executeHandler(input) {
+	const { job, claimed } = input;
+	const controller = new AbortController();
+	const handlerDb = closable(input.db);
+	const deadline = input.clock.nowMs() + job.timeoutMs;
+	const ctx = {
+		jobId: claimed.id,
+		kind: claimed.kind,
+		attempt: claimed.attemptNo,
+		idempotencyKey: claimed.id,
+		signal: controller.signal,
+		deadline,
+		remainingMs: () => Math.max(0, deadline - input.clock.nowMs()),
+		deps: input.deps,
+		tenantKey: claimed.tenantKey,
+		correlationId: claimed.correlationId,
+		metadata: claimed.metadata,
+		db: handlerDb.db
+	};
+	let expired = false;
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			expired = true;
+			resolve({ settled: "timeout" });
+		}, job.timeoutMs);
+	});
+	const run = (async () => {
+		const validated = await validatePayload(job, claimed.payload);
+		if (expired) return {
+			settled: "error",
+			error: /* @__PURE__ */ new Error("validation finished after the attempt timed out")
+		};
+		if (!validated.ok) return {
+			settled: "invalid_payload",
+			message: validated.message
+		};
+		try {
+			return {
+				settled: "value",
+				value: await job.handle(validated.value, ctx)
+			};
+		} catch (error) {
+			return {
+				settled: "error",
+				error
+			};
+		}
+	})();
+	const first = await Promise.race([run, timeout]);
+	clearTimeout(timer);
+	handlerDb.close();
+	if (first.settled === "timeout") {
+		controller.abort(/* @__PURE__ */ new Error(`job ${claimed.id} timed out after ${job.timeoutMs}ms`));
+		return {
+			outcome: { type: "timeout" },
+			runaway: !await Promise.race([run.then(() => true), input.clock.sleep(job.graceMs).then(() => false)])
+		};
+	}
+	if (first.settled === "invalid_payload") return {
+		outcome: {
+			type: "retry",
+			code: "invalid_payload",
+			message: first.message
+		},
+		runaway: false
+	};
+	if (first.settled === "error") return {
+		outcome: classifySafely(job, first.error),
+		thrown: first.error,
+		runaway: false
+	};
+	if (!isHandlerOutcome(first.value)) return {
+		outcome: retry({
+			code: "invalid_outcome",
+			message: "handler returned a value that is not an outcome"
+		}),
+		runaway: false
+	};
+	return {
+		outcome: first.value,
+		runaway: false
+	};
+}
+async function validatePayload(job, payload) {
+	try {
+		const validated = await job.payload["~standard"].validate(payload);
+		if (validated.issues) return {
+			ok: false,
+			message: validated.issues.map((issue) => issue.message).join("; ")
+		};
+		return {
+			ok: true,
+			value: validated.value
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: errorMessage(error)
+		};
+	}
+}
+/**
+* Revocation is checked when a method is called, not when it is read, so a captured
+* `ctx.db.execute` or a `tx` handed to `transaction()` stops working too. Query builders
+* created before close and awaited after it are not covered: don't let work outlive the handler.
+*/
+function closable(db) {
+	let closed = false;
+	const revoked = () => /* @__PURE__ */ new Error("ctx.db used after the handler returned");
+	const wrap = (target) => new Proxy(target, { get(inner, prop) {
+		const value = Reflect.get(inner, prop, inner);
+		if (typeof value !== "function") {
+			if (closed) throw revoked();
+			return value;
+		}
+		if (prop === "transaction") return (fn, ...rest) => closed ? Promise.reject(revoked()) : value.call(inner, (tx) => fn(wrap(tx)), ...rest);
+		return (...args) => closed ? Promise.reject(revoked()) : value.apply(inner, args);
+	} });
+	return {
+		db: wrap(db),
+		close: () => {
+			closed = true;
+		}
+	};
+}
+function classifySafely(job, error) {
+	try {
+		const outcome = job.classify(error);
+		return isHandlerOutcome(outcome) ? outcome : retry({ code: "unexpected" });
+	} catch {
+		return defaultClassify(error);
+	}
+}
+const isOptional = (value, type) => value == null || typeof value === type;
+/** Checks every field settlement reads, not just the tag: JS or an unsafe cast can return anything. */
+function isHandlerOutcome(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const outcome = value;
+	switch (outcome["type"]) {
+		case "ok": return isOptional(outcome["commit"], "function");
+		case "retry":
+		case "fail": return isCode(outcome["code"]) && isOptional(outcome["message"], "string");
+		case "cancel": return typeof outcome["reason"] === "string";
+		default: return false;
+	}
+}
+const isCode = (value) => typeof value === "string" && value !== "";
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]+/g;
+function sanitizeErrorMessage(message, redact) {
+	const flattened = (redact ? redact(message) : message).replace(CONTROL_CHARACTERS, " ").replace(/ {2,}/g, " ").trim();
+	if (flattened.length <= 2e3) return flattened;
+	return `${flattened.slice(0, 1999)}…`;
+}
+// src/runtime/serialize-error.ts
+const MAX_CAUSE_DEPTH = 5;
+function serializeError(error, depth = 0) {
+	if (!(error instanceof Error)) return {
+		name: "NonError",
+		message: safeString(error)
+	};
+	const serialized = {
+		name: error.name,
+		message: error.message
+	};
+	if (error.stack !== void 0) serialized.stack = error.stack;
+	const code = error.code;
+	if (typeof code === "string") serialized.code = code;
+	if (error.cause !== void 0 && depth + 1 < MAX_CAUSE_DEPTH) serialized.cause = serializeError(error.cause, depth + 1);
+	return serialized;
+}
+function safeString(value) {
+	try {
+		return String(value);
+	} catch {
+		return "[unprintable]";
+	}
+}
+// src/runtime/types.ts
+const systemClock = {
+	dbNow: () => null,
+	nowMs: () => Date.now(),
+	sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+const MAX_QUEUE_DELAY_SECONDS = 86400;
+// src/runtime/runtime.ts
+const emptyTally = () => ({
+	claimed: 0,
+	succeeded: 0,
+	retrying: 0,
+	dead: 0,
+	cancelled: 0,
+	leaseLost: 0,
+	settleFailed: 0
+});
+const emptyReport = () => ({
+	...emptyTally(),
+	byKind: {},
+	errored: 0,
+	erroredSamples: [],
+	reachedLimit: false,
+	reachedDeadline: false
+});
+const MAX_ERROR_SAMPLES = 5;
+function tally(report, kind, key) {
+	report[key]++;
+	const forKind = Object.hasOwn(report.byKind, kind) ? report.byKind[kind] : report.byKind[kind] = emptyTally();
+	forKind[key]++;
+}
+function recordError(report, error) {
+	report.errored++;
+	if (report.erroredSamples.length < MAX_ERROR_SAMPLES) report.erroredSamples.push(errorMessage(error));
+}
+/** What an event reports about a database fault. */
+const dbFault = (error) => ({
+	dbCode: sqlstateOf(error),
+	transient: isTransientDbError(error),
+	error: serializeError(error)
+});
+/** A settlement that ran out of time: its outcome is unknown, and left to recovery. */
+const settlementExpired = (claimed) => ({
+	type: "settle_failed",
+	jobId: claimed.id,
+	kind: claimed.kind,
+	attemptNo: claimed.attemptNo,
+	dbCode: null,
+	transient: true,
+	error: serializeError(/* @__PURE__ */ new Error("settlement deadline exceeded; outcome left to recovery"))
+});
+var HookError = class extends Error {
+	original;
+	constructor(original) {
+		super("onTransition hook failed", { cause: original });
+		this.original = original;
+	}
+};
+/** The handler's `ok({ commit })` callback threw inside the settle transaction. */
+var CommitError = class extends Error {
+	original;
+	constructor(original) {
+		super("ok({ commit }) failed", { cause: original });
+		this.original = original;
+	}
+};
+var LeaseLostRollback = class extends Error {};
+const SETTLE_SAFETY_MS = 2e3;
+const WATCHDOG_SLACK_MS = 1e3;
+const QUEUE_SEND_TIMEOUT_MS = 1e4;
+const CLAIM_LATE_SETTLE_MS = 5e3;
+/** A claimed job starts only if this much lease and deadline remain after its timeout and grace. */
+const MIN_SETTLE_WINDOW_MS = 1e4;
+/** For a phase called without an invocation deadline (direct runtime use, operator paths). */
+const DEFAULT_PHASE_DEADLINE_MS = 6e4;
+/** Recovery's share of an invocation when none is given: count-limited *and* time-limited. */
+const DEFAULT_RECOVERY_BUDGET_MS = 12e4;
+const RENUDGE_DELAY_SECONDS = 5;
+const HANDOFF_COOLDOWN_MS = 9e5;
+function createRuntime(config) {
+	const { registry, emit, clock } = config;
+	const gate = config.version ? { version: config.version } : {};
+	const queueFor = (lane) => Object.hasOwn(config.queues, lane) ? config.queues[lane] : void 0;
+	const phaseDeadline = (options) => options.deadlineAt ?? clock.nowMs() + 6e4;
+	const kindFilter = (remainingMs, scope = {}) => {
+		const lane = scope.lane === void 0 ? {} : { lane: scope.lane };
+		const inScope = (kind) => scope.kinds === void 0 || scope.kinds.includes(kind);
+		const fitting = new Set(registry.claimable(remainingMs, lane).map((k) => k.kind));
+		return registry.claimable(Number.POSITIVE_INFINITY, lane).filter((k) => inScope(k.kind)).map((k) => ({
+			...k,
+			fits: fitting.has(k.kind)
+		}));
+	};
+	async function withLanes(count, work, deadlineAt = clock.nowMs() + DEFAULT_PHASE_DEADLINE_MS) {
+		const opening = await Promise.allSettled(Array.from({ length: Math.max(1, count) }, () => openLane(deadlineAt)));
+		const lanes = opening.flatMap((r) => r.status === "fulfilled" ? [r.value] : []);
+		const failed = opening.find((r) => r.status === "rejected");
+		if (failed) {
+			await Promise.all(lanes.map((lane) => lane.close().catch(() => void 0)));
+			throw failed.reason;
+		}
+		try {
+			const settled = await Promise.allSettled(lanes.map((lane, index) => work(lane, index)));
+			const rejected = settled.find((r) => r.status === "rejected");
+			if (rejected) throw rejected.reason;
+			return settled.map((r) => r.value);
+		} finally {
+			await Promise.all(lanes.map((lane) => lane.close()));
+		}
+	}
+	/** One bounded statement on a short-lived lane: its session is destroyed if it overruns. */
+	async function onOneLane(what, deadlineAt, read) {
+		const [result] = await withLanes(1, (lane) => lane.bounded(() => read(lane.db), deadlineAt, what), deadlineAt);
+		return result;
+	}
+	/** Acquisition bounded by `deadlineAt`; a connection that arrives after it is destroyed. */
+	async function acquire(deadlineAt, isWanted = () => true) {
+		const connection = await acquireConnection(() => config.connect(), clock, deadlineAt);
+		if (!isWanted()) {
+			discardConnection(connection);
+			throw new Error("runtime: lane was retired while reconnecting");
+		}
+		return connection;
+	}
+	/**
+	* A lane owns one connection at a time. A runaway or timed-out session is destroyed — never
+	* returned to a pool — *before* its replacement is acquired, so a one-client pool still works.
+	*/
+	async function openLane(deadlineAt) {
+		let connection = await acquire(deadlineAt);
+		let generation = 0;
+		let retired = false;
+		const discard = async () => {
+			const stale = connection;
+			connection = null;
+			generation++;
+			if (stale) await destroyConnection(stale);
+		};
+		const lane = {
+			get db() {
+				if (!connection) throw new Error("runtime: lane has no connection");
+				return connection.db;
+			},
+			get usable() {
+				return connection !== null && !retired;
+			},
+			get broken() {
+				return connection?.isBroken?.() === true;
+			},
+			ready: async (readyBy) => {
+				if (retired) return false;
+				if (connection?.isBroken?.() === true) await discard();
+				if (connection) return true;
+				const mine = generation;
+				try {
+					connection = await acquire(readyBy, () => !retired && generation === mine);
+					return true;
+				} catch (error) {
+					emit({
+						type: "infra_error",
+						operation: "run_job",
+						...dbFault(error)
+					});
+					return false;
+				}
+			},
+			replace: async () => {
+				await discard();
+				const mine = generation;
+				const fresh = await config.connect();
+				if (retired || generation !== mine) {
+					discardConnection(fresh);
+					throw new Error("runtime: lane was retired while reconnecting");
+				}
+				connection = fresh;
+			},
+			retire: async () => {
+				retired = true;
+				await discard();
+			},
+			bounded: async (work, until, what) => {
+				const running = Promise.resolve().then(work);
+				const result = await untilDeadline(clock, running, until);
+				if (!result.done) await lane.retire();
+				return unwrap(result, what);
+			},
+			close: async () => {
+				const open = connection;
+				connection = null;
+				if (open) await closeConnection(open);
+			}
+		};
+		return lane;
+	}
+	/**
+	* One absolute deadline for a settlement: shared by its retries, reconnects, fallbacks and
+	* read-back, never reset. It never runs past the lease (less a safety margin).
+	*/
+	function startSettlement(leaseEndsAtMs, invocationDeadlineAt) {
+		return {
+			deadlineAt: Math.min(clock.nowMs() + config.settleRetry.budgetMs, leaseEndsAtMs === void 0 ? Infinity : leaseEndsAtMs - SETTLE_SAFETY_MS, invocationDeadlineAt ?? Infinity),
+			abandoned: false
+		};
+	}
+	const remainingOf = (settlement) => settlement.abandoned ? 0 : settlement.deadlineAt - clock.nowMs();
+	async function runClaimed(lane, claimed, report, trigger, claimedAtMs, deadlineAt) {
+		tally(report, claimed.kind, "claimed");
+		const job = registry.get(claimed.kind);
+		if (!job) throw new Error(`runtime: claimed unregistered kind ${claimed.kind}`);
+		const leaseEndsAtMs = claimedAtMs + job.leaseMs;
+		const startedAtMs = clock.nowMs();
+		const needMs = job.timeoutMs + job.graceMs + MIN_SETTLE_WINDOW_MS;
+		if (leaseEndsAtMs - startedAtMs < needMs || deadlineAt - startedAtMs < needMs) {
+			emit({
+				type: "claim_late",
+				jobId: claimed.id,
+				kind: claimed.kind,
+				attemptNo: claimed.attemptNo,
+				claimLatencyMs: startedAtMs - claimedAtMs
+			});
+			await settle(lane, job, claimed, { type: "claim_late" }, report, {
+				thrown: false,
+				recovered: false,
+				trigger
+			}, {
+				deadlineAt: clock.nowMs() + CLAIM_LATE_SETTLE_MS,
+				abandoned: false
+			});
+			return;
+		}
+		const execution = await executeHandler({
+			job,
+			claimed,
+			db: lane.db,
+			deps: config.deps,
+			clock
+		});
+		if (execution.thrown !== void 0) emit({
+			type: "handler_threw",
+			jobId: claimed.id,
+			kind: claimed.kind,
+			attemptNo: claimed.attemptNo,
+			error: serializeError(execution.thrown)
+		});
+		if (execution.outcome.type === "timeout") emit({
+			type: "handler_timeout",
+			jobId: claimed.id,
+			kind: claimed.kind,
+			attemptNo: claimed.attemptNo,
+			timeoutMs: job.timeoutMs
+		});
+		await settle(lane, job, claimed, execution.outcome, report, {
+			thrown: execution.thrown !== void 0,
+			recovered: false,
+			trigger
+		}, startSettlement(leaseEndsAtMs, deadlineAt), execution.runaway ? () => lane.replace() : void 0);
+	}
+	/**
+	* Native timeouts bound SQL; this watchdog bounds everything else a settlement waits on —
+	* connection acquisition, hooks and commit callbacks between statements. When it fires the
+	* outcome is unknown (a timeout doesn't prove rollback): the lane's session is destroyed, the
+	* lane retires, and recovery resolves the job through the fenced settle path.
+	*/
+	async function settle(lane, job, claimed, outcome, report, context, settlement, before) {
+		const work = (async () => {
+			if (before) await before();
+			return persistOutcome(lane, job, claimed, outcome, context, settlement);
+		})();
+		work.catch(() => void 0);
+		const raced = await untilDeadline(clock, work, Math.max(settlement.deadlineAt, clock.nowMs()) + WATCHDOG_SLACK_MS);
+		if (!raced.done) {
+			settlement.abandoned = true;
+			tally(report, claimed.kind, "settleFailed");
+			emit(settlementExpired(claimed));
+			await lane.retire();
+			return;
+		}
+		if (raced.error !== void 0) throw raced.error;
+		const settled = raced.value;
+		return afterSettle(job, claimed, settled.transition, settled.result, report, settled.context, lane, settlement);
+	}
+	async function persistOutcome(lane, job, claimed, outcome, context, settlement) {
+		const budget = {
+			id: claimed.id,
+			spentAttempts: claimed.spentAttempts,
+			codeStreak: claimed.codeStreak,
+			lastErrorCode: claimed.lastErrorCode,
+			stickyCode: claimed.stickyCode ?? null
+		};
+		const decide = (decided) => sanitize(decideTransition({
+			outcome: decided,
+			job: budget,
+			policy: job.retry,
+			timing: { graceMs: job.graceMs }
+		}));
+		const transition = decide(outcome);
+		const commit = outcome.type === "ok" ? outcome.commit : void 0;
+		let commitError;
+		const applied = await persist(lane, claimed, transition, settlement, {
+			hooked: true,
+			requireExpiredLease: context.recovered,
+			...commit ? {
+				commit,
+				onCommitError: (error) => commitError = error
+			} : {}
+		});
+		if (applied === "commit_failed") {
+			emitWhileLive(settlement, {
+				type: "handler_threw",
+				jobId: claimed.id,
+				kind: claimed.kind,
+				attemptNo: claimed.attemptNo,
+				error: serializeError(commitError)
+			});
+			return persistOutcome(lane, job, claimed, classifySafely(job, commitError), {
+				...context,
+				thrown: true
+			}, settlement);
+		}
+		if (applied === "hook_failed") {
+			const fallback = decide(retry({ code: HOOK_FAILED_CODE }));
+			return {
+				transition: fallback,
+				result: await persist(lane, claimed, fallback, settlement, {
+					hooked: false,
+					requireExpiredLease: context.recovered
+				}),
+				context: {
+					...context,
+					thrown: true
+				}
+			};
+		}
+		return {
+			transition,
+			result: applied,
+			context
+		};
+	}
+	function emitWhileLive(settlement, event) {
+		if (!settlement.abandoned) emit(event);
+	}
+	function sanitize(transition) {
+		if ("code" in transition && transition.message !== null) return {
+			...transition,
+			message: sanitizeErrorMessage(transition.message, config.redact)
+		};
+		return transition;
+	}
+	async function persist(lane, claimed, transition, settlement, options) {
+		const hook = options.hooked ? config.onTransition : void 0;
+		const { commit } = options;
+		const fenced = hook !== void 0 || commit !== void 0;
+		const settleInput = {
+			jobId: claimed.id,
+			leaseToken: claimed.leaseToken,
+			transition,
+			now: clock.dbNow(),
+			requireExpiredLease: options.requireExpiredLease
+		};
+		const deadlineFailure = () => {
+			emitWhileLive(settlement, settlementExpired(claimed));
+			return "settle_failed";
+		};
+		let ambiguous = false;
+		const resolve = async (result) => {
+			if (result === "lease_lost" && ambiguous) {
+				if (remainingOf(settlement) <= 0) return deadlineFailure();
+				return await readAttemptOutcome(lane.db, settleInput) === transition.attemptOutcome ? "applied" : "lease_lost";
+			}
+			return result;
+		};
+		for (let attempt = 0;; attempt++) {
+			const remaining = remainingOf(settlement);
+			if (remaining <= 0) return deadlineFailure();
+			try {
+				if (lane.broken) await lane.replace();
+				return await resolve(await lane.db.transaction(async (tx) => {
+					await setSettlementTimeouts(tx, {
+						transactionMs: remaining,
+						statementMs: remaining,
+						lockMs: Math.min(config.settleRetry.lockTimeoutMs, remaining)
+					});
+					if (fenced && !await isLeaseHeld(tx, settleInput)) return "lease_lost";
+					if (commit) try {
+						await commit(tx);
+					} catch (error) {
+						throw new CommitError(error);
+					}
+					if (hook) try {
+						await hook(tx, {
+							job: claimed,
+							transition
+						});
+					} catch (error) {
+						throw new HookError(error);
+					}
+					const settled = await settleJob(tx, settleInput);
+					if (settled === "lease_lost" && fenced) throw new LeaseLostRollback();
+					return settled;
+				}));
+			} catch (error) {
+				if (error instanceof LeaseLostRollback) return resolve("lease_lost");
+				const fault = error instanceof HookError || error instanceof CommitError ? error.original : error;
+				if (isTransientDbError(fault) && attempt < config.settleRetry.attempts) {
+					if (isConnectionError(fault) || isTimeoutError(fault)) ambiguous = true;
+					if (isConnectionError(fault)) await lane.replace();
+					if (settlement.abandoned) return "settle_failed";
+					emit({
+						type: "settle_retried",
+						jobId: claimed.id,
+						kind: claimed.kind,
+						dbCode: sqlstateOf(fault),
+						retry: attempt + 1
+					});
+					const base = config.settleRetry.delaysMs[attempt] ?? 8e3;
+					const delay = Math.round(base * (1 + Math.random() * .25));
+					await clock.sleep(Math.max(0, Math.min(delay, remainingOf(settlement))));
+					continue;
+				}
+				if (error instanceof CommitError) {
+					options.onCommitError?.(fault);
+					return "commit_failed";
+				}
+				if (error instanceof HookError) {
+					emitWhileLive(settlement, {
+						type: "hook_failed",
+						jobId: claimed.id,
+						kind: claimed.kind,
+						to: transition.to,
+						error: serializeError(fault)
+					});
+					return "hook_failed";
+				}
+				emitWhileLive(settlement, {
+					type: "settle_failed",
+					jobId: claimed.id,
+					kind: claimed.kind,
+					attemptNo: claimed.attemptNo,
+					...dbFault(fault)
+				});
+				return "settle_failed";
+			}
+		}
+	}
+	async function afterSettle(job, claimed, transition, result, report, context, lane, settlement) {
+		if (result === "settle_failed" || result === "hook_failed" || result === "commit_failed") {
+			tally(report, claimed.kind, "settleFailed");
+			return;
+		}
+		if (result === "lease_lost") {
+			tally(report, claimed.kind, "leaseLost");
+			emit({
+				type: "lease_lost",
+				jobId: claimed.id,
+				kind: claimed.kind,
+				attemptNo: claimed.attemptNo
+			});
+			return;
+		}
+		tally(report, claimed.kind, transition.to);
+		emit(transitionEvent(job, claimed, transition, context));
+		if ((transition.to === "retrying" || transition.to === "dead") && config.warnAtStreak !== void 0 && transition.codeStreak === config.warnAtStreak) emit({
+			type: "attempt_threshold",
+			jobId: claimed.id,
+			kind: claimed.kind,
+			code: transition.code,
+			codeStreak: transition.codeStreak,
+			threshold: config.warnAtStreak
+		});
+		if (transition.to === "retrying") await nudgeJobs([{
+			id: claimed.id,
+			kind: claimed.kind
+		}], Math.ceil(transition.delayMs / 1e3), {
+			...lane.usable ? { lane } : {},
+			deadlineAt: settlement.deadlineAt
+		});
+	}
+	function transitionEvent(job, claimed, transition, context) {
+		const failing = "code" in transition;
+		const charged = transition.attemptOutcome === "lease_expired" ? 0 : 1;
+		return {
+			type: "transition",
+			severity: transition.to === "dead" ? "error" : transition.to === "retrying" && context.thrown ? "warn" : "info",
+			jobId: claimed.id,
+			kind: claimed.kind,
+			tenantKey: claimed.tenantKey,
+			correlationId: claimed.correlationId,
+			attemptNo: claimed.attemptNo,
+			to: transition.to,
+			reason: transition.to === "dead" || transition.to === "cancelled" ? transition.reason : null,
+			code: failing ? transition.code : null,
+			codeStreak: failing ? transition.codeStreak : 0,
+			attemptsUsed: claimed.spentAttempts + charged,
+			maxAttempts: job.retry.maxAttempts,
+			delayMs: transition.to === "retrying" ? transition.delayMs : null,
+			recovered: context.recovered,
+			trigger: context.trigger
+		};
+	}
+	async function nudgeJobs(jobs, delaySeconds = 0, via = {}) {
+		const byLane = /* @__PURE__ */ new Map();
+		for (const job of jobs) {
+			const lane = job.kind === void 0 ? "default" : registry.laneOf(job.kind) ?? "default";
+			const ids = byLane.get(lane) ?? [];
+			ids.push(job.id);
+			byLane.set(lane, ids);
+		}
+		for (const [lane, ids] of byLane) await nudgeLane(lane, ids, delaySeconds, via);
+	}
+	async function nudgeLane(lane, ids, delaySeconds, via = {}) {
+		if (ids.length === 0) return;
+		const delay = Number.isFinite(delaySeconds) ? Math.min(MAX_QUEUE_DELAY_SECONDS, Math.max(0, Math.ceil(delaySeconds))) : 0;
+		const queue = queueFor(lane);
+		if (!queue) {
+			emit({
+				type: "nudge_skipped",
+				ids: [...ids],
+				lane,
+				reason: "no_queue"
+			});
+			await stampNudges(ids, `no_queue: lane ${lane} has no queue`, via);
+			return;
+		}
+		for (let i = 0; i < ids.length; i += 100) {
+			const chunk = ids.slice(i, i + 100);
+			const message = {
+				v: 1,
+				type: "nudge",
+				ids: chunk
+			};
+			try {
+				const limitMs = via.deadlineAt === void 0 ? QUEUE_SEND_TIMEOUT_MS : Math.min(QUEUE_SEND_TIMEOUT_MS, via.deadlineAt - clock.nowMs());
+				if (limitMs <= 0) throw new Error("settlement deadline exceeded before the nudge was sent");
+				const sent = await untilDeadline(clock, queue.send(message, delay > 0 ? { delaySeconds: delay } : void 0), clock.nowMs() + limitMs);
+				if (!sent.done) throw new Error(`queue send exceeded its ${limitMs}ms deadline`);
+				if (sent.error !== void 0) throw sent.error;
+				emit({
+					type: "nudge_sent",
+					ids: chunk,
+					lane,
+					delaySeconds: delay
+				});
+				await stampNudges(chunk, null, via);
+			} catch (error) {
+				emit({
+					type: "nudge_failed",
+					ids: chunk,
+					lane,
+					error: serializeError(error)
+				});
+				await stampNudges(chunk, errorMessage(error), via);
+			}
+		}
+	}
+	/** On `db` when the caller holds an idle connection: a second checkout can deadlock a full pool. */
+	async function stampNudges(ids, error, via = {}) {
+		if (!config.recordNudges && !via.record) return;
+		const deadlineAt = phaseDeadline(via);
+		const record = (runner) => recordNudgeResult(runner, {
+			ids,
+			error: error === null ? null : sanitizeErrorMessage(error, config.redact),
+			now: clock.dbNow()
+		});
+		try {
+			if (via.lane?.usable) await via.lane.bounded(() => record(via.lane.db), deadlineAt, "nudge bookkeeping");
+			else if (via.db) await record(via.db);
+			else await onOneLane("nudge bookkeeping", deadlineAt, record);
+		} catch (stampError) {
+			emit({
+				type: "infra_error",
+				operation: "record_nudge",
+				...dbFault(stampError)
+			});
+		}
+	}
+	async function processNudge(ids, budget, scope = {}, options = {}) {
+		const report = emptyReport();
+		const unique = [...new Set(ids)];
+		const started = clock.nowMs();
+		const deadlineAt = Math.min(started + budget.deadlineMs, options.deadlineAt ?? Infinity);
+		const laneCount = Math.min(config.lanes, unique.length);
+		if (unique.length === 0) return report;
+		const renudge = [];
+		let reserved = 0;
+		await withLanes(laneCount, async (lane, index) => {
+			const mine = unique.filter((_, i) => i % laneCount === index);
+			for (const id of mine) {
+				if (reserved >= budget.maxJobs) {
+					renudge.push(id);
+					continue;
+				}
+				reserved++;
+				if (!await lane.ready(deadlineAt)) {
+					reserved--;
+					renudge.push(id);
+					continue;
+				}
+				const remaining = deadlineAt - clock.nowMs();
+				const claimedAtMs = clock.nowMs();
+				const [result] = await lane.bounded(() => claimByIds(lane.db, {
+					...gate,
+					ids: [id],
+					kinds: kindFilter(remaining, scope),
+					leaseToken: v7(),
+					now: clock.dbNow()
+				}), deadlineAt, "claim");
+				if (!result) {
+					reserved--;
+					continue;
+				}
+				if (result.result !== "claimed") {
+					reserved--;
+					emit({
+						type: "nudge_miss",
+						jobId: id,
+						result: result.result
+					});
+					if (result.result === "over_budget" || result.result === "locked" || result.result === "newer_version") renudge.push(id);
+					continue;
+				}
+				await runClaimed(lane, result.job, report, "nudge", claimedAtMs, deadlineAt);
+			}
+		}, deadlineAt);
+		await nudgeLane(scope.lane ?? "default", renudge, RENUDGE_DELAY_SECONDS, { ...options.deadlineAt === void 0 ? {} : { deadlineAt: options.deadlineAt } });
+		return report;
+	}
+	async function drain(budget, trigger, scope = {}, options = {}) {
+		const report = emptyReport();
+		const started = clock.nowMs();
+		const deadlineAt = Math.min(started + budget.deadlineMs, options.deadlineAt ?? Infinity);
+		let reserved = 0;
+		await withLanes(config.lanes, async (lane) => {
+			for (;;) {
+				if (!await lane.ready(deadlineAt)) return;
+				const remaining = deadlineAt - clock.nowMs();
+				if (reserved >= budget.maxJobs) {
+					report.reachedLimit = true;
+					return;
+				}
+				if (remaining <= 0) {
+					report.reachedDeadline = true;
+					return;
+				}
+				const kinds = kindFilter(remaining, scope);
+				if (kinds.length > 0 && !kinds.some((k) => k.fits)) {
+					report.reachedDeadline = true;
+					return;
+				}
+				reserved++;
+				const claimedAtMs = clock.nowMs();
+				const [claimed] = await lane.bounded(() => claimDue(lane.db, {
+					...gate,
+					kinds,
+					limit: 1,
+					trigger,
+					leaseToken: v7(),
+					now: clock.dbNow()
+				}), deadlineAt, "claim");
+				if (!claimed) {
+					reserved--;
+					return;
+				}
+				try {
+					await runClaimed(lane, claimed, report, trigger, claimedAtMs, deadlineAt);
+				} catch (error) {
+					recordError(report, error);
+					emit({
+						type: "infra_error",
+						operation: "run_job",
+						...dbFault(error)
+					});
+				}
+			}
+		}, deadlineAt);
+		return report;
+	}
+	async function handoff(budgetMs, limit = 100, options = {}) {
+		const deadlineAt = phaseDeadline(options);
+		let handed = 0;
+		for (const laneName of registry.lanes()) {
+			const long = kindFilter(budgetMs, { lane: laneName }).filter((k) => !k.fits).map((k) => k.kind);
+			if (long.length === 0) continue;
+			const ids = await onOneLane("handoff", deadlineAt, (db) => listDueJobIds(db, {
+				kinds: long,
+				limit,
+				now: clock.dbNow(),
+				nudgeCooldownMs: HANDOFF_COOLDOWN_MS,
+				...gate
+			}));
+			await nudgeLane(laneName, ids, 0, {
+				deadlineAt,
+				record: true
+			});
+			handed += ids.length;
+		}
+		return handed;
+	}
+	async function recover(limit, options = {}) {
+		const report = emptyReport();
+		const kinds = registry.claimable().map((k) => k.kind);
+		const deadlineAt = options.deadlineAt ?? clock.nowMs() + 12e4;
+		await withLanes(1, async (lane) => {
+			const expired = await lane.bounded(() => listExpiredLeases(lane.db, {
+				limit,
+				now: clock.dbNow(),
+				kinds
+			}), deadlineAt, "recovery listing");
+			for (const lease of expired) {
+				const job = registry.get(lease.kind);
+				if (deadlineAt - clock.nowMs() < MIN_SETTLE_WINDOW_MS) {
+					report.reachedDeadline = true;
+					return;
+				}
+				if (!await lane.ready(deadlineAt)) return;
+				if (!job) continue;
+				await settle(lane, job, {
+					...lease,
+					payload: null,
+					stickyCode: lease.stickyCode ?? null
+				}, { type: "lease_expired" }, report, {
+					thrown: false,
+					recovered: true,
+					trigger: "recovery"
+				}, startSettlement(void 0, deadlineAt));
+			}
+		}, deadlineAt);
+		return report;
+	}
+	async function cleanup(retention, options = {}) {
+		const deadlineAt = phaseDeadline(options);
+		let deleted = 0;
+		await withLanes(1, async (lane) => {
+			for (let i = 0; i < retention.maxBatches; i++) {
+				const batch = await lane.bounded(() => deleteFinishedJobs(lane.db, {
+					...retention,
+					now: clock.dbNow()
+				}), deadlineAt, "cleanup");
+				deleted += batch;
+				if (batch < retention.batch) return;
+			}
+		}, deadlineAt);
+		emit({
+			type: "cleanup",
+			deleted
+		});
+		return deleted;
+	}
+	async function monitorBacklog(options = {}) {
+		const counts = await onOneLane("backlog", phaseDeadline(options), (db) => countBacklog(db, {
+			agedMs: options.agedMs ?? 9e5,
+			now: clock.dbNow()
+		}));
+		const report = evaluateBacklog({
+			counts,
+			laneOf: (kind) => registry.laneOf(kind),
+			...options.thresholds ? { thresholds: options.thresholds } : {},
+			...options.lanes ? { lanes: options.lanes } : {}
+		});
+		emit({
+			type: "backlog",
+			report
+		});
+		return report;
+	}
+	async function hasBacklog(scope = {}, options = {}) {
+		return onOneLane("backlog check", phaseDeadline(options), (db) => hasDueJobs(db, {
+			...gate,
+			kinds: kindFilter(Number.POSITIVE_INFINITY, scope),
+			now: clock.dbNow()
+		}));
+	}
+	async function continueDrain(lane = "default", options = {}) {
+		const queue = queueFor(lane);
+		if (!queue) {
+			emit({
+				type: "continuation_skipped",
+				lane,
+				reason: "no_queue"
+			});
+			return false;
+		}
+		const message = {
+			v: 1,
+			type: "drain",
+			lane
+		};
+		try {
+			const deadlineAt = Math.min(options.deadlineAt ?? Infinity, clock.nowMs() + QUEUE_SEND_TIMEOUT_MS);
+			unwrap(await untilDeadline(clock, queue.send(message), deadlineAt), "continuation send");
+			emit({
+				type: "continuation_sent",
+				lane
+			});
+			return true;
+		} catch (error) {
+			emit({
+				type: "continuation_failed",
+				lane,
+				error: serializeError(error)
+			});
+			return false;
+		}
+	}
+	const nudge = (jobs, delaySeconds = 0, via = {}) => nudgeJobs(jobs.map((job) => typeof job === "string" ? { id: job } : job), delaySeconds, via);
+	return {
+		emit,
+		nudge,
+		processNudge,
+		drain,
+		handoff,
+		recover,
+		cleanup,
+		hasBacklog,
+		monitorBacklog,
+		continueDrain,
+		lanes: () => registry.lanes(),
+		nowMs: () => clock.nowMs(),
+		sleep: (ms) => clock.sleep(ms)
+	};
+}
+// src/runtime/create-outbox.ts
+const DEFAULT_VERSION_GATE_MS = 216e5;
+function parseVersion(version) {
+	if (version === void 0) return;
+	const mineMs = typeof version.timestamp === "number" ? version.timestamp : Date.parse(version.timestamp);
+	if (!Number.isFinite(mineMs)) throw new Error(`createOutbox: version.timestamp ${JSON.stringify(version.timestamp)} is not a date`);
+	return {
+		mineMs,
+		gateMs: version.gateMs ?? DEFAULT_VERSION_GATE_MS
+	};
+}
+/** Thrown by a strict outbox's enqueue (`strictEnqueue: true`) instead of returning a refusal. */
+var EnqueueRefusedError = class extends Error {
+	kind;
+	result;
+	constructor(kind, result) {
+		const detail = result.status === "dedupe_conflict" ? `: its dedupeKey belongs to kind ${JSON.stringify(result.existingKind)}` : "";
+		super(`outbox.enqueue: ${JSON.stringify(kind)} refused (${result.status})${detail}`);
+		this.name = "EnqueueRefusedError";
+		this.kind = kind;
+		this.result = result;
+	}
+};
+/** Not part of the public API. */
+const RUNTIME = Symbol("workers-outbox.runtime");
+const MAX_DEDUPE_KEY_LENGTH = 512;
+const MAX_ERASE_BATCH = 1e4;
+function createOutbox(options) {
+	const registry = createJobRegistry(options.jobs);
+	const emit = createEmitter(options.events);
+	const clock = options.clock ?? systemClock;
+	const lanes = options.lanes ?? 1;
+	if (!Number.isInteger(lanes) || lanes < 1) throw new Error(`createOutbox: lanes must be a positive integer, got ${lanes}`);
+	const version = parseVersion(options.version);
+	const generateId = options.generateId ?? v7;
+	const strictEnqueue = options.strictEnqueue ?? false;
+	const refused = (kind, result) => {
+		if (strictEnqueue) throw new EnqueueRefusedError(kind, result);
+		return result;
+	};
+	const runtime = createRuntime({
+		version,
+		registry,
+		deps: options.deps,
+		connect: options.connect,
+		lanes,
+		queues: normalizeQueues(options.queue),
+		recordNudges: options.recordNudges ?? false,
+		onTransition: options.onTransition,
+		emit,
+		clock,
+		redact: options.redactError,
+		warnAtStreak: options.warnAtStreak,
+		settleRetry: {
+			attempts: 6,
+			delaysMs: [
+				250,
+				750,
+				1500,
+				3e3,
+				5e3,
+				8e3
+			],
+			lockTimeoutMs: 5e3,
+			budgetMs: 25e3
+		}
+	});
+	const operationTimeoutMs = options.operationTimeoutMs ?? 6e4;
+	if (!Number.isInteger(operationTimeoutMs) || operationTimeoutMs < 1) throw new Error(`createOutbox: operationTimeoutMs must be a positive integer, got ${operationTimeoutMs}`);
+	const maxPayloadBytes = options.maxPayloadBytes ?? 262144;
+	if (!Number.isInteger(maxPayloadBytes) || maxPayloadBytes < 1) throw new Error(`createOutbox: maxPayloadBytes must be a positive integer, got ${maxPayloadBytes}`);
+	const withConnection = async (work, invocationDeadlineAt = Infinity) => {
+		const deadlineAt = Math.min(clock.nowMs() + operationTimeoutMs, invocationDeadlineAt);
+		const connection = await acquireConnection(() => options.connect(), clock, deadlineAt);
+		const running = Promise.resolve().then(() => work(connection));
+		const result = await untilDeadline(clock, running, deadlineAt);
+		if (!result.done) {
+			running.catch(() => void 0);
+			await destroyConnection(connection);
+			return unwrap(result, "operator action");
+		}
+		await closeConnection(connection);
+		return unwrap(result, "operator action");
+	};
+	/**
+	* Runs `work` in a transaction and returns what it created, unannounced: the caller nudges once
+	* it no longer holds the connection, since recording a nudge may check out another.
+	*/
+	const collectTransaction = async (db, work) => {
+		const pending = /* @__PURE__ */ new Map();
+		return {
+			result: await db.transaction((tx) => work(tx, async (job, request) => {
+				const enqueued = await outbox.enqueue(tx, job, request);
+				if (enqueued.status === "created") {
+					const delayMs = Number.isFinite(request.delayMs) ? Math.max(0, request.delayMs) : 0;
+					const delaySeconds = Math.ceil(delayMs / 1e3);
+					if (delaySeconds <= 86400) {
+						const group = pending.get(delaySeconds) ?? [];
+						group.push({
+							id: enqueued.id,
+							kind: enqueued.kind
+						});
+						pending.set(delaySeconds, group);
+					}
+				}
+				return enqueued;
+			})),
+			pending
+		};
+	};
+	/** Never throws: a nudge is best effort, the cron sweep is the backstop. */
+	const nudgePending = async (pending, deadlineAt) => {
+		for (const [delaySeconds, jobs] of pending) await runtime.nudge(jobs, delaySeconds, deadlineAt === void 0 ? {} : { deadlineAt });
+	};
+	const outbox = {
+		/** Runs iff the caller's transaction commits; a duplicate `dedupeKey` returns the existing job. */
+		async enqueue(tx, job, request) {
+			if (registry.get(job.kind) !== job) throw new Error(`outbox.enqueue: job ${JSON.stringify(job.kind)} is not registered with this outbox`);
+			if (request.tenantKey === "") throw new Error("outbox.enqueue: tenantKey must be non-empty, or null for no tenant");
+			if (request.dedupeKey.length === 0 || request.dedupeKey.length > MAX_DEDUPE_KEY_LENGTH) throw new Error(`outbox.enqueue: dedupeKey must be 1–${MAX_DEDUPE_KEY_LENGTH} characters`);
+			const wire = toWire(request.payload, maxPayloadBytes);
+			if (!wire.ok) return refused(job.kind, {
+				status: "invalid_payload",
+				issues: [{ message: wire.message }]
+			});
+			const validated = await job.payload["~standard"].validate(wire.value);
+			if (validated.issues) return refused(job.kind, {
+				status: "invalid_payload",
+				issues: validated.issues
+			});
+			const id = generateId();
+			if (!isUuid(id)) throw new Error(`outbox.enqueue: generateId returned ${JSON.stringify(id)}, not a UUID`);
+			const row = await insertJob(tx, {
+				id,
+				kind: job.kind,
+				dedupeKey: request.dedupeKey,
+				payload: wire.value,
+				tenantKey: request.tenantKey ?? null,
+				correlationId: request.correlationId ?? null,
+				metadata: request.metadata ?? {},
+				delayMs: Math.max(0, request.delayMs ?? 0),
+				minVersionMs: version?.mineMs ?? null
+			}, clock.dbNow());
+			if (row.kind !== job.kind) return refused(job.kind, {
+				status: "dedupe_conflict",
+				reason: "kind",
+				id: row.id,
+				existingKind: row.kind
+			});
+			emit({
+				type: "enqueued",
+				jobId: row.id,
+				kind: row.kind,
+				created: row.created
+			});
+			return {
+				status: row.created ? "created" : "exists",
+				id: row.id,
+				kind: row.kind
+			};
+		},
+		async transaction(db, work) {
+			const { result, pending } = await collectTransaction(db, work);
+			await nudgePending(pending);
+			return result;
+		},
+		/** Call after commit; bare ids go to the default lane. Never throws. */
+		nudge: (jobs) => runtime.nudge(jobs),
+		cancel: (ref, reason, scope = {}) => withConnection((c) => cancelJob(c.db, {
+			ref,
+			reason,
+			now: clock.dbNow(),
+			...tenantScope(scope)
+		})),
+		replay: (id, scope = {}) => withConnection((c) => replayJob(c.db, {
+			id,
+			now: clock.dbNow(),
+			...tenantScope(scope)
+		})),
+		/** Makes a pending or retrying job due now. */
+		retryNow: (id, scope = {}) => withConnection(async (c) => {
+			const { result, kind } = await rescheduleNow(c.db, {
+				id,
+				now: clock.dbNow(),
+				...tenantScope(scope)
+			});
+			if (result === "rescheduled" && kind !== null) await runtime.nudge([{
+				id,
+				kind
+			}], 0, { db: c.db });
+			return result;
+		}),
+		/** One statement; every id gets a result. */
+		cancelMany: (ids, reason, scope = {}) => withConnection((c) => cancelJobs(c.db, {
+			ids,
+			reason,
+			now: clock.dbNow(),
+			...tenantScope(scope)
+		})),
+		/** One statement; every id gets a result. */
+		replayMany: (ids, scope = {}) => withConnection((c) => replayJobs(c.db, {
+			ids,
+			now: clock.dbNow(),
+			...tenantScope(scope)
+		})),
+		/** Erasure: deletes every job of one tenant, including in-flight ones. Returns the count. */
+		eraseTenant: (tenantKey, opts = {}) => withConnection(async (c) => {
+			const batch = opts.batch ?? 1e3;
+			if (!Number.isInteger(batch) || batch < 1 || batch > MAX_ERASE_BATCH) throw new Error(`outbox.eraseTenant: batch must be an integer in [1, ${MAX_ERASE_BATCH}], got ${batch}`);
+			let deleted = 0;
+			for (;;) {
+				const removed = await deleteTenantJobs(c.db, {
+					tenantKey,
+					batch
+				});
+				deleted += removed;
+				if (removed < batch) return deleted;
+			}
+		}),
+		[RUNTIME]: {
+			...runtime,
+			withConnection,
+			collectTransaction,
+			nudgePending
+		}
+	};
+	return outbox;
+}
+const isQueueSender = (value) => typeof value === "object" && value !== null && typeof value.send === "function";
+function normalizeQueues(queue) {
+	if (queue === void 0) return {};
+	return isQueueSender(queue) ? { default: queue } : { ...queue };
+}
+const tenantScope = (scope) => scope.tenantKey === void 0 ? {} : { tenantKey: scope.tenantKey };
+const utf8 = new TextEncoder();
+function toWire(payload, maxBytes) {
+	try {
+		const json = JSON.stringify(payload);
+		if (json === void 0) return {
+			ok: false,
+			message: "payload is not JSON-serializable"
+		};
+		const bytes = json.length * 3 <= maxBytes ? json.length : utf8.encode(json).byteLength;
+		if (bytes > maxBytes) return {
+			ok: false,
+			message: `payload is ${bytes} bytes as JSON, over maxPayloadBytes (${maxBytes}); store it elsewhere and enqueue a reference`
+		};
+		return {
+			ok: true,
+			value: JSON.parse(json)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: `payload is not JSON-serializable: ${errorMessage(error)}`
+		};
+	}
+}
+export { emptyReport as a, createEmitter as c, defineJob as d, defineJobFor as f, retry as g, ok as h, DEFAULT_RECOVERY_BUDGET_MS as i, MAX_LEASE_MS as l, fail as m, RUNTIME as n, serializeError as o, cancel as p, createOutbox as r, isTransientDbError as s, EnqueueRefusedError as t, defaultClassify as u };