@makerkit/workers-outbox 0.0.0-stage → 0.0.2

package/dist/backlog-Bd62tjCT.mjs

@@ -0,0 +1,686 @@
+import { o as TERMINAL_STATUSES } from "./status-BZhIWoE0.mjs";
+import { t as queryRows } from "./catalog-G6w4wb_w.mjs";
+import { sql } from "drizzle-orm";
+// src/core/uuid.ts
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Any-case hex in the 8-4-4-4-12 form the `uuid` column accepts. */
+const isUuid = (value) => UUID_PATTERN.test(value);
+// src/store/outbox-store.ts
+const versionClause = (alias, gate) => gate === void 0 ? sql`` : sql` AND (${alias}.min_version_ms IS NULL OR ${alias}.min_version_ms <= ${gate.mineMs} OR ${alias}.created_at <= (SELECT t FROM clock) - ${ms(gate.gateMs)})`;
+const DEFAULT_SUCCEEDED_RETENTION_MS = 6048e5;
+const DEFAULT_TERMINAL_RETENTION_MS = 7776e6;
+const MAX_MESSAGE_LENGTH = 2e3;
+const MAX_NUDGE_ERROR_LENGTH = 500;
+const isTerminal = (status) => TERMINAL_STATUSES.includes(status);
+const dbNow = (now) => sql`COALESCE(${now?.toISOString() ?? null}::timestamptz, now())`;
+const ms = (value) => sql`(${Math.round(value)}::bigint * interval '1 millisecond')`;
+const jsonb = (value) => sql`${JSON.stringify(value)}::jsonb`;
+const arrayLiteral = (values) => `{${values.map((value) => `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`).join(",")}}`;
+const textArray = (values) => sql`${arrayLiteral(values)}::text[]`;
+const uuidArray = (values) => sql`${arrayLiteral(values)}::uuid[]`;
+const tenantClause = (column, tenantKey) => {
+	if (tenantKey === void 0) return sql``;
+	return tenantKey === null ? sql` AND ${column} IS NULL` : sql` AND ${column} = ${tenantKey}`;
+};
+/** float8 epoch ms: every driver returns it as a number. */
+const epochMs = (column) => sql`(EXTRACT(EPOCH FROM ${column}) * 1000)::float8`;
+const toDate = (value) => value === null ? null : new Date(value);
+const kindsTable = (kinds) => sql`jsonb_to_recordset(${jsonb(kinds.map((k) => ({
+	kind: k.kind,
+	lease_ms: k.leaseMs,
+	fits: k.fits
+})))}) AS k(kind text, lease_ms bigint, fits boolean)`;
+const isDue = (alias) => sql`((${alias}.status = 'pending' AND ${alias}.available_at <= (SELECT t FROM clock)) OR (${alias}.status = 'retrying' AND ${alias}.next_attempt_at <= (SELECT t FROM clock)))`;
+async function insertJob(tx, job, now) {
+	const created = (await queryRows(tx, sql`INSERT INTO "outbox"."job" (id, kind, dedupe_key, payload, tenant_key, correlation_id, metadata, min_version_ms, available_at, created_at, updated_at)
+        VALUES (${job.id}, ${job.kind}, ${job.dedupeKey}, ${jsonb(job.payload)}, ${job.tenantKey}, ${job.correlationId},
+                ${jsonb(job.metadata)}, ${job.minVersionMs ?? null}::bigint, ${dbNow(now)} + ${ms(job.delayMs)}, ${dbNow(now)}, ${dbNow(now)})
+        ON CONFLICT ((COALESCE(tenant_key, '')), dedupe_key) DO NOTHING
+        RETURNING id, kind, tenant_key`))[0];
+	if (created) return {
+		id: created.id,
+		kind: created.kind,
+		tenantKey: created.tenant_key,
+		created: true
+	};
+	const row = (await queryRows(tx, sql`SELECT id, kind, tenant_key, now() AS read_at FROM "outbox"."job" WHERE dedupe_key = ${job.dedupeKey} AND tenant_key IS NOT DISTINCT FROM ${job.tenantKey}`))[0];
+	if (!row) throw new Error(`insertJob: dedupe key ${JSON.stringify(job.dedupeKey)} conflicted but no row holds it`);
+	return {
+		id: row.id,
+		kind: row.kind,
+		tenantKey: row.tenant_key,
+		created: false
+	};
+}
+async function claimDue(db, input) {
+	const claimable = input.kinds.filter((k) => k.fits);
+	if (claimable.length === 0 || input.limit < 1) return [];
+	return (await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        k AS (SELECT * FROM ${kindsTable(claimable)}),
+        picked AS (
+          SELECT j.id FROM "outbox"."job" j
+          WHERE j.kind = ANY(${textArray(claimable.map((k) => k.kind))}) AND ${isDue(sql`j`)}${tenantClause(sql`j.tenant_key`, input.tenantKey)}${versionClause(sql`j`, input.version)}
+          ORDER BY COALESCE(j.next_attempt_at, j.available_at), j.created_at, j.id
+          LIMIT ${input.limit}
+          FOR UPDATE SKIP LOCKED
+        ),
+        ${claimAndOpenAttempt(input.leaseToken, input.trigger)}
+        SELECT * FROM claimed`)).map(toClaimedJob);
+}
+/** Never claims a substitute; each id's diagnosis reads the pre-claim snapshot. */
+async function claimByIds(db, input) {
+	const ids = [...new Set(input.ids)];
+	const valid = ids.filter((id) => isUuid(id));
+	const invalid = ids.filter((id) => !isUuid(id)).map((id) => ({
+		id,
+		result: "not_found"
+	}));
+	if (valid.length === 0 || input.kinds.length === 0) return [...invalid, ...valid.map((id) => ({
+		id,
+		result: "not_found"
+	}))];
+	const rows = await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        k AS (SELECT * FROM ${kindsTable(input.kinds)}),
+        req AS (SELECT DISTINCT unnest(${uuidArray(valid)}) AS id),
+        picked AS (
+          SELECT j.id FROM "outbox"."job" j
+          JOIN req ON req.id = j.id
+          WHERE j.kind = ANY(${textArray(input.kinds.filter((k) => k.fits).map((k) => k.kind))}) AND ${isDue(sql`j`)}${tenantClause(sql`j.tenant_key`, input.tenantKey)}${versionClause(sql`j`, input.version)}
+          FOR UPDATE OF j SKIP LOCKED
+        ),
+        ${claimAndOpenAttempt(input.leaseToken, "nudge")}
+        SELECT req.id::text AS req_id,
+          CASE
+            WHEN c.id IS NOT NULL THEN 'claimed'
+            WHEN j.id IS NULL THEN 'not_found'
+            WHEN NOT EXISTS (SELECT 1 FROM k WHERE k.kind = j.kind) THEN 'unregistered_kind'
+            WHEN j.status IN ('succeeded', 'dead', 'cancelled') THEN 'terminal'
+            WHEN j.status = 'processing' THEN 'leased'
+            WHEN NOT ${isDue(sql`j`)} THEN 'not_due'
+            WHEN ${input.version === void 0 ? sql`false` : sql`NOT (TRUE${versionClause(sql`j`, input.version)})`} THEN 'newer_version'
+            WHEN NOT (SELECT fits FROM k WHERE k.kind = j.kind) THEN 'over_budget'
+            ELSE 'locked'
+          END AS result,
+          c.*
+        FROM req
+        LEFT JOIN claimed c ON c.id = req.id
+        -- LATERAL forces a primary-key probe per id; a plain join may seq-scan the table.
+        LEFT JOIN LATERAL (SELECT * FROM "outbox"."job" WHERE id = req.id${tenantClause(sql`tenant_key`, input.tenantKey)}) j ON true`);
+	return [...invalid, ...rows.map((row) => row.result === "claimed" ? {
+		id: row.req_id,
+		result: "claimed",
+		job: toClaimedJob(row)
+	} : {
+		id: row.req_id,
+		result: row.result
+	})];
+}
+/** The lease token fences stale workers: they get `lease_lost` and write nothing. */
+async function settleJob(db, input) {
+	const t = input.transition;
+	const failure = "code" in t ? t : null;
+	const code = failure?.code ?? null;
+	const message = failure ? truncate(failure.message) : null;
+	const codeStreak = failure?.codeStreak ?? 0;
+	const stickyCode = failure?.stickyCode ?? null;
+	const reason = t.to === "dead" || t.to === "cancelled" ? t.reason : null;
+	const delayMs = t.to === "retrying" ? t.delayMs : 0;
+	const finishes = t.to !== "retrying";
+	const expiredClause = input.requireExpiredLease ? sql` AND leased_until < (SELECT t FROM clock)` : sql``;
+	return firstRow(await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        settled AS (
+          UPDATE "outbox"."job" SET
+            status = ${t.to},
+            lease_token = NULL,
+            leased_until = NULL,
+            finished_attempts = finished_attempts + 1,
+            spent_attempts = spent_attempts + ${t.attemptOutcome === "lease_expired" ? 0 : 1},
+            next_attempt_at = ${t.to === "retrying" ? sql`(SELECT t FROM clock) + ${ms(delayMs)}` : sql`NULL`},
+            code_streak = ${codeStreak},
+            sticky_code = COALESCE(${stickyCode}, sticky_code),
+            last_error_code = COALESCE(${code}, last_error_code),
+            last_error_message = ${code === null ? sql`last_error_message` : sql`${message}`},
+            terminal_reason = ${reason},
+            finished_at = ${finishes ? sql`(SELECT t FROM clock)` : sql`NULL`},
+            updated_at = (SELECT t FROM clock)
+          WHERE id = ${input.jobId} AND lease_token = ${input.leaseToken} AND status = 'processing'${expiredClause}
+          RETURNING id, started_attempts
+        ),
+        closed AS (
+          UPDATE "outbox"."attempt" a SET
+            finished_at = (SELECT t FROM clock),
+            outcome = ${t.attemptOutcome},
+            code = ${code},
+            message = ${message},
+            duration_ms = LEAST(2147483647, GREATEST(0, EXTRACT(EPOCH FROM ((SELECT t FROM clock) - a.started_at)) * 1000))::int
+          FROM settled
+          WHERE a.job_id = settled.id AND a.attempt_no = settled.started_attempts AND a.lease_token = ${input.leaseToken}
+          RETURNING 1
+        )
+        SELECT (SELECT count(*) FROM settled)::int AS applied`), "settleJob").applied === 1 ? "applied" : "lease_lost";
+}
+/** Lock-free pre-check before a settle hook; `settleJob` stays the authoritative fence. */
+async function isLeaseHeld(db, input) {
+	if (!isUuid(input.jobId) || !isUuid(input.leaseToken)) return false;
+	const expiredClause = input.requireExpiredLease ? sql` AND leased_until < ${dbNow(input.now)}` : sql``;
+	return firstRow(await queryRows(db, sql`SELECT EXISTS (
+          SELECT 1 FROM "outbox"."job"
+          WHERE id = ${input.jobId} AND lease_token = ${input.leaseToken} AND status = 'processing'${expiredClause}
+        ) AS held, now() AS read_at`), "isLeaseHeld").held;
+}
+/**
+* Native bounds for the rest of the current transaction (PostgreSQL 17+), in one round trip:
+* the whole transaction (FATAL 25P04: the session ends), each statement (57014), each lock wait (55P03).
+*/
+async function setSettlementTimeouts(tx, input) {
+	const toMs = (value) => `'${Math.max(1, Math.ceil(value))}ms'`;
+	await tx.execute(sql.raw(`SELECT set_config('transaction_timeout', ${toMs(input.transactionMs)}, true), set_config('statement_timeout', ${toMs(input.statementMs)}, true), set_config('lock_timeout', ${toMs(input.lockMs)}, true), now() AS read_at`));
+}
+/**
+* How the attempt opened under this lease ended, if it did: resolves a settle whose
+* connection dropped after the write may have committed.
+*/
+async function readAttemptOutcome(db, input) {
+	return (await queryRows(db, sql`SELECT outcome, now() AS read_at FROM "outbox"."attempt"
+        WHERE job_id = ${input.jobId} AND lease_token = ${input.leaseToken}`))[0]?.outcome ?? null;
+}
+async function listExpiredLeases(db, input) {
+	if (input.kinds?.length === 0 || input.limit < 1) return [];
+	const kindClause = input.kinds ? sql` AND kind = ANY(${textArray(input.kinds)})` : sql``;
+	return (await queryRows(db, sql`SELECT id, kind, lease_token, spent_attempts, code_streak, last_error_code, sticky_code,
+               tenant_key, correlation_id, metadata, started_attempts
+        FROM "outbox"."job"
+        WHERE status = 'processing' AND leased_until < ${dbNow(input.now)}${kindClause}
+        ORDER BY leased_until
+        LIMIT ${input.limit}`)).map((row) => ({
+		id: row.id,
+		kind: row.kind,
+		leaseToken: row.lease_token,
+		spentAttempts: row.spent_attempts,
+		codeStreak: row.code_streak,
+		lastErrorCode: row.last_error_code,
+		stickyCode: row.sticky_code,
+		tenantKey: row.tenant_key,
+		correlationId: row.correlation_id,
+		metadata: row.metadata,
+		attemptNo: row.started_attempts
+	}));
+}
+/** A job mid-attempt is `in_flight`: its worker owns it until it settles. */
+async function cancelJob(db, input) {
+	if ("id" in input.ref && !isUuid(input.ref.id)) return "not_found";
+	const [row] = await updateMatching(db, {
+		match: "id" in input.ref ? sql`id = ${input.ref.id}` : sql`dedupe_key = ${input.ref.dedupeKey} AND tenant_key IS NOT DISTINCT FROM ${input.ref.tenantKey}`,
+		tenantKey: input.tenantKey,
+		now: input.now,
+		...cancellation(input.reason)
+	});
+	return row ? cancelResult(row) : "not_found";
+}
+/** Dead or cancelled → pending, with a fresh retry budget. */
+async function replayJob(db, input) {
+	if (!isUuid(input.id)) return "not_found";
+	const [row] = await updateMatching(db, {
+		match: sql`id = ${input.id}`,
+		tenantKey: input.tenantKey,
+		now: input.now,
+		...REPLAY
+	});
+	return row ? replayResult(row) : "not_found";
+}
+async function deleteFinishedJobs(db, input) {
+	const expired = sql`((status = 'succeeded' AND finished_at < (SELECT t FROM clock) - ${ms(input.succeededRetentionMs)})
+             OR (status IN ('dead', 'cancelled') AND finished_at < (SELECT t FROM clock) - ${ms(input.terminalRetentionMs)}))`;
+	return firstRow(await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        doomed AS (
+          SELECT id FROM "outbox"."job"
+          WHERE ${expired}
+          LIMIT ${input.batch}
+        ),
+        deleted AS (DELETE FROM "outbox"."job" WHERE id IN (SELECT id FROM doomed) AND ${expired} RETURNING 1)
+        SELECT count(*)::int AS deleted FROM deleted`), "deleteFinishedJobs").deleted;
+}
+async function hasDueJobs(db, input) {
+	const claimable = input.kinds.filter((k) => k.fits);
+	if (claimable.length === 0) return false;
+	return firstRow(await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t)
+        SELECT EXISTS (
+          SELECT 1 FROM "outbox"."job" j WHERE j.kind = ANY(${textArray(claimable.map((k) => k.kind))}) AND ${isDue(sql`j`)}${versionClause(sql`j`, input.version)}
+        ) AS due`), "hasDueJobs").due;
+}
+async function listDueJobIds(db, input) {
+	if (input.kinds.length === 0 || input.limit < 1) return [];
+	return (await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t)
+        SELECT j.id FROM "outbox"."job" j
+        WHERE j.kind = ANY(${textArray(input.kinds)}) AND ${isDue(sql`j`)}
+          AND (j.nudge_sent_at IS NULL OR j.nudge_sent_at <= (SELECT t FROM clock) - ${ms(input.nudgeCooldownMs)})${tenantClause(sql`j.tenant_key`, input.tenantKey)}${versionClause(sql`j`, input.version)}
+        ORDER BY COALESCE(j.next_attempt_at, j.available_at), j.created_at, j.id
+        LIMIT ${input.limit}`)).map((row) => row.id);
+}
+async function countBacklog(db, input) {
+	if (input.kinds?.length === 0) return [];
+	const kindClause = input.kinds ? sql` AND j.kind = ANY(${textArray(input.kinds)})` : sql``;
+	return (await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        active AS (
+          SELECT j.kind, j.status, j.leased_until,
+                 CASE j.status WHEN 'pending' THEN j.available_at WHEN 'retrying' THEN j.next_attempt_at END AS due_at
+          FROM "outbox"."job" j
+          WHERE j.status IN ('pending', 'retrying', 'processing')${kindClause}${tenantClause(sql`j.tenant_key`, input.tenantKey)}
+        )
+        SELECT kind,
+          count(*) FILTER (WHERE due_at <= (SELECT t FROM clock))::int AS due,
+          count(*) FILTER (WHERE due_at < (SELECT t FROM clock) - ${ms(input.agedMs)})::int AS aged,
+          count(*) FILTER (WHERE due_at > (SELECT t FROM clock))::int AS scheduled,
+          count(*) FILTER (WHERE status = 'processing')::int AS processing,
+          count(*) FILTER (WHERE status = 'processing' AND leased_until < (SELECT t FROM clock))::int AS stuck,
+          (max(EXTRACT(EPOCH FROM ((SELECT t FROM clock) - due_at))) FILTER (WHERE due_at <= (SELECT t FROM clock)) * 1000)::float8 AS oldest_due_age_ms
+        FROM active
+        GROUP BY kind
+        ORDER BY kind`)).map((row) => ({
+		kind: row.kind,
+		due: row.due,
+		aged: row.aged,
+		scheduled: row.scheduled,
+		processing: row.processing,
+		stuck: row.stuck,
+		oldestDueAgeMs: row.oldest_due_age_ms === null ? null : Math.round(row.oldest_due_age_ms)
+	}));
+}
+const optional = (value, clause) => value === void 0 ? sql`` : clause(value);
+const jobFilter = (filter) => sql`j.status = ${filter.status}${optional(filter.kind, (v) => sql` AND j.kind = ${v}`)}${tenantClause(sql`j.tenant_key`, filter.tenantKey)}${optional(filter.dedupeKey, (v) => sql` AND j.dedupe_key = ${v}`)}${optional(filter.terminalReason, (v) => sql` AND j.terminal_reason = ${v}`)}${optional(filter.createdAfter, (v) => sql` AND j.created_at > ${v.toISOString()}::timestamptz`)}${optional(filter.createdBefore, (v) => sql` AND j.created_at < ${v.toISOString()}::timestamptz`)}${optional(filter.finishedAfter, (v) => sql` AND j.finished_at > ${v.toISOString()}::timestamptz`)}${optional(filter.finishedBefore, (v) => sql` AND j.finished_at < ${v.toISOString()}::timestamptz`)}`;
+const jobSummaryColumns = sql`j.id, j.kind, j.status, j.dedupe_key, j.tenant_key, j.correlation_id, j.metadata,
+  j.started_attempts, j.finished_attempts, j.spent_attempts, j.code_streak, j.sticky_code,
+  j.last_error_code, j.last_error_message, j.terminal_reason, j.nudge_attempts, j.last_nudge_error,
+  ${epochMs(sql`j.available_at`)} AS available_at, ${epochMs(sql`j.next_attempt_at`)} AS next_attempt_at,
+  ${epochMs(sql`j.leased_until`)} AS leased_until, ${epochMs(sql`j.created_at`)} AS created_at,
+  ${epochMs(sql`j.updated_at`)} AS updated_at, ${epochMs(sql`j.finished_at`)} AS finished_at,
+  ${epochMs(sql`j.nudge_sent_at`)} AS nudge_sent_at, now() AS read_at`;
+/** Keyset-paginated: pass `nextCursor` back as `cursor`. */
+async function listJobs(db, input) {
+	const after = input.cursor ? parseCursor(input.cursor) : null;
+	const afterClause = after ? sql` AND (j.created_at, j.id) > (${after.createdAt}::timestamptz, ${after.id}::uuid)` : sql``;
+	const rows = await queryRows(db, sql`SELECT ${jobSummaryColumns}
+        FROM "outbox"."job" j
+        WHERE ${jobFilter(input)}${afterClause}
+        ORDER BY j.created_at, j.id
+        LIMIT ${Math.max(0, input.limit) + 1}`);
+	const page = rows.slice(0, Math.max(0, input.limit)).map(toJobSummary);
+	const last = page.at(-1);
+	return {
+		jobs: page,
+		nextCursor: rows.length > page.length && last ? `${last.createdAt.toISOString()}|${last.id}` : null
+	};
+}
+async function countJobs(db, input) {
+	return firstRow(await queryRows(db, sql`SELECT count(*)::int AS count, now() AS read_at FROM "outbox"."job" j WHERE ${jobFilter(input)}`), "countJobs").count;
+}
+async function aggregateAttemptOutcomes(db, input) {
+	const filters = sql.join([
+		input.kinds ? sql` AND j.kind = ANY(${textArray(input.kinds)})` : sql``,
+		tenantClause(sql`j.tenant_key`, input.tenantKey),
+		input.outcomes ? sql` AND a.outcome = ANY(${textArray(input.outcomes)})` : sql``,
+		input.code === void 0 ? sql`` : sql` AND a.code = ${input.code}`
+	], sql``);
+	const maxRows = Math.max(0, input.maxRows);
+	const row = firstRow(await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        w AS (SELECT (SELECT t FROM clock) - ${ms(input.windowMs)} AS cutoff),
+        g AS (
+          SELECT j.kind, j.tenant_key, a.outcome, a.code, count(*)::int AS count
+          FROM "outbox"."attempt" a
+          JOIN "outbox"."job" j ON j.id = a.job_id
+          WHERE a.finished_at >= (SELECT cutoff FROM w)${filters}
+          GROUP BY j.kind, j.tenant_key, a.outcome, a.code
+          ORDER BY count DESC, j.kind, j.tenant_key NULLS FIRST, a.outcome, a.code NULLS FIRST
+          LIMIT ${maxRows + 1}
+        )
+        SELECT ${epochMs(sql`(SELECT cutoff FROM w)`)} AS cutoff_ms,
+          COALESCE((SELECT json_agg(g ORDER BY g.count DESC, g.kind, g.tenant_key NULLS FIRST, g.outcome, g.code NULLS FIRST) FROM g), '[]'::json) AS groups`), "aggregateAttemptOutcomes");
+	return {
+		cutoff: new Date(row.cutoff_ms),
+		groups: row.groups.slice(0, maxRows).map((g) => ({
+			kind: g.kind,
+			tenantKey: g.tenant_key,
+			outcome: g.outcome,
+			code: g.code,
+			count: g.count
+		})),
+		truncated: row.groups.length > maxRows
+	};
+}
+/** Only waiting jobs are stamped: bookkeeping must never wait on a claimed row's settle lock. */
+async function recordNudgeResult(db, input) {
+	const ids = [...new Set(input.ids)].filter((id) => isUuid(id));
+	if (ids.length === 0) return 0;
+	const stamp = input.error === null ? sql`nudge_sent_at = (SELECT t FROM clock), last_nudge_error = NULL` : sql`last_nudge_error = ${truncate(input.error, MAX_NUDGE_ERROR_LENGTH)}`;
+	return firstRow(await queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        stamped AS (
+          UPDATE "outbox"."job" SET nudge_attempts = nudge_attempts + 1, ${stamp}
+          WHERE id = ANY(${uuidArray(ids)}) AND status IN ('pending', 'retrying')
+          RETURNING 1
+        )
+        SELECT count(*)::int AS stamped FROM stamped`), "recordNudgeResult").stamped;
+}
+function toJobSummary(row) {
+	return {
+		id: row.id,
+		kind: row.kind,
+		status: row.status,
+		dedupeKey: row.dedupe_key,
+		tenantKey: row.tenant_key,
+		correlationId: row.correlation_id,
+		metadata: row.metadata,
+		startedAttempts: row.started_attempts,
+		finishedAttempts: row.finished_attempts,
+		spentAttempts: row.spent_attempts,
+		codeStreak: row.code_streak,
+		stickyCode: row.sticky_code,
+		lastErrorCode: row.last_error_code,
+		lastErrorMessage: row.last_error_message,
+		terminalReason: row.terminal_reason,
+		availableAt: new Date(row.available_at),
+		nextAttemptAt: toDate(row.next_attempt_at),
+		leasedUntil: toDate(row.leased_until),
+		createdAt: new Date(row.created_at),
+		updatedAt: new Date(row.updated_at),
+		finishedAt: toDate(row.finished_at),
+		nudgeSentAt: toDate(row.nudge_sent_at),
+		nudgeAttempts: row.nudge_attempts,
+		lastNudgeError: row.last_nudge_error
+	};
+}
+function parseCursor(cursor) {
+	const [createdAt = "", id = ""] = cursor.split("|");
+	if (!isUuid(id) || Number.isNaN(Date.parse(createdAt))) throw new Error(`listJobs: invalid cursor ${JSON.stringify(cursor)}`);
+	return {
+		createdAt,
+		id
+	};
+}
+/** One statement claims and opens the attempt: a claim never exists without its attempt. */
+function claimAndOpenAttempt(leaseToken, trigger) {
+	return sql`claimed AS (
+          UPDATE "outbox"."job" j SET
+            status = 'processing',
+            started_attempts = j.started_attempts + 1,
+            next_attempt_at = NULL,
+            lease_token = ${leaseToken},
+            leased_until = (SELECT t FROM clock) + k.lease_ms * interval '1 millisecond',
+            updated_at = (SELECT t FROM clock)
+          FROM picked, k
+          WHERE j.id = picked.id AND k.kind = j.kind
+          RETURNING j.id, j.kind, j.payload, j.tenant_key, j.correlation_id, j.metadata,
+                    j.lease_token, j.started_attempts, j.spent_attempts, j.code_streak, j.last_error_code,
+                    j.sticky_code
+        ),
+        opened AS (
+          INSERT INTO "outbox"."attempt" (job_id, attempt_no, kind, lease_token, trigger, started_at)
+          SELECT id, started_attempts, kind, lease_token, ${trigger}, (SELECT t FROM clock) FROM claimed
+          RETURNING 1
+        )`;
+}
+function toClaimedJob(row) {
+	return {
+		id: row.id,
+		kind: row.kind,
+		payload: row.payload,
+		tenantKey: row.tenant_key,
+		correlationId: row.correlation_id,
+		metadata: row.metadata,
+		leaseToken: row.lease_token,
+		attemptNo: row.started_attempts,
+		spentAttempts: row.spent_attempts,
+		codeStreak: row.code_streak,
+		lastErrorCode: row.last_error_code,
+		stickyCode: row.sticky_code
+	};
+}
+function truncate(message, max = MAX_MESSAGE_LENGTH) {
+	if (message === null || message.length <= max) return message;
+	return `${message.slice(0, max - 1)}…`;
+}
+function firstRow(rows, statement) {
+	const row = rows[0];
+	if (!row) throw new Error(`${statement}: statement returned no row`);
+	return row;
+}
+/** One job with its attempt ledger, for an operator view. Payload excluded. */
+async function getJob(db, input) {
+	if (!isUuid(input.id)) return null;
+	const [row] = await queryRows(db, sql`SELECT ${jobSummaryColumns}
+        FROM "outbox"."job" j
+        WHERE j.id = ${input.id}${tenantClause(sql`j.tenant_key`, input.tenantKey)}`);
+	if (!row) return null;
+	const attempts = await queryRows(db, sql`SELECT attempt_no, trigger, outcome, code, message, duration_ms,
+               ${epochMs(sql`started_at`)} AS started_at, ${epochMs(sql`finished_at`)} AS finished_at, now() AS read_at
+        FROM "outbox"."attempt" WHERE job_id = ${input.id}
+        ORDER BY attempt_no`);
+	return {
+		...toJobSummary(row),
+		attempts: attempts.map((a) => ({
+			attemptNo: a.attempt_no,
+			trigger: a.trigger,
+			outcome: a.outcome,
+			code: a.code,
+			message: a.message,
+			durationMs: a.duration_ms,
+			startedAt: new Date(a.started_at),
+			finishedAt: toDate(a.finished_at)
+		}))
+	};
+}
+/** Every job one request produced, newest first. */
+async function findJobsByCorrelationId(db, input) {
+	return (await queryRows(db, sql`SELECT ${jobSummaryColumns}
+        FROM "outbox"."job" j
+        WHERE j.correlation_id = ${input.correlationId}${tenantClause(sql`j.tenant_key`, input.tenantKey)}
+        ORDER BY j.created_at DESC, j.id DESC
+        LIMIT ${Math.max(0, input.limit)}`)).map(toJobSummary);
+}
+/** Makes a pending or retrying job due now ("retry now"). */
+async function rescheduleNow(db, input) {
+	if (!isUuid(input.id)) return {
+		result: "not_found",
+		kind: null
+	};
+	const [row] = await updateMatching(db, {
+		match: sql`id = ${input.id}`,
+		tenantKey: input.tenantKey,
+		now: input.now,
+		set: sql`available_at = CASE WHEN status = 'pending' THEN (SELECT t FROM clock) ELSE available_at END,
+        next_attempt_at = CASE WHEN status = 'retrying' THEN (SELECT t FROM clock) ELSE next_attempt_at END,
+        updated_at = (SELECT t FROM clock)`,
+		allowed: WAITING
+	});
+	if (!row) return {
+		result: "not_found",
+		kind: null
+	};
+	return {
+		result: row.done ? "rescheduled" : "not_waiting",
+		kind: row.kind
+	};
+}
+/**
+* Erasure: deletes one tenant's jobs (attempts cascade), in flight or not. A worker
+* mid-attempt then settles `lease_lost`. One bounded batch per call.
+*/
+async function deleteTenantJobs(db, input) {
+	return firstRow(await queryRows(db, sql`WITH doomed AS (
+          SELECT id FROM "outbox"."job" WHERE tenant_key = ${input.tenantKey} LIMIT ${input.batch}
+        ),
+        deleted AS (DELETE FROM "outbox"."job" WHERE id IN (SELECT id FROM doomed) RETURNING 1)
+        SELECT count(*)::int AS deleted, now() AS read_at FROM deleted`), "deleteTenantJobs").deleted;
+}
+/** Cancels many waiting jobs in one statement; every requested id gets a result. */
+async function cancelJobs(db, input) {
+	const rows = await updateByIds(db, input, cancellation(input.reason));
+	return mapBulk(input.ids, rows, cancelResult);
+}
+/** Replays many dead or cancelled jobs in one statement, each with a fresh budget. */
+async function replayJobs(db, input) {
+	const rows = await updateByIds(db, input, REPLAY);
+	return mapBulk(input.ids, rows, replayResult);
+}
+const WAITING = sql`status IN ('pending', 'retrying')`;
+const cancellation = (reason) => ({
+	set: sql`status = 'cancelled', terminal_reason = ${reason}, next_attempt_at = NULL,
+        finished_at = (SELECT t FROM clock), updated_at = (SELECT t FROM clock)`,
+	allowed: WAITING
+});
+const REPLAY = {
+	set: sql`status = 'pending', available_at = (SELECT t FROM clock), next_attempt_at = NULL,
+        terminal_reason = NULL, finished_at = NULL, spent_attempts = 0, code_streak = 0,
+        sticky_code = NULL, updated_at = (SELECT t FROM clock)`,
+	allowed: sql`status IN ('dead', 'cancelled')`
+};
+const cancelResult = (row) => row.done ? "cancelled" : isTerminal(row.status) ? "already_terminal" : "in_flight";
+const replayResult = (row) => row.done ? "replayed" : "not_replayable";
+/** One statement: every matching job (in the tenant scope) reports its status, and whether it changed. */
+function updateMatching(db, input) {
+	return queryRows(db, sql`WITH clock AS (SELECT ${dbNow(input.now)} AS t),
+        target AS (
+          SELECT id, kind, status FROM "outbox"."job"
+          WHERE ${input.match}${tenantClause(sql`tenant_key`, input.tenantKey)}
+        ),
+        updated AS (
+          UPDATE "outbox"."job" SET ${input.set}
+          WHERE id IN (SELECT id FROM target) AND ${input.allowed}
+          RETURNING id
+        )
+        SELECT target.id::text AS id, target.kind, target.status, (updated.id IS NOT NULL) AS done
+        FROM target LEFT JOIN updated USING (id)`);
+}
+async function updateByIds(db, input, change) {
+	const valid = [...new Set(input.ids)].filter((id) => isUuid(id));
+	if (valid.length === 0) return [];
+	return updateMatching(db, {
+		...change,
+		match: sql`id = ANY(${uuidArray(valid)})`,
+		tenantKey: input.tenantKey,
+		now: input.now
+	});
+}
+function mapBulk(ids, rows, decide) {
+	const byId = new Map(rows.map((row) => [row.id, row]));
+	const results = {};
+	for (const id of new Set(ids)) {
+		const row = byId.get(id.toLowerCase());
+		results[id] = row ? decide(row) : "not_found";
+	}
+	return results;
+}
+// src/core/backlog.ts
+const DEFAULT_BACKLOG_THRESHOLDS = {
+	maxDue: 1e3,
+	maxAged: 100,
+	maxStuck: 0,
+	criticalFactor: 2,
+	maxSeverity: "critical"
+};
+/** Milliseconds a due job may wait before it counts as aged. */
+const DEFAULT_BACKLOG_AGED_MS = 9e5;
+const UNREGISTERED_THRESHOLDS = {
+	maxDue: 0,
+	maxAged: 0,
+	maxSeverity: "warning"
+};
+const SEVERITY_RANK = {
+	ok: 0,
+	warning: 1,
+	critical: 2
+};
+function evaluateBacklog(input) {
+	const byLane = /* @__PURE__ */ new Map();
+	for (const count of input.counts) {
+		const lane = input.laneOf(count.kind) ?? "(unregistered)";
+		byLane.set(lane, [...byLane.get(lane) ?? [], count]);
+	}
+	const lanes = [...byLane.entries()].map(([lane, kinds]) => gradeLane(lane, kinds, resolveThresholds(lane, input)));
+	const totals = sumTotals(lanes);
+	const severity = lanes.reduce((worst, l) => worse(worst, l.severity), "ok");
+	if (severity === "ok") return {
+		severity,
+		totals,
+		lanes,
+		alert: null
+	};
+	const breaching = lanes.filter((lane) => lane.severity !== "ok");
+	return {
+		severity,
+		totals,
+		lanes,
+		alert: {
+			severity,
+			message: alertMessage(severity, breaching),
+			lanes: breaching,
+			totals
+		}
+	};
+}
+function resolveThresholds(lane, input) {
+	return {
+		...DEFAULT_BACKLOG_THRESHOLDS,
+		...lane === "(unregistered)" ? UNREGISTERED_THRESHOLDS : input.thresholds,
+		...input.lanes?.[lane]
+	};
+}
+function gradeLane(lane, kinds, thresholds) {
+	const totals = sumTotals(kinds);
+	const breaches = [
+		[
+			"due",
+			totals.due,
+			thresholds.maxDue
+		],
+		[
+			"aged",
+			totals.aged,
+			thresholds.maxAged
+		],
+		[
+			"stuck",
+			totals.stuck,
+			thresholds.maxStuck
+		]
+	].flatMap(([metric, value, threshold]) => {
+		if (value <= threshold) return [];
+		return [{
+			metric,
+			value,
+			threshold,
+			severity: value >= threshold * thresholds.criticalFactor && thresholds.maxSeverity === "critical" ? "critical" : "warning"
+		}];
+	});
+	const ages = kinds.flatMap((k) => k.oldestDueAgeMs === null ? [] : [k.oldestDueAgeMs]);
+	return {
+		lane,
+		kinds,
+		...totals,
+		oldestDueAgeMs: ages.length === 0 ? null : Math.max(...ages),
+		severity: breaches.reduce((worst, b) => worse(worst, b.severity), "ok"),
+		breaches,
+		thresholds
+	};
+}
+function sumTotals(rows) {
+	return rows.reduce((sum, row) => ({
+		due: sum.due + row.due,
+		aged: sum.aged + row.aged,
+		scheduled: sum.scheduled + row.scheduled,
+		processing: sum.processing + row.processing,
+		stuck: sum.stuck + row.stuck
+	}), {
+		due: 0,
+		aged: 0,
+		scheduled: 0,
+		processing: 0,
+		stuck: 0
+	});
+}
+function worse(a, b) {
+	return SEVERITY_RANK[b] > SEVERITY_RANK[a] ? b : a;
+}
+function alertMessage(severity, lanes) {
+	return `outbox backlog ${severity}: ${lanes.flatMap((lane) => lane.breaches.map((b) => `${lane.lane} ${b.metric} ${b.value} > ${b.threshold}`)).join("; ")}`;
+}
+export { isUuid as A, readAttemptOutcome as C, rescheduleNow as D, replayJobs as E, setSettlementTimeouts as O, listJobs as S, replayJob as T, hasDueJobs as _, DEFAULT_TERMINAL_RETENTION_MS as a, listDueJobIds as b, cancelJobs as c, countBacklog as d, countJobs as f, getJob as g, findJobsByCorrelationId as h, DEFAULT_SUCCEEDED_RETENTION_MS as i, settleJob as k, claimByIds as l, deleteTenantJobs as m, DEFAULT_BACKLOG_THRESHOLDS as n, aggregateAttemptOutcomes as o, deleteFinishedJobs as p, evaluateBacklog as r, cancelJob as s, DEFAULT_BACKLOG_AGED_MS as t, claimDue as u, insertJob as v, recordNudgeResult as w, listExpiredLeases as x, isLeaseHeld as y };